SKILL.md
testId Guide
開發前端頁面元件時，為所有可互動元素添加 testId，確保 E2E 測試的穩定性。
觸發時機
- 使用者提到要開發「頁面」、「元件」、「UI」等相關功能時
- 新增或修改
.component.html檔案時 - 涉及按鈕、表單輸入、連結等可互動元素時
開發指南
必須添加 testId 的元素
| 元素類型 | 說明 | 範例 |
|---|---|---|
| UI 元件 | fm-button、fm-icon-button、fm-labeled-input、fm-toggle、fm-search-input、fm-textarea、fm-number-input、fm-alert、fm-fab |
testId="login-submit" |
| 表單元素 | input、textarea、select、button |
data-testid="login-email" |
| 導航連結 | 帶有 routerLink 的元素 |
data-testid="nav-home" |
| 可點擊元素 | 帶有 (click) 事件的元素 |
data-testid="deck-item-123" |
可省略 testId 的元素
- 純裝飾性元素（icon、分隔線）
- 靜態文字內容（標題、說明文字）
ng-container、ng-template等結構性元素
testId 命名規範
格式：{page/context}-{element}[-{qualifier}]
- page/context：從檔案路徑取得頁面名稱（如
deck-detail、login） - element：元素用途（如
submit、back、search、email） - qualifier：可選，用於區分相似元素
命名對照表
| 元素類型 | 命名方式 | 範例 |
|---|---|---|
| 提交按鈕 | {page}-submit |
login-submit |
| 取消按鈕 | {page}-cancel |
deck-form-cancel |
| 返回按鈕 | {page}-back |
deck-detail-back |
| 設定按鈕 | {page}-settings |
deck-detail-settings |
| 輸入欄位 | {page}-{field} |
login-email |
| 搜尋框 | {page}-search |
deck-list-search |
| 錯誤訊息 | {page}-error |
login-error |
| 列表項目 | {item}-item-{id} |
deck-item-{id} |
| FAB 按鈕 | {page}-{action} |
deck-detail-add-card |
使用方式
<!-- UI 元件使用 testId 屬性 -->
<fm-button testId="login-submit">登入</fm-button>
<fm-labeled-input testId="login-email" ... />
<fm-icon-button testId="deck-detail-back" ... />
<!-- 原生元素使用 data-testid 屬性 -->
<div data-testid="deck-list-empty">尚無牌組</div>
<button data-testid="card-delete">刪除</button>開發步驟
- 辨識頁面中的可互動元素（按鈕、輸入框、連結等）
- 根據命名規範決定 testId 名稱
- UI 元件使用
testId屬性，原生元素使用data-testid - 確保同一頁面內 testId 不重複
參考
- ADR-019：前端 testId 規範
- AGENTS.md：E2E 測試選擇器規範