Skip to content

Graduate the native runner from experimental #96

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
woksin merged 1 commit into from
Oct 25, 2026
Merged

Graduate the native runner from experimental #96

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions Documentation/runner.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,11 @@
`Cratis.Specifications.Runner` runs specifications directly on
[Microsoft.Testing.Platform](https://learn.microsoft.com/dotnet/core/testing/microsoft-testing-platform-intro) (MTP),
without xUnit, NUnit or TUnit underneath. A source generator registers the specification classes at compile time, so
discovery needs no reflection scan and the runner starts fast. The runner remains experimental.
discovery needs no reflection scan and the runner starts fast.

This guide covers where the runner works, how to run and filter it, what it cannot do, and how to move an existing
xUnit project to it. For the specification vocabulary itself, see the
[repository README](https://github.com/Cratis/Specifications/blob/main/README.md#native-runner-on-microsoft-testing-platform-experimental).
[repository README](https://github.com/Cratis/Specifications/blob/main/README.md#native-runner-on-microsofttestingplatform).

## Set up a project

Expand Down
6 changes: 3 additions & 3 deletions Documentation/running-fast.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,9 +25,9 @@ What to take from it:

- The same xUnit v3 suite costs about 4.5 times more CPU through `dotnet test` than as an executable in this run.
Running the executable is the cheap win.
- The native runner (`Cratis.Specifications.Runner`, [experimental](https://github.com/Cratis/Specifications/blob/main/README.md#native-runner-on-microsoft-testing-platform-experimental))
- The native runner (`Cratis.Specifications.Runner`, [README](https://github.com/Cratis/Specifications/blob/main/README.md#native-runner-on-microsofttestingplatform))
and xUnit v3 executables start fastest. Choose the native runner when you want its features (cache, sharding,
readable names) and accept that it may change without notice.
readable names).
- TUnit runs on Microsoft.Testing.Platform. See
[Using TUnit](https://github.com/Cratis/Specifications/blob/main/README.md#using-tunit) for how it coexists with VSTest projects.
- Keep xUnit v2 or NUnit when you depend on their adapters and tooling; they are not slow for typical suites.
Expand Down Expand Up @@ -71,7 +71,7 @@ repository's [build workflow](https://github.com/Cratis/Specifications/blob/main

## Filter, shard and cache

The native runner options (see the [README](https://github.com/Cratis/Specifications/blob/main/README.md#native-runner-on-microsoft-testing-platform-experimental)):
The native runner options (see the [README](https://github.com/Cratis/Specifications/blob/main/README.md#native-runner-on-microsofttestingplatform)):

| Option | Use |
| --- | --- |
Expand Down
10 changes: 5 additions & 5 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ Packages:
- [Cratis.Specifications.NUnit](https://www.nuget.org/packages/cratis.specifications.nunit) — for NUnit 4
- [Cratis.Specifications.NUnit5](https://www.nuget.org/packages/cratis.specifications.nunit5) — for NUnit 5
- [Cratis.Specifications.TUnit](https://www.nuget.org/packages/cratis.specifications.tunit) — for TUnit
- [Cratis.Specifications.Runner](https://www.nuget.org/packages/cratis.specifications.runner) — the native runner on Microsoft.Testing.Platform (experimental)
- [Cratis.Specifications.Runner](https://www.nuget.org/packages/cratis.specifications.runner) — the native runner on Microsoft.Testing.Platform
- [Cratis.Specifications](https://www.nuget.org/packages/cratis.specifications) — the shared core (the `Specification` base, assertions and analyzers); every package above depends on it

All packages target `net10.0`; specification projects that must target .NET 8 or .NET 9 stay on 4.x. Use the same version of
Expand Down Expand Up @@ -438,9 +438,9 @@ Standard SDK switches also work:
excluding assets on a framework package does not remove them, and on `Cratis.Specifications.Runner` it also drops the
source generator, so the specifications are no longer registered. Use the property.

## Native runner on Microsoft.Testing.Platform (experimental)
## Native runner on Microsoft.Testing.Platform

`Cratis.Specifications.Runner` is an experimental, native specification runner on
`Cratis.Specifications.Runner` is a native specification runner on
[Microsoft.Testing.Platform](https://learn.microsoft.com/dotnet/core/testing/microsoft-testing-platform-intro),
without xUnit, NUnit or TUnit underneath. Reference the package and the test project becomes an executable test
application; a source generator registers the specifications at compile time. Ordinary methods use generated
Expand All @@ -463,7 +463,7 @@ public class when_registering : Specification
- One instance per class: `Establish` and `Because` run once, facts may run concurrently and must only read the
shared context, then `Destroy` and disposal (`IDisposable`/`IAsyncDisposable`) run once.
- Stop/cancellation stops scheduling new classes, then waits for running classes to finish all their facts, `Destroy`
and disposal. Unstarted facts are reported as skipped. Running code can cooperate through
and disposal. Unstarted facts are reported as skipped, except after a hard IDE stop, where the host suppresses further updates (see [Limits](./Documentation/runner.md#limits)). Running code can cooperate through
`SpecificationContext.CancellationToken`, which flows across awaits and is isolated per class; outside a class it
is `CancellationToken.None`. Cancellation does not forcibly interrupt running code.
- `--treenode-filter '/<assembly>/<namespace>/<class>/<fact>'` selects methods by their code names, not their
Expand All @@ -477,7 +477,7 @@ public class when_registering : Specification
`--shard <index>/<count>` and `--specs-cache <path|none>`; standard options such as `--filter-uid` and `--report-trx` apply.

Run it with `dotnet run --project <spec project>` or the built executable. The package, its options and its
behavior may change without notice while it is experimental.
behavior follow the same versioning as the rest of the packages.

## Guides

Expand Down
2 changes: 1 addition & 1 deletion Source/Runner/Runner.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
<IsPackable>true</IsPackable>
<EnablePackageValidation>true</EnablePackageValidation>
<PackageValidationBaselineVersion>4.5.0</PackageValidationBaselineVersion>
<Description>Experimental: Specification by Example (BDD) for .NET with a native runner on Microsoft.Testing.Platform - Given/When/Then specifications with one shared context per specification class, source generated discovery and no runtime reflection.</Description>
<Description>Specification by Example (BDD) for .NET with a native runner on Microsoft.Testing.Platform - Given/When/Then specifications with one shared context per specification class, source generated discovery and no runtime reflection.</Description>
<Nullable>enable</Nullable>
<IsAotCompatible>true</IsAotCompatible>
</PropertyGroup>
Expand Down
Loading