From 42795b2470c054326af2c62b93cde2b4e8719848 Mon Sep 17 00:00:00 2001 From: woksin Date: Sun, 25 Oct 2026 13:31:49 +0100 Subject: [PATCH] Graduate the native runner from experimental Remove the experimental markers from the Runner package description, README and runner documentation, repoint links to the renamed README heading, and qualify the skipped-results promise for a hard IDE stop. --- Documentation/runner.md | 4 ++-- Documentation/running-fast.md | 6 +++--- README.md | 10 +++++----- Source/Runner/Runner.csproj | 2 +- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/Documentation/runner.md b/Documentation/runner.md index aa27f4c..faaf71c 100644 --- a/Documentation/runner.md +++ b/Documentation/runner.md @@ -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 diff --git a/Documentation/running-fast.md b/Documentation/running-fast.md index 9d57d99..851740e 100644 --- a/Documentation/running-fast.md +++ b/Documentation/running-fast.md @@ -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. @@ -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 | | --- | --- | diff --git a/README.md b/README.md index 57259bc..28dbaaf 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 @@ -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 '////'` selects methods by their code names, not their @@ -477,7 +477,7 @@ public class when_registering : Specification `--shard /` and `--specs-cache `; standard options such as `--filter-uid` and `--report-trx` apply. Run it with `dotnet run --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 diff --git a/Source/Runner/Runner.csproj b/Source/Runner/Runner.csproj index cfb208d..1e5a626 100644 --- a/Source/Runner/Runner.csproj +++ b/Source/Runner/Runner.csproj @@ -5,7 +5,7 @@ true true 4.5.0 - 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. + 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. enable true