メインコンテンツにスキップ

フレームワーク

WebdriverIOランナーは、Mocha、Jasmine、Cucumber.jsの組み込みサポートを備えています。また、Serenity/JSなどのサードパーティ製のオープンソースフレームワークと統合することもできます。

WebdriverIOとテストフレームワークの統合

WebdriverIOをテストフレームワークと統合するには、NPMで入手できるアダプターパッケージが必要です。アダプターパッケージは、WebdriverIOがインストールされているのと同じ場所にインストールする必要があることに注意してください。したがって、WebdriverIOをグローバルにインストールした場合は、アダプターパッケージもグローバルにインストールしてください。

WebdriverIOをテストフレームワークと統合すると、スペックファイルまたはステップ定義でグローバルなbrowser変数を使用してWebDriverインスタンスにアクセスできます。WebdriverIOはSeleniumセッションのインスタンス化と終了も処理するため、自分でそれを行う必要がないことに注意してください。

Mochaの使用​

まず、NPMからアダプターパッケージをインストールします

npm install @wdio/mocha-framework --save-dev

デフォルトでは、WebdriverIOはすぐに開始できる組み込みのアサーションライブラリを提供します

describe('my awesome website', () => {
    it('should do some assertions', async () => {
        await browser.url('https://webdriverio.dokyumento.jp')
        await expect(browser).toHaveTitle('WebdriverIO · Next-gen browser and mobile automation test framework for Node.js | WebdriverIO')
    })
})

WebdriverIOは、MochaのBDD（デフォルト）、TDD、およびQUnit インターフェースをサポートしています。

TDDスタイルでスペックを作成する場合は、mochaOpts構成のuiプロパティをtddに設定します。これで、テストファイルは次のように記述する必要があります

suite('my awesome website', () => {
    test('should do some assertions', async () => {
        await browser.url('https://webdriverio.dokyumento.jp')
        await expect(browser).toHaveTitle('WebdriverIO · Next-gen browser and mobile automation test framework for Node.js | WebdriverIO')
    })
})

他のMocha固有の設定を定義する場合は、構成ファイルのmochaOptsキーを使用して行うことができます。すべてのオプションのリストは、MochaプロジェクトのWebサイトにあります。

注意: WebdriverIOは、Mochaでの非推奨のdoneコールバックの使用をサポートしていません

it('should test something', (done) => {
    done() // throws "done is not a function"
})

Mochaオプション​

Mocha環境を構成するために、次のオプションをwdio.conf.jsに適用できます。注意: すべてのオプションがサポートされているわけではありません。たとえば、parallelオプションを適用すると、WDIOテストランナーにはテストを並行して実行する独自の方法があるため、エラーが発生します。ただし、次のオプションはサポートされています。

require​

requireオプションは、基本的な機能を追加または拡張する場合に役立ちます（WebdriverIOフレームワークオプション）。

タイプ: string|string[]
デフォルト: []

コンパイラ​

指定されたモジュールを使用してファイルをコンパイルします。コンパイラはrequireの前に含まれます（WebdriverIOフレームワークオプション）。

タイプ: string[]
デフォルト: []

allowUncaught​

キャッチされないエラーを伝播します。

タイプ: boolean
デフォルト: false

bail​

最初のテスト失敗後に中止します。

タイプ: boolean
デフォルト: false

checkLeaks​

グローバル変数リークをチェックします。

タイプ: boolean
デフォルト: false

delay​

ルートスイートの実行を遅延させます。

タイプ: boolean
デフォルト: false

fgrep​

指定された文字列でテストをフィルタリングします。

タイプ: string
デフォルト: null

forbidOnly​

onlyとマークされたテストはスイートを失敗させます。

タイプ: boolean
デフォルト: false

forbidPending​

保留中のテストはスイートを失敗させます。

タイプ: boolean
デフォルト: false

fullTrace​

失敗時の完全なスタックトレース。

タイプ: boolean
デフォルト: false

global​

グローバルスコープで想定される変数。

タイプ: string[]
デフォルト: []

grep​

指定された正規表現でテストをフィルタリングします。

タイプ: RegExp|string
デフォルト: null

invert​

テストフィルターの一致を反転します。

タイプ: boolean
デフォルト: false

retries​

失敗したテストをリトライする回数。

タイプ: number
デフォルト: 0

timeout​

タイムアウトしきい値（ミリ秒単位）。

タイプ: number
デフォルト: 30000

Jasmineの使用​

まず、NPMからアダプターパッケージをインストールします

npm install @wdio/jasmine-framework --save-dev

次に、構成でjasmineOptsプロパティを設定してJasmine環境を構成できます。すべてのオプションのリストは、JasmineプロジェクトのWebサイトにあります。

Jasmineオプション​

次のオプションをwdio.conf.jsに適用して、jasmineOptsプロパティを使用してJasmine環境を構成できます。これらの構成オプションの詳細については、Jasmineドキュメントを確認してください。

defaultTimeoutInterval​

Jasmine操作のデフォルトのタイムアウト間隔。

タイプ: number
デフォルト: 60000

helpers​

Jasmineスペックの前に含めるspec_dirを基準としたファイルパス（およびグロブ）の配列。

タイプ: string[]
デフォルト: []

requires​

requiresオプションは、基本的な機能を追加または拡張する場合に役立ちます。

タイプ: string[]
デフォルト: []

random​

スペックの実行順序をランダム化するかどうか。

タイプ: boolean
デフォルト: true

seed​

ランダム化の基礎として使用するシード。nullの場合、シードは実行開始時にランダムに決定されます。

タイプ: Function
デフォルト: null

failSpecWithNoExpectations​

期待値を実行しなかった場合にスペックを失敗させるかどうか。デフォルトでは、期待値を実行しなかったスペックは合格として報告されます。これをtrueに設定すると、このようなスペックは失敗として報告されます。

タイプ: boolean
デフォルト: false

oneFailurePerSpec​

スペックごとに1つの期待値の失敗のみを発生させるかどうか。

タイプ: boolean
デフォルト: false

specFilter​

スペックをフィルタリングするために使用する関数。

タイプ: Function
デフォルト: (spec) => true

grep​

この文字列または正規表現に一致するテストのみを実行します。（カスタムspecFilter関数が設定されていない場合にのみ適用されます）

型: string|Regexp
デフォルト: null

invertGrep​

trueの場合、一致するテストを反転し、grepで使用された式に一致しないテストのみを実行します。（カスタムspecFilter関数が設定されていない場合にのみ適用されます）

タイプ: boolean
デフォルト: false

Cucumberの使用​

まず、NPMからアダプターパッケージをインストールします

npm install @wdio/cucumber-framework --save-dev

Cucumberを使用したい場合は、設定ファイルにframework: 'cucumber'を追加して、frameworkプロパティをcucumberに設定してください。

Cucumberのオプションは、設定ファイルでcucumberOptsを使用して指定できます。オプションの全リストはこちらをご覧ください。

Cucumberをすぐに使い始めるには、必要なすべてのステップ定義が含まれているcucumber-boilerplateプロジェクトをご覧ください。すぐにフィーチャーファイルを作成できるようになります。

Cucumberのオプション​

wdio.conf.jsで以下のオプションを適用して、cucumberOptsプロパティを使用してCucumber環境を構成できます。

コマンドラインからのオプションの調整

テストをフィルタリングするためのカスタムtagsなどのcucumberOptsは、コマンドラインで指定できます。これは、cucumberOpts.{optionName}="value"形式を使用することで実現できます。

たとえば、@smokeのタグが付いたテストのみを実行したい場合は、次のコマンドを使用できます。

# When you only want to run tests that hold the tag "@smoke"
npx wdio ./wdio.conf.js --cucumberOpts.tags="@smoke"

このコマンドは、cucumberOptsのtagsオプションを@smokeに設定し、このタグを持つテストのみが実行されるようにします。

backtrace​

エラーの完全なバックトレースを表示します。

型: Boolean
デフォルト: true

requireModule​

サポートファイルを必要とする前に、モジュールを必要とします。

タイプ: string[]
デフォルト: []
例

cucumberOpts: {
    requireModule: ['@babel/register']
    // or
    requireModule: [
        [
            '@babel/register',
            {
                rootMode: 'upward',
                ignore: ['node_modules']
            }
        ]
    ]
 }

failFast​

最初の失敗で実行を中止します。

タイプ: boolean
デフォルト: false

name​

式に一致する名前のシナリオのみを実行します（反復可能）。

型: RegExp[]
デフォルト: []

require​

フィーチャーを実行する前に、ステップ定義を含むファイルを必要とします。ステップ定義へのglobを指定することもできます。

タイプ: string[]
デフォルト: [] 例

cucumberOpts: {
    require: [path.join(__dirname, 'step-definitions', 'my-steps.js')]
}

import​

サポートコードがある場所へのパス（ESM用）。

型: String[]
デフォルト: [] 例

cucumberOpts: {
    import: [path.join(__dirname, 'step-definitions', 'my-steps.js')]
}

strict​

未定義または保留中のステップがある場合は失敗します。

タイプ: boolean
デフォルト: false

tags​

式に一致するタグを持つフィーチャーまたはシナリオのみを実行します。詳細については、Cucumberのドキュメントを参照してください。

型: String
デフォルト: ``

timeout​

ステップ定義のタイムアウト（ミリ秒単位）。

型: Number
デフォルト: 30000

retry​

失敗したテストケースを再試行する回数を指定します。

型: Number
デフォルト: 0

retryTagFilter​

式に一致するタグを持つフィーチャーまたはシナリオのみを再試行します（反復可能）。このオプションを使用するには、「--retry」を指定する必要があります。

型: RegExp

language​

フィーチャーファイルのデフォルト言語

型: String
デフォルト: en

order​

定義された/ランダムな順序でテストを実行します。

型: String
デフォルト: defined

format​

使用するフォーマッターの名前と出力ファイルパス。WebdriverIOは、主にファイルに出力を書き込むフォーマッターのみをサポートしています。

タイプ: string[]

formatOptions​

フォーマッターに提供されるオプション

型: object

tagsInTitle​

フィーチャーまたはシナリオ名にCucumberタグを追加します。

型: Boolean
デフォルト: false

これは@wdio/cucumber-framework固有のオプションであり、cucumber-js自体では認識されないことに注意してください。

ignoreUndefinedDefinitions​

未定義の定義を警告として扱います。

型: Boolean
デフォルト: false

これは@wdio/cucumber-framework固有のオプションであり、cucumber-js自体では認識されないことに注意してください。

failAmbiguousDefinitions​

あいまいな定義をエラーとして扱います。

型: Boolean
デフォルト: false

これは@wdio/cucumber-framework固有のオプションであり、cucumber-js自体では認識されないことに注意してください。

tagExpression​

式に一致するタグを持つフィーチャーまたはシナリオのみを実行します。詳細については、Cucumberのドキュメントを参照してください。

型: String
デフォルト: ``

このオプションは将来廃止される予定です。代わりにtags設定プロパティを使用してください。

profile​

使用するプロファイルを指定します。

タイプ: string[]
デフォルト: []

プロファイル内では、特定の値（worldParameters、name、retryTagFilter）のみがサポートされていることに注意してください。これは、cucumberOptsが優先されるためです。さらに、プロファイルを使用する場合は、言及された値がcucumberOpts内で宣言されていないことを確認してください。

Cucumberでのテストのスキップ​

cucumberOptsで利用可能な通常のCucumberテストフィルタリング機能を使用してテストをスキップしたい場合は、capabilitiesで構成されているすべてのブラウザとデバイスに対してスキップすることになります。特定のcapabilitiesの組み合わせでのみシナリオをスキップできるように、必要でない場合はセッションを開始せずに、WebdriverIOはCucumberに次の特定のタグ構文を提供します。

@skip([condition])

ここで、conditionは、すべて一致した場合に、タグ付けされたシナリオまたはフィーチャーをスキップさせるcapabilitiesプロパティとその値のオプションの組み合わせです。もちろん、複数の異なる条件下でテストをスキップするために、シナリオやフィーチャーに複数のタグを追加できます。

また、`tagExpression`を変更せずに'@skip'アノテーションを使用してテストをスキップすることもできます。この場合、スキップされたテストはテストレポートに表示されます。

この構文の例をいくつか示します。

  • @skipまたは@skip()：タグ付けされた項目を常にスキップします。
  • @skip(browserName="chrome")：chromeブラウザに対してテストは実行されません。
  • @skip(browserName="firefox";platformName="linux")：linux実行でfirefoxのテストをスキップします。
  • @skip(browserName=["chrome","firefox"])：タグ付けされた項目は、chromeとfirefoxブラウザの両方でスキップされます。
  • @skip(browserName=/i.*explorer/)：正規表現に一致するブラウザを持つcapabilitiesはスキップされます（iexplorer、internet explorer、internet-explorerなど）。

ステップ定義ヘルパーのインポート​

Given、When、Thenなどのステップ定義ヘルパーやフックを使用するには、@cucumber/cucumberからインポートする必要があります。たとえば、次のようになります。

import { Given, When, Then } from '@cucumber/cucumber'

ここで、WebdriverIOとは関係のない他のタイプのテストですでにCucumberを使用している場合は、特定のバージョンを使用している場合、WebdriverIO Cucumberパッケージからe2eテストにこれらのヘルパーをインポートする必要があります。たとえば、次のようになります。

import { Given, When, Then } from '@wdio/cucumber-framework'

これにより、WebdriverIOフレームワーク内で適切なヘルパーを使用できるようになり、他のタイプのテストに独立したCucumberバージョンを使用できるようになります。

レポートの発行​

Cucumberには、https://reports.cucumber.io/にテスト実行レポートを公開する機能があり、cucumberOptsでpublishフラグを設定するか、CUCUMBER_PUBLISH_TOKEN環境変数を構成することで制御できます。ただし、テスト実行にWebdriverIOを使用する場合、このアプローチには制限があります。各フィーチャーファイルに対して個別にレポートを更新するため、統合されたレポートを表示するのが困難になります。

この制限を克服するために、@wdio/cucumber-framework内にpublishCucumberReportというpromiseベースのメソッドを導入しました。このメソッドは、呼び出すのに最適な場所であるonCompleteフックで呼び出す必要があります。publishCucumberReportには、Cucumberメッセージレポートが保存されているレポートディレクトリの入力が必要です。

cucumber message レポートは、cucumberOpts の format オプションを設定することで生成できます。レポートの上書きを防ぎ、各テスト実行が正確に記録されるように、cucumber message 形式オプション内で動的なファイル名を指定することを強く推奨します。

この機能を使用する前に、以下の環境変数を設定してください。

  • CUCUMBER_PUBLISH_REPORT_URL: Cucumber レポートを公開する URL。指定しない場合は、デフォルトの URL 'https://messages.cucumber.io/api/reports' が使用されます。
  • CUCUMBER_PUBLISH_REPORT_TOKEN: レポートの公開に必要な認証トークン。このトークンが設定されていない場合、この機能はレポートを公開せずに終了します。

以下は、実装に必要な設定とコード例です。

import { v4 as uuidv4 } from 'uuid'
import { publishCucumberReport } from '@wdio/cucumber-framework';

export const config = {
    // ... Other Configuration Options
    cucumberOpts: {
        // ... Cucumber Options Configuration
        format: [
            ['message', `./reports/${uuidv4()}.ndjson`],
            ['json', './reports/test-report.json']
        ]
    },
    async onComplete() {
        await publishCucumberReport('./reports');
    }
}

./reports/ は、cucumber message レポートが保存されるディレクトリであることに注意してください。

Serenity/JS の使用​

Serenity/JS は、複雑なソフトウェアシステムの受け入れテストと回帰テストをより迅速に、より協調的に、そしてより簡単に拡張できるように設計されたオープンソースのフレームワークです。

WebdriverIO テストスイート向けに、Serenity/JS は以下を提供します。

Serenity BDD Report Example

Serenity/JS のインストール​

既存の WebdriverIO プロジェクトに Serenity/JS を追加するには、NPM から次の Serenity/JS モジュールをインストールします。

npm install @serenity-js/{core,web,webdriverio,assertions,console-reporter,serenity-bdd} --save-dev

Serenity/JS モジュールの詳細

Serenity/JS の設定​

Serenity/JS との統合を有効にするには、WebdriverIO を次のように設定します。

wdio.conf.ts
import { WebdriverIOConfig } from '@serenity-js/webdriverio';

export const config: WebdriverIOConfig = {

    // Tell WebdriverIO to use Serenity/JS framework
    framework: '@serenity-js/webdriverio',

    // Serenity/JS configuration
    serenity: {
        // Configure Serenity/JS to use the appropriate adapter for your test runner
        runner: 'cucumber',
        // runner: 'mocha',
        // runner: 'jasmine',

        // Register Serenity/JS reporting services, a.k.a. the "stage crew"
        crew: [
            // Optional, print test execution results to standard output
            '@serenity-js/console-reporter',

            // Optional, produce Serenity BDD reports and living documentation (HTML)
            '@serenity-js/serenity-bdd',
            [ '@serenity-js/core:ArtifactArchiver', { outputDirectory: 'target/site/serenity' } ],

            // Optional, automatically capture screenshots upon interaction failure
            [ '@serenity-js/web:Photographer', { strategy: 'TakePhotosOfFailures' } ],
        ]
    },

    // Configure your Cucumber runner
    cucumberOpts: {
        // see Cucumber configuration options below
    },


    // ... or Jasmine runner
    jasmineOpts: {
        // see Jasmine configuration options below
    },

    // ... or Mocha runner
    mochaOpts: {
        // see Mocha configuration options below
    },

    runner: 'local',

    // Any other WebdriverIO configuration
};

詳細はこちらをご覧ください。

Serenity BDD レポートと生きたドキュメントの生成​

Serenity BDD レポートと生きたドキュメントは、Serenity BDD CLI によって生成されます。これは、@serenity-js/serenity-bdd モジュールによってダウンロードおよび管理される Java プログラムです。

Serenity BDD レポートを生成するには、テストスイートが次のことを行う必要があります。

  • serenity-bdd update を呼び出して Serenity BDD CLI をダウンロードし、CLI の jar をローカルにキャッシュします。
  • SerenityBDDReporter を 設定手順に従って登録することで、中間 Serenity BDD .json レポートを生成します。
  • レポートを生成したいときに、serenity-bdd run を呼び出して Serenity BDD CLI を起動します。

すべての Serenity/JS プロジェクトテンプレートで使用されているパターンは、以下を使用することに依存しています。

  • postinstall NPM スクリプトを使用して Serenity BDD CLI をダウンロードします。
  • テストスイート自体が失敗した場合でも (これは、テストレポートが最も必要な場合です)、レポート処理を実行するためのnpm-failsafe。
  • 前の実行から残ったテストレポートを削除するための便利な方法としてrimraf。
package.json
{
  "scripts": {
    "postinstall": "serenity-bdd update",
    "clean": "rimraf target",
    "test": "failsafe clean test:execute test:report",
    "test:execute": "wdio wdio.conf.ts",
    "test:report": "serenity-bdd run"
  }
}

SerenityBDDReporter の詳細については、以下を参照してください。

Serenity/JS Screenplay パターン API の使用​

Screenplay パターンは、高品質な自動受け入れテストを作成するための革新的でユーザー中心のアプローチです。これにより、抽象化レイヤーの効果的な使用が促進され、テストシナリオがドメインのビジネス用語を捉えるのに役立ち、チームの優れたテストとソフトウェアエンジニアリングの習慣が奨励されます。

デフォルトでは、WebdriverIO の framework として @serenity-js/webdriverio を登録すると、Serenity/JS は 役者のキャストを設定します。ここで、各役者は

これは、既存のテストスイートにも Screenplay パターンに従うテストシナリオを導入するのに十分役立つはずです。たとえば、

specs/example.spec.ts
import { actorCalled } from '@serenity-js/core'
import { Navigate, Page } from '@serenity-js/web'
import { Ensure, equals } from '@serenity-js/assertions'

describe('My awesome website', () => {
    it('can have test scenarios that follow the Screenplay Pattern', async () => {
        await actorCalled('Alice').attemptsTo(
            Navigate.to(`https://webdriverio.dokyumento.jp`),
            Ensure.that(
                Page.current().title(),
                equals(`WebdriverIO · Next-gen browser and mobile automation test framework for Node.js | WebdriverIO`)
            ),
        )
    })

    it('can have non-Screenplay scenarios too', async () => {
        await browser.url('https://webdriverio.dokyumento.jp')
        await expect(browser)
            .toHaveTitle('WebdriverIO · Next-gen browser and mobile automation test framework for Node.js | WebdriverIO')
    })
})

Screenplay パターンの詳細については、以下を参照してください。

ようこそ！何かお手伝いできることはありますか？

WebdriverIO AI Copilot