Skip to main content

Test ID Style Guide

使用 Constants Object 來統一彙整 data-testid​

export const surveyTestIds = {
  BUTTON_NEW_SURVEY: 'button-new-survey',
  // and more...
}


// bad
<Button
  data-testid="button-new-survey"
>

// good
<Button
  data-testid={surveyTestIds.BUTTON_NEW_SURVEY}
>

從 constants object 取用實際的 test id，而不是直接寫死，原因與好處如下 :

  • 從 object 來取 property 可以享有 IDE 自動完成，打錯時也有更好的提示
  • 查看 constants object 即可一次檢視全部 test id，有助於取名時的一致性
  • 寫在同一個 object 可以讓 Github Copilot 看到全部的 case，程式碼生成會精準許多

Constants Object 的資料夾結構​

src/
├─ constants/
│  ├─ test-ids/
│  │  ├─ index.js
│  │  ├─ survey-test-ids.js // 問卷相關的 test id
│  │  ├─ global-test-ids.js // APP 層級元件的 test id
// index.js
import { globalTestIds } from './global-test-ids'
import { surveyTestIds } from './survey-test-ids'
export { globalTestIds, surveyTestIds }

使用 index.js 統一 export，就可以 import { surveyTestIds } from 'constants/test-ids'，不用再填寫額外的路徑

Constants Object Key Value Pair 命名規則​

{
  BUTTON_NEW_SURVEY: 'button-new-survey', 
  // and more...
}

  • key : 使用大寫下底線的 SCREAMING_SNAKE_CASE

    • 通常用於 JavaScript 中的 constants (常量)
    • 隱藏的好處是，搜尋取代時的區隔性高

  • value : 使用小寫連字號的 kebab-case

    • HTML 中 class 和 id 的值很常使用這種這種命名規則，我們使用的 data-testid 也是 HTML 的 attribute，故沿用此命名規則

Test ID 的命名策略​

// bad
"new-survey"

// good
"button-new-survey" // BUTTON_NEW_SURVEY

// bad
"upload-zip"

// good
"radio-upload-zip" // RADIO_UPLOAD_ZIP
  • 依據被定位 element 的 UI 性質，選取適當的 prefix (前綴)
  • 再依據 element 的功能和所屬歸類進行補充描述，組成 test id

最後，key 則根據 test id 實際值改為 SCREAMING_SNAKE_CASE，新增至 constants object

Test ID Prefix 參考​

詳細的 prefix 列表，請 參考 ARIA role 為基礎，若往後有需要，再討論新增 prefix，並文件化

Test ID 的特別使用案例​

// text area
// 使用 textbox-multiline-{}
// ARIA 沒有把 text area 獨立出一個 role, 參考 aria-multiline 這個屬性來表達 text area

// drop down 
// 使用 listbox-{}

// drop down 的選項
// 使用 option-{}

// dialog: 跳出彈窗停止使用者當前動作, 要求使用者「確認」或「取消」

// 具有警告、警示的意味的 dialog: 使用 alertdialog
// alertdialog-{}
// button-alertdialog-confirm
// button-alertdialog-cancel

// 一般泛用的 dialog: 使用 dialog
// dialog-{}
// button-dialog-confirm
// button-dialog-confirm

前端 data-testid 置入原則​

一律從 constants object 取用 test id 實際值

  • 一般的 HTML JSX : 直接新增 data-testid 塞入
  • 共用元件如 Button、Input : 定義一個 testId props ，再塞進元件內的 HTML JSX 中的 data-testid
  • 非共用元件、與特定功能相關的元件 : 可以考慮直接在元件內部寫好 data-testid ，不用從 props 傳入 (因為可能元件內也很多地方要塞 test id)