SpecFormula.Core 0.0.1

SpecFormula C#

SpecFormula C# 框架，將 ISA 規格驅動的 BDD 測試自動化帶入 .NET 生態系。基於 .NET 10.0 (LTS)。

驗收狀態

專案架構

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

純核心邏輯，無框架依賴。

規格解析

指令引擎

符號系統

工具類

SpecFormula.AspNetCore

ASP.NET Core 整合層。

SpecFormula.Reqnroll

Reqnroll BDD 整合層。Assembly 名稱：SpecFormula.ReqnrollPlugin

支援格式：DataTable + JSON DocString（with JSON: 語法）

SpecFormula.Testcontainers

自動啟動資料庫容器、FK 拓撲排序建表、場景結束自動清理。

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