設定檔

SpecFormula 透過 isa.yml 配置檔定義測試框架的運行規格，包含 API Spec、Entity Spec 和指令映射三個部分。

專案結構

isa.yml 放置於測試資源目錄的根層級，與 Spec 檔案和測試檔案共同組成完整的測試專案：

src/test/resources/
├── isa.yml                              # ISA 設定檔
├── specs/
│   ├── api/
│   │   └── api-spec.yml                 # API Spec（OpenAPI 3.0）
│   └── data/
│       ├── schema.sql                   # DDL 定義
│       └── entity_to_table_mapping.yml  # Entity 對應表
└── features/
    └── todo.feature                     # Gherkin 測試檔

完整範例

config:
  api:
    resource_path: specs/api
    project_path: my-project/src/test/resources/specs/api
    time_format: ISO
  data:
    source:
      - name: default
        resource_path: specs/data
        project_path: my-project/src/test/resources/specs/data
        db_type: postgresql

instructions:
  - name: Time control
    format: ^現在的時間是 "(?P<time>.+)"$
    instruction_type: time_control

  - name: Data preparation
    format: ^準備一個(?P<entity>[\u4e00-\u9fffa-zA-Z0-9_]+), with table:$
    instruction_type: entity_setup

  - name: API call
    format: ^\((?:No Actor|UID="(?P<userId>\$[\w.]+)")\) (?P<summary>.+?), call table:$
    instruction_type: api_call

  - name: API call (JSON)
    format: ^\((?:No Actor|UID="(?P<userId>\$[\w.]+)")\) (?P<summary>.+?), call JSON:$
    instruction_type: api_call
    data_format: json

  - name: Response validation
    format: ^(?P<summary>.+?)\((?P<status_code>\d{3})\)回應,?\s*with table:$
    instruction_type: response_validate

  - name: Response validation (JSON)
    format: ^(?P<summary>.+?)\((?P<status_code>\d{3})\)回應為,?\s*with JSON:$
    instruction_type: response_validate
    data_format: json

  - name: Database validation
    format: ^應該存在一個(?P<entity>[\u4e00-\u9fffa-zA-Z0-9_]+), with table:$
    instruction_type: entity_validate

  - name: Database validation (JSON)
    format: ^應該存在一個(?P<entity>[\u4e00-\u9fffa-zA-Z0-9_]+), with json:$
    instruction_type: entity_validate
    data_format: json

  - name: Database non-existence validation
    format: ^應該不存在一個(?P<entity>[\u4e00-\u9fffa-zA-Z0-9_]+), with table:$
    instruction_type: entity_non_existence_validate

  - name: Data preparation (JSON)
    format: ^準備一個(?P<entity>[\u4e00-\u9fffa-zA-Z0-9_]+), with json:$
    instruction_type: entity_setup
    data_format: json

API 配置

config.api 設定 API Spec 檔案的位置：

欄位	說明	預設值
`resource_path`	API Spec 在 classpath 中的路徑（必填）	—
`project_path`	API Spec 在專案中的路徑（供 Lint 使用，必填）	—
`time_format`	時間表達式的輸出格式	`ISO`

resource_path：測試執行時的 classpath 路徑，框架用來讀取 Spec 檔案
project_path：原始碼中的檔案路徑，供 Lint 工具定位檔案並報告錯誤位置

時間格式

值	輸出範例
`ISO`（預設）	`"2025-12-25T14:30:00+08:00"`
`TIMESTAMP`	`1766735400000`（Unix 毫秒）
`EPOCH`	`1766735400`（Unix 秒）
`DATE_ONLY`	`"2025-12-25"`
`TIME_ONLY`	`"14:30:00"`

資料庫配置

config.data 設定資料庫規格檔的位置，支援多資料源：

欄位	說明	預設值
`permission`	資料源權限隔離模式	`isolated`
`reuse`	是否重用 Testcontainer 容器	`false`
`source`	資料源列表	—

permission: isolated：各 DataSource 之間權限隔離，無法互相存取對方的資料表
permission: shared：各 DataSource 之間權限共通，可互相存取資料表
reuse: true：重用 Testcontainer 容器，避免每次測試都重新啟動，加快執行速度

每個 source 項目的欄位：

欄位	說明	預設值
`name`	資料源名稱（必填）	—
`resource_path`	DDL 與 mapping 檔案在 classpath 中的路徑（必填）	—
`project_path`	DDL 與 mapping 檔案在專案中的路徑（供 Lint 使用，必填）	—
`db_type`	資料庫類型：`embedded`、`postgresql`、`mysql`、`mssql`。`embedded` 為「框架選實作」抽象代名（Java→H2、C#→sqlite-style、Python→DuckDB）。	`embedded`
`schema`	指定 DataSource 連線的預設 schema（選填）	資料庫預設值

Schema 設定

schema 欄位用於企業級多 schema 架構，指定 DataSource 連線的預設 schema：

config:
  data:
    source:
      - name: default
        resource_path: specs/data
        db_type: postgresql
        schema: app_schema       # 選填

各資料庫的行為差異：

db_type	schema 行為	預設 schema
`postgresql`	設定 `search_path` 為 `"<schema>", public`	`public`
`mssql`	設定連線的 `DEFAULT_SCHEMA`	`dbo`
`mysql` / `mariadb`	忽略（schema 等同於 database，由連線 URL 決定）	N/A
`embedded`	忽略（內嵌測試資料庫，不支援多 schema 路由；Java 實作使用 H2）	`PUBLIC`

DDL 中的 CREATE TABLE 語句可包含 schema 前綴（如 CREATE TABLE dbo.users (...)），框架會擷取並保存 schema 前綴，在生成的 SQL 中使用完整限定名（schema.table）。

資料夾結構

specs/data/
├── schema.sql                    # DDL 定義
└── entity_to_table_mapping.yml   # Entity 到 Table 的對應

Entity Mapping

定義 Gherkin 中使用的業務名稱與資料表的對應：

entity_to_table_mapping:
  - 使用者: users
  - 待辦事項: todos

使用時：

Given 準備一個使用者, with table:
  | name  | email             |
  | Alice | alice@example.com |

指令映射

instructions 定義 Gherkin Step 文字與 ISA 指令的對應關係：

欄位	說明
`name`	指令名稱（用於識別與錯誤訊息）
`format`	正則表達式，用於匹配 Gherkin Step
`instruction_type`	對應的 ISA 指令類型
`data_format`	Step payload 格式：`none`、`data_table`、`json`、`text`。省略時依 `instruction_type` 決定預設值。

data_format payload contract

data_format 描述 Step 後方是否需要 DataTable 或 DocString，以及 DocString 內容應如何解析。這是 ISA 與各語言 runtime 的共同契約。

data_format	Payload	用途
`none`	無 payload	不接 DataTable / DocString 的指令；`custom` 預設為 `none`。
`data_table`	Gherkin DataTable	表格型資料準備、API call、回應驗證、Entity 驗證。
`json`	JSON DocString	JSON body、JSON response expectation、JSON Entity payload。
`text`	Text DocString	純文字 payload；若 Step 使用文字 DocString，必須明確設定 `data_format: text`。

預設規則：

內建 ISA 指令若未指定 data_format，預設為 data_table。
instruction_type: custom 若未指定 data_format，預設為 none，代表 Step Definition 自行決定行為且不由 ISA runtime 解析 payload。
JSON DocString 必須設定 data_format: json。
純文字 DocString 必須設定 data_format: text，避免被誤判成無 payload 或 JSON。

範例：

instructions:
  - name: Custom log message
    format: ^記錄訊息:$
    instruction_type: custom
    data_format: text

  - name: Custom checkpoint
    format: ^標記檢查點 (?P<name>.+)$
    instruction_type: custom
    # data_format 省略，custom 預設為 none

指令類型對照

instruction_type	對應指令
`time_control`	TimeControl
`entity_setup`	EntitySetup
`api_call`	ApiCall
`response_validate`	ResponseValidate
`entity_validate`	EntityValidate
`entity_non_existence_validate`	EntityNonExistenceValidate
`custom`	自訂指令

正則表達式與 Gherkin 的對應

ISA 的指令映射 不支援 Cucumber Expression（例如 {int}、{string}）。

format 必須使用 正則表達式 完整匹配 Gherkin Step 文字，並透過 命名擷取群組（named capture group） 取得參數。

Python 寫法：(?P<name>...)
Java/JVM 寫法：(?<name>...)

以 api_call 為例：

Gherkin:  (UID="$Alice.id") 新增待辦事項, call table:
正則（Python）: ^\((?:No Actor|UID="(?P<userId>...)")\) (?P<summary>.+?), call table:$
正則（Java）:   ^\((?:No Actor|UID="(?<userId>...)")\) (?<summary>.+?), call table:$
擷取:              userId = $Alice.id      summary = 新增待辦事項

擷取群組一覽

instruction_type	必要群組
`time_control`	`time`
`entity_setup`	`entity`
`api_call`	`summary`、`userId`（選填）
`response_validate`	`summary`、`status_code`
`entity_validate`	`entity`
`entity_non_existence_validate`	`entity`
`custom`	（依自訂 Step Definition 決定）