SpecFormula.Dsl 0.0.1

dotnet add package SpecFormula.Dsl --version 0.0.1

NuGet\Install-Package SpecFormula.Dsl -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.Dsl" Version="0.0.1">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>

For projects that support PackageReference, copy this XML node into the project file to reference the package.

<PackageVersion Include="SpecFormula.Dsl" Version="0.0.1" />
                    

                            Directory.Packages.props

<PackageReference Include="SpecFormula.Dsl">
  <PrivateAssets>all</PrivateAssets>
  <IncludeAssets>runtime; build; native; contentfiles; analyzers</IncludeAssets>
</PackageReference>
                    

                            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.Dsl --version 0.0.1

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

#r "nuget: SpecFormula.Dsl, 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.Dsl@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.Dsl&version=0.0.1
                    

                            Install as a Cake Addin

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

                            Install as a Cake Tool

The NuGet Team does not provide support for this client. Please contact its maintainers for support.

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	基礎建設與依賴架構

There are no supported framework assets in this package.

Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

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