SpecFormula.Testcontainers 0.0.1

.NET 8.0 This package targets .NET 8.0. The package is compatible with this framework or higher. 
dotnet add package SpecFormula.Testcontainers --version 0.0.1
                    


                    

                
NuGet\Install-Package SpecFormula.Testcontainers -Version 0.0.1
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="SpecFormula.Testcontainers" Version="0.0.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="SpecFormula.Testcontainers" Version="0.0.1" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="SpecFormula.Testcontainers" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add SpecFormula.Testcontainers --version 0.0.1
                    


                    

                
#r "nuget: SpecFormula.Testcontainers, 0.0.1"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package SpecFormula.Testcontainers@0.0.1
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=SpecFormula.Testcontainers&version=0.0.1
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=SpecFormula.Testcontainers&version=0.0.1
                    


                            Install as a Cake Tool

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、&gt、&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

ADR 說明
csharp-0001 基礎建設與依賴架構
Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.0.1 94 5/18/2026