SauceLabs および saucectl のレポート

SauceLabs とは

SauceLabs は、 クラウドベースのテストプラットフォーム であり、 何百ものブラウザー、オペレーティングシステム、デバイス上でウェブテストやモバイルテストを実行でき、ハードウェアを自分でセットアップしたりメンテナンスしたりする必要がありません。

SauceLabs は、以下のことが可能な巨大な仮想ラボのようなものです。

- 手動テストの担当者は、実際のブラウザーやデバイスとリモートで対話できます。
- 自動化エンジニアは、一度に多くの環境で並行してテストスクリプトを実行できます。
- QA マネージャーは、すべてのテストの詳細な実行履歴、スクリーンショット、動画を確認できます。

SauceLabs はクラウドで稼働しているため、以下のことが可能です:

- 時間の節約 (ローカル環境のセットアップが不要)
- より多くの組み合わせをより短時間でテスト (並列実行)
- マシンに関係なく、一貫したテスト結果を得られる

`saucectl`とは

saucectl はSauceLabs の コマンドラインインターフェイスです。ターミナルで実行し、ローカルテストフレームワーク (Cypress、Playwright、TestCafeなど) を SauceLabs のクラウドインフラストラクチャに接続するツールです。

saucectlを使用すると、以下のことが可能です:

- コマンドラインまたは CI/CD パイプラインからクラウド上のテストを直接トリガーする
- 異なるブラウザーやデバイスでテストを並行して実行する
- 詳細なテスト結果を JUnit XML フォーマットで収集する
- 有用なメタデータを付加する (ブラウザー、OS、SauceLabs セッションURL など)

SauceLabs と TestRail の統合の利点

SauceLabs で自動テストを実行しているなら、ブラウザー、プラットフォーム、実行時間、SauceLabs セッションへの直接リンクなどの詳細な結果をすでに取得できています。
テストケースの管理と結果の追跡に TestRail を使用している場合、 SauceLabs のレポートを TestRail に直接インポートして、手動テストと自動テストの結果を 1 か所にまとめることができます。

この統合により、以下のことが可能になります:

- SauceLabs から TestRail への結果のインポートを自動化する
- テストケースが存在しない場合、自動的にテストケースを作成する
- ブラウザ／プラットフォーム別にランを整理する
- SauceLabs セッションに直接リンク し、より深いデバッグを可能にする

TestRail への結果の統合

統合の仕組み

概要としては、次のように動作します。SauceLabs が自動テストを実行 → 結果ファイルを作成 → TestRail がその結果をインポートして整理します。

次に、順を追って詳細を説明します。

1. SauceLabs でテストが実行されます
  saucectlを使用して自動テストを開始します。
  - 非技術的な説明: これは、SauceLabs のクラウドラボにテストを送信するツールに過ぎません。
  - 技術的な説明: saucectl は、テストスクリプトを SauceLabs にアップロードし、選択したブラウザー/デバイスで並列にトリガーし、結果を収集します。
2. SauceLabs が JUnit XML レポートを生成します
  テストが終了すると、SauceLabsは JUnit XML ファイルを生成します。
  - このファイルは、自動テスト結果の構造化されたスプレッドシートのようなものです。
  - 以下の内容が含まれます:
    - どのテストが実行されたか
    - 成功/失敗ステータス
    - ブラウザーおよび OS 情報
    - SauceLabs テストセッションへの直接リンク
3. TestRail CLI がレポートを解析します
  --special-parser saucectl オプションを指定してTestRail CLI コマンドを実行します。
  - これは TestRail に SauceLabs 固有のパーサーを使用するように指示します。このパーサーは SauceLabs の JUnit レポートの固有のセッション情報を理解します。
  - このフラグがないと、CLI はマルチブラウザーの結果を誤って解釈する可能性があります。
4. 結果が TestRail にインポートされます
  CLI は解析された結果を TestRail プロジェクトに送信します。
  - 各ブラウザー + プラットフォームの組み合わせが個別の TestRail テストランになります (たとえば、「Chrome 106 – Windows 11」および「Firefox 108 – Windows 11」)。
  - テストケースが TestRail にまだ存在しない場合は、自動的に作成されます。
  - ブラウザー/OS 情報はテストランの説明に設定されます。
  - SauceLabs セッション URL は、各テスト結果に直接リンクされており、素早くアクセスできます。

簡単な視覚的フロー

1. テストの実行 → saucectl run
2. レポートの生成 → results.xml (SauceLabs 固有の情報を含む JUnit フォーマット)
3. 結果のインポート → trcli parse_junit --special-parser saucectl results.xml
4. TestRail で表示 → ブラウザ/プラットフォームごとにグループ化されたラン、SauceLabs への直接リンク付き

※すぐに使い始められるサンプルコードが必要な場合は、GitHub 上の Cypress-saucectl サンプルプロジェクトを参照してください。

SauceLabs の結果と TestRail のエントリの対応

--special-parser saucectl オプションを使用してSauceLabs JUnit XML レポートを TestRail にインポートすると、レポートの各部分は特定の TestRail エンティティに変換されます。
これにより、テストケースの重複作成を回避しながら、 実行のコンテキスト (ブラウザー、OS、セッションリンク) を維持できます。

1.ブラウザーおよびプラットフォーム → 個別の TestRail テストラン

- JUnit XML では、<testsuite name> に ブラウザー名およびテストスクリプトファイル名が含まれることがよくあります。
- 各 testsuite の <properties> ブロックには以下が含まれます:
  - browser → 例えば chrome 106 や firefox 108 など
  - platform → 例えば Windows 11 など
- TestRail では以下のようになります:
  - ユニークな ブラウザー + プラットフォームの組み合わせが個別のテストランになります。
  - ブラウザーおよびプラットフォームがテストランのタイトルに追加されます (例: Cross-browser automated tests (Chrome 106 - Windows 11))。

2.テスト名 → TestRail テストケース

- XMLでは、各 <testcase name="..."> が特定の自動テストを表しています。
- TestRail では以下のようになります:
  - 同じ名前のテストケースがすでにプロジェクトに存在する場合、TestRail はそのテストケースを新しい結果で更新します。
  - 存在しない場合は、TestRail が自動的にテストケースを作成します。
  - 同じテストが複数のブラウザーで実行される場合、 1 つのテストケース だけが作成され、それぞれのテストランで固有の結果を持ちます。

3.SauceLabs のセッション URL → TestRail 結果のリンク

- XMLの <property name="url"> には、SauceLabs のテストセッションへの直接リンクが含まれています。
- TestRail では以下のようになります:
  - この URL は、対応するテストケースの結果詳細の中に保存されます。
  - クリックすると SauceLabs に直接ジャンプし、動画記録、スクリーンショット、ログ、詳細な実行データを参照できます。

4.失敗およびエラー → TestRail での結果メモ

- XMLでは、<testcase> 要素に <failure> 要素が含まれます:
  - type → 失敗の種類 (「要素が見つかりません」など)
  - message →簡単な説明
  - インナーテキスト → スタックトレースまたはデバッグ情報
- TestRail では以下のようになります:
  - この情報は結果コメントに追加され、テストが失敗した理由に関して即座にコンテキスト情報を得られます。

5.同じセッションで複数のテスト → 共有セッションリンク

- 同じ SauceLabs セッション内で複数の <testcase> エントリが実行されることがあります。
- TestRail では以下のようになります:
  - 関連するすべてのテスト結果は、結果の詳細で同じセッションURL を持ちます。
  - これは、セッションが複数の小さな検証ステップにわたる場合に便利です。

対応の例

JUnit XML 要素	値の例	TestRail のフィールド
`<testsuite name>`	`Firefox - test_suite_1.cy.js`	テストランのタイトル＋括弧で囲まれたブラウザー/プラットフォーム
`<property name="browser">`	`firefox 108`	テストランの説明
`<property name="platform">`	`Windows 11`	テストランの説明
`<testcase name>`	`Component 1 Verify page structure`	テストケースのタイトル
`<property name="url">`	`https://app.saucelabs.com/tests/7d75...`	結果の詳細 (SauceLabs セッションへのクリック可能なリンク)
`<failure type>` + メッセージ + スタック	`element not found` + `Fail due to...` + スタックトレース…	結果コメント

SauceLabs の JUnit XML スニペットの例

<testsuites tests="8">
  <testsuite name="Firefox - test_suite_1.cy.js" tests="1" time="48">
    <properties>
      <property name="url" value="https://app.saucelabs.com/tests/7d7544f09a47428fb97ee53d1a5b1419"/>
      <property name="browser" value="firefox 108"/>
      <property name="platform" value="Windows 11"/>
    </properties>
    <testcase name="Component 1 Verify page structure" time="0.9450" classname="Verify page structure"/>
  </testsuite>
  <testsuite name="Firefox - test_suite_2.cy.js" tests="1" time="80">
    <properties>
      <property name="url" value="https://app.saucelabs.com/tests/cbb864e049c645e1a96d56e953fe33f0"/>
      <property name="browser" value="firefox 108"/>
      <property name="platform" value="Windows 11"/>
    </properties>
    <testcase name="Component 2 Verify page structure" time="0.9670" classname="Verify page structure"/>
  </testsuite>
  <testsuite name="Chrome - test_suite_1.cy.js" tests="1" time="65">
    <properties>
      <property name="url" value="https://app.saucelabs.com/tests/349cf779c0f94e649f7ea6ccc42e1753"/>
      <property name="browser" value="chrome 106"/>
      <property name="platform" value="Windows 11"/>
    </properties>
    <testcase name="Component 1 Verify page structure" time="0.7500" classname="Verify page structure">
      <failure type="element not found" message="Fail due to...">stacktrace...</failure>
    </testcase>
  </testsuite>
  <testsuite name="Chrome - test_suite_2.cy.js" tests="1" time="33">
    <properties>
      <property name="url" value="https://app.saucelabs.com/tests/c0e3ddae1e104b86b940ed7e8026ff83"/>
      <property name="browser" value="chrome 106"/>
      <property name="platform" value="Windows 11"/>
    </properties>
    <testcase name="Component 2 Verify page structure" 
    time="0.7570" classname="Verify page structure"/>
  </testsuite>
</testsuites>

このレポートは、Firefox と Chrome の 2 つのデバイスでの 1 つのプロジェクトの実行を含んでおり、次の画像のとおり、testsuite 要素名で識別できます。つまり、TestRail CLI は TestRail に 2 つのテストランを作成し、それぞれのテスト結果を追加します。各テストランには、Component 2 Verify page structure および Component 1 Verify page structure という同じテストが含まれています。

また、TestRail は、各テストランの説明に browser および platform の値を追加し、セッションの url を各テストケースの結果に追加します。

SauceLabs レポートをインポートする CLI コマンド

ターミナルから以下のコマンドを実行します:

$ trcli -y \
>  -h https://INSERT-INSTANCE-NAME.testrail.io \
>  --project "My Project" \
>  --username INSERT-EMAIL \
>  --password INSERT-PASSWORD \
>  parse_junit \
>  --title "Cross-browser automated tests" \
>  --special-parser "saucectl" \
>  -f "./saucelabs-report.xml"

パラメーターの説明

- <INSTANCE-NAME> → TestRail インスタンスのサブドメイン
- <EMAIL> / <PASSWORD> → TestRail のログイン認証情報
- "My Project" → TestRail のプロジェクト名
- "Cross-browser automated tests" → テストランのタイトル
- "./saucelabs-report.xml" → SauceLabs の JUnit レポートへのパス

TestRail でのインポート後の処理

- テストケースが存在しない場合は、新しいテストケースが作成されます。

- テスト実行はブラウザー/プラットフォームごとにグループ化 されます。
  - Cross-browser automated tests (Chrome)
  - Cross-browser automated tests (Firefox)

- テストランの説明にはプラットフォームとブラウザーが含まれます。
- テストケースの結果 には、すばやく移動できるよう SauceLabs セッション URL が含まれています。

ヒントとトラブルシューティング

- SauceLabs が JUnit レポート (saucectl 設定内の--reporter junit) をエクスポートしていることを確認します。
- 複数のテストケースが同じ SauceLabs セッションで実行されると、TestRail で同じセッション URL を共有します。
- テストが重複しているように見える場合は、<testcase name> の値が一意であることを確認してください。
- 大規模なテストの場合、XML ファイルをブラウザーごとに分割すると、インポート速度が向上する可能性があります。

次のステップ

- GitHub の Cypress-saucectl サンプルプロジェクトで実践的な例を確認します。
- その他のパラメータについては、TestRail CLI のマニュアルを参照してください。
- チームの GitHub や TestRail のサポートを通じて、改善の提案や質問を行います。

SauceLabs とは

saucectlとは

SauceLabs と TestRail の統合の利点

TestRail への結果の統合

統合の仕組み

簡単な視覚的フロー

SauceLabs の結果と TestRail のエントリの対応

1.ブラウザーおよびプラットフォーム → 個別の TestRail テスト ラン

2.テスト名 → TestRail テスト ケース

3.SauceLabs のセッション URL → TestRail 結果のリンク

4.失敗およびエラー → TestRail での結果メモ

5.同じセッションで複数のテスト → 共有セッション リンク

対応の例

SauceLabs の JUnit XML スニペットの例

SauceLabs レポートをインポートする CLI コマンド

TestRail でのインポート後の処理

ヒントとトラブルシューティング

次のステップ

目次

`saucectl`とは

1.ブラウザーおよびプラットフォーム → 個別の TestRail テストラン

2.テスト名 → TestRail テストケース

5.同じセッションで複数のテスト → 共有セッションリンク