跳到主要內容

快照測試

概觀​

透過 Playwright 快照測試，您可以針對預定義的快照範本，斷言頁面的可存取性樹狀結構。

page.goto('https://playwright.dev.org.tw/')
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 Pane。

快照比對​

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 快照

- 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

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

使用正規表示式比對​

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

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

範例:

snapshot = page.locator("body").aria_snapshot()
print(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]