ChronoATX 公式技術ドキュメント

【ドキュメント概要（BLUF）】：ChronoATXは、Windows/macOSに対応したインストーラー不要のポータブル自動テスト基盤です。本技術ガイドでは、ツールの初期化からWeb・デスクトップ（Windows/Mac）・モバイル（iOS/Android）の自動化シナリオ記述、ChronoRunner CLIを用いたCI/CD自動実行までの完全なリファレンスと実コード例を提供します。

Section 01

環境準備とポータブル実行環境のセットアップ

ChronoATXは完全ポータブル（解凍即実行可能）仕様です。レジストリ書き込みや管理者インストーラーを必要とせず、任意のフォルダに解凍するだけで準備が整います。

Windows の場合 (x64)

配布パッケージ ChronoATX-Portable-v1.0.0-win-x64.zip を任意の作業ディレクトリに解凍します。
VS Code を起動し、拡張機能マーケットプレイスで「ChronoATX」を検索してインストールします。

macOS の場合 (Apple Silicon / Intel)

配布パッケージ ChronoATX-Portable-osx-arm64.tar.gz を解凍します。
ターミナルを開き、バイナリに実行権限を付与します：
```
chmod +x ChronoRunner als/ChronoATX.ALS
```

【補足】Web自動テスト用ブラウザ（Chromium）のセットアップについて

原則として手動インストールは不要です：初回テストシナリオ実行時に、ChronoATXランタイムが必要なChromiumブラウザを自動検知し、静默インストール（自動セットアップ）を行います。

※ CI/CDパイプライン環境（Docker等）での事前キャッシュ構築や、初回のダウンロード待ち時間をなくしたい場合は、以下のコマンドで事前に一括導入しておくことが推奨されます：

macOS / Linux: ./ChronoRunner --install-browsers

Windows (PowerShell): .\ChronoRunner.exe --install-browsers

※ デスクトップOS自動化（Desktop Engine）またはモバイルテスト（Mobile Engine）のみを利用する場合は、本手順は一切不要です。

Section 02

プロジェクトの初期化と環境設定 (chrono.json)

ChronoATXでは、プロジェクトの立ち上げ方法として「VS Code 拡張機能のGUI向導（推奨）」と「ChronoRunner CLI コマンド（CI/CD・ターミナル向け）」の2つのアプローチを提供しています。

推奨

方法 1: VS Code 拡張機能（GUI向導）

左側のアクティビティバーにある ChronoATX アイコン を開き、Quick Actions から対話形式でプロジェクトを作成できます。

New ChronoATX Project... (向導作成)：
プロジェクト名、ターゲットディレクトリ、用途別テンプレート（Web / デスクトップ / モバイル / 3端統合フルスタック / 最小構成）をステップ選択して一括自動生成します。
Quick Initialize Project (即時初期化)：
現在VS Codeで開いているフォルダに、標準骨架と chrono.json をワンクリックで展開します。

CI/CD・端末

方法 2: CLI コマンド（ChronoRunner）

ターミナルでの作業やCI/CDパイプラインでの自動構築には、ワンコマンドによる初期化が利用可能です。

# 任意ディレクトリで初期化
ChronoRunner --init

実行した作業ディレクトリ直下に、多環境設定テンプレート chrono.json が瞬時に生成されます。

chrono.json の設定とビジュアルエディタ (GUI / コード両対応)

VS Codeで chrono.json を開くと、統合されたビジュアル設定パネル（React WebView）が自動起動します。JSONコードを手書きすることなく、フォーム入力とスイッチ操作で環境や実行オプションを設定できます（※コード直接編集との相互同期にも対応）。

🌐 接続先切替 (SIT / UAT / 本番) ⚙️ ヘッドレス実行 / 失敗時動画・スクリーンショット 📊 Allure レポート出力設定

{
  "ProjectName": "ChronoATX_Insurance_E2E",
  "Version": "1.0.0",
  "DefaultEnvironment": "SIT",
  "Environments": {
    "SIT": {
      "BaseUrl": "https://sit-insurance.example.com",
      "Username": "admin",
      "Password": "admin123"
    },
    "UAT": {
      "BaseUrl": "https://uat-insurance.example.com",
      "Username": "tester",
      "Password": "tester456"
    }
  },
  "RunnerConfig": {
    "Headless": false,
    "RecordVideo": true,
    "ScreenshotOnFailed": true,
    "RetryCount": 1
  },
  "ReportConfig": {
    "OutputDir": "./reports",
    "EnableAllure": true
  }
}

Section 03

Webブラウザ自動化シナリオ記述 (.atx)

ChronoATXは、クラス定義不要のトップレベルステートメントを採用しています。自然で直感的な構文でWeb要素の操作と自動待機・自己修復が行われます。

// 1. 指定URLへ遷移
await Web.GotoAsync(Env["BaseUrl"] + "/login");

// 2. ラベル指定によるテキスト入力（自己修復エンジンが自動探索）
await Web.InputByLabelAsync("ユーザー名", Env["Username"]);
await Web.InputByLabelAsync("パスワード", Env["Password"]);

// 3. ボタンクリック
await Web.ClickButtonAsync("ログイン");

// 4. 表示テキストの自己検証（アサーション）
await Web.VerifyTextAsync("ダッシュボードへようこそ");

Console.WriteLine("✅ ログイン自動検証に成功しました");

Section 04

デスクトップOS認証・ウィンドウ制御 (Desktop Engine)

ブラウザテスト中に表示されるWindows/macOSのOSダイアログや証明書ポップアップも、同一シナリオ内でシームレスにキャッチして制御可能です。

// OS認証ダイアログの出現を検知してアタッチ
var securityDialog = await Desktop.AttachToWindowAsync("Windows セキュリティ");

if (securityDialog != null)
{
    // 暗証番号入力フィールドにPINを注入
    await Desktop.InputByAutomationIdAsync("PinTextBox", "888888", simulateHardware: true);
    
    // 「確定」ボタンを押下してダイアログを閉じる
    await Desktop.ClickWindowButtonAsync("確定");
}

// 再びWebブラウザに戻り、認証後画面を検証
await Web.VerifyTextVisibleAsync("電子署名が完了しました");

Section 05

モバイル（iOS / Android）自動テスト環境の構築

ChronoATX Mobile エンジンは業界標準の Appium 2.x と通信し、実機およびエミュレータ・シミュレータのネイティブアプリをWebやデスクトップと同じ記述でテストします。

必要環境の準備

Node.js 18+ 及び Appium 2.x（npm install -g appium）
Android: Android SDK (adb), appium driver install uiautomator2
iOS: Xcode, appium driver install xcuitest, WebDriverAgent (WDA)

モバイル自動テストコード例 (.atx)

// モバイルアプリ起動
await Mobile.LaunchAppAsync("com.example.insurance.app");

// テキスト入力
await Mobile.InputAsync("input_account_number", "ACC-998877");

// スクロールして利用規約を承認
await Mobile.SwipeToTextAsync("利用規約に同意する");
await Mobile.ClickAsync("btn_agree_and_submit");

// トースト通知または結果画面を検証
await Mobile.VerifyElementExistsAsync("view_submit_complete");

Section 06

ChronoRunner CLI コマンド一覧 & CI/CD パイプライン連携

Jenkins、GitHub Actions、GitLab CI などにそのまま組み込んで、夜間回帰テストやプルリクエスト時のスモークテストを完全自動化できます。

CLI 実行コマンド構文

# 単一スクリプトの実行（環境指定）
ChronoRunner --run scripts/login.atx --env SIT

# 回帰テストスイートの全件ヘッドレス実行
ChronoRunner --run-suite suites/regression.suite.json --env UAT --headless

GitHub Actions ワークフロー設定例 (.github/workflows/test.yml)

name: ChronoATX Automated Regression Test
on: [push, pull_request]

jobs:
  e2e-test:
    runs-on: windows-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Run ChronoATX Tests
        run: |
          ./tools/ChronoRunner.exe --run-suite suites/regression.suite.json --env SIT --headless

      - name: Upload Test Reports & Video Artifacts
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: test-reports
          path: reports/