Config 配置

export_vars、datatable_parameters 與 allow_dynamic_parameters 的完整設定參考

自訂指令透過三個 OPTIONAL 欄位擴充基礎的三欄結構，讓 Linter 擁有完整的輸入/輸出契約。

Instruction Object（完整欄位）

欄位	型別	必填	說明
`name`	`string`	REQUIRED	指令唯一識別名。用於錯誤訊息；同一 `isa.yml` 內不得重複。
`format`	`string (regex)`	REQUIRED	匹配 Gherkin Step 的正則表達式。以 `(?P<name>...)` 具名群組擷取步驟參數。
`instruction_type`	`enum`	REQUIRED	本章節適用值為 `custom`。
`export_vars`	`map<string, ExportVar>`	OPTIONAL	此指令執行後可導出的變數契約。Map key 為變數名樣式（可含 `{{param}}` 插值）。
`datatable_parameters`	`map<string, DatatableParam>`	OPTIONAL	DataTable 欄位 Schema。
`allow_dynamic_parameters`	`boolean`	OPTIONAL	預設 `false`。為 `true` 時 Linter 接受任意 header。

allow_dynamic_parameters

值	行為
`false`（預設）	DataTable 中出現未宣告的 header 時觸發 `error`
`true`	Linter 接受任意 header，不報錯

適用場景：指令的 Step Definition 接受任意鍵值對時（例如商品擴充欄位），設為 true 可避免每次新增欄位都要更新 schema。

- name: Product setup
  format: ^"(?P<alias>[^"]+)" 是一個商品 "(?P<productCode>[^"]+)", with table:$
  instruction_type: custom
  allow_dynamic_parameters: true    # ← 接受任意 DataTable 欄位

  datatable_parameters:
    name:
      type: String
      required: true
      description: "商品名稱（必填）"

上例中 name 為必填，其餘欄位任意。

對應的 Gherkin 用法：

Given "Widget" 是一個商品 "WIDGET_01", with table:
  | name   | color | weight |
  | 小元件 | red   | 150    |

# Linter 驗證：
#   ✓ name 為已宣告的必填欄位
#   ✓ color、weight 未宣告，但 allow_dynamic_parameters: true → 不報錯

export_vars（輸出層）

宣告此指令執行後會導出哪些 $var，供後續步驟引用。

ExportVar Object

欄位	型別	必填	說明
`type`	`string`	REQUIRED	變數型別。允許值：`String`、`Boolean`、`Number`。
`description`	`string`	REQUIRED	變數語義說明，顯示於 IDE hover 與生成文件。
`example`	`scalar`	OPTIONAL	示例值（number / string / boolean）。
`nullable`	`boolean`	OPTIONAL（預設 `false`）	`true` 時允許 null/空值；`false` 時 null 觸發 `error`。

`{{param}}` 插值

export_vars 的 Map key 可使用 {{param}} 語法引用 format 正則中的具名擷取群。這讓匯出變數的名稱隨步驟參數動態生成。

- name: Admin setup
  format: ^"(?P<alias>[^"]+)" 是一個管理員, with table:$
  instruction_type: custom

  export_vars:
    "{{alias}}.id":             # ← alias 來自 format 的 (?P<alias>...)
      type: Number
      description: "管理員 ID"
      example: 1
      nullable: false
    "{{alias}}.account":
      type: String
      description: "管理員登入帳號"
      example: "sam"
      nullable: false

對應的 Gherkin 用法：

Given "SAM" 是一個管理員, with table:
  | role        |
  | SUPER_ADMIN |

# alias 擷取到 "SAM"，Linter 知道此 step 導出：
#   $SAM.id      → Number
#   $SAM.account → String

When (UID="$SAM.id") 執行某操作, call table:
  | account        |
  | $SAM.account   |

# Linter 驗證：
#   ✓ $SAM.id 存在且型別為 Number
#   ✓ $SAM.account 存在且型別為 String

型別

型別	說明
`String`	字串
`Number`	整數或帶小數的數值
`Boolean`	`true` / `false`

datatable_parameters（輸入層）

宣告此指令的 DataTable 接受哪些欄位，讓 Linter 在 lint-time 驗證 header 拼字、型別與必填性。

DatatableParam Object

欄位	型別	必填	說明
`type`	`string`	REQUIRED	欄位型別。允許值：`String`、`Number`、`Boolean`、`Time`。
`description`	`string`	REQUIRED	欄位語義說明，顯示於 IDE hover 與生成文件。
`required`	`boolean`	OPTIONAL（預設 `false`）	`true` 時 DataTable 缺少此欄位觸發 `error`。
`enums`	`array<scalar>`	OPTIONAL	枚舉限制；值不在清單內觸發 `error`。

型別

型別	接受值
`String`	任意字串
`Number`	整數與帶小數的數值
`Boolean`	`true` / `false`
`Time`	`@time`、`@date`、`@localTime` 時間表達式

範例

- name: Admin setup
  format: ^"(?P<alias>[^"]+)" 是一個管理員, with table:$
  instruction_type: custom

  datatable_parameters:
    role:
      type: String
      required: true
      description: "管理員角色"
      enums: ["SUPER_ADMIN", "EDITOR", "VIEWER"]
    department:
      type: String
      required: false
      description: "所屬部門"

對應的 Gherkin 用法：

Given "SAM" 是一個管理員, with table:
  | role        | department |
  | SUPER_ADMIN | 營運部     |

# Linter 驗證：
#   ✓ role 為必填欄位且值 "SUPER_ADMIN" 在 enums 內
#   ✓ department 為已宣告的選填欄位
#   ✗ 若寫成 deparment（少一個 t）→ error：未宣告的欄位
#   ✗ 若 role 值為 "ADMIN" → error：不在 enums 內
#   ✗ 若省略 role → error：必填欄位缺失

完整範例

- name: Admin setup
  format: ^"(?P<alias>[^"]+)" 是一個管理員, with table:$
  instruction_type: custom

  export_vars:
    "{{alias}}.id":
      type: Number
      description: "管理員 ID"
      example: 1
      nullable: false
    "{{alias}}.account":
      type: String
      description: "管理員登入帳號"
      example: "sam"
      nullable: false

  datatable_parameters:
    role:
      type: String
      required: true
      description: "管理員角色"
      enums: ["SUPER_ADMIN", "EDITOR", "VIEWER"]
    department:
      type: String
      required: false
      description: "所屬部門"

Config 配置

目錄