使用 React Testing Library 的 15 個常見錯誤
哈嘍，大家好。以前的我(Kent)并不是很喜歡那個時候的測試環境，為此寫了一個 React Testing Library。它是原來 DOM Testing Library 的一個擴展，隨著不斷更新迭代，現在 Testing Library 的實現也能支持當下所有流行的 JS 框架和工具來定位組件中的 DOM 了。
隨時代發展，我們也對這個庫的 API 做了很多修改，同時也發現社區中有很多不怎么優雅的使用方式。雖然我們已經很努力地在文檔里寫要怎么 “更好地” 使用我們提供的工具 API，但我還是在別的文章和博客中看到他們在用這些不優雅的使用方法。接下來，我就一一盤點這些方法，解釋為什么它們不是很好，以及如何改進測試以避免這些陷阱。
注：下面是重要程度的說明。
低：一般為我的主觀想法，如果你覺得使用上沒啥問題可以忽略它
中：如果你不遵循，可能會出現 Bugs、低效的測試用例、還可能會做額外的工作
高：一定要用我建議的方法。不然很有可能你會遇到大問題，而且測試用例并不怎么高效
沒有使用 Testing Library 的 ESLint 插件
重要程度：中
如果你想避免這些常見的錯誤，那么官方的 ESLint 插件可以給你帶來很多幫助：
- eslint-plugin-testing-library
- eslint-plugin-jest-dom
注：如果你已經在用 create-react-library，那 eslint-plugin-testing-library 已經包含包在依賴中了
建議：最好把這兩個 ESLint 插件都裝上。
還在用 Wrapper 作為 render 返回值的變量名
重要程度：低
// ?
const wrapper = render(<Example prop="1" />)
wrapper.rerender(<Example prop="2" />)
// ?
const {rerender} = render(<Example prop="1" />)
rerender(<Example prop="2" />)
Wrapper 是以前 Enzyme 的過時用法，現在已經不需要它了。而且 render 的返回值里也并沒有 Wraper 任何東西，它只是一些工具 API 的集合而已。所以，一般情況下可以不需要它了。
建議：直接使用從 render 返回值解構出來的東西，或者將返回值命名為 view。
手動使用 cleanup
重要性：中
// ?
import {render, screen, cleanup} from '@testing-library/react'
afterEach(cleanup)
// ?
import {render, screen} from '@testing-library/react'
現在cleanup 都是自動調用的，所以你已經不再需要再考慮它了。詳見這里。
建議：別手動調 cleanup
不用 screen
重要程度：中
// ?
const {getByRole} = render(<Example />)
const errorMessageNode = getByRole('alert')
// ?
render(<Example />)
const errorMessageNode = screen.getByRole('alert')
screen 是在 DOM Testing Library v6.11.0 引入的 (就就是說，你可以在 @testing-library/react@>=9 這些版本中使用它)。直接在 render 引入的時候一并引入就可以了：
import {render, screen} from '@testing-library/react'使用 screen 的好處是：在添加/刪除 DOM Query 時，不需要實時地解構 render 的返回值來獲取內容。輸入 screen，你的編輯器就能自動補全它里面的 API 了。
除非一種情況：你在配置 container 或者 baseElement。不過，你應該避免使用它們(因為我實在想不出使用它們的現實場景，除非你是在處理一些歷史遺留問題)。
你也可以直接調 screen.debug 而不是 debug。
建議：用 screen 來做 Querying 和 Debugging
使用錯誤的斷言 API
重要程度：高
const button = screen.getByRole('button', {name: /disabled button/i})
// ?
expect(button.disabled).toBe(true)
// error message:
// expect(received).toBe(expected) // Object.is equality
//
// Expected: true
// Received: false
// ?
expect(button).toBeDisabled()
// error message:
// Received element is not disabled:
// <button />建議：用 @testing-library/jest-dom 這個庫
將不必要的操作放在 act 里
重要程度：中
// ?
act(() => {
render(<Example />)
})
const input = screen.getByRole('textbox', {name: /choose a fruit/i})
act(() => {
fireEvent.keyDown(input, {key: 'ArrowDown'})
})
// ?
render(<Example />)
const input = screen.getByRole('textbox', {name: /choose a fruit/i})
fireEvent.keyDown(input, {key: 'ArrowDown'})
我經常看到不少人像上面那樣把一些操作放在 act 里，因為他們一看到 "act" 的 Warning，就把操作放在 act 里面，以此去掉 Warning。但他們不知道的是 render 和 fireEvent 已經包裹在 act 里了!所以這樣么其實沒啥卵用。
大多數時間，如果你看到這些 act 的 Warning，不是要讓你無腦地干掉它們，是在告訴你：你的測試有問題了。可以看這里的視頻來了解更多：Fix the "not wrapped in act(...)" warning。
建議：去了解什么時候應該用 act，別把啥東西都往 act 里放
使用錯誤的 Query
重要程度：高
// ?
// 假設你有這樣的 DOM：
// <label>Username</label><input data-testid="username" />
screen.getByTestId('username')
// ?
// 改成通過關聯 label 以及設置 type 來訪問 DOM
// <label for="username">Username</label><input id="username" type="text" />
screen.getByRole('textbox', {name: /username/i})
我們文檔里一直有維護一個頁面：“Which query should I use?”。你應該按這個頁面中的順序來使用 Query API。如果你的目標和我們的一樣，都想通過測試來確保用戶在使用時應用能夠正常工作的話，那你就要盡量用更接近用戶的使用方式來查詢 DOM。我們提供的 Query 都能幫你做到這一點，但并非所有 Query API 都是一樣的。
使用 container 來查詢元素
作為 “使用錯誤的 Query” 的子集，我想聊一下直接用 container 來查詢元素的問題：
// ?
const {container} = render(<Example />)
const button = container.querySelector('.btn-primary')
expect(button).toHaveTextContent(/click me/i)
// ?
render(<Example />)
screen.getByRole('button', {name: /click me/i})
實際上我們更希望用戶能直接和 UI 進行交互，然而，如果你用 querySelector 這些來做查詢的話，不僅我們不能模仿用戶的 UI 交互行為，測試代碼也會變得很難讀，而且容易崩。這和下面這一節也有關系：
沒有用文本來做查詢
作為 “使用錯誤的 Query” 的子集，我想聊一下為什么我們更建議你用真實的文本來做查詢(關于地區語言，應該用默認的地區語言文本)，而不是用 Test ID 以及別的一些機制。
// ?
screen.getByTestId('submit-button')
// ?
screen.getByRole('button', {name: /submit/i})
如果不用真實的文本來查詢，那你要做很多額外的工作，因為你要確保你的地區語言的翻譯轉換是正確的。這里肯定有多人會吐槽說：要是別人改了文本的內容，你的測試不就崩了么?我對此的反駁是，首先，如果有人將 “UserName” 更改為 “Email”，這是我絕對想知道的變更(因為我需要更改我的實現了)。而且，就算有人因為改了個名搞崩了測試，修復測試也用不了多長時間，馬上就能修好了。
總的來說，修復的成本是很低的，而好處則是可以增加你對翻譯正確性信心，而且寫出來的測試也是容易閱讀和修改的。
還是要聲明一下，并不是所有人都同意我這個觀點的，具體可以看下 Twitter 上的這個 Thread。
多數情況下沒有使用 *ByRole
作為 “使用錯誤的 Query” 的子集，我想來聊聊 *ByRole。在最近 RTL 的幾個版本里，對 *ByRole 相關的 Query API 都做了很多的升級，這了是對組件渲染輸出做查詢操作最推薦的方法。下面是我比較喜歡它的一些功能。
name 選項可以讓你通過元素的 "Accessible Name" 查詢元素，這也是 Screen Reader 會對每個元素讀取的內容。好處是：即使元素的文本內容被其它不同元素分割了，它還是能夠以此做查詢。比如：
// 假如現在我們有這樣的 DOM：//
// 假如現在我們有這樣的 DOM：
// <button><span>Hello</span> <span>World</span></button>
screen.getByText(/hello world/i)
// ? 報錯:
// Unable to find an element with the text: /hello world/i. This could be
// because the text is broken up by multiple elements. In this case, you can
// provide a function for your text matcher to make your matcher more flexible.
screen.getByRole('button', {name: /hello world/i})
// ? 成功!
人們不使用 *ByRole 做查詢的原因之一是他們不熟悉在元素上的隱式 Role。，沒關系，大家可以參考 MDN，MDN 上有寫這些元素上的 Role List。
另一個我喜歡這個 API 的功能是：如果不能通過指定好的 Role 找到元素，它不僅會像 get* 以及 find* API 一樣把整個 DOM 樹都打印出來，而且還會把當前能訪問的 Role 都打印出來!
// 假設我們有這樣的 DOM
// <button><span>Hello</span> <span>World</span></button>
screen.getByRole('blah')
上面會報這樣的錯誤：
TestingLibraryElementError: Unable to find an accessible element with the role "blah"
Here are the accessible roles:
button:
Name "Hello World":
<button />
--------------------------------------------------
<body>
<div>
<button>
<span>
Hello
</span>
<span>
World
</span>
</button>
</div>
</body>
這里要注意的是，我們并沒有為設置 Role 而加上 role=button。因為這是隱式的 Role，下一節會詳細說明。
建議：閱讀并根據 “Which Query Should I Use" Guide” 里的推薦順序來使用 Query
錯誤地添加可訪問屬性：aria-，role
重要程度：高
// ?
render(<button role="button">Click me</button>)
// ?
render(<button>Click me</button>)
像上面那樣隨意添加/修改可訪問屬性(Accessibility Attributes)不僅沒有必要，而且還會把 Screen Reader 和用戶搞懵。只有當無法滿足當前的 HTML 語義時(比如你寫了一個非原生的 UI 組件，同時也要讓它 像 AutoComplete 一樣可訪問)，你才應該使用可訪問屬性。假如這就是你現在要開發的東西，那可以用現有的第三庫根據 WAI-ARIA 實踐來實現可訪問性。它們一般會有一些 很好的樣例來參考。
注意：如果要讓 input 可以通過 role 來訪問，你需要指定對應的 type 屬性值!
建議：避免錯誤地添加不必要的或不正確的可訪問屬性
沒有使用 @testing-library/user-event
重要程度：高
// ?
fireEvent.change(input, {target: {value: 'hello world'}})
// ?
userEvent.type(input, 'hello world')
@testing-library/user-event 是在 fireEvent 基礎上實現的，但它提供了一些更接近用戶交互的方法。上面這個例子中，fireEvent.change 其實只觸發了 Input 的一個 Change 事件。但是 type 則可以對每個字符都會觸發 keyDown、keyPress 和 keyUp 一系列事件。這能更接近用戶的真實交互場景。好處是可以很好地和你當前那些沒有監聽 Change 事件的庫一起使用。
我們現在還在進行 @testing-library/user-event 這個庫的開發，來保證它能像它承諾的那樣：能夠觸發用戶在執行特定操作時會觸發的所有相同事件。不過，現在它還沒完全做到這一點，這也是為什么它還沒有合入 @testing-library/dom (可能在未來的某個時候會合入)。但是，我對它有足夠的信心，建議你多關注和使用它，而不是 fireEvent。
建議：盡可能地使用 @testing-library/user-event，而不是 fireEvent
沒有用 query* 來斷言元素不存在
重要程度：高
// ?
expect(screen.queryByRole('alert')).toBeInTheDocument()
// ?
expect(screen.getByRole('alert')).toBeInTheDocument()
expect(screen.queryByRole('alert')).not.toBeInTheDocument()
把暴露 query* 相關的 API 出來的唯一原因是：可以在找不到元素的情況下不會拋出異常(返回 null)。唯一的好處是可以用來判斷這個元素是否沒有被渲染到頁面上。這是很重要的，因為類似 get* 和 find* 相關的 API 在找不到元素時都會自動拋出異常 —— 這樣你就可以看到渲染的內容以及為什么找不到元素的原因。然而，query* 只會返回 null，所以 toBeInTheDocument 在這里最好的用法就是：判斷 null 不在 Document 上。
建議：query* API 只用于斷言當前元素不能被找到
用 waitFor 等待 find* 的查詢結果
重要程度：高
// ?
const submitButton = await waitFor(() =>
screen.getByRole('button', {name: /submit/i}),
)
// ?
const submitButton = await screen.findByRole('button', {name: /submit/i})
上面兩段代碼幾乎是等價的(find* 其實也是在內部用了 waitFor)，但是第二種使用方法更清晰，而且拋出的錯誤信息會更友好。
建議：當查詢那些不能立馬能訪問到的元素時，使用 find*
給 waitFor 傳空 callback
重要程度：高
// ?
await waitFor(() => {})
expect(window.fetch).toHaveBeenCalledWith('foo')
expect(window.fetch).toHaveBeenCalledTimes(1)
// ?
await waitFor(() => expect(window.fetch).toHaveBeenCalledWith('foo'))
expect(window.fetch).toHaveBeenCalledTimes(1)
waitFor 的目的是可以讓你等一些指定的事情發生。如果傳了空的 callback，可能它在今天還能 Work，因為你只是想在 Event Loop 等一個 Tick 就好了。但這樣你也會留下一個脆弱的測試用例，一旦改了某些異步邏輯它很可能就崩了。
建議：在 waitFor 里等待指定的斷言，不要傳空 callback
一個 waitFor callback 里有多個斷言
重要程度：低
// ?
await waitFor(() => {
expect(window.fetch).toHaveBeenCalledWith('foo')
expect(window.fetch).toHaveBeenCalledTimes(1)
})
// ?
await waitFor(() => expect(window.fetch).toHaveBeenCalledWith('foo'))
expect(window.fetch).toHaveBeenCalledTimes(1)
在上面的例子中，如果 window.fetch 調用了兩次，那么 waitFor 就會失敗，但是我們就得等到超時了才能看到具體報錯。而如果 waitFor 里只有一個斷言，我們則可以等待 UI 渲染到斷言的同時，也可以在其中一個斷言失敗時更快地獲得報錯信息。
建議：waitFor 的 callback 里只放一個斷言
在 waitFor 中使用副作用
重要程度：高
// ?
await waitFor(() => {
fireEvent.keyDown(input, {key: 'ArrowDown'})
expect(screen.getAllByRole('listitem')).toHaveLength(3)
})
// ?
fireEvent.keyDown(input, {key: 'ArrowDown'})
await waitFor(() => {
expect(screen.getAllByRole('listitem')).toHaveLength(3)
})
waitFor 適用的情況是：在執行的操作和斷言之間存在不確定的時間量。因此，callback 可在不確定的時間和頻率(在間隔以及 DOM 變化時調用)被調用(或者檢查錯誤)。所以這也意味著你的副作用可能會被多次調用!
同時，這也意味著你不能在 waitFor 里面使用快照斷言(SnapShot Assertion)。如果你想要用快照斷言，首先要等待某些斷言走完了，然后再拍快照。
建議：把副作用放在 waitFor 回調的外面，回調里只能有斷言
用 get* 來做斷言
重要程度：低
// ?
screen.getByRole('alert', {name: /error/i})
// ?
expect(screen.getByRole('alert', {name: /error/i})).toBeInTheDocument()
雖然這不是什么大問題，但我還是想說下我的觀點。如果 get* API 找不到元素，它就會拋出異常，打印整個 DOM 樹結構(語法高亮)，在 Debug 的時候很有用。也因為這點，斷言是永遠不可能失敗的(因為如果找不到元素，查詢在斷言之前拋出異常)。
因為這個原因，很多人直接不做斷言了。這其實也還好，但是我個人通常來說，會把斷言留著，這樣可以讓后面做重構、修改的人知道：這里不是個查詢操作，而是個斷言操作。
建議：如果你想斷言某個東西是否存在，那么就做顯式的斷言操作
總結
作為測試庫工具系列的維護者，我們盡最大努力使 API 能夠引導人們盡可能有效地使用，一些不足之處，我們會嘗試正確地記錄下來，即使這會非常地困難(尤其是 API 改動/升級等)。希望這篇文章會幫到你，我們只是想你更有信心地交付你的代碼。
Good Luck!
好了，這篇外文就給大家帶到這里了。翻譯這篇文章還是花不少時間的，同時也學到了很多 RTL 這個庫的一些思想，希望大家也能吸收里面一些測試思路。
