universal-dev-standards 4.2.0 → 5.0.0-beta.10

package/bundled/locales/zh-TW/skills/bdd-assistant/gherkin-guide.md

@@ -0,0 +1,454 @@
+---
+source: ../../../../skills/bdd-assistant/gherkin-guide.md
+source_version: 1.0.0
+translation_version: 1.0.0
+last_synced: 2026-02-05
+status: current
+---
+
+# Gherkin 快速參考指南
+
+**版本**: 1.0.0
+**最後更新**: 2026-01-19
+
+---
+
+## 概述
+
+Gherkin 是一種商業可讀、領域特定的語言，用於描述軟體行為而不詳述該行為如何實作。
+
+---
+
+## 關鍵字
+
+### Feature
+
+相關場景的容器。
+
+```gherkin
+Feature: 購物車
+  As a 客戶
+  I want 管理我的購物車
+  So that 我可以購買我想要的產品
+```
+
+### Scenario
+
+描述特定行為的單一測試案例。
+
+```gherkin
+Scenario: 新增商品到空購物車
+  Given 我有一個空的購物車
+  When 我新增「Widget」到我的購物車
+  Then 我的購物車應該包含 1 個商品
+```
+
+### Given
+
+設定初始情境或狀態。
+
+```gherkin
+Given 我以 "admin@example.com" 登入
+Given 我的購物車有 3 個商品
+Given 存在以下使用者:
+  | email            | role  |
+  | user@example.com | user  |
+  | admin@example.com| admin |
+```
+
+### When
+
+觸發動作或事件。
+
+```gherkin
+When 我點擊「提交」按鈕
+When 我搜尋「筆電」
+When 我新增「Widget」到我的購物車
+```
+
+### Then
+
+斷言預期結果。
+
+```gherkin
+Then 我應該看到「訂單已確認」
+Then 我的購物車總計應該是 $99.99
+Then 我應該收到確認電子郵件
+```
+
+### And / But
+
+延續前一個關鍵字。
+
+```gherkin
+Scenario: 使用有效憑證登入
+  Given 我在登入頁面
+  And 我有一個註冊帳號
+  When 我輸入我的電子郵件
+  And 我輸入我的密碼
+  And 我點擊登入
+  Then 我應該看到我的儀表板
+  And 我應該看到歡迎訊息
+  But 我不應該看到登入表單
+```
+
+### Background
+
+功能中所有場景的共同設定。
+
+```gherkin
+Feature: 使用者個人資料
+  Background:
+    Given 我已登入
+    And 我在我的個人資料頁面
+
+  Scenario: 更新顯示名稱
+    When 我將顯示名稱改為「新名稱」
+    Then 我的顯示名稱應該是「新名稱」
+
+  Scenario: 更新電子郵件
+    When 我將電子郵件改為 "new@example.com"
+    Then 我的電子郵件應該是 "new@example.com"
+```
+
+### Scenario Outline
+
+帶多組資料的範本。
+
+```gherkin
+Scenario Outline: 計算折扣
+  Given 我的購物車總計 <cart_total>
+  When 我套用折扣碼 "<code>"
+  Then 我的總計應該是 <final_total>
+
+  Examples:
+    | cart_total | code    | final_total |
+    | $100       | SAVE10  | $90         |
+    | $100       | SAVE20  | $80         |
+    | $50        | SAVE10  | $45         |
+```
+
+---
+
+## 資料表格
+
+### 雜湊表格（具名欄位）
+
+```gherkin
+Given 存在以下使用者:
+  | name  | email            | role  |
+  | John  | john@example.com | admin |
+  | Jane  | jane@example.com | user  |
+```
+
+```typescript
+// 步驟定義
+Given('存在以下使用者:', async function (dataTable) {
+  const users = dataTable.hashes();
+  // users = [
+  //   { name: 'John', email: 'john@example.com', role: 'admin' },
+  //   { name: 'Jane', email: 'jane@example.com', role: 'user' }
+  // ]
+  for (const user of users) {
+    await createUser(user);
+  }
+});
+```
+
+### 原始表格（無標題）
+
+```gherkin
+Given 我有以下商品:
+  | Widget A |
+  | Widget B |
+  | Widget C |
+```
+
+```typescript
+// 步驟定義
+Given('我有以下商品:', async function (dataTable) {
+  const items = dataTable.raw().flat();
+  // items = ['Widget A', 'Widget B', 'Widget C']
+});
+```
+
+### 列陣列
+
+```gherkin
+Given 這些價格等級:
+  | tier     | min | max  | discount |
+  | Bronze   | 0   | 99   | 0%       |
+  | Silver   | 100 | 499  | 5%       |
+  | Gold     | 500 | 999  | 10%      |
+```
+
+```typescript
+// 步驟定義
+Given('這些價格等級:', async function (dataTable) {
+  const rows = dataTable.rows();
+  // rows = [
+  //   ['Bronze', '0', '99', '0%'],
+  //   ['Silver', '100', '499', '5%'],
+  //   ['Gold', '500', '999', '10%']
+  // ]
+});
+```
+
+---
+
+## Doc Strings
+
+用於多行文字內容。
+
+```gherkin
+Scenario: 建立文章
+  Given 我在新文章頁面
+  When 我輸入以下內容:
+    """
+    # 歡迎
+
+    這是文章內容。
+
+    - 要點 1
+    - 要點 2
+    """
+  And 我點擊發布
+  Then 文章應該被建立
+```
+
+---
+
+## Tags
+
+組織和篩選場景。
+
+### 常用 Tags
+
+```gherkin
+@smoke @critical
+Feature: 使用者認證
+
+  @happy-path
+  Scenario: 成功登入
+    ...
+
+  @error-handling
+  Scenario: 失敗登入
+    ...
+
+  @wip
+  Scenario: 雙因素認證
+    ...
+
+  @slow @integration
+  Scenario: SSO 登入
+    ...
+```
+
+### Tag 類別
+
+| Tag | 用途 |
+|-----|------|
+| `@smoke` | 快速健全性測試 |
+| `@critical` | 高優先級功能 |
+| `@wip` | 進行中的工作 |
+| `@slow` | 長時間執行的測試 |
+| `@manual` | 需要手動驗證 |
+| `@skip` | 暫時禁用 |
+| `@integration` | 整合測試 |
+| `@api` | API 層級測試 |
+| `@ui` | UI 層級測試 |
+
+### 使用 Tags 執行
+
+```bash
+# 只執行 smoke 測試
+cucumber --tags @smoke
+
+# 執行 critical 但不執行 slow 測試
+cucumber --tags "@critical and not @slow"
+
+# 執行 smoke 或 critical 測試
+cucumber --tags "@smoke or @critical"
+```
+
+---
+
+## 本地化
+
+Gherkin 支援多種語言。
+
+### 英文（預設）
+
+```gherkin
+Feature: Shopping Cart
+  Scenario: Add item
+    Given I have an empty cart
+    When I add an item
+    Then my cart should have 1 item
+```
+
+### 繁體中文 (zh-TW)
+
+```gherkin
+# language: zh-TW
+功能: 購物車
+  場景: 新增商品
+    假設 我有一個空的購物車
+    當 我新增一個商品
+    那麼 我的購物車應該有 1 個商品
+```
+
+### 簡體中文 (zh-CN)
+
+```gherkin
+# language: zh-CN
+功能: 购物车
+  场景: 添加商品
+    假如 我有一个空的购物车
+    当 我添加一个商品
+    那么 我的购物车应该有 1 个商品
+```
+
+### 日文 (ja)
+
+```gherkin
+# language: ja
+機能: ショッピングカート
+  シナリオ: 商品を追加
+    前提 カートが空である
+    もし 商品を追加する
+    ならば カートには 1 個の商品がある
+```
+
+---
+
+## 最佳實踐
+
+### 應該
+
+```gherkin
+# ✅ 宣告式 - 描述行為
+Scenario: 成功結帳
+  Given 我的購物車有商品
+  And 我已登入
+  When 我使用有效付款完成結帳
+  Then 我的訂單應該被確認
+
+# ✅ 商業語言
+Scenario: 套用會員折扣
+  Given 我是金卡會員
+  And 我的購物車總計 $100
+  When 我進入結帳
+  Then 我應該獲得 15% 折扣
+
+# ✅ 獨立場景
+# 每個場景設定自己的情境
+Scenario: 新使用者註冊
+  Given 我是新訪客
+  When 我使用有效資訊註冊
+  Then 我應該擁有一個帳號
+```
+
+### 不應該
+
+```gherkin
+# ❌ 命令式 - 太技術
+Scenario: 登入
+  Given 我導航到 "/login"
+  And 我輸入 "user@example.com" 到 "#email"
+  And 我輸入 "password" 到 "#password"
+  And 我點擊 "#submit"
+  Then 我應該看到元素 ".dashboard"
+
+# ❌ 技術術語
+Scenario: API 認證
+  Given 我 POST 到 "/api/auth" 帶 JSON payload
+  Then 回應碼應該是 200
+  And 回應應該包含 "token"
+
+# ❌ 相依場景
+Scenario: 步驟 1 - 建立使用者
+  ...
+Scenario: 步驟 2 - 以上面建立的使用者登入
+  # 這依賴於 Scenario 1 先執行！
+```
+
+---
+
+## 常見模式
+
+### Page Object 整合
+
+```gherkin
+# 場景引用頁面，不是元素
+Scenario: 導航到結帳
+  Given 我在購物車頁面
+  When 我點擊進入結帳
+  Then 我應該在結帳頁面
+```
+
+### 資料驅動測試
+
+```gherkin
+Scenario Outline: 驗證電子郵件格式
+  When 我以電子郵件 "<email>" 註冊
+  Then 我應該看到 "<message>"
+
+  Examples:
+    | email           | message         |
+    | valid@test.com  | 成功            |
+    | invalid         | 無效電子郵件    |
+    | @test.com       | 無效電子郵件    |
+    |                 | 需要電子郵件    |
+```
+
+### Hooks（非 Gherkin）
+
+```typescript
+// 在步驟定義中
+import { Before, After, BeforeAll, AfterAll } from '@cucumber/cucumber';
+
+BeforeAll(async function () {
+  // 所有場景前設定一次
+  await database.connect();
+});
+
+Before(async function () {
+  // 每個場景前設定
+  await database.beginTransaction();
+});
+
+After(async function () {
+  // 每個場景後清理
+  await database.rollback();
+});
+
+AfterAll(async function () {
+  // 所有場景後清理一次
+  await database.disconnect();
+});
+```
+
+---
+
+## 各語言工具
+
+| 語言 | 工具 | 套件 |
+|------|------|------|
+| JavaScript | Cucumber.js | `@cucumber/cucumber` |
+| TypeScript | Cucumber.js | `@cucumber/cucumber` |
+| Python | Behave | `behave` |
+| Python | pytest-bdd | `pytest-bdd` |
+| Java | Cucumber-JVM | `io.cucumber:cucumber-java` |
+| C# | SpecFlow | `SpecFlow` |
+| Ruby | Cucumber | `cucumber` |
+| Go | Godog | `github.com/cucumber/godog` |
+
+---
+
+## 相關資源
+
+- [BDD 工作流程指南](./bdd-workflow.md)
+- [BDD 核心標準](../../../../core/behavior-driven-development.md)
+- [官方 Gherkin 參考](https://cucumber.io/docs/gherkin/reference/)