SpecFormula.AspNetCore 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.AspNetCore --version 0.0.1
                    


                    

                
NuGet\Install-Package SpecFormula.AspNetCore -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.AspNetCore" Version="0.0.1" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="SpecFormula.AspNetCore" Version="0.0.1" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="SpecFormula.AspNetCore" />
                    


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


                    

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


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=SpecFormula.AspNetCore&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 (2)

Showing the top 2 NuGet packages that depend on SpecFormula.AspNetCore:

Package Downloads
SpecFormula.Reqnroll

SpecFormula Reqnroll Plugin：動態 Step Definition 註冊、ISA 指令派發、Reqnroll runtime plugin 整合（reqnroll.json 配置以 SpecFormula.ReqnrollPlugin 為名）。
SpecFormula.Testcontainers

SpecFormula Testcontainers 整合（選配）：PostgreSQL / MySQL / MSSQL 容器自動管理，與 SpecFormulaBridge cleanup 機制對接。

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.0.1 138 5/18/2026