【逆引きTIPS】CI/CDパイプラインでのT-Plan Robot ヘッドレス実行設定（CLI運用）

非侵入型（画像認識ベース）のテスト自動化ツールである T-Plan Robot は、GUIを開かずにコマンドライン（CLI）から実行する「ヘッドレスモード」に対応しています。

本記事では、Jenkins、GitHub Actions、GitLab CI/CDなどのCI/CDパイプラインにT-Plan Robotを組み込み、夜間ビルドやコードプッシュ時にバックグラウンドで自動テストを走らせるための具体的な設定手順と注意点を解説します。

?️ 1. 基本コマンド（ヘッドレス実行の核）

T-Plan RobotをCUI環境やCI/CDのエージェント上で動かすには、-n（--nodisplay）オプションと -r（--run）オプションを組み合わせるのが基本です。

Windows環境（コマンドプロンプト / PowerShell）

DOS

robot.bat -r "C:\Automation\suites\smoke_test.tpr" -n -o "robot.outputdir=C:\Automation\results"

Linux / Mac環境（Bash）

Bash

./robot.sh -r "./scripts/smoke_test.java" -n -o "robot.outputdir=./results"

? 主要オプション解説

-n, --nodisplay: 最重要パラメータ。 T-Plan RobotのGUI（開発画面）を立ち上げず、ヘッドレスモードで起動します。
-r, --run <file>: 実行するテストスクリプト（.tpr またはコンパイル済みの .java）を指定します。
-o, --option <name=value>: 実行時の一時的な設定変更です。上記例では、テスト結果（レポートやスクリーンショット）の出力先ディレクトリ（robot.outputdir）を動的に指定しています。

? 2. CI/CDパイプラインへの組み込み例 (GitHub Actions)

以下は、Linux環境（Ubuntuランナー）上でT-Plan Robotをヘッドレス実行し、テスト結果をアーティファクトとして保存する一般的なワークフローの定義例（YAML）です。

YAML

name: T-Plan Robot Automated Testing

on:
  push:
    branches: [ "main" ]
  schedule:
    - cron: '0 21 * * 1-5' # 平日毎晩（日本時間AM6:00）に定期実行

jobs:
  tplan-test:
    runs-on: ubuntu-latest

    steps:
      - name: リポジトリのチェックアウト
        uses: actions/checkout@v4

      - name: Java環境のセットアップ (JDK 17)
        uses: actions/setup-java@v4
        with:
          distribution: 'temurin'
          java-version: '17'

      - name: T-Plan Robotのヘッドレス実行
        run: |
          cd /opt/t-plan-robot
          ./robot.sh -r "${{ github.workspace }}/tests/regression.tpr" -n

      - name: テストレポートのアップロード
        if: always() # テストが失敗（Fail）しても必ず実行
        uses: actions/upload-artifact@v4
        with:
          name: tplan-test-results
          path: /opt/t-plan-robot/results/

⚠️ 3. 現場で差が出る「落とし穴」と対策（運用Tips）

① パイプライン（CIツール）は成否をどう判断している？

T-Plan Robotは、テスト結果に応じて独自の「終了コード（Exit Code）」をシステムに返します。CI/CDツールはこのコードを検知して自動で検収（Pass/Fail）を判断します。

終了コード	意味	パイプラインの挙動
0	テスト成功 (Success)	正常終了（次のステップへ）
1	テスト失敗 (Template match fail / Verification fail)	ビルド失敗（警告・停止）
4	スクリプトの構文エラー (Syntax Error)	ビルド失敗（停止）

? Tips: 途中のテストが失敗してもパイプライン全体を強制終了させたくない場合は、CIツール側の設定（GitHub Actionsなら continue-on-error: true）で制御してください。

② Linuxサーバーで「画像認識」を安定させるための工夫

Linuxの完全なCUI環境（X11などのデスクトップ環境がないコンテナやサーバー）で画像認識やVNC/RDP接続を伴うテストを行う際、ごく稀に画面のレンダリング領域が存在しないことで座標ズレやエラーが起きる場合があります。

その場合は、仮想ディスプレイをメモリ上に作成する Xvfb (X virtual framebuffer) を裏で立ち上げ、そこに向けてRobotを実行すると劇的に安定します。

LinuxでのXvfb併用コマンド例:

Bash

# 仮想ディスプレイ :99 を解像度 1920x1080 (24bitカラー) で起動
Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99

# 仮想ディスプレイ環境下でT-Plan Robotを実行
./robot.sh -r "./scripts/smoke_test.tpr" -n

③ 環境ごとの変数（URLや認証情報）を外部から注入する

「開発環境」「ステージング環境」でテスト対象のURLやアカウントを切り替えたい場合、スクリプトを書き換える必要はありません。-v オプションを使って、CI/CDの環境変数（Secrets）を安全に注入できます。

Bash

./robot.sh -r "test.tpr" -n -v "TARGET_URL=https://stg.example.com" -v "LOGIN_ID=${{ secrets.TEST_USER_ID }}"

※スクリプト内では {TARGET_URL} や {LOGIN_ID} のように変数として呼び出すことで、動的なテストが可能です。

? 4. 公式リファレンス

さらに詳しいコマンドラインのオプションや詳細仕様については、以下の公式ドキュメントを参照してください。

執筆・編集： 株式会社チャネルブリッジ T-Plan Robotチーム

その他のTIPSも下記よりご覧ください。