TestInfo

TestInfo 包含關於目前執行測試的資訊。它適用於測試函式、test.beforeEach()、test.afterEach()、test.beforeAll() 和 test.afterAll() hook，以及測試範圍的 fixture。TestInfo 提供實用工具來控制測試執行：附加檔案、更新測試逾時、判斷目前正在執行的測試以及是否已重試等等。

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

test('basic test', async ({ page }, testInfo) => {
  expect(testInfo.title).toBe('basic test');
  await page.screenshot(testInfo.outputPath('screenshot.png'));
});

---

方法

attach

加入於：v1.10 testInfo.attach

將值或磁碟中的檔案附加到目前的測試。某些報告器會顯示測試附件。必須指定 path 或 body，但不能同時指定兩者。

例如，您可以將螢幕截圖附加到測試

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

test('basic test', async ({ page }, testInfo) => {
  await page.goto('https://playwright.dev.org.tw');
  const screenshot = await page.screenshot();
  await testInfo.attach('screenshot', { body: screenshot, contentType: 'image/png' });
});

或者您可以附加 API 傳回的檔案

import { test, expect } from '@playwright/test';
import { download } from './my-custom-helpers';

test('basic test', async ({}, testInfo) => {
  const tmpPath = await download('a');
  await testInfo.attach('downloaded', { path: tmpPath });
});

注意

testInfo.attach() 會自動處理將附加檔案複製到報告器可存取的位置。在等待附加呼叫後，您可以安全地移除附件。

用法

await testInfo.attach(name);
await testInfo.attach(name, options);

引數

• name string#

  附件名稱。此名稱也會被清理，並在儲存到磁碟時用作檔案名稱的前綴。

• options Object (選用)

  • body string | Buffer (選用)#

    附件主體。與 path 互斥。

  • contentType string (選用)#

    此附件的內容類型，以便在報告中正確呈現，例如 'application/json' 或 'image/png'。如果省略，則會根據 path 推斷內容類型，或者對於 string 附件預設為 text/plain，對於 Buffer 附件預設為 application/octet-stream。

  • path string (選用)#

    檔案系統上附加檔案的路徑。與 body 互斥。

傳回

• Promise<void>#

---

fail()

加入於：v1.10 testInfo.fail()

將目前執行的測試標記為「應該失敗」。Playwright Test 會執行此測試，並確保它實際上會失敗。這對於文件用途很有用，以確認某些功能在修復之前已損壞。這與 test.fail() 類似。

用法

testInfo.fail();

---

fail(condition)

加入於：v1.10 testInfo.fail(condition)

有條件地將目前執行的測試標記為「應該失敗」，並帶有選用的描述。這與 test.fail() 類似。

用法

testInfo.fail(condition);
testInfo.fail(condition, description);

引數

• condition boolean#

  當條件為 true 時，測試會標記為「應該失敗」。

• description string (選用)#

  選用的描述，將反映在測試報告中。

---

fixme()

加入於：v1.10 testInfo.fixme()

將測試標記為「fixme」，意圖修復它。測試會立即中止。這與 test.fixme() 類似。

用法

testInfo.fixme();

---

fixme(condition)

加入於：v1.10 testInfo.fixme(condition)

有條件地將目前執行的測試標記為「fixme」，並帶有選用的描述。這與 test.fixme() 類似。

用法

testInfo.fixme(condition);
testInfo.fixme(condition, description);

引數

• condition boolean#

  當條件為 true 時，測試會標記為「fixme」。

• description string (選用)#

  選用的描述，將反映在測試報告中。

---

outputPath

加入於：v1.10 testInfo.outputPath

傳回 testInfo.outputDir 內的路徑，測試可以在其中安全地放置暫存檔。保證並行執行的測試不會互相干擾。

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

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

請注意，pathSegments 接受測試輸出目錄的路徑區段，例如 testInfo.outputPath('relative', 'path', 'to', 'output')。但是，此路徑必須保留在每個測試的 testInfo.outputDir 目錄（即 test-results/a-test-title）內，否則會擲回錯誤。

用法

testInfo.outputPath(...pathSegments);

引數

• ...pathSegments Array<string>#

  要附加在結果路徑結尾的路徑區段。

傳回

• string#

---

setTimeout

加入於：v1.10 testInfo.setTimeout

變更目前執行測試的逾時時間。零表示沒有逾時。深入瞭解各種逾時。

逾時時間通常在組態檔中指定，但在某些情況下，變更逾時時間可能很有用

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

test.beforeEach(async ({ page }, testInfo) => {
  // Extend timeout for all tests running this hook by 30 seconds.
  testInfo.setTimeout(testInfo.timeout + 30000);
});

用法

testInfo.setTimeout(timeout);

引數

• timeout number#

  逾時時間，以毫秒為單位。

---

skip()

加入於：v1.10 testInfo.skip()

無條件跳過目前執行的測試。測試會立即中止。這與 test.skip() 類似。

用法

testInfo.skip();

---

skip(condition)

加入於：v1.10 testInfo.skip(condition)

有條件地跳過目前執行的測試，並帶有選用的描述。這與 test.skip() 類似。

用法

testInfo.skip(condition);
testInfo.skip(condition, description);

引數

• condition boolean#

  跳過條件。當條件為 true 時，會跳過測試。

• description string (選用)#

  選用的描述，將反映在測試報告中。

---

slow()

加入於：v1.10 testInfo.slow()

將目前執行的測試標記為「slow」，使其逾時時間為預設逾時時間的三倍。這與 test.slow() 類似。

用法

testInfo.slow();

---

slow(condition)

加入於：v1.10 testInfo.slow(condition)

有條件地將目前執行的測試標記為「slow」，並帶有選用的描述，使其逾時時間為預設逾時時間的三倍。這與 test.slow() 類似。

用法

testInfo.slow(condition);
testInfo.slow(condition, description);

引數

• condition boolean#

  當條件為 true 時，測試會標記為「slow」。

• description string (選用)#

  選用的描述，將反映在測試報告中。

---

snapshotPath

加入於：v1.10 testInfo.snapshotPath

傳回具有指定 pathSegments 的快照檔案路徑。深入瞭解快照。

請注意，pathSegments 接受快照檔案的路徑區段，例如 testInfo.snapshotPath('relative', 'path', 'to', 'snapshot.png')。但是，此路徑必須保留在每個測試檔案的快照目錄（即 a.spec.js-snapshots）內，否則會擲回錯誤。

用法

testInfo.snapshotPath(...pathSegments);

引數

• ...pathSegments Array<string>#

  快照的名稱或定義快照檔案路徑的路徑區段。在同一個測試檔案中具有相同名稱的快照應該相同。

傳回

• string#

---

屬性

annotations

加入於：v1.10 testInfo.annotations

適用於目前測試的註解清單。包含來自測試的註解、來自測試所屬的所有 test.describe() 群組的註解，以及測試檔案的檔案層級註解。

深入瞭解測試註解。

用法

testInfo.annotations

類型

• Array<Object>

  • type string

    註解類型，例如 'skip' 或 'fail'。

  • description string (選用)

    選用的描述。

---

attachments

加入於：v1.10 testInfo.attachments

附加到目前測試的檔案或緩衝區清單。某些報告器會顯示測試附件。

若要新增附件，請使用 testInfo.attach()，而不是直接推送到此陣列。

用法

testInfo.attachments

類型

• Array<Object>

  • name string

    附件名稱。

  • contentType string

    此附件的內容類型，以便在報告中正確呈現，例如 'application/json' 或 'image/png'。

  • path string (選用)

    檔案系統上附加檔案的選用路徑。

  • body Buffer (選用)

    選用的附件主體，用於取代檔案。

---

column

加入於：v1.10 testInfo.column

宣告目前執行測試的行號。

用法

testInfo.column

類型

• number

---

config

加入於：v1.10 testInfo.config

來自組態檔的已處理組態。

用法

testInfo.config

類型

• FullConfig

---

duration

加入於：v1.10 testInfo.duration

測試完成所花費的毫秒數。在測試完成之前（無論成功與否）始終為零。可用於 test.afterEach() hook。

用法

testInfo.duration

類型

• number

---

error

加入於：v1.10 testInfo.error

測試執行期間擲回的第一個錯誤（如果有的話）。這等於 testInfo.errors 中的第一個元素。

用法

testInfo.error

類型

• TestInfoError

---

errors

加入於：v1.10 testInfo.errors

測試執行期間擲回的錯誤（如果有的話）。

用法

testInfo.errors

類型

• Array<TestInfoError>

---

expectedStatus

加入於：v1.10 testInfo.expectedStatus

目前執行測試的預期狀態。這通常是 'passed'，但有幾種情況除外

• 對於跳過的測試，'skipped'，例如使用 test.skip()；
• 對於標記為失敗的測試，'failed'，使用 test.fail()。

預期狀態通常與實際 testInfo.status 比較

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

test.afterEach(async ({}, testInfo) => {
  if (testInfo.status !== testInfo.expectedStatus)
    console.log(`${testInfo.title} did not run as expected!`);
});

用法

testInfo.expectedStatus

類型

• "passed" | "failed" | "timedOut" | "skipped" | "interrupted"

---

file

加入於：v1.10 testInfo.file

宣告目前執行測試的檔案的絕對路徑。

用法

testInfo.file

類型

• string

---

fn

加入於：v1.10 testInfo.fn

傳遞給 test(title, testFunction) 的測試函式。

用法

testInfo.fn

類型

• function

---

line

加入於：v1.10 testInfo.line

宣告目前執行測試的行號。

用法

testInfo.line

類型

• number

---

outputDir

加入於：v1.10 testInfo.outputDir

此特定測試執行的輸出目錄的絕對路徑。每個測試執行都有自己的目錄，因此它們不會衝突。

用法

testInfo.outputDir

類型

• string

---

parallelIndex

加入於：v1.10 testInfo.parallelIndex

worker 的索引，介於 0 和 workers - 1 之間。保證同時執行的 worker 具有不同的 parallelIndex。當 worker 重新啟動時（例如在失敗後），新的 worker 處理序具有相同的 parallelIndex。

也可用作 process.env.TEST_PARALLEL_INDEX。深入瞭解 Playwright Test 的並行和分片。

用法

testInfo.parallelIndex

類型

• number

---

project

加入於：v1.10 testInfo.project

來自組態檔的已處理專案組態。

用法

testInfo.project

類型

• FullProject

---

repeatEachIndex

加入於：v1.10 testInfo.repeatEachIndex

在「重複每個」模式下執行時，指定唯一的重複索引。此模式透過將 --repeat-each 傳遞到命令列來啟用。

用法

testInfo.repeatEachIndex

類型

• number

---

retry

加入於：v1.10 testInfo.retry

指定在失敗後重試測試時的重試次數。第一次測試執行 testInfo.retry 等於零，第一次重試等於一，依此類推。深入瞭解重試。

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

test.beforeEach(async ({}, testInfo) => {
  // You can access testInfo.retry in any hook or fixture.
  if (testInfo.retry > 0)
    console.log(`Retrying!`);
});

test('my test', async ({ page }, testInfo) => {
  // Here we clear some server-side state when retrying.
  if (testInfo.retry)
    await cleanSomeCachesOnTheServer();
  // ...
});

用法

testInfo.retry

類型

• number

---

snapshotDir

加入於：v1.10 testInfo.snapshotDir

此特定測試的快照輸出目錄的絕對路徑。每個測試套件都有自己的目錄，因此它們不會衝突。

此屬性不考慮 testProject.snapshotPathTemplate 組態。

用法

testInfo.snapshotDir

類型

• string

---

snapshotSuffix

加入於：v1.10 testInfo.snapshotSuffix

注意

不建議使用 testInfo.snapshotSuffix。請使用 testConfig.snapshotPathTemplate 來組態快照路徑。

用於區分多個測試組態之間快照的後綴。例如，如果快照取決於平台，您可以將 testInfo.snapshotSuffix 設定為等於 process.platform。在這種情況下，expect(value).toMatchSnapshot(snapshotName) 將根據平台使用不同的快照。深入瞭解快照。

用法

testInfo.snapshotSuffix

類型

• string

---

status

加入於：v1.10 testInfo.status

目前執行測試的實際狀態。在 test.afterEach() hook 和 fixture 中，測試完成後可用。

狀態通常與 testInfo.expectedStatus 比較

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

test.afterEach(async ({}, testInfo) => {
  if (testInfo.status !== testInfo.expectedStatus)
    console.log(`${testInfo.title} did not run as expected!`);
});

用法

testInfo.status

類型

• "passed" | "failed" | "timedOut" | "skipped" | "interrupted"

---

tags

加入於：v1.43 testInfo.tags

適用於測試的標籤。深入瞭解標籤。

注意

在測試執行時對此清單所做的任何變更，測試報告器都看不到。

用法

testInfo.tags

類型

• Array<string>

---

testId

加入於：v1.32 testInfo.testId

測試 ID，符合報告器 API 中的測試案例 ID。

用法

testInfo.testId

類型

• string

---

timeout

加入於：v1.10 testInfo.timeout

目前執行測試的逾時時間，以毫秒為單位。零表示沒有逾時。深入瞭解各種逾時。

逾時時間通常在組態檔中指定

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

test.beforeEach(async ({ page }, testInfo) => {
  // Extend timeout for all tests running this hook by 30 seconds.
  testInfo.setTimeout(testInfo.timeout + 30000);
});

用法

testInfo.timeout

類型

• number

---

title

加入於：v1.10 testInfo.title

目前執行測試的標題，如傳遞給 test(title, testFunction) 的標題。

用法

testInfo.title

類型

• string

---

titlePath

加入於：v1.10 testInfo.titlePath

以測試檔案名稱開頭的完整標題路徑。

用法

testInfo.titlePath

類型

• Array<string>

---

workerIndex

加入於：v1.10 testInfo.workerIndex

正在執行測試的 worker 處理序的唯一索引。當 worker 重新啟動時（例如在失敗後），新的 worker 處理序會取得新的唯一 workerIndex。

也可用作 process.env.TEST_WORKER_INDEX。深入瞭解 Playwright Test 的並行和分片。

用法

testInfo.workerIndex

類型

• number