快照測試

概觀⎘

透過 Playwright 快照測試，您可以根據預定義的快照範本，斷言頁面的協助工具樹狀結構。

await page.GotoAsync("https://playwright.dev.org.tw/");
await Expect(page.Locator("banner")).ToMatchAriaSnapshotAsync(@"
  - banner:
    - heading ""Playwright enables reliable end-to-end testing for modern web apps."" [level=1]
    - link ""Get started""
    - link ""Star microsoft/playwright on GitHub""
    - link /[\\d]+k\\+ stargazers on GitHub/
");

斷言測試 vs 快照測試⎘

快照測試和斷言測試在測試自動化中服務於不同的目的

斷言測試⎘

斷言測試是一種目標明確的方法，您可以在其中斷言關於元素或組件的特定值或條件。例如，使用 Playwright，Expect(Locator).ToHaveTextAsync() 驗證元素是否包含預期的文字，而 Expect(Locator).ToHaveValueAsync() 確認輸入欄位是否具有預期的值。斷言測試是明確的，通常會根據預期的預定義狀態檢查元素或屬性的目前狀態。它們適用於可預測的單一值檢查，但在測試更廣泛的結構或變化時範圍有限。

優點

清晰度：測試的意圖明確且易於理解。
明確性：測試專注於功能的特定方面，使其更能抵抗不相關的變更。
偵錯：失敗提供目標明確的回饋，直接指向有問題的方面。

缺點

複雜輸出的冗長：為複雜資料結構或大型輸出編寫斷言可能很繁瑣且容易出錯。
維護負擔：隨著程式碼的演變，手動更新斷言可能很耗時。

快照測試⎘

快照測試會擷取元素、組件或資料在給定時刻的整個狀態的「快照」或表示，然後儲存以供未來比較。重新執行測試時，會將目前狀態與快照進行比較，如果存在差異，則測試失敗。這種方法對於複雜或動態結構特別有用，因為手動斷言每個細節會太耗時。快照測試比斷言測試更廣泛且更全面，讓您可以追蹤更複雜的變更。

優點

簡化複雜輸出：例如，使用傳統斷言來測試 UI 組件的呈現輸出可能很乏味。快照擷取整個輸出以方便比較。
快速回饋迴圈：開發人員可以輕鬆發現輸出中意外的變更。
鼓勵一致性：有助於在程式碼演變時維持一致的輸出。

缺點

過度依賴：可能會很想接受對快照的變更，而沒有完全理解它們，這可能會隱藏錯誤。
細微性：當差異出現時，大型快照可能難以解讀，尤其是在微小的變更影響大部分輸出時。
適用性：不適用於輸出頻繁或不可預測地變更的高度動態內容。

何時使用⎘

快照測試非常適合
- 整個頁面和組件的 UI 測試。
- 複雜 UI 組件的廣泛結構檢查。
- 輸出結構很少變更的回歸測試。
斷言測試非常適合
- 核心邏輯驗證。
- 計算值測試。
- 需要精確條件的細微測試。

透過結合用於廣泛結構檢查的快照測試和用於特定功能的斷言測試，您可以實現完善的測試策略。

Aria 快照⎘

在 Playwright 中，aria 快照提供頁面協助工具樹狀結構的 YAML 表示法。這些快照可以儲存並稍後比較，以驗證頁面結構是否保持一致或符合定義的預期。

YAML 格式描述頁面上可存取元素的階層式結構，詳細說明角色、屬性、值和文字內容。該結構遵循樹狀語法，其中每個節點代表一個可存取的元素，而縮排表示巢狀元素。

樹狀結構中的每個可存取元素都表示為 YAML 節點

- role "name" [attribute=value]

role：指定元素的 ARIA 或 HTML 角色（例如，heading、list、listitem、button）。
"name"：元素的可存取名稱。引號字串表示確切值，/patterns/ 用於正則表達式。
[attribute=value]：屬性和值，在方括號中，表示特定的 ARIA 屬性，例如 checked、disabled、expanded、level、pressed 或 selected。

這些值衍生自 ARIA 屬性或根據 HTML 語意計算得出。若要檢查頁面的協助工具樹狀結構，請使用 Chrome DevTools 協助工具面板。

快照比對⎘

Playwright 中的 Expect(Locator).ToMatchAriaSnapshotAsync() 斷言方法將定位器範圍的可存取結構與預定義的 aria 快照範本進行比較，有助於根據測試需求驗證頁面的狀態。

對於以下 DOM

<h1>title</h1>

您可以使用以下快照範本進行比對

await Expect(page.Locator("body")).ToMatchAriaSnapshotAsync(@"
  - heading ""title""
");

比對時，快照範本會與頁面的目前協助工具樹狀結構進行比較

如果樹狀結構與範本相符，則測試通過；否則，測試失敗，表示預期狀態與實際協助工具狀態之間不符。
比較區分大小寫並摺疊空白字元，因此會忽略縮排和換行符號。
比較對順序敏感，這表示快照範本中元素的順序必須與頁面協助工具樹狀結構中的順序相符。

部分比對⎘

您可以透過省略屬性或可存取名稱，對節點執行部分比對，從而驗證協助工具樹狀結構的特定部分，而無需完全比對。這種彈性對於動態或不相關的屬性很有幫助。

<button>Submit</button>

aria 快照

- button

在此範例中，比對了按鈕角色，但未指定可存取名稱（「Submit」），因此測試無論按鈕的標籤為何都會通過。

對於具有 ARIA 屬性（例如 checked 或 disabled）的元素，省略這些屬性允許部分比對，僅專注於角色和階層。

<input type="checkbox" checked>

用於部分比對的 aria 快照

- checkbox

在此部分比對中，checked 屬性會被忽略，因此無論核取方塊狀態為何，測試都會通過。

同樣地，您可以透過省略特定清單項目或巢狀元素，部分比對清單或群組中的子項目。

<ul>
  <li>Feature A</li>
  <li>Feature B</li>
  <li>Feature C</li>
</ul>

用於部分比對的 aria 快照

- list
  - listitem: Feature B

部分比對可讓您建立彈性的快照測試，以驗證必要的頁面結構，而無需強制執行特定內容或屬性。

使用正則表達式比對⎘

正則表達式允許彈性比對具有動態或可變文字的元素。可存取名稱和文字可以支援正則表達式模式。

<h1>Issues 12</h1>

具有正則表達式的 aria 快照

- heading /Issues \d+/

產生快照⎘

在 Playwright 中建立 aria 快照有助於確保和維護應用程式的結構。您可以根據測試設定和工作流程，以各種方式產生快照。

1. 使用 Playwright 程式碼產生器產生快照⎘

如果您使用的是 Playwright 的程式碼產生器，則使用其互動式介面可以簡化產生 aria 快照的流程

「斷言快照」動作：在程式碼產生器中，您可以使用「斷言快照」動作，自動為選取的元素建立快照斷言。這是擷取 aria 快照作為錄製測試流程一部分的快速方法。
「Aria 快照」標籤：「Aria 快照」標籤在程式碼產生器介面中以視覺方式呈現選取定位器的 aria 快照，讓您可以探索、檢查和驗證元素角色、屬性和可存取名稱，以協助快照建立和檢閱。

2. 使用 `@playwright/test` 和 `--update-snapshots` 旗標更新快照⎘

當使用 Playwright 測試執行器 (@playwright/test) 時，您可以透過使用 --update-snapshots 旗標執行測試來自動更新快照

npx playwright test --update-snapshots

此命令會重新產生斷言的快照，包括 aria 快照，並取代過時的快照。當應用程式結構變更需要新的快照作為基準時，這非常有用。請注意，Playwright 將等待測試執行器組態中指定的最大預期逾時，以確保頁面在拍攝快照之前已穩定。如果測試在產生快照時達到逾時，則可能需要調整 --timeout。

用於快照產生的空白範本⎘

在斷言中將空字串作為範本傳遞會即時產生快照

請注意，Playwright 將等待測試執行器組態中指定的最大預期逾時，以確保頁面在拍攝快照之前已穩定。如果測試在產生快照時達到逾時，則可能需要調整 --timeout。

快照修補程式檔案⎘

更新快照時，Playwright 會建立擷取差異的修補程式檔案。這些修補程式檔案可以檢閱、套用和提交至原始碼控制，讓團隊可以追蹤一段時間內的結構變更，並確保更新與應用程式需求一致。

3. 使用 `Locator.ariaSnapshot` 方法⎘

Locator.AriaSnapshotAsync() 方法可讓您以程式設計方式建立定位器範圍內可存取元素的 YAML 表示法，這對於在測試執行期間動態產生快照特別有用。

範例:

var snapshot = await page.Locator("body").AriaSnapshotAsync();
Console.WriteLine(snapshot);

此命令以 YAML 格式輸出指定定位器範圍內的 aria 快照，您可以根據需要驗證或儲存。

協助工具樹狀結構範例⎘

具有層級屬性的標題⎘

標題可以包含 level 屬性，以指示其標題層級。

<h1>Title</h1>
<h2>Subtitle</h2>

aria 快照

- heading "Title" [level=1]
- heading "Subtitle" [level=2]

文字節點⎘

獨立或描述性文字元素會顯示為文字節點。

<div>Sample accessible name</div>

aria 快照

- text: Sample accessible name

內嵌多行文字⎘

多行文字（例如段落）會在 aria 快照中標準化。

<p>Line 1<br>Line 2</p>

aria 快照

- paragraph: Line 1 Line 2

連結⎘

連結會顯示其文字或來自虛擬元素的組合內容。

<a href="#more-info">Read more about Accessibility</a>

aria 快照

- link "Read more about Accessibility"

文字方塊⎘

類型為 text 的輸入元素會顯示其 value 屬性內容。

<input type="text" value="Enter your name">

aria 快照

- textbox: Enter your name

具有項目的清單⎘

有序和無序清單包含其清單項目。

<ul aria-label="Main Features">
  <li>Feature 1</li>
  <li>Feature 2</li>
</ul>

aria 快照

- list "Main Features":
  - listitem: Feature 1
  - listitem: Feature 2

群組元素⎘

群組擷取巢狀元素，例如具有摘要內容的 <details> 元素。

<details>
  <summary>Summary</summary>
  <p>Detail content here</p>
</details>

aria 快照

- group: Summary

屬性和狀態⎘

常用的 ARIA 屬性，例如 checked、disabled、expanded、level、pressed 和 selected，代表控制狀態。

具有 `checked` 屬性的核取方塊⎘

<input type="checkbox" checked>

aria 快照

- checkbox [checked]

具有 `pressed` 屬性的按鈕⎘

<button aria-pressed="true">Toggle</button>

aria 快照

- button "Toggle" [pressed=true]

概觀⎘

斷言測試 vs 快照測試⎘

斷言測試⎘

快照測試⎘

何時使用⎘

Aria 快照⎘

快照比對⎘

部分比對⎘

使用正則表達式比對⎘

產生快照⎘

1. 使用 Playwright 程式碼產生器產生快照⎘

2. 使用 @playwright/test 和 --update-snapshots 旗標更新快照⎘

用於快照產生的空白範本⎘

快照修補程式檔案⎘

3. 使用 Locator.ariaSnapshot 方法⎘

協助工具樹狀結構範例⎘

具有層級屬性的標題⎘

文字節點⎘

內嵌多行文字⎘

連結⎘

文字方塊⎘

具有項目的清單⎘

群組元素⎘

屬性和狀態⎘

具有 checked 屬性的核取方塊⎘

具有 pressed 屬性的按鈕⎘

2. 使用 `@playwright/test` 和 `--update-snapshots` 旗標更新快照⎘

3. 使用 `Locator.ariaSnapshot` 方法⎘

具有 `checked` 屬性的核取方塊⎘

具有 `pressed` 屬性的按鈕⎘