From ef61b9dc9d4d6721e0b952b28477dfbf5c0eed6f Mon Sep 17 00:00:00 2001 From: Johan Benschop Date: Mon, 15 Sep 2025 11:02:51 +0200 Subject: [PATCH] Updates doc to explain how to enable .razor files with TUnit Explains that TUnit only works with Razor files in reflection mode due to source generator limitations. Provides instructions for setting up TUnit with .razor files using a .runsettings file and updating the .csproj. Adds a note recommending a separate test project for bUnit tests to avoid performance issues. --- .../getting-started/create-test-project.md | 36 +++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/docs/site/docs/getting-started/create-test-project.md b/docs/site/docs/getting-started/create-test-project.md index de3e4a430..ee2d01697 100644 --- a/docs/site/docs/getting-started/create-test-project.md +++ b/docs/site/docs/getting-started/create-test-project.md @@ -147,7 +147,7 @@ dotnet add package bunit --version #{NBGV_NuGetPackageVersion}# The test projects setting needs to be set to the following: -- the project's SDK needs to be set to `Microsoft.NET.Sdk.Razor` (this does not work with **TUnit** - a more detailed explanation can be found below) +- the project's SDK needs to be set to `Microsoft.NET.Sdk.Razor` (for **TUnit** this only works in reflection mode - a more detailed explanation can be found below) - set the `` to `net8.0` > [!NOTE] @@ -313,7 +313,39 @@ The result should be a test project with a `.csproj` that looks like this (non b ``` > [!WARNING] -> **TUnit** and the `Microsoft.NET.Sdk.Razor` both utilize source code generators. Source generators can not see or interact with the output of another generator. Therefore **TUnit** does not work with `razor` files. Using `cs` based tests is working perfectly fine. For more information regarding the setup of **TUnit** head over to: https://github.com/thomhurst/TUnit +> **TUnit** and the `Microsoft.NET.Sdk.Razor` SDK both utilize source code generators. Source generators cannot see or interact with the output of another generator. Therefore **TUnit** only works with `.razor` files in **reflection mode**. However `.cs`-based tests work as expected in the default mode. For more information regarding the setup of **TUnit** head over to: https://github.com/thomhurst/TUnit + +To set up TUnit for use with `.razor` files, the `TUNIT_EXECUTION_MODE` environment variable must be set to `reflection` so that the TUnit test runner can discover these tests. + +A straightforward way to configure this is by creating a `.runsettings` file in the test project and referencing it from the `.csproj`. + +**.runsettings** + +```xml + + + + + reflection + + + +``` + +Add the following `RunSettingsFilePath` property to the `.csproj`: + +```xml + + $(MSBuildProjectDirectory)\.runsettings + +``` + +With this setup, all bUnit `.razor` tests are discovered and run consistently in Visual Studio and other supported environments. + +> [!NOTE] +> Running in reflection mode is slower than the default execution mode. It is therefore recommended to keep bUnit tests in a separate test project, so they don’t affect the performance of other test runs. + +For more information on reflection mode, see: https://tunit.dev/docs/execution/engine-modes/. ***