WebdriverIO との統合

WebdriverIO は、シンプルなアプローチで Web アプリケーションをテストするための堅牢な自動テストフレームワークです。

このチュートリアルでは、TestRail CLI を使用して、WebdriverIO の自動テスト実行で生成されたテスト結果を TestRail に統合する方法を説明します。統合によって、自動テストの結果を中央で管理し、TestRail が提供するすべての解析およびレポート機能を活用できます。

概要

このチュートリアルでは、サンプルプロジェクトを使用して、TestRail CLI と互換性があるWebdriverIO の自動テストプロジェクトをセットアップし、生成されたテスト結果をアップロードする手順を案内します。

このチュートリアルを通して読むと、以下のことができるようになります。

- 簡単な WebdriverIO プロジェクトからテストを実行する
- TestRail CLI をインストールする
- TestRail インスタンスを設定する
- CLI を実行する
- TestRail でテストケースとテスト結果を確認する

前提条件

WebdriverIO のテストプロジェクトを実行するには、npm または WebdriverIO セットアップガイドに記載されている他のオプションのいずれかを使用してインストールします。このチュートリアルでは npm を使用してインストールします。 WebdriverIO は Node.js によってインストールされるため、まず Node.js をインストールする必要があります。

さらに、テスト結果を TestRail にインポートするために TestRail CLI をインストールして実行するには、Python が必要です。

前提条件	説明
Node.js	OS に合ったバージョンをダウンロードし、インストールウィザードの指示に従います。正常にインストールされたことを確認するには、コマンドラインから次のコマンドを実行します。 `node --version` および `npm --version` すると、インストールされたバージョンが出力されます。
Python 3.x	OS に合ったバージョンをダウンロードし、インストールウィザードの指示に従います。正常にインストールされたことを確認するには、コマンドラインから `python --version` および `pip --version` コマンドを実行します。すると、バージョンが出力されます。

サンプルプロジェクトのインストール

まず、サンプルプロジェクトのコードを取得し、必要な依存ライブラリをインストールします。

1. サンプルプロジェクトをクローンまたはダウンロードします。
2. プロジェクトのルートフォルダーでコマンドプロンプトを開いて次のコマンドを実行します。

npm install

サンプルプロジェクトの確認

任意の IDE を使用してサンプルプロジェクトを開き、テストファイルを確認します。このチュートリアルでは、実行結果のインポート方法に集中できるよう、自動テストのコードはシンプルにしてあります。テストはログインページの簡単な操作で構成されます。

(サンプルフィーチャーファイル）

Feature: The Internet Website Access

  Scenario: As a user, I can log into the secure area

    Given I am on the login page
    When I login with  and 
    Then I should see a flash message saying 

    Examples:
      | username | password             | message                        |
      | tomsmith | SuperSecretPassword! | You logged into a secure area! |

Scenario: As a user, I can't log into the secure area

    Given I am on the login page
    When I login with  and 
    Then I should see a flash message saying 

    Examples:
      | username | password             | message                        |
      | tomsmith | barfoo               | Your password invalid!         |

(ステップ定義のサンプル)

import { Given, When, Then } from '@wdio/cucumber-framework';
import { expect, $ } from '@wdio/globals'

import LoginPage from '../pageobjects/login.page.js';
import SecurePage from '../pageobjects/secure.page.js';

const pages = {
    login: LoginPage
}

Given(/^I am on the (\w+) page$/, async (page) = {
    await pages[page].open()
});

When(/^I login with (\w+) and (.+)$/, async (username, password) = {
    await LoginPage.login(username, password)
});

Then(/^I should see a flash message saying (.*)$/, async (message) = {

    const now = new Date();
    const timestamp = now.toISOString().replace(/[^\w]/g, '-');
    const screenshotName = `screenshots-login-${timestamp}.png`;
    await browser.saveScreenshot(`./results/screenshots/${screenshotName}`);

    await expect(SecurePage.flashAlert).toBeExisting();
    await expect(SecurePage.flashAlert).toHaveText(expect.stringContaining(message));
});

サンプルプロジェクトの実行

同じコマンドプロンプトで次のコマンドを実行し、プロジェクトで WebdriverIO のテストを実行して結果を JUnit XML 形式で保存します。

npx wdio run wdio.conf.js

WebdriverIO コマンドが正常に実行されたら、results フォルダーにテスト結果があるのが確認できます。プロジェクトは 1 つのレポートファイルを生成するよう設定されています。

wdio.conf.js ファイルで指定したとおり、JUnit XML フォーマットのテスト結果を含む webdriverIO-test-results.xml というファイルもあるはずです。次のステップでは、このファイルを TestRail CLI で解析し、テストランを作成してテスト結果を TestRail へアップロードします。

TestRail への結果のインポート

TestRail CLI のインストール

すでにマシンに Python がインストールされている場合、TestRail CLI をインストールするには、コマンドラインで次のコマンドを実行するだけです。

$ pip install trcli

TestRail の設定

次に、下の手順に従って TestRail インスタンスを設定する必要があります。

1. [管理] > [サイト設定] に移動して [API] タブをクリックし、[API の有効化] オプションをオンにして TestRail API を有効化します。
2. 自動テストケースのコードと実際の TestRail のケースをマッピングするためのカスタムフィールドを作成します。それには、[管理] > [カスタマイズ] に移動して [フィールドの追加] をクリックします。フィールド作成画面に移動したら、下記の 2 つの要件に従ってフィールドを作成します。
  - システム名は automation_id
  - [タイプ] は Text にする必要があります。

テストを実行し、JUnit 形式のレポートファイルを生成したら、簡単にテスト結果 (およびテストケース) を TestRail にインポートできます。そうすると、自動テストの実行を可視化し、実際にどのようにアプリケーションがテストされているかに関する概要をすべて TestRail 内で参照できます。

TestRail への結果の送信

TestRail CLI をインストールし、TestRail インスタンスの設定が完了したら、次のコマンドを実行してテスト結果をアップロードできます。

$ trcli -y \
>  -h https://INSERT-INSTANCE-NAME.testrail.io \
>  --project "My Project" \
>  --username INSERT-EMAIL \
>  --password INSERT-PASSWORD \
>  parse_junit \
>  --title "Automation Demo - WebdriverIO" \
>  -f "results/test-results.xml"

デフォルトの場所を変更した場合、-f オプションの後のファイル名がレポートファイルへのパスに一致している必要があります。その他のオプションはすべて TestRail インスタンスおよびプロジェクトに合わせます。他のコマンドラインオプションについては、プロジェクトリポジトリの TestRail CLI README.md ファイルまたは TRCLI のマニュアルページを参照するか、下記のコマンドを実行して CLI の組み込みヘルプを参照します。

$ trcli --help
$ trcli parse_junit --help

TestRail での結果の可視化

TestRail プロジェクトのテストケース ページに移動すると、テスト結果レポートに基づいて、TestRail CLI によってテストケースが自動的に作成されていることがわかるでしょう。

JUnit レポートの classname および name 属性を組み合わせて各テストケースに一意の Automation ID が割り当てられています。この Automation ID により、TestRail CLI は、実行のたびにテストケースを照合できます。同じ Automation ID を持つテストケースがすでに存在する場合、該当テストケースが更新されます。テストケースが存在しない場合は新しいテストケースが作成されます。

テストの名前を変更したり、レポートファイル名を変更したり、場所を移動したりすると、Automation ID が変更され、TestRail の既存のテストケースに正しくマッピングできなくなります。

[テストランと結果] ページでは、Automation Demo – WebdriverIO という名前のテストランが作成されたのを確認できます。テストランを開き、各自動テスト結果の詳細をドリルダウンします。下の図に示すように、テストが失敗したときには、画面ショットなどの添付ファイルとともにテスト自動化フレームワークが出力したエラーメッセージもテスト結果に登録されているため、テストが失敗した理由の高度な解析が可能です。

次のステップ

テスト結果が TestRail に集約されたので、失敗したテストのエラーメッセージも含めて自動テスト実行の結果を確認できるだけでなく、手動テストと自動テストをレポート上で集約し、アプリケーションに関する完全なテストカバレッジを表示したり、テスト自動化プロセスを追跡したりすることも可能です。また、手動テストの結果だけでなく、自動テストの結果から任意の課題トラッカーに直接バグをレポートすることもできます。

TestRail のレポート機能を活用する方法については、TestRail のレポートおよびテストメトリクスの動画を参照してください。

概要

前提条件

サンプル プロジェクトのインストール

サンプル プロジェクトの実行

TestRail への結果のインポート

TestRail CLI のインストール

TestRail の設定

TestRail への結果の送信

TestRail での結果の可視化

次のステップ

目次

サンプルプロジェクトのインストール

サンプルプロジェクトの実行