TestProject

Playwright 測試支援同時執行多個測試專案。這對於在多個配置中執行測試非常有用。例如，考慮針對多個瀏覽器執行測試。此類型描述了組態檔中專案的格式，若要在執行階段存取已解析的組態參數，請使用 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 匹配器的預設逾時時間（以毫秒為單位），預設為 5000 毫秒。
- toHaveScreenshot Object (選用)
  - threshold number (選用)
    
    比較影像中相同像素之間可接受的感知色彩差異，範圍從 0 (嚴格) 到 1 (寬鬆)。"pixelmatch" 比較器計算 YIQ 色彩空間中的色彩差異，預設 threshold 值為 0.2。
  - maxDiffPixels number (選用)
    
    可能不同的可接受像素數量，預設為未設定。
  - maxDiffPixelRatio number (選用)
    
    不同像素與像素總數之間的可接受比率，介於 0 和 1 之間，預設為未設定。
  - animations "allow" | "disabled" (選用)
    
    請參閱 animations（在 page.screenshot() 中）。預設為 "disabled"。
  - caret "hide" | "initial" (選用)
    
    請參閱 caret（在 page.screenshot() 中）。預設為 "hide"。
  - scale "css" | "device" (選用)
    
    請參閱 scale（在 page.screenshot() 中）。預設為 "css"。
  - stylePath string | Array<string> (選用)
    
    請參閱 style（在 page.screenshot() 中）。
  expect(page).toHaveScreenshot() 方法的組態。
- toMatchSnapshot Object (選用)
  - threshold number (選用)
    
    比較影像中相同像素之間可接受的感知色彩差異，範圍從 0 (嚴格) 到 1 (寬鬆)。"pixelmatch" 比較器計算 YIQ 色彩空間中的色彩差異，預設 threshold 值為 0.2。
  - maxDiffPixels number (選用)
    
    可能不同的可接受像素數量，預設為未設定。
  - maxDiffPixelRatio number (選用)
    
    不同像素與像素總數之間的可接受比率，介於 0 和 1 之間，預設為未設定。
  expect(value).toMatchSnapshot() 方法的組態。
- toPass Object (選用)
  - timeout number (選用)
    
    toPass 方法的逾時時間（以毫秒為單位）。
  - intervals Array<number> (選用)
    
    toPass 方法的探查間隔（以毫秒為單位）。
  expect(value).toPass() 方法的組態。

fullyParallel

新增於：v1.10

testProject.fullyParallel

Playwright 測試以平行方式執行測試。為了達到此目的，它會執行多個工作進程，這些進程同時執行。依預設，測試檔案會以平行方式執行。單一檔案中的測試會依序在相同的工作進程中執行。

您可以使用此選項，將整個測試專案配置為同時執行所有檔案中的所有測試。

用法

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

專案名稱在報告和測試執行期間可見。

用法

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(value).toMatchSnapshot() 產生的快照位置。

用法

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

export default defineConfig({
  testDir: './tests',
  snapshotPathTemplate: '{testDir}/__screenshots__/{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() 和 toMatchSnapshot() 呼叫的引數；如果呼叫時沒有引數，這將是自動產生的快照名稱。
- 值：foo/bar/baz
{ext} - 快照副檔名（含點）
- 值：.png
{platform} - process.platform 的值。
{projectName} - 專案的檔案系統安全名稱（如果有的話）。
- 值：'' (空字串)。
{snapshotDir} - 專案的 testConfig.snapshotDir。
- 值：/home/playwright/tests (由於組態中未提供 snapshotDir，因此預設為 testDir)
{testDir} - 專案的 testConfig.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/... 中。
第二個專案有名稱，因此其快照將儲存在 <configDir>/__screenshots__/chromium/example.spec.ts/.. 中。
由於 snapshotPathTemplate 解析為相對路徑，因此它將相對於 configDir 解析。
正斜線 "/" 可在任何平台上用作路徑分隔符。

teardown

新增於：v1.34

testProject.teardown

在此專案和所有相依專案完成後需要執行的專案名稱。Teardown 對於清除此專案取得的任何資源非常有用。

傳遞 --no-deps 引數會忽略 testProject.teardown，其行為就像未指定一樣。

用法

常見模式是具有對應「teardown」的「setup」相依性

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

將以遞迴方式掃描測試檔案的目錄。預設為組態檔的目錄。

每個專案都可以使用不同的目錄。以下範例會在三個瀏覽器中執行煙霧測試，並在穩定的 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

與這些模式之一相符的檔案不會作為測試檔案執行。比對是針對絕對檔案路徑執行的。字串會被視為 glob 模式。

例如，'**/test-assets/**' 將會忽略 test-assets 目錄中的任何檔案。

使用 testConfig.testIgnore 為所有專案變更此選項。

用法

testProject.testIgnore

類型

string | RegExp | Array<string | RegExp>

testMatch

新增於：v1.10

testProject.testMatch

僅執行與這些模式之一相符的檔案作為測試檔案。比對是針對絕對檔案路徑執行的。字串會被視為 glob 模式。

依預設，Playwright 會尋找與以下 glob 模式相符的檔案：**/*.@(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

屬性​

dependencies​

expect​

fullyParallel​

grep​

grepInvert​

ignoreSnapshots​

metadata​

name​

outputDir​

repeatEach​

respectGitIgnore​

retries​

snapshotDir​

snapshotPathTemplate​

teardown​

testDir​

testIgnore​

testMatch​

timeout​

use​

屬性

dependencies

expect

fullyParallel

grep

grepInvert

ignoreSnapshots

metadata

name

outputDir

repeatEach

respectGitIgnore

retries

snapshotDir

snapshotPathTemplate

teardown

testDir

testIgnore

testMatch

timeout

use