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

型

オブジェクト
- timeout number (オプション)
  
  非同期のexpectマッチャーのデフォルトのタイムアウト（ミリ秒単位）。デフォルトは5000msです。
- toHaveScreenshot オブジェクト (オプション)
  - 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 オブジェクト (オプション)
  - pathTemplate string (オプション)
    
    ARIAスナップショットの保存場所を制御するテンプレートです。詳細については、testProject.snapshotPathTemplateを参照してください。
  expect(locator).toMatchAriaSnapshot()メソッドの設定です。
- toMatchSnapshot オブジェクト (オプション)
  - threshold number (オプション)
    
    比較画像内の同じピクセル間の許容される知覚色差で、`0` (厳密) から `1` (緩やか) の範囲です。`"pixelmatch"` コンパレータはYIQ色空間で色差を計算し、`threshold` のデフォルト値は`0.2`です。
  - maxDiffPixels number (オプション)
    
    許容できる異なるピクセル数。デフォルトでは設定されていません。
  - maxDiffPixelRatio number (オプション)
    
    異なるピクセルが総ピクセル数に対して許容できる比率（`0`から`1`の間）。デフォルトでは設定されていません。
  expect(value).toMatchSnapshot()メソッドの設定です。
- toPass オブジェクト (オプション)
  - timeout number (オプション)
    
    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 （`snapshotDir`が設定で提供されていないため、デフォルトで`testDir`になります）
{testDir} - プロジェクトのtestProject.testDir。
- 値: /home/playwright/tests （`testDir`は設定ファイルがあるディレクトリからの相対パスで解決されるため、絶対パスです）
{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