Skip to content

C# module unit testing - #6501

Open
lisandroct wants to merge 31 commits into
masterfrom
lisandro/csharp-module-unit-testing-split
Open

lisandroct wants to merge 31 commits into
masterfrom
lisandro/csharp-module-unit-testing-split

Conversation

@lisandroct

@lisandroct lisandroct commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Description of Changes

Depends on: #6499 and #6500

Adds unit testing for C# modules. Tests call reducers, procedures, views and typed queries directly, in-process, against the real datastore.

using var test = ModuleTestContext.Create(typeof(Module).Assembly);
test.Clock.Set(new Timestamp(1_000_000));
test.WithReducerTx(TestAuth.Internal(), ctx => Module.SendMessage(ctx, "Hello!"));
Assert.Equal("Hello!", Assert.Single(test.Db.Message.Iter()).Text);
  • New SpacetimeDB.Testing NuGet package (only .NET 10).

  • New Rust crate crates/test-datastore-ffi. A cdylib (publish = false) that exposes test-datastore through a versioned C ABI. Important: this was 100% implemented by LLMs.

  • Changes to Runtime to . The net10 package now contains two assemblies:

    • a managed assembly in lib/net10.0, used for compiling and testing;
    • the WASM assembly in runtimes/wasi-wasm/lib/net10.0, which spacetime build selects.

    In the managed build, table and index handles go through the fixture's transaction. A handle used after its transaction or fixture has ended throws.

    • Package validation compares the public API of the two assemblies.
    • HTTP request validation is now shared between them, with no behavior change in WASM.
  • Codegen emits the same WASM output when SPACETIMEDB_WASM_AOT is defined (spacetime publish and spacetime build). When managed (test environment) it generates no module of its own, instead it adds a global using for the root module's namespace.

  • Adds module testing to the chat-console-cs template.

  • Updates spacetime init to copy the test package from a module only for .NET 10 and sets the SpacetimeDB.Testing version to the Runtime version.

  • Updates documentation.

  • CI and release (this were also fully implemented by an LLM):

    • A new reusable csharp-testing.yml workflow builds the native bridge and packs the packages.
    • Release publishes SpacetimeDB.Testing from the same tested package set as SpacetimeDB.Runtime and SpacetimeDB.BSATN.Runtime.

Important note: test-datastore-ffi was 100% implemented by LLMs.

API and ABI breaking changes

No breaking changes. All the new stuff affects testing only.

Rollback safety impact

n/a.

Expected complexity level and risk

Possibly a 4/5.

  • Runtime now has both managed and WASM builds selected by #if. A mistake in a conditional block could change WASM output, and the managed-only tests wouldn't notice. It's not the most robust thing in the world. If it starts becoming a problem or a pain to maintain, I'll have to think of something better.
  • The FFI layer handles buffer ownership, handle lifetimes across finalizers, and a worker thread per datastore.
  • CI and release. The release now waits on a three-platform native build matrix (Linux ARM, Linux x86 and Windows x86).

Testing

  • All new tests are passing
    These cover the new Testing project, the release and packaging, the new test-datastore-ffi and more...
  • Old tests are still passing

@lisandroct
lisandroct force-pushed the lisandro/csharp-module-unit-testing-split branch from 8d6a5eb to 756a2e3 Compare November 6, 2026 14:27
@lisandroct
lisandroct marked this pull request as draft November 6, 2026 15:03
@lisandroct
lisandroct force-pushed the lisandro/csharp-module-unit-testing-split branch from 6e02c8c to 1fe54be Compare November 9, 2026 15:47
@lisandroct
lisandroct marked this pull request as ready for review November 9, 2026 19:48
@lisandroct
lisandroct force-pushed the lisandro/csharp-module-unit-testing-split branch from f7dab74 to c73a019 Compare November 19, 2026 11:31

@JasonAtClockwork JasonAtClockwork left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I haven't completed a full review but found something important enough to reach out on straight-away. It looks like we have a regression for sub-modules with this change because they are not getting built with the wasm flag so they're becoming managed and then fail during publish.

I had AI whip up a quick small repro to keep it small to describe:


Repro. This is the docs example, inside the project spacetime init --lang csharp creates for .NET 10. Pack the PR's packages into a local feed first:

dotnet pack crates/bindings-csharp/BSATN.Runtime -c Release -p:Version=2.16.0-pr -o feed
dotnet pack crates/bindings-csharp/Runtime       -c Release -p:Version=2.16.0-pr -o feed
NuGet.config                      add `feed` as a package source
spacetimedb/
  StdbModule.csproj               from `spacetime init`, plus the docs' ProjectReference
  Lib.cs
  libraries/AuthLib/
    AuthLib.csproj
    Lib.cs

Files

spacetimedb/StdbModule.csproj: spacetime init output with SpacetimeDB.Runtime at 2.16.0-pr, plus the ItemGroup from the docs.

<ItemGroup>
  <ProjectReference Include="libraries/AuthLib/AuthLib.csproj" />
  <!-- Prevent the root project from also compiling the library's source. -->
  <Compile Remove="libraries/**/*.cs" />
</ItemGroup>

spacetimedb/Lib.cs

using SpacetimeDB;

[assembly: Namespace(typeof(AuthLib.Marker), Accessor = "MyAuth", Name = "auth_data")]

public static partial class Module
{
    [Reducer]
    public static void AddAuthUser(ReducerContext ctx, uint id)
    {
        AuthLib.Functions.Add(ctx.As.MyAuth, id);
        Log.Info($"Auth users: {AuthLib.Functions.Count(ctx.As.MyAuth)}");
    }
}

spacetimedb/libraries/AuthLib/AuthLib.csproj

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
    <ImplicitUsings>enable</ImplicitUsings>
    <Nullable>enable</Nullable>
  </PropertyGroup>
  <ItemGroup>
    <PackageReference Include="SpacetimeDB.Runtime" Version="2.16.0-pr" />
  </ItemGroup>
</Project>

spacetimedb/libraries/AuthLib/Lib.cs

using SpacetimeDB;

namespace AuthLib;

public class Marker { }

[Table(Accessor = "User", Name = "auth_users", Public = true)]
public partial struct User
{
    [PrimaryKey]
    public uint Id;
    public uint Score;
}

public static partial class Functions
{
    public static void Insert(ReducerContext ctx, uint id) =>
        ctx.Db.User.Insert(new User { Id = id, Score = 42 });

    public static ulong Count(ReducerContext ctx) => ctx.Db.User.Count;

    [Reducer]
    public static void Add(ReducerContext ctx, uint id) => Insert(ctx, id);
}

Result

$ spacetime publish -p spacetimedb submodule-docs
...
Build finished successfully.
Error: Local module schema inspection failed:
Error: wasm trap while calling "__preinit__10_init_csharp"
   ...
   9: S_P_CoreLib_Internal_Runtime_CompilerHelpers_ThrowHelpers__ThrowTypeLoadException
  10: StdbModule.wasm!AuthLib_ModuleRegistration__Register
  11: StdbModule_ModuleRegistration__RegisterModule

@lisandroct
lisandroct force-pushed the lisandro/csharp-module-unit-testing-split branch from 79e41d0 to 7f18777 Compare November 20, 2026 13:33
lisandroct and others added 16 commits November 20, 2026 16:09
C# modules can now be unit tested natively. The new SpacetimeDB.Testing
package runs reducers, procedures and views against a native test
datastore through the spacetimedb-test-datastore-ffi C ABI.

Includes codegen and runtime support, the Testing library and its tests,
templates, docs, CI packaging and release flow.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Decode each row from a slice of its declared length (FramedRows), so
malformed results always throw InvalidDataException. Used by RunQuery
and the managed TableAccessor.Iter.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
After an internal error stops the native worker, later calls report
INTERNAL_ERROR with the original message (including the panic message)
instead of DATASTORE_CLOSED, so C# no longer reports a panic as a
disposed datastore.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
HttpClient.Send validates the request and clamps its timeout the same
way in both builds, before the managed transaction check, matching WASM.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Enable package validation so pack fails when the WASM assembly lacks
API the managed one exposes. Existing intended differences are listed in
CompatibilitySuppressions.xml.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@lisandroct
lisandroct force-pushed the lisandro/csharp-module-unit-testing-split branch from 5547a26 to 3c8728c Compare November 20, 2026 22:22

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants