TestProject

Playwright Testは、複数のテストプロジェクトを同時に実行することをサポートしています。これは、複数の構成でテストを実行する場合に役立ちます。たとえば、複数のブラウザに対してテストを実行することを考えてみましょう。このタイプは、構成ファイル内のプロジェクトの形式を記述するもので、実行時に解決された構成パラメータにアクセスするには、FullProjectを使用します。

TestProjectは、単一のプロジェクトに固有の構成をカプセル化します。プロジェクトは、構成ファイルで指定されたtestConfig.projectsで構成されます。TestProjectのすべてのプロパティは、トップレベルのTestConfigで利用でき、その場合はすべてのプロジェクト間で共有されます。

以下は、Chromium、Firefox、WebKitで、デスクトップ版とモバイル版の両方で各テストを実行する構成例です。

playwright.config.ts
import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  // Options shared for all projects.
  timeout: 30000,
  use: {
    ignoreHTTPSErrors: true,
  },

  // Options specific to each project.
  projects: [
    {
      name: 'chromium',
      use: devices['Desktop Chrome'],
    },
    {
      name: 'firefox',
      use: devices['Desktop Firefox'],
    },
    {
      name: 'webkit',
      use: devices['Desktop Safari'],
    },
    {
      name: 'Mobile Chrome',
      use: devices['Pixel 5'],
    },
    {
      name: 'Mobile Safari',
      use: devices['iPhone 12'],
    },
  ],
});

プロパティ

dependencies

追加バージョン: v1.31

testProject.dependencies

このプロジェクト内のテストを実行する前に実行する必要があるプロジェクトのリスト。依存関係は、すべての処理がテストの形式になるようにグローバルなセットアップ処理を構成する場合に役立ちます。--no-deps引数を渡すと、依存関係は無視され、指定されていないかのように動作します。

依存関係を使用すると、グローバルセットアップでトレースやその他の成果物を生成したり、テストレポートでセットアップステップを確認したりすることができます。

使用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'setup',
      testMatch: /global.setup\.ts/,
    },
    {
      name: 'chromium',
      use: devices['Desktop Chrome'],
      dependencies: ['setup'],
    },
    {
      name: 'firefox',
      use: devices['Desktop Firefox'],
      dependencies: ['setup'],
    },
    {
      name: 'webkit',
      use: devices['Desktop Safari'],
      dependencies: ['setup'],
    },
  ],
});

タイプ

Array<string>

expect

追加バージョン: v1.10

testProject.expect

expectアサーションライブラリの構成。

すべてのプロジェクトでこのオプションを変更するには、testConfig.expectを使用します。

使用法

testProject.expect

タイプ

Object
- timeout number (optional)
  
  非同期expectマッチャーのデフォルトのタイムアウトはミリ秒単位で、デフォルトは5000msです。
- toHaveScreenshot Object (オプション)
  - threshold number (オプション)
    
    比較された画像内の同じピクセル間の許容可能な知覚色差で、0 (厳密) から 1 (緩やか) の範囲です。"pixelmatch"コンパレータは、YIQ色空間で色差を計算し、threshold値はデフォルトで0.2になります。
  - maxDiffPixels number (オプション)
    
    許容できる異なるピクセル数。デフォルトでは設定されていません。
  - maxDiffPixelRatio number (オプション)
    
    異なるピクセルの総ピクセル数に対する許容可能な比率で、0から1の間。デフォルトでは設定されていません。
  - animations "allow" | "disabled" (オプション)
    
    page.screenshot()のanimationsを参照してください。デフォルトは"disabled"です。
  - caret "hide" | "initial" (オプション)
    
    page.screenshot()のcaretを参照してください。デフォルトは"hide"です。
  - scale "css" | "device" (オプション)
    
    page.screenshot()のscaleを参照してください。デフォルトは"css"です。
  - stylePath string | Array<string> (オプション)
    
    page.screenshot()のstyleを参照してください。
  - pathTemplate string (オプション)
    
    スクリーンショットの場所を制御するテンプレート。testProject.snapshotPathTemplateで詳細を参照してください。
  expect(page).toHaveScreenshot()メソッドの構成。
- toMatchAriaSnapshot Object (オプション)
  - pathTemplate string (オプション)
    
    ariaスナップショットの場所を制御するテンプレート。testProject.snapshotPathTemplateで詳細を参照してください。
  expect(locator).toMatchAriaSnapshot()メソッドの構成。
- toMatchSnapshot Object (オプション)
  - threshold number (オプション)
    
    比較された画像内の同じピクセル間の許容可能な知覚色差で、0 (厳密) から 1 (緩やか) の範囲です。"pixelmatch"コンパレータは、YIQ色空間で色差を計算し、threshold値はデフォルトで0.2になります。
  - maxDiffPixels number (オプション)
    
    許容できる異なるピクセル数。デフォルトでは設定されていません。
  - maxDiffPixelRatio number (オプション)
    
    異なるピクセルの総ピクセル数に対する許容可能な比率で、0から1の間。デフォルトでは設定されていません。
  expect(value).toMatchSnapshot()メソッドの構成。
- toPass Object (オプション)
  - timeout number (optional)
    
    toPassメソッドのタイムアウト（ミリ秒単位）。
  - intervals Array<number> (オプション)
    
    toPassメソッドのプローブ間隔（ミリ秒単位）。
  expect(value).toPass()メソッドの構成。

fullyParallel

追加バージョン: v1.10

testProject.fullyParallel

Playwright Test はテストを並行して実行します。これを実現するために、同時に動作する複数のワーカープロセスを実行します。デフォルトでは、テストファイルが並列で実行されます。単一ファイル内のテストは、同じワーカープロセス内で順次実行されます。

このオプションを使用して、テストプロジェクト全体を構成し、すべてのファイル内のすべてのテストを並行して実行できます。

使用法

testProject.fullyParallel

タイプ

boolean

grep

追加バージョン: v1.10

testProject.grep

指定されたパターンのいずれかに一致するタイトルを持つテストのみを実行するフィルター。たとえば、grep: /cart/を渡すと、「cart」がタイトルに含まれるテストのみが実行されます。グローバルにも、-gオプションでコマンドラインでも利用できます。正規表現は、プロジェクト名、テストファイル名、test.describe名（もしあれば）、テスト名、テストタグをスペースで区切った文字列（例: chromium my-test.spec.ts my-suite my-test）に対してテストされます。

grepオプションは、テストにタグを付けるのにも役立ちます。

使用法

testProject.grep

タイプ

RegExp | Array<RegExp>

grepInvert

追加バージョン: v1.10

testProject.grepInvert

指定されたパターンのいずれにも一致しないタイトルを持つテストのみを実行するフィルター。これはtestProject.grepの逆です。グローバルにも、--grep-invertオプションでコマンドラインでも利用できます。

grepInvertオプションは、テストにタグを付けるのにも役立ちます。

使用法

testProject.grepInvert

タイプ

RegExp | Array<RegExp>

ignoreSnapshots

追加バージョン: v1.44

testProject.ignoreSnapshots

expect(value).toMatchSnapshot()やawait expect(page).toHaveScreenshot()などのスナップショットアサーションをスキップするかどうか。

使用法

以下の例では、Chromiumでのみスクリーンショットアサーションを実行します。

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'chromium',
      use: devices['Desktop Chrome'],
    },
    {
      name: 'firefox',
      use: devices['Desktop Firefox'],
      ignoreSnapshots: true,
    },
    {
      name: 'webkit',
      use: devices['Desktop Safari'],
      ignoreSnapshots: true,
    },
  ],
});

タイプ

boolean

metadata

追加バージョン: v1.10

testProject.metadata

テストレポートにJSONとしてシリアライズされるメタデータ。

使用法

testProject.metadata

タイプ

メタデータ

name

追加バージョン: v1.10

testProject.name

プロジェクト名は、レポートおよびテスト実行中に表示されます。

警告

Playwrightは構成ファイルを複数回実行します。構成で動的に不安定な値を生成しないでください。

使用法

testProject.name

タイプ

string

outputDir

追加バージョン: v1.10

testProject.outputDir

テスト実行中に作成されたファイルの出力ディレクトリ。デフォルトは<package.json-directory>/test-resultsです。

このディレクトリは開始時にクリーンアップされます。テストを実行すると、testProject.outputDir内に一意のサブディレクトリが作成され、並行して実行されるテストが競合しないことが保証されます。このディレクトリは、testInfo.outputDirとtestInfo.outputPath()でアクセスできます。

以下は、testInfo.outputPath()を使用して一時ファイルを作成する例です。

import { test, expect } from '@playwright/test';
import fs from 'fs';

test('example test', async ({}, testInfo) => {
  const file = testInfo.outputPath('temporary-file.txt');
  await fs.promises.writeFile(file, 'Put some data to the file', 'utf8');
});

すべてのプロジェクトでこのオプションを変更するには、testConfig.outputDirを使用します。

使用法

testProject.outputDir

タイプ

string

repeatEach

追加バージョン: v1.10

testProject.repeatEach

各テストを繰り返す回数。不安定なテストのデバッグに役立ちます。

すべてのプロジェクトでこのオプションを変更するには、testConfig.repeatEachを使用します。

使用法

testProject.repeatEach

タイプ

number

respectGitIgnore

追加されたバージョン: v1.45

testProject.respectGitIgnore

テストファイルの検索時に.gitignoreのエントリをスキップするかどうか。デフォルトでは、testConfig.testDirもtestProject.testDirも明示的に指定されていない場合、Playwrightは.gitignoreエントリに一致するテストファイルをすべて無視します。このオプションを使用すると、その動作を上書きできます。

使用法

testProject.respectGitIgnore

タイプ

boolean

retries

追加バージョン: v1.10

testProject.retries

失敗したテストに与えられる最大再試行回数。テストの再試行の詳細については、こちらを参照してください。

特定のファイルまたはテストのグループの再試行回数を変更するには、test.describe.configure()を使用します。

すべてのプロジェクトでこのオプションを変更するには、testConfig.retriesを使用します。

使用法

testProject.retries

タイプ

number

snapshotDir

追加バージョン: v1.10

testProject.snapshotDir

toMatchSnapshotで作成されたスナップショットファイルの、設定ファイルに対するベースディレクトリ。デフォルトはtestProject.testDirです。

各テストのディレクトリは、testInfo.snapshotDirとtestInfo.snapshotPath()でアクセスできます。

このパスは、各テストファイルのスナップショットディレクトリのベースディレクトリとして機能します。snapshotDirを'snapshots'に設定すると、testInfo.snapshotDirはsnapshots/a.spec.js-snapshotsに解決されます。

使用法

testProject.snapshotDir

タイプ

string

snapshotPathTemplate

追加バージョン: v1.28

testProject.snapshotPathTemplate

このオプションは、expect(page).toHaveScreenshot()、expect(locator).toMatchAriaSnapshot()、expect(value).toMatchSnapshot()によって生成されるスナップショットの場所を制御するテンプレートを構成します。

testConfig.expectで、各アサーションのテンプレートを個別に構成できます。

使用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  testDir: './tests',

  // Single template for all assertions
  snapshotPathTemplate: '{testDir}/__screenshots__/{testFilePath}/{arg}{ext}',

  // Assertion-specific templates
  expect: {
    toHaveScreenshot: {
      pathTemplate: '{testDir}/__screenshots__{/projectName}/{testFilePath}/{arg}{ext}',
    },
    toMatchAriaSnapshot: {
      pathTemplate: '{testDir}/__snapshots__/{testFilePath}/{arg}{ext}',
    },
  },
});

タイプ

string

詳細

値には、テスト実行中に実際の値に置き換えられるいくつかの「トークン」を含めることができます。

次のファイル構造を考慮してください

playwright.config.ts
tests/
└── page/
    └── page-click.spec.ts

そして、toHaveScreenshot()呼び出しを使用する次のpage-click.spec.ts

page-click.spec.ts
import { test, expect } from '@playwright/test';

test.describe('suite', () => {
  test('test should work', async ({ page }) => {
    await expect(page).toHaveScreenshot(['foo', 'bar', 'baz.png']);
  });
});

サポートされているトークンのリスト

{arg} - 拡張子なしの相対スナップショットパス。これはtoHaveScreenshot()、toMatchAriaSnapshot()、またはtoMatchSnapshot()に渡される引数から取得されます。引数なしで呼び出された場合、これは自動生成されたスナップショット名になります。
- 値: foo/bar/baz
{ext} - スナップショット拡張子（先頭のドットを含む）。
- 値: .png
{platform} - process.platformの値。
{projectName} - プロジェクトのファイルシステムでサニタイズされた名前（もしあれば）。
- 値: '' (空文字列)。
{snapshotDir} - プロジェクトのtestProject.snapshotDir。
- 値: /home/playwright/tests (configでsnapshotDirが提供されていないため、デフォルトでtestDirになります)
{testDir} - プロジェクトのtestProject.testDir。
- 値: /home/playwright/tests (configのあるディレクトリに対する相対パスとして解決されるため、絶対パス)
{testFileDir} - testDirからテストファイルへの相対パスのディレクトリ。
- 値: page
{testFileName} - 拡張子付きのテストファイル名。
- 値: page-click.spec.ts
{testFilePath} - testDirからテストファイルへの相対パス。
- 値: page/page-click.spec.ts
{testName} - ファイルシステムでサニタイズされたテストタイトル。親のdescribeは含まれますが、ファイル名は含まれません。
- 値: suite-test-should-work

各トークンは、このトークンが空でない値を持つ場合にのみ使用される単一の文字を前に付けることができます。

次の設定を検討してください

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  snapshotPathTemplate: '__screenshots__{/projectName}/{testFilePath}/{arg}{ext}',
  testMatch: 'example.spec.ts',
  projects: [
    { use: { browserName: 'firefox' } },
    { name: 'chromium', use: { browserName: 'chromium' } },
  ],
});

この設定では

最初のプロジェクトには名前がないため、スナップショットは<configDir>/__screenshots__/example.spec.ts/...に保存されます。
2番目のプロジェクトには名前があるため、スナップショットは<configDir>/__screenshots__/chromium/example.spec.ts/..に保存されます。
snapshotPathTemplateは相対パスに解決されるため、configDirに対する相対パスとして解決されます。
フォワードスラッシュ"/"は、どのプラットフォームでもパスセパレータとして使用できます。

teardown

追加バージョン: v1.34

testProject.teardown

このプロジェクトとそのすべての依存プロジェクトが終了した後に実行する必要があるプロジェクトの名前。ティアダウンは、このプロジェクトによって取得されたリソースをクリーンアップするのに役立ちます。

--no-deps引数を渡すと、testProject.teardownは無視され、指定されていないかのように動作します。

使用法

一般的なパターンは、対応する「ティアダウン」を持つ「セットアップ」依存関係です。

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'setup',
      testMatch: /global.setup\.ts/,
      teardown: 'teardown',
    },
    {
      name: 'teardown',
      testMatch: /global.teardown\.ts/,
    },
    {
      name: 'chromium',
      use: devices['Desktop Chrome'],
      dependencies: ['setup'],
    },
    {
      name: 'firefox',
      use: devices['Desktop Firefox'],
      dependencies: ['setup'],
    },
    {
      name: 'webkit',
      use: devices['Desktop Safari'],
      dependencies: ['setup'],
    },
  ],
});

タイプ

string

testDir

追加バージョン: v1.10

testProject.testDir

テストファイルを再帰的にスキャンするディレクトリ。デフォルトは構成ファイルのあるディレクトリです。

各プロジェクトは異なるディレクトリを使用できます。以下は、スモークテストを3つのブラウザで実行し、その他すべてのテストを安定版Chromeブラウザで実行する例です。

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'Smoke Chromium',
      testDir: './smoke-tests',
      use: {
        browserName: 'chromium',
      }
    },
    {
      name: 'Smoke WebKit',
      testDir: './smoke-tests',
      use: {
        browserName: 'webkit',
      }
    },
    {
      name: 'Smoke Firefox',
      testDir: './smoke-tests',
      use: {
        browserName: 'firefox',
      }
    },
    {
      name: 'Chrome Stable',
      testDir: './',
      use: {
        browserName: 'chromium',
        channel: 'chrome',
      }
    },
  ],
});

すべてのプロジェクトでこのオプションを変更するには、testConfig.testDirを使用します。

使用法

testProject.testDir

タイプ

string

testIgnore

追加バージョン: v1.10

testProject.testIgnore

これらのパターンのいずれかに一致するファイルは、テストファイルとして実行されません。マッチングは絶対ファイルパスに対して実行されます。文字列はグロブパターンとして扱われます。

たとえば、'**/test-assets/**'は、test-assetsディレクトリ内のすべてのファイルを無視します。

すべてのプロジェクトでこのオプションを変更するには、testConfig.testIgnoreを使用します。

使用法

testProject.testIgnore

タイプ

string | RegExp | Array<string | RegExp>

testMatch

追加バージョン: v1.10

testProject.testMatch

これらのパターンのいずれかに一致するファイルのみがテストファイルとして実行されます。マッチングは絶対ファイルパスに対して実行されます。文字列はグロブパターンとして扱われます。

デフォルトでは、Playwrightは次のグロブパターンに一致するファイルを検索します: **/*.@(spec|test).?(c|m)[jt]s?(x)。これは、".test"または".spec"のサフィックスを持つJavaScriptまたはTypeScriptファイル（例: login-screen.wrong-credentials.spec.ts）を意味します。

すべてのプロジェクトでこのオプションを変更するには、testConfig.testMatchを使用します。

使用法

testProject.testMatch

タイプ

string | RegExp | Array<string | RegExp>

timeout

追加バージョン: v1.10

testProject.timeout

各テストのタイムアウト（ミリ秒単位）。デフォルトは30秒です。

これはすべてのテストの基本タイムアウトです。各テストはtest.setTimeout()で独自のタイムアウトを設定できます。各ファイルまたはテストのグループは、test.describe.configure()でタイムアウトを設定できます。

すべてのプロジェクトでこのオプションを変更するには、testConfig.timeoutを使用します。

使用法

testProject.timeout

タイプ

number

use

追加バージョン: v1.10

testProject.use

このプロジェクト内のすべてのテストのオプション。たとえば、testOptions.browserNameなど。構成の詳細と、利用可能なオプションを参照してください。

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  projects: [
    {
      name: 'Chromium',
      use: {
        browserName: 'chromium',
      },
    },
  ],
});

すべてのプロジェクトでこのオプションを変更するには、testConfig.useを使用します。

使用法

testProject.use

タイプ

TestOptions

workers

追加バージョン: v1.52

testProject.workers

このプロジェクトのテストを並列化するために使用する同時ワーカプロセスの最大数。論理CPUコアのパーセンテージ（例: '50%'）としても設定できます。

これは、たとえば、プロジェクトのすべてのテストがテストアカウントのような単一のリソースを共有し、したがって並行して実行できない場合に役立ちます。そのようなプロジェクトのワーカ数を1に制限すると、共有リソースの同時使用が防止されます。

グローバルなtestConfig.workers制限は、ワーカプロセスの合計数に適用されることに注意してください。ただし、Playwrightは、このプロジェクトに使用されるワーカ数をtestProject.workersの値で制限します。

デフォルトでは、プロジェクトごとの制限はありません。合計ワーカ制限のデフォルトについては、testConfig.workersを参照してください。

使用法

playwright.config.ts
import { defineConfig } from '@playwright/test';

export default defineConfig({
  workers: 10,  // total workers limit

  projects: [
    {
      name: 'runs in parallel',
    },
    {
      name: 'one at a time',
      workers: 1,  // workers limit for this project
    },
  ],
});

タイプ

number | string

プロパティ​

dependencies​

expect​

fullyParallel​

grep​

grepInvert​

ignoreSnapshots​

metadata​

name​

outputDir​

repeatEach​

respectGitIgnore​

retries​

snapshotDir​

snapshotPathTemplate​

teardown​

testDir​

testIgnore​

testMatch​

timeout​

use​

workers​

プロパティ

dependencies

expect

fullyParallel

grep

grepInvert

ignoreSnapshots

metadata

name

outputDir

repeatEach

respectGitIgnore

retries

snapshotDir

snapshotPathTemplate

teardown

testDir

testIgnore

testMatch

timeout

use

workers