From df9b6df3d0cc0d1144a5199eac10d4dc6d9f4b8a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mattias=20Sundstr=C3=B6m?= Date: Sun, 4 Oct 2026 21:15:14 +0200 Subject: [PATCH 1/5] docs: make examples work on Linux and macOS - filebased-csharp.md told readers to create `Directory.build.props`. MSBuild looks for `Directory.Build.props`, and on a case-sensitive file system the differently cased file is silently not imported (checked on a case-sensitive APFS volume: "props NOT imported"). - Two pages showed an unquoted `--treenode-filter /*/*/*/*[...]`. zsh, the default macOS shell, rejects it with "no matches found", and bash can expand it to real file paths. The filters are quoted. - running-your-tests.md used `C:/...` paths, PowerShell fences and a win-x64 publish path in every example; they are now OS-neutral, with the Windows executable name noted. - The performance benchmark README published AOT with `-r win-x64`, which cannot work off Windows since native AOT does not cross-compile, and its filter examples had the same globbing problem. Co-Authored-By: Claude Opus 5.5 --- benchmarks/TUnit.Performance.Tests/README.md | 14 +++++----- docs/docs/comparison/framework-differences.md | 2 +- docs/docs/examples/filebased-csharp.md | 6 ++-- .../getting-started/running-your-tests.md | 28 +++++++++++-------- docs/docs/writing-tests/test-context.md | 2 +- 5 files changed, 28 insertions(+), 24 deletions(-) diff --git a/benchmarks/TUnit.Performance.Tests/README.md b/benchmarks/TUnit.Performance.Tests/README.md index 68402475591..f4273f2af97 100644 --- a/benchmarks/TUnit.Performance.Tests/README.md +++ b/benchmarks/TUnit.Performance.Tests/README.md @@ -38,24 +38,24 @@ dotnet run -c Release ### Native AOT Comparison ```bash -# Build for AOT -dotnet publish -c Release -r win-x64 --self-contained -p:PublishAot=true +# Build for AOT (native AOT cannot cross-compile, so target the current machine) +dotnet publish -c Release --use-current-runtime --self-contained -p:PublishAot=true -o publish -# Run the published executable -./bin/Release/net8.0/win-x64/publish/TUnit.Performance.Tests.exe +# Run the published executable (TUnit.Performance.Tests.exe on Windows) +./publish/TUnit.Performance.Tests ``` ### Run Specific Benchmarks ```bash # Run only discovery benchmarks -dotnet run -c Release -- --filter *Discovery* +dotnet run -c Release -- --filter '*Discovery*' # Run only execution benchmarks -dotnet run -c Release -- --filter *Execution* +dotnet run -c Release -- --filter '*Execution*' # Run only data source benchmarks -dotnet run -c Release -- --filter *DataSource* +dotnet run -c Release -- --filter '*DataSource*' ``` ## Expected Results diff --git a/docs/docs/comparison/framework-differences.md b/docs/docs/comparison/framework-differences.md index d7091d8a2e8..fcce9daebd4 100644 --- a/docs/docs/comparison/framework-differences.md +++ b/docs/docs/comparison/framework-differences.md @@ -65,7 +65,7 @@ TUnit creates a new instance for every test, with no way to opt out. If you need Consider a multi-tenanted test suite where tests repeat with different tenants injected via `[TestFixtureSource]`. A natural next step is filtering by tenant. In NUnit, you might try using `IApplyToTest` to set a property based on the constructor argument, but it doesn't work — tests are enumerated at startup before the fixture source provides its values. -Because TUnit discovers tests via source generation, constructor arguments are available upfront. You can set properties with `ITestDiscoveryEvent` and filter with `--treenode-filter /*/*/*/*[Tenant=MyTenant]`. +Because TUnit discovers tests via source generation, constructor arguments are available upfront. You can set properties with `ITestDiscoveryEvent` and filter with `--treenode-filter "/*/*/*/*[Tenant=MyTenant]"`. ### Attribute scope diff --git a/docs/docs/examples/filebased-csharp.md b/docs/docs/examples/filebased-csharp.md index 4e0b59d9356..6cf46667dda 100644 --- a/docs/docs/examples/filebased-csharp.md +++ b/docs/docs/examples/filebased-csharp.md @@ -19,7 +19,7 @@ To use TUnit with a file-based C# application, you can follow these steps: #:package TUnit@1.6.0 ``` - - You can also use msbuild props files to include TUnit. By creating a `Directory.build.props` file in the same directory as the csharp file. + - You can also use msbuild props files to include TUnit. By creating a `Directory.Build.props` file in the same directory as the csharp file. ```xml @@ -72,7 +72,7 @@ dotnet project convert Program.cs Single file csharp applications can also be used with msbuild props files. You can create a `*.props` file and the dotnet sdk will automatically include it when running the file-based application. -1. Create a file named `Directory.build.props` with the following content: +1. Create a file named `Directory.Build.props` with the following content: ```xml @@ -112,4 +112,4 @@ Single file csharp applications can also be used with msbuild props files. You c dotnet run file.cs ``` -This will automatically include the `Directory.build.props` file as long as it is in the same directory as the csharp file, and you will be able to run your tests with TUnit. +This will automatically include the `Directory.Build.props` file as long as it is in the same directory as the csharp file, and you will be able to run your tests with TUnit. diff --git a/docs/docs/getting-started/running-your-tests.md b/docs/docs/getting-started/running-your-tests.md index b88a74ba2f6..8da0e3da5fe 100644 --- a/docs/docs/getting-started/running-your-tests.md +++ b/docs/docs/getting-started/running-your-tests.md @@ -12,8 +12,8 @@ Coverage and TRX reporting are built in. See [Extensions](../extending/built-in- For a simple execution of a project, `dotnet run` is the preferred method, allowing easier passing in of command line flags. -```powershell -cd 'C:/Your/Test/Directory' +```sh +cd path/to/YourTestProject dotnet run -c Release # or with flags dotnet run -c Release --report-trx --coverage @@ -23,8 +23,8 @@ dotnet run -c Release --report-trx --coverage `dotnet test` requires any command line flags to be specified as application arguments, meaning after a `--` - Otherwise you'll get an error about unknown switches. -```powershell -cd 'C:/Your/Test/Directory' +```sh +cd path/to/YourTestProject dotnet test -c Release # or with flags dotnet test -c Release -- --report-trx --coverage @@ -34,8 +34,8 @@ dotnet test -c Release -- --report-trx --coverage If your test project has already been built, you can use `dotnet exec` or just `dotnet` with the `.dll` path -```powershell -cd 'C:/Your/Test/Directory/bin/Release/net8.0' +```sh +cd path/to/YourTestProject/bin/Release/net8.0 dotnet exec YourTestProject.dll # or with flags dotnet exec YourTestProject.dll --report-trx --coverage @@ -43,8 +43,8 @@ dotnet exec YourTestProject.dll --report-trx --coverage or -```powershell -cd 'C:/Your/Test/Directory/bin/Release/net8.0' +```sh +cd path/to/YourTestProject/bin/Release/net8.0 dotnet YourTestProject.dll # or with flags dotnet YourTestProject.dll --report-trx --coverage @@ -57,13 +57,17 @@ On Windows this will be a `.exe` and on Linux/macOS there will be no extension. This can be invoked directly and passed any flags. -```powershell -cd 'C:/Your/Test/Directory/bin/Release/net8.0/win-x64/publish' -./YourTestProject.exe +The publish folder sits under the runtime identifier you published for, such as `win-x64`, `linux-x64` or `osx-arm64`. + +```sh +cd path/to/YourTestProject/bin/Release/net8.0/linux-x64/publish +./YourTestProject # or with flags -./YourTestProject.exe --report-trx --coverage +./YourTestProject --report-trx --coverage ``` +On Windows, run `.\YourTestProject.exe` instead. + ## IDE Support ## Visual Studio diff --git a/docs/docs/writing-tests/test-context.md b/docs/docs/writing-tests/test-context.md index 2b6ed64a5ba..e48df372d03 100644 --- a/docs/docs/writing-tests/test-context.md +++ b/docs/docs/writing-tests/test-context.md @@ -100,7 +100,7 @@ See the [Test Parameters](../execution/parameters.md) guide for full details. Custom properties can be added to a test using the `[Property]` attribute. Properties are key-value pairs of strings that serve multiple purposes: -- **Test filtering**: Filter tests at the command line with `dotnet run --treenode-filter /*/*/*/*[PropertyName=PropertyValue]` +- **Test filtering**: Filter tests at the command line with `dotnet run --treenode-filter "/*/*/*/*[PropertyName=PropertyValue]"` - **Runtime logic**: Access properties in setup/cleanup hooks via `TestContext` to conditionally execute logic - **Inheritance**: Apply `[Property]` on a base class and all sub-class tests inherit it From 23e52e48c9a6651100d07af312fe20e5acaa2c6d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mattias=20Sundstr=C3=B6m?= Date: Sun, 4 Oct 2026 21:24:50 +0200 Subject: [PATCH 2/5] docs(benchmarks): show the Windows command for the AOT benchmark run Co-Authored-By: Claude Opus 5.5 --- benchmarks/TUnit.Performance.Tests/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/benchmarks/TUnit.Performance.Tests/README.md b/benchmarks/TUnit.Performance.Tests/README.md index f4273f2af97..babf129b4ca 100644 --- a/benchmarks/TUnit.Performance.Tests/README.md +++ b/benchmarks/TUnit.Performance.Tests/README.md @@ -41,8 +41,10 @@ dotnet run -c Release # Build for AOT (native AOT cannot cross-compile, so target the current machine) dotnet publish -c Release --use-current-runtime --self-contained -p:PublishAot=true -o publish -# Run the published executable (TUnit.Performance.Tests.exe on Windows) +# Run the published executable ./publish/TUnit.Performance.Tests +# On Windows: +./publish/TUnit.Performance.Tests.exe ``` ### Run Specific Benchmarks From 99b7fb7b5864faf2997f59e0d9e8f37e46a85c13 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mattias=20Sundstr=C3=B6m?= Date: Mon, 5 Oct 2026 06:40:45 +0200 Subject: [PATCH 3/5] docs(benchmarks): native AOT only rules out cross-OS compilation Co-Authored-By: Claude Opus 5.5 --- benchmarks/TUnit.Performance.Tests/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/benchmarks/TUnit.Performance.Tests/README.md b/benchmarks/TUnit.Performance.Tests/README.md index babf129b4ca..90ed59dd8d8 100644 --- a/benchmarks/TUnit.Performance.Tests/README.md +++ b/benchmarks/TUnit.Performance.Tests/README.md @@ -38,7 +38,7 @@ dotnet run -c Release ### Native AOT Comparison ```bash -# Build for AOT (native AOT cannot cross-compile, so target the current machine) +# Build for AOT (native AOT cannot cross-compile across operating systems, so target the current machine) dotnet publish -c Release --use-current-runtime --self-contained -p:PublishAot=true -o publish # Run the published executable From cf70ccb83c7d89bc604b70c8fe35b8367f2c9bf1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mattias=20Sundstr=C3=B6m?= Date: Mon, 5 Oct 2026 07:30:40 +0200 Subject: [PATCH 4/5] docs: placeholder RID with a matching Windows example; AOT prerequisites Co-Authored-By: Claude Opus 5.5 --- benchmarks/TUnit.Performance.Tests/README.md | 2 ++ docs/docs/getting-started/running-your-tests.md | 11 ++++++++--- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/benchmarks/TUnit.Performance.Tests/README.md b/benchmarks/TUnit.Performance.Tests/README.md index 90ed59dd8d8..dc230548256 100644 --- a/benchmarks/TUnit.Performance.Tests/README.md +++ b/benchmarks/TUnit.Performance.Tests/README.md @@ -37,6 +37,8 @@ dotnet run -c Release ### Native AOT Comparison +Native AOT needs a platform toolchain: the Visual Studio "Desktop development with C++" workload on Windows, the Xcode Command Line Tools on macOS, and `clang` plus the zlib development package on Linux. See the [.NET Native AOT prerequisites](https://learn.microsoft.com/dotnet/core/deploying/native-aot/#prerequisites). + ```bash # Build for AOT (native AOT cannot cross-compile across operating systems, so target the current machine) dotnet publish -c Release --use-current-runtime --self-contained -p:PublishAot=true -o publish diff --git a/docs/docs/getting-started/running-your-tests.md b/docs/docs/getting-started/running-your-tests.md index 8da0e3da5fe..a9364290319 100644 --- a/docs/docs/getting-started/running-your-tests.md +++ b/docs/docs/getting-started/running-your-tests.md @@ -57,16 +57,21 @@ On Windows this will be a `.exe` and on Linux/macOS there will be no extension. This can be invoked directly and passed any flags. -The publish folder sits under the runtime identifier you published for, such as `win-x64`, `linux-x64` or `osx-arm64`. +The publish folder sits under the runtime identifier (``) you published for, such as `win-x64`, `linux-x64` or `osx-arm64`. ```sh -cd path/to/YourTestProject/bin/Release/net8.0/linux-x64/publish +cd path/to/YourTestProject/bin/Release/net8.0//publish ./YourTestProject # or with flags ./YourTestProject --report-trx --coverage ``` -On Windows, run `.\YourTestProject.exe` instead. +On Windows, from the `win-x64` publish folder: + +```powershell +cd path/to/YourTestProject/bin/Release/net8.0/win-x64/publish +.\YourTestProject.exe --report-trx --coverage +``` ## IDE Support From 3c27c15b834f1355f95f8d4f22f1e8fc85fde081 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mattias=20Sundstr=C3=B6m?= Date: Mon, 5 Oct 2026 16:51:48 +0200 Subject: [PATCH 5/5] docs: use a concrete RID in the shell example; is parsed as redirection Co-Authored-By: Claude Opus 5.5 --- docs/docs/getting-started/running-your-tests.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/getting-started/running-your-tests.md b/docs/docs/getting-started/running-your-tests.md index a9364290319..fbbee910a53 100644 --- a/docs/docs/getting-started/running-your-tests.md +++ b/docs/docs/getting-started/running-your-tests.md @@ -57,10 +57,10 @@ On Windows this will be a `.exe` and on Linux/macOS there will be no extension. This can be invoked directly and passed any flags. -The publish folder sits under the runtime identifier (``) you published for, such as `win-x64`, `linux-x64` or `osx-arm64`. +The publish folder sits under the runtime identifier you published for, such as `win-x64`, `linux-x64` or `osx-arm64`. Replace `linux-x64` below with yours. ```sh -cd path/to/YourTestProject/bin/Release/net8.0//publish +cd path/to/YourTestProject/bin/Release/net8.0/linux-x64/publish ./YourTestProject # or with flags ./YourTestProject --report-trx --coverage