測試元件契約
元件的契約就是它的公開 API:接受的 props、發出的事件、渲染的插槽,以及維護的無障礙屬性。驗證契約的測試能讓使用者確信元件行為正確,而無需指定元件內部如何實現這些行為。驗證實作細節的測試——哪個內部函式被呼叫、哪個內部狀態被設定——每當實作改變時就必須更新,即使可觀察的行為並未改變。採用契約測試作為預設測試邊界,也意味著一種明確的工程立場:元件測試應該從使用者的感知出發,而不是從元件的實作細節出發。這種立場在 Code Review、新人培訓,以及測試策略討論中,都能提供清晰的判斷基準,並使測試意圖對整個團隊更加透明。
Testing Library 系列工具(React Testing Library、Vue Testing Library 等)正是圍繞這個區別設計的。其核心原則——「你的測試愈接近軟體的使用方式,它們能給你的信心就愈多」——正是測試契約而非實作的另一種表達。以 role 和 label 查詢,而非以 CSS class 或元件名稱查詢,就是將這個原則落實到具體操作的方式。Testing Library 的設計者刻意不提供存取元件內部狀態或實例的 API,這是有意為之的限制,而非功能缺失:缺少這些 API 意味著測試作者必然被引導到契約測試的方向,因為那是唯一可用的路徑。這個工具設計上的限制,實際上轉化為測試品質的保障機制,讓團隊在沒有額外規範的情況下,也能自然地避免測試實作細節的陷阱。
元件契約在設計系統和共用元件庫中尤為重要。一個為了無障礙改進而調整內部 DOM 結構的按鈕元件,不應要求更新每一個查詢舊結構的測試。針對契約撰寫的測試——按鈕以 role="button" 渲染、按下 Enter 觸發 onClick——能夠在實作重構後繼續通過。當一個基礎元件被數十個應用程式的測試套件依賴時,元件的任何內部改動都不應造成消費端的測試失敗——只要其對使用者的行為保持不變。透過嚴格遵守契約測試的邊界,設計系統團隊能夠安心地進行無障礙改進、效能最佳化和 DOM 重構,而無需協調所有消費端同步更新測試。這種解耦是大型前端系統中維持高開發速度的重要架構決策。
從契約角度思考元件也能改善元件設計本身。如果一個元件難以在不使用 data-testid 或模擬內部實作的情況下進行測試,原因通常是該元件尚未在其 DOM 輸出中呈現正確的語義結構。測試的阻力是設計問題的症狀:元件的公開介面與使用者和輔助技術感知它的方式不符。將「可透過契約進行測試」作為設計要求——與功能性和視覺外觀並列——能產出更具無障礙性、更易組合,且更能獨立升級的元件。將測試視為元件公開行為主要規格說明的做法,對剛接觸契約測試的團隊是個有用的框架:先撰寫描述元件應為使用者做什麼的測試,再實作元件使其通過。衡量這種設計轉變成效的一個實用方法是:在重構一個元件的內部實作後,記錄有多少測試因此失敗——這個數字越接近零,說明測試套件的契約導向程度越高,元件的公開設計也越成熟。
設計思維
契約作為設計反饋機制
可測試性並非獨立於元件設計之外——它直接反映設計品質。一個只能透過存取內部狀態才能測試的元件, 說明其公開介面沒有暴露足夠的語義資訊。當測試需要 querySelector 才能找到元素時,代表元件缺少 一個能夠透過使用者面向身份識別元素的角色或標籤。當測試必須模擬子元件才能隔離行為時,代表父元件 承擔了過多責任,需要更清晰的介面或組合邊界。
這個反饋迴路是契約導向測試中最常被低估的價值之一。在實作之前或同時撰寫測試的團隊,能在問題 修復成本最低的時候發現設計問題。一個難以撰寫的測試是元件契約不完整的早期警訊。透過改善元件的 語義結構來解決測試阻力,同時也提升了元件的無障礙性和可組合性。測試套件因此成為一個持續的設計 稽核工具,而非事後的驗證步驟。
契約測試 vs. 實作測試
契約測試與實作測試之間的差異,在比較兩個檢查模態對話框是否開啟的測試時變得具體。實作測試可能 斷言 component.state.isOpen === true。契約測試則斷言 getByRole('dialog') 在文件中可見。 當元件被重構為以 reducer 取代 useState 來管理開啟狀態時,實作測試會失敗——狀態結構已改變。 契約測試無需修改即可通過,因為可見的對話框仍然存在。這種不對稱性正是以契約為導向的測試的核心 論點:實作細節會隨程式碼演進而改變;對使用者的可觀察行為則不應如此。同樣的道理也適用於從 CSS 類別名稱切換到 CSS Modules、從受控元件改為非受控元件,或從本地狀態遷移到狀態管理函式庫等常見 重構場景——契約測試在所有這些情況下都不需要更新,因為使用者感知到的行為並未改變。
契約測試的意圖也更加清晰。getByRole('dialog') 表示「一個對使用者和輔助技術可見的對話框」。 component.state.isOpen === true 表示「一個內部變數具有特定值」。前者是使用者在乎的行為, 後者是某種特定實作方法的產物。讀起來像行為規格說明的測試,對團隊而言更易於理解、維護和擴展。 這種可讀性上的差異在新進工程師加入時尤為明顯:以契約撰寫的測試幾乎不需要額外說明,測試名稱本身 就成為元件行為的活文件,讓測試套件同時承擔規格說明與驗證兩個職責。
從維護成本角度看,契約測試的優勢也更加明顯。設計系統中的一個元件可能被數十個消費端測試套件 依賴。如果每個測試套件都斷言內部狀態或 CSS class 名稱,那麼每次改進元件實作(例如,為了更好的 無障礙性而重構 DOM 結構)都會在所有消費端觸發測試失敗,即使使用者可見的行為完全相同。以契約為 導向的測試讓元件內部可以自由演進,只要公開行為維持穩定,消費端測試就不需要更新。這種穩定性在 維護共用元件庫時尤為關鍵。從長期維護的角度看,實作測試所累積的技術債不只體現在每次重構時的測試 更新成本,還體現在工程師對重構的心理阻力:當開發者知道修改一個元件的內部結構將觸發大量測試失敗 時,他們往往會選擇繞過改進,而不是面對更新測試的負擔。契約測試從根本上消除了這種阻力,讓改進和 重構成為低成本的日常工程實踐,而非需要謹慎評估的高風險操作。
查詢優先順序:語義優先
Testing Library 定義了一個查詢優先順序,反映了每種查詢與實作細節的耦合程度。從最低耦合到最高 耦合:getByRole(使用者和螢幕閱讀器依賴的語義 HTML 和 ARIA 角色)→ getByLabelText(定義 無障礙名稱的表單元素關聯)→ getByPlaceholderText(視力正常的使用者可見的提示文字)→ getByText(渲染輸出中可見的文字內容)→ getByDisplayValue(表單欄位的當前值)→ getByAltText(圖片 alt 文字)→ getByTitle(title 屬性)→ getByTestId(沒有面向使用者 意義的自訂屬性)。
實際的啟示是:在每個測試中首先使用 getByRole。當元件沒有有意義的角色時——對互動元件而言這種 情況很罕見——沿著優先順序向下找到一個以使用者能感知的內容為基礎的查詢。將 getByTestId 保留給 元件確實沒有無障礙特徵可查詢的少數情況,並將其使用視為一個訊號,重新審視是否需要為元件添加角色 或標籤使其可以透過契約進行測試。在 Code Review 中,查詢優先順序也可以作為評估測試品質的快速框架: 一個測試中出現的查詢越靠近優先順序的低耦合端,該測試對實作重構的耐受性就越高,這個觀察框架能讓 查詢選擇的討論建立在具體標準上,而非依賴個人風格偏好。
getByRole 的第二個參數 { name: '...' } 用於篩選出具有特定無障礙名稱的元素。無障礙名稱來自 aria-label、aria-labelledby,或元素的可見文字內容。getByRole('button', { name: 'Submit' }) 不只確認存在一個按鈕,還確認該按鈕有正確的標籤——這正是螢幕閱讀器用戶用來識別控制項的資訊。當 頁面上有多個同類型角色的元素時(例如多個按鈕),name 選項就成為區分它們且不依賴位置或 class 的唯一方式。此外,getByRole 在查詢失敗時會提供詳細的錯誤訊息,列出頁面上所有可用的 ARIA 角色 和名稱,這個除錯輸出本身就有助於工程師發現元件的無障礙結構是否與預期不符,比 CSS 選擇器的靜默 失敗提供了更豐富的診斷資訊。
userEvent vs. fireEvent
Testing Library 提供兩種模擬使用者輸入的方式:fireEvent 派發單一合成 DOM 事件,而 @testing-library/user-event 則模擬真實瀏覽器為使用者互動生成的完整事件序列。在瀏覽器中點擊 按鈕會依序觸發 pointerover、pointerenter、mouseover、mouseenter、pointermove、 mousemove、pointerdown、mousedown、focus、pointerup、mouseup、click。 fireEvent.click 只觸發 click。一個依賴於 focus 在 click 之前被設定的元件——例如一個 只有在聚焦後才開啟的下拉選單——在使用 fireEvent.click 的測試中將無法正確運作。
在所有互動測試中,應優先使用 userEvent.click() 而非 fireEvent.click()。 @testing-library/user-event v14 使用 pointer 和 keyboard API 產生真實的事件序列,其 setup() 工廠方法建立一個在多次互動間保持狀態的使用者工作階段——對於測試焦點管理、多步驟鍵盤 導航,以及事件順序重要的互動十分有用。更真實模擬的代價在測試執行時間上可以忽略不計;其好處是 測試能在更接近真實瀏覽器行為的條件下執行元件。
userEvent 的 setup() API 也讓多步驟互動測試更加簡潔。呼叫 const user = userEvent.setup() 後,user.click()、user.keyboard()、user.tab() 等方法共享同一個指標和焦點狀態,模擬 使用者在 UI 中實際操作的連續性。相比之下,每次呼叫 fireEvent 都是獨立的合成事件,不攜帶任何 先前互動的狀態。對於需要驗證「Tab 導航→ Enter 啟動→ Escape 關閉」這類完整互動流程的測試, setup() API 提供了比一系列 fireEvent 呼叫更貼近真實使用者行為的測試環境。從契約的角度看, 這種完整的事件序列模擬不只是技術上的精確性要求,更是確保測試真正驗證使用者感知行為的必要條件: 一個只在 click 事件觸發時正確運作、但在完整的指標事件序列下行為異常的元件,對使用者而言是有 缺陷的,而這類缺陷只有透過 userEvent 的完整事件序列才能在測試中被捕捉。
Storybook play 函式作為契約測試
Storybook 的 play 函式(隨互動插件引入)允許 story 包含在 story 渲染後在瀏覽器中執行的自動化 互動。使用 @storybook/test 工具撰寫的 play 函式——底層使用 @testing-library/user-event ——作為瀏覽器執行的契約測試,與記錄元件的 story 並置。Storybook 可以透過 storybook test 在 CI 中執行這些 play 函式,使其成為自動化測試套件的一部分,而不僅僅是視覺文件。
play 函式的策略性價值在於它們緊鄰元件的 story,並在 Storybook UI 中可見,因此兼具元件互動 契約的活文件功能。審閱元件 story 的開發者可以即時觀看 play 函式執行,以了解元件應有的行為。 與在模擬 DOM 環境中執行的單元測試不同,play 函式在真實瀏覽器環境中執行——能捕捉基於 jsdom 的測試所遺漏的瀏覽器特定渲染問題。這種瀏覽器執行環境對於依賴真實 CSS 計算、瀏覽器焦點管理 行為或原生表單驗證的元件尤為重要,因為這些特性在 jsdom 的模擬環境中往往無法精確重現,而正是 這些細節決定了元件在真實使用者裝置上的實際行為是否符合契約預期。
從組織架構的角度看,play 函式消除了測試與文件之間的重複。在沒有 play 函式的典型設置中,元件 有記錄視覺狀態的 story,以及在獨立測試檔案中驗證行為的測試。這兩個產出物可能逐漸偏離:story 展示一種互動模式,而測試驗證另一種。play 函式消弭了這個落差——story 和契約測試成為同一個產出物。 特別是在設計系統團隊中,這種並置能讓元件的預期行為對消費端更易發現,消費端無需在使用文件之外 額外閱讀測試檔案。從治理角度來看,play 函式也讓契約測試的覆蓋率對非工程師的利害關係人(例如 設計師和產品負責人)更加可見:他們可以直接在 Storybook UI 中觀察 play 函式執行,而無需理解 測試框架或原始碼,這種透明度有助於在跨職能團隊中建立對元件行為規格的共識。當一個 play 函式 失敗時,它所代表的不只是測試失敗,更是一個元件的可觀察行為不符合其文件化規格的明確訊號,這種 即時的反饋迴路在設計系統的持續整合流程中具有重要的品質保障價值。
元件設計與可測試性的相互影響
元件的可測試性是其設計品質的重要指標。如果一個元件難以透過語義查詢進行測試,通常意味著它在設計 上存在問題:缺少必要的 ARIA 角色、沒有適當的無障礙名稱、或者元件的視覺呈現與其語義結構脫節。這 種情況下,新增 data-testid 是治標不治本的做法——它讓測試可以執行,但不解決元件的根本問題。
正確的做法是在元件開發過程中,以「如何用 getByRole 查詢」作為設計問題的一部分。對話框需要 role="dialog" 和 aria-labelledby;自訂下拉選單需要正確的 role="combobox" 或 role="listbox" 結構;表單欄位需要 <label> 關聯或 aria-label。當這些語義屬性到位時, getByRole 查詢自然而然地成為最具表達力的測試方式,而不需要依賴任何實作細節。這種設計與測試的 相互強化關係,是為何「以契約為先的測試思維」能同時提升程式碼品質和無障礙性的根本原因。值得注意 的是,ARIA 角色和語義屬性並非只是為測試而添加的標記——它們本身就是元件公開契約的一部分,決定了 輔助技術如何呈現元件給使用者,因此在設計階段就納入這些考量,反映的是對元件使用者群體完整性的 尊重。
從實踐角度,可以將「能否以 getByRole 撰寫測試」作為元件驗收的門檻之一。在 Code Review 中, 當一個測試使用 getByTestId 或 container.querySelector 時,提問「這個元件是否缺少對應的語義 角色或無障礙名稱?」往往能發現設計上的缺失。這樣的 Code Review 文化將無障礙性問題在測試撰寫 階段就識別出來,而非等到測試完成後再進行獨立的無障礙稽核。
這種「以可測試性為設計門檻」的思維方式,也能改變元件設計的討論方式。當工程師在設計評審中問「這 個元件如何用 getByRole 查詢?」時,對話自然地從視覺設計轉向語義結構和使用者感知,往往能在元 件還未實作之前,就識別出 ARIA 角色缺失或鍵盤互動未定義等問題。這種前置的設計問題識別,比在元件 實作完成後才補加語義屬性,在工程成本上要低得多。長期下來,團隊會形成一種習慣:將語義設計與視覺 設計視為同等重要的元件設計面向,而不是在無障礙稽核被提出時才被動應對。契約測試在這個過程中扮演 了雙重角色:它既是驗證機制,也是設計反饋工具,將無障礙性從事後檢查轉變為貫穿整個開發流程的設計 考量。
最佳實踐
必須(MUST)在元件測試中優先使用 getByRole 作為查詢方式。 角色對應於使用者和螢幕閱讀器 互動的語義 HTML 和 ARIA 角色。查詢 getByRole('button', { name: 'Submit' }) 的測試會在渲染 元素缺少正確角色或無障礙名稱時失敗——而這正是重要的失敗模式。查詢 document.querySelector('.submit-btn') 的測試即使按鈕無法以鍵盤存取也會通過。當元件測試無法 使用 getByRole 撰寫時,幾乎總是因為元件本身需要改進以暴露正確的語義結構。getByRole 附帶 { name: '...' } 選項時同時驗證了無障礙名稱,這是語義查詢相對於 CSS 選擇器的關鍵附加價值—— 一次查詢同時確認了元素存在、角色正確,以及標籤可被輔助技術讀取。
必須(MUST)透過模擬使用者互動來測試互動元件,而非直接呼叫元件方法或設定內部狀態。 若對話框 在按鈕點擊時開啟,就透過點擊按鈕進行測試:await userEvent.click(getByRole('button', { name: 'Open' }))。測試必須(MUST)不呼叫 component.open() 或直接設定 setState({ isOpen: true })。使用者無法呼叫 內部方法;測試也必須(MUST)不能這樣做。直接操作狀態會繞過互動觸發的所有事件處理器、驗證邏輯 和副作用——產生即使真實的使用者面向互動已損壞也能通過的測試。測試應該是元件行為的可執行規格, 而行為的定義是「使用者執行操作後看到什麼」,而非「內部變數的值為何」。
禁止(MUST NOT)在元件測試中模擬(mock)子元件,除非該子元件來自外部套件且其行為在測試環境中無法被控制。 模擬內部子元件會破壞整合——測試不再執行實際的渲染輸出——並在父子元件之間的真實互動有誤時產生虛假的信心。應按照元件在實際使用中的渲染方式進行測試,包含其子元件;若子元件有難以控制的外部依賴,應模擬依賴本身,不得模擬整個子元件。
應該(SHOULD)為所有互動元件加入鍵盤互動測試。 只能點擊開啟卻無法以 Enter 開啟的下拉選單 對鍵盤使用者來說是失敗的。一個按 Tab 聚焦觸發器再按 Enter 開啟的測試能涵蓋這種情況。鍵盤互動 測試是在進入生產環境之前捕捉無障礙契約違規最有效的方式。userEvent.tab() 和 userEvent.keyboard('{Enter}') 工具讓這些測試易於撰寫。團隊應該(SHOULD)為每個互動元件至少 配置一個鍵盤互動測試,作為任何新元件工作完成定義的一部分。WAI-ARIA 創作實踐指南(APG)為每種 ARIA 角色定義了預期的鍵盤行為,可作為撰寫鍵盤契約測試的規格參考。鍵盤路徑的覆蓋不僅保護鍵盤 使用者,也間接確保了元件的焦點管理是正確的——焦點陷阱(focus trap)在對話框關閉後正確釋放焦點、 Tab 鍵順序符合視覺佈局等,都可以透過鍵盤互動測試在單元測試層級加以驗證。
視覺呈現
範例
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { Dialog } from './Dialog';
test('點擊觸發器時開啟對話框,按 Escape 時關閉', async () => {
render(
<Dialog trigger={<button>Open</button>} title="Confirm">
<p>Content</p>
</Dialog>
);
// 互動前對話框不存在
expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
// 模擬真實點擊——userEvent 觸發完整的瀏覽器事件序列
await userEvent.click(screen.getByRole('button', { name: 'Open' }));
// 針對契約斷言:無障礙名稱為「Confirm」的對話框可見
expect(screen.getByRole('dialog', { name: 'Confirm' })).toBeVisible();
// 模擬按下 Escape 關閉——鍵盤互動是契約的一部分
await userEvent.keyboard('{Escape}');
// 關閉後對話框從 DOM 中消失
expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
});常見錯誤
- 以
getByTestId作為預設查詢方式。data-testid不提供任何關於元件角色、標籤或可見文字 的資訊——而這些屬性才決定使用者是否能感知和互動該元素。以data-testid撰寫的測試即使元素 不可見、缺少鍵盤角色或沒有無障礙名稱也會通過。優先使用getByRole;只有在元素沒有使用者可感 知特徵可查詢時才添加data-testid。 - 模擬子元件以隔離被測單元。 模擬子元件會將元件測試轉變為只驗證父元件渲染邏輯的部分測試, 而不測試父子元件之間的實際互動。當真實的子元件以破壞組合的方式改變時,使用模擬子元件的測試 仍然通過。只模擬來自無法在測試環境中控制的外部套件的子元件。
- 使用
fireEvent進行互動測試。fireEvent派發單一合成事件,對單元測試通常足夠,但會 遺漏真實瀏覽器互動生成的多事件序列。依賴click之前的focus、pointerdown或keydown事件的元件,在fireEvent下與真實瀏覽器中的行為會有所不同。所有互動模擬應優先使用userEvent。如果測試使用fireEvent但元件在真實瀏覽器中表現正常,這本身就是一個訊號: 測試覆蓋的互動路徑,與使用者實際經歷的路徑不完全相同。 - 斷言內部狀態或方法呼叫。 使用
wrapper.instance().state或監視內部方法的測試,會將實作 選擇編碼進測試套件。當實作被重構——即使是為了改進它——這些測試就會失敗並需要更新,而這些更新 不提供任何關於使用者可見行為的額外信心。將此類測試改寫為對渲染輸出的斷言。 - 在互動元件測試中省略鍵盤和焦點測試。 以點擊為基礎的測試只涵蓋一種輸入模式;鍵盤使用者、 開關使用者和螢幕閱讀器使用者依賴不同的互動模型。通過所有滑鼠測試的元件,仍可能完全無法用鍵盤 操作。在每個互動元件的契約測試中至少包含一條鍵盤路徑,確保元件的無障礙契約與其指標操作契約 一起被驗證,而不是留到無障礙稽核或使用者回報時才發現。
- 對設計系統元件使用不同的查詢策略。 有些團隊在應用程式測試中使用語義查詢,但在元件庫測試 中仍使用
getByTestId或 CSS 選擇器,理由是元件庫「只需要測試 DOM 輸出」。這種區分是錯誤的: 設計系統元件是最需要以契約為導向測試的地方,因為它們被最多消費端依賴。針對角色和無障礙名稱進行 測試,確保元件作為設計系統的語義承諾得到驗證,而不只是視覺外觀的驗證。 - 在非同步互動測試中遺漏
await。userEvent的方法是非同步的,必須以await等待。遺漏await會導致斷言在互動完成之前就執行,產生難以除錯的假性失敗(元件行為正確,但測試因時序問題 而失敗)。使用await userEvent.click(...)而非userEvent.click(...),並確保測試函式 宣告為async,是使用userEventv14 API 的基本要求。TypeScript 在此提供了天然的防護: 若測試函式未宣告為async,對await的使用會產生編譯錯誤,從而在執行前就捕捉到這個常見 問題。
相關 FEE
參考資料
- Testing Library: 指導原則 — 關於為何 Testing Library 圍繞使用者可見查詢設計的權威說明;「你的測試愈接近軟體的使用方式, 它們能給你的信心就愈多」這個原則是所有以契約為導向的元件測試的基礎;在撰寫任何元件測試之前 閱讀此頁面,能讓查詢優先順序的選擇變得直覺而非任意,也能建立測試設計決策的正確心智模型
- Testing Library: 查詢優先順序 — 從
getByRole到getByTestId的官方查詢優先順序,並說明每個層級為何反映了該查詢與實作 細節相對於使用者面向行為的耦合程度;頁面中包含getByTestId應作為最後手段的明確指引, 僅在沒有語義特徵可查詢時使用;此頁面也是 Code Review 中討論查詢選擇的有效參考來源 - Kent C. Dodds: 測試實作細節 — 在 React 測試背景下闡述契約與實作區別的文章;說明了為何測試實作細節會產生偽陽性(行為損壞時 測試通過)和偽陰性(只有實作改變時測試失敗),以及為何使用者可觀察的行為是測試斷言的正確單元; 所述的兩類實作細節——元件實例方法與內部狀態——適用於任何元件框架,不只限於 React;對正在說服 團隊從實作測試轉向契約測試的工程師而言,本文提供了有力的論述基礎
- WAI-ARIA 創作實踐指南:模式 — W3C 按 ARIA 角色定義預期鍵盤互動模式的參考文件;為對話框、手風琴或下拉選單撰寫鍵盤互動測試時, 該元件的 APG 模式定義了哪些鍵盤事件是無障礙契約的一部分;未涵蓋這些模式的測試會留下未驗證的 無障礙契約缺口;此文件同時適合作為元件設計規格和測試規格的雙重參考
- Storybook: 互動測試 —
play函式和 Storybook 測試執行器的官方文件;說明如何使用@storybook/test撰寫互動測試、 如何透過storybook test在 CI 中執行,以及瀏覽器執行環境如何捕捉 jsdom 測試無法重現的問題; 適合使用 Storybook 且希望將契約測試與元件 story 並置、消除測試與文件重複的團隊