Skip to main content

快照測試

概述​

透過 Playwright 的快照測試，您可以針對預定義的快照範本斷言頁面的無障礙樹。

page.goto('https://playwright.dev/')
expect(page.query_selector('banner')).to_match_aria_snapshot("""
  - banner:
    - heading /Playwright enables reliable end-to-end/ [level=1]
    - link "Get started"
    - link "Star microsoft/playwright on GitHub"
    - link /[\\d]+k\\+ stargazers on GitHub/
""")

斷言測試 vs 快照測試​

快照測試和斷言測試在測試自動化中有不同的用途：

斷言測試​

斷言測試是一種針對性的方法，您可以斷言元素或元件的特定值或條件。例如，使用 Playwright 的 expect(locator).to_have_text() 驗證元素包含預期文字，而 expect(locator).to_have_value() 則確認輸入欄位具有預期值。斷言測試是特定的，通常檢查元素或屬性的當前狀態與預期的預定義狀態。它們適用於可預測的單一值檢查，但在測試更廣泛的結構或變化時範圍有限。

優點

  • 清晰度：測試的意圖明確且易於理解。
  • 特異性：測試專注於功能的特定方面，使它們對無關變更更加穩健。
  • 偵錯：失敗提供有針對性的回饋，直接指向有問題的方面。

缺點

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

快照測試​

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

優點

  • 簡化複雜輸出：例如，使用傳統斷言測試 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 Accessibility Tab。

快照比對​

Playwright 中的 expect(locator).to_match_aria_snapshot() 斷言方法會將定位器範圍的無障礙結構與預定義的 aria 快照範本進行比較，有助於根據測試需求驗證頁面狀態。

對於以下 DOM：

<h1>title</h1>

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

expect(page.locator("body")).to_match_aria_snapshot("""
  - heading "title"
""")

比對時，快照範本會與頁面的當前無障礙樹進行比較：

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

部分比對​

您可以透過省略屬性或無障礙名稱對節點執行部分比對，從而能夠驗證無障礙樹的特定部分，而無需完全相符。這種靈活性對於動態或無關的屬性很有幫助。

<button>Submit</button>

aria snapshot

- button

在此範例中，button 角色會被比對，但未指定無障礙名稱（「Submit」），允許測試無論按鈕標籤為何都能通過。

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

<input type="checkbox" checked>

aria snapshot for partial match

- checkbox

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

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

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

aria snapshot for partial match

- list
  - listitem: Feature B

部分比對讓您能夠建立靈活的快照測試，驗證基本頁面結構而無需強制執行特定內容或屬性。

嚴格比對​

預設情況下，包含子元素子集的範本將會被比對：

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

aria snapshot for partial match

- list
  - listitem: Feature B

/children 屬性可用於控制子元素的比對方式：

  • contain（預設）：如果所有指定的子元素按順序存在則比對
  • equal：如果子元素完全按順序符合指定清單則比對
  • equal：如果子元素完全按順序符合指定清單則比對
<ul>
  <li>Feature A</li>
  <li>Feature B</li>
  <li>Feature C</li>
</ul>

aria snapshot will fail due to Feature C not being in the template

- list
  - /children: equal
  - listitem: Feature A
  - listitem: Feature B

使用正規表示式比對​

正規表示式允許對具有動態或可變文字的元素進行靈活比對。無障礙名稱和文字可以支援正規表示式模式。

<h1>Issues 12</h1>

aria snapshot with regular expression

- heading /Issues \d+/

產生快照​

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

使用 Playwright 程式碼產生器產生快照​

如果您使用 Playwright 的 程式碼產生器，透過其互動式介面產生 aria 快照會變得非常簡潔：

  • 「Assert snapshot」動作：在程式碼產生器中，您可以使用「Assert snapshot」動作為選定的元素自動建立快照斷言。這是將 aria 快照作為錄製測試流程一部分捕獲的快速方法。
  • 「Aria snapshot」分頁：程式碼產生器介面中的「Aria snapshot」分頁會視覺化地表示選定定位器的 aria 快照，讓您探索、檢查和驗證元素角色、屬性和無障礙名稱，以協助快照建立和檢閱。

使用 Locator.ariaSnapshot 方法​

locator.aria_snapshot() 方法讓您能夠以程式化方式建立定位器範圍內無障礙元素的 YAML 表示法，這對於在測試執行期間動態產生快照特別有幫助。

Example:

snapshot = page.locator("body").aria_snapshot()
print(snapshot)

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

無障礙樹範例​

具有層級屬性的標題​

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

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

aria snapshot

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

文字節點​

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

<div>Sample accessible name</div>

aria snapshot

- text: Sample accessible name

行內多行文字​

多行文字（如段落）在 aria 快照中會被正規化。

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

aria snapshot

- paragraph: Line 1 Line 2

連結​

連結會顯示其文字或由偽元素組成的內容。

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

aria snapshot

- link "Read more about Accessibility"

文字方塊​

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

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

aria snapshot

- textbox: Enter your name

含項目的清單​

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

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

aria snapshot

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

群組元素​

群組會捕獲巢狀元素，例如包含摘要內容的 <details> 元素。

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

aria snapshot

- group: Summary

屬性和狀態​

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

帶有 checked 屬性的核取方塊​

<input type="checkbox" checked>

aria snapshot

- checkbox [checked]

帶有 pressed 屬性的按鈕​

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

aria snapshot

- button "Toggle" [pressed=true]