SpecFormula C#
SpecFormula C# 框架，將 ISA 規格驅動的 BDD 測試自動化帶入 .NET 生態系。基於 .NET 10.0 (LTS)。
驗收狀態
| 測試類別 |
結果 |
| 框架單元測試 |
772/772 pass |
| ecommerce benchmark（排除 @expected-failure） |
132/132 pass |
| ecommerce benchmark（@expected-failure） |
25/25 正確失敗 |
專案架構
specformula-csharp/
├── src/
│ ├── SpecFormula.Core # 核心層：規格解析、指令引擎、符號系統
│ ├── SpecFormula.Core.Tests # 核心層單元測試（772 tests）
│ ├── SpecFormula.AspNetCore # 整合層：ASP.NET Core Bridge、HTTP Adapter、Auth
│ ├── SpecFormula.Reqnroll # BDD 層：Reqnroll Plugin、動態 Step 註冊、Hooks
│ └── SpecFormula.Testcontainers # 測試容器層：PostgreSQL / MySQL / MSSQL 自動管理
└── specs/
└── adr/ # 專案級 ADR
模組依賴關係
SpecFormula.Testcontainers ──┐
├──► SpecFormula.AspNetCore ──► SpecFormula.Core
SpecFormula.Reqnroll ────────┘
SpecFormula.Core
純核心邏輯，無框架依賴。
規格解析
| 類別 |
說明 |
IsaSpecReader |
讀取 isa.yml，產出 IsaSpec |
ApiSpecReader |
讀取 OpenAPI YAML（支援 $ref 跨檔引用），產出 ApiSpec |
EntityDdlReader |
解析 SQL DDL + entity_to_table_mapping.yml，FK 拓撲排序，產出 DatabaseSchema |
指令引擎
| 類別 |
說明 |
ApiCall |
HTTP 請求建構、變數/時間替換、回應變數擷取 |
DataTableResponseValidate |
HTTP 回應驗證（狀態碼 + 欄位 + CAS 約束） |
EntitySetup |
記憶體 Entity 準備（INSERT + TypeConverter 型別對齊） |
EntityValidate |
Entity 存在驗證（PK/QBE 查詢 + CAS 約束） |
EntityNonExistenceValidate |
Entity 不存在驗證 |
ResponseSchemaValidator |
OpenAPI Schema 驗證 |
符號系統
| 類別 |
說明 |
VarSystem |
$var、>${contextKey}、<executionKey、${interpolation} |
TimeSystem |
@time()、@date()、@localtime()、相對時間（now-1d） |
CasSystem |
&eq、>、&contains、&sameTime、&withinDays 等 30+ 約束 |
工具類
| 類別 |
說明 |
TypeConverter |
SQL column type → .NET type 轉換（支援 TIMESTAMPTZ/UTC 區分） |
NamingConverter |
snake_case ↔ camelCase |
IdentifierUtils |
跨 DB SQL 識別符引號 |
SpecFormulaJsonParser |
SpecFormula JSON 解析（支援 $var、@time、&constraint） |
JsonToDataTableConverter |
JSON → DataTable 扁平化 |
SpecFormula.AspNetCore
ASP.NET Core 整合層。
| 類別 |
說明 |
SpecFormulaBridge |
Singleton：ScenarioContext (AsyncLocal)、ConnectionFactory、HttpClient、MockTime |
IAuthenticator |
Actor ID → API Token 介面 |
WebApplicationFactoryHttpClientAdapter |
in-process 測試用 HTTP Adapter |
SpecFormula.Reqnroll
Reqnroll BDD 整合層。Assembly 名稱：SpecFormula.ReqnrollPlugin
| 類別 |
說明 |
SpecFormulaPlugin |
IRuntimePlugin：從 isa.yml 動態註冊 Step Definitions |
IsaStepHandler |
partial class 調度器（EntitySetup / EntityValidate / ApiCall / ResponseValidate / TimeControl） |
TestRunHooks |
[BeforeTestRun(Order=0)]：讀取 specs、初始化 Bridge |
ScenarioHooks |
[BeforeScenario] / [AfterScenario]：場景生命週期 |
支援格式：DataTable + JSON DocString（with JSON: 語法）
SpecFormula.Testcontainers
自動啟動資料庫容器、FK 拓撲排序建表、場景結束自動清理。
| db_type |
容器映像 |
postgresql |
postgres:16-alpine |
mysql |
mysql:8.0 |
mssql |
mcr.microsoft.com/mssql/server:2022-latest |
Hook 執行順序
Order=0 TestRunHooks 讀取 isa.yml / schema / api spec → 初始化 Bridge
Order=10 TestcontainerHooks 啟動容器 → 註冊 ConnectionFactory → FK 排序建表
Order=100 User TestConfig 取得連線字串 → 配置 WebApplicationFactory → HttpClient
導入指南
測試專案結構
MyProject.Tests/
├── Features/ # .isa.feature（Reqnroll 自動產生 .feature.cs）
├── specs/
│ ├── api/api-spec.yml
│ └── data/
│ ├── schema.sql
│ └── entity_to_table_mapping.yml
├── isa.yml
├── reqnroll.json
├── xunit.runner.json
└── TestConfig.cs
Step 1: 加入專案參考
<ProjectReference Include="SpecFormula.Core" />
<ProjectReference Include="SpecFormula.AspNetCore" />
<ProjectReference Include="SpecFormula.Reqnroll" />
<ProjectReference Include="SpecFormula.Testcontainers" />
Step 2: reqnroll.json
{
"stepAssemblies": [
{ "assembly": "SpecFormula.ReqnrollPlugin" },
{ "assembly": "SpecFormula.Testcontainers" }
]
}
Step 3: TestConfig.cs
[Binding]
public class TestConfig : IAuthenticator
{
private static WebApplicationFactory<Program>? _factory;
[BeforeTestRun(Order = 100)]
public static void Setup()
{
var bridge = SpecFormulaBridge.Instance;
var connStr = bridge.GetConnectionString("default")!;
_factory = new WebApplicationFactory<Program>()
.WithWebHostBuilder(builder =>
{
builder.UseSetting("ConnectionString", connStr);
});
bridge.SetHttpClient(new WebApplicationFactoryHttpClientAdapter(_factory.CreateClient()));
bridge.SetAuthenticator(new TestConfig());
}
[AfterTestRun]
public static void TearDown() => _factory?.Dispose();
public string GetToken(object actorId)
=> new AuthService().GenerateToken(Convert.ToInt64(actorId));
}
Step 4: 確保檔案複製到 output
<ItemGroup>
<None Update="isa.yml" CopyToOutputDirectory="PreserveNewest" />
<None Update="specs\**\*" CopyToOutputDirectory="PreserveNewest" />
<Content Include="reqnroll.json" CopyToOutputDirectory="PreserveNewest" />
<Content Include="xunit.runner.json" CopyToOutputDirectory="PreserveNewest" />
</ItemGroup>
Feature File 同步
全域 Feature File 位於 specs/features/，透過術語替換同步到 C#：
./scripts/sync-global-features.sh csharp
術語對照表：specs/features/terminology-mapping-csharp.yml
ADR
