Creating a new bUnit test project

To write tests, you need a place to put them - a test project. bUnit is not a unit test runner, so a general-purpose test framework like xUnit, NUnit, or MSTest is needed in addition to bUnit in order to write and run tests.

To use bUnit, the easiest approach is to use the bUnit project template described in the following section. To create a test project manually and in a general-purpose testing frameworks agnostic way, read the section Creating a test project manually section further down the page.

Creating a test project with bUnit template

To quickly get started with bUnit, install and use the bUnit test project template.

The steps for creating a test project with the bUnit template are as follows:

1. Install the template (only needed the first time)
2. Create a new bUnit test project
3. Add the test project to your solution

These steps look like this from the dotnet CLI:

1. Install the template

Install the template from NuGet using this command:

dotnet new --install bunit.template

Or, since .NET 7 onwards:

dotnet new install bunit.template

2. Create a new test project

If you successfully installed the template listed in the previous section, you can create a new project directly from the "Create new project" wizard in Visual Studio (or Rider), where the bUnit project type will also show up.

Otherwise, use one of the following command to create a bUnit test project with the framework of your choice:

• xUnit
• NUnit
• MSTest

dotnet new bunit --framework xunit -o <NAME OF TEST PROJECT>

The --framework option in the dotnet new command above is used to specify the unit testing framework used by the test project. If the --framework option is omitted, the default test framework xunit will be configured. Currently supported options are the following:

• xunit - xUnit,
• nunit - NUnit,
• mstest - MSTest

3. Add the test project to your solution

If using Visual Studio, add the test project to your solution (.sln), and add a reference between the test project and the project containing the components that should be tested:

dotnet sln <NAME OF PROJECT>.sln add <NAME OF TEST PROJECT>
dotnet add <NAME OF TEST PROJECT>.csproj reference <NAME OF COMPONENT PROJECT>.csproj

This will allow the test project to see and test the components in the component project.

Creating a test project manually

This section will take you through the steps required to create a project for testing Blazor components using bUnit. Any of the three general-purpose test frameworks shown in step 1 below can be used. Briefly, here is what we will do:

1. Create a new xUnit/NUnit/MSTest testing project
2. Add bUnit to the test project
3. Configure project settings
4. Add the test project to your existing solution

Let's look at these in more detail. These steps look like this from the 'dotnet' CLI:

1. Create a new test project

Use the following command (click on the tab for the test framework of choice):

• xUnit
• NUnit
• MSTest

dotnet new xunit -o <NAME OF TEST PROJECT>

The -o option in the dotnet new command above is used to specify the name of the test project.

2. Add bUnit to the test project

To add bUnit to the test project, change to the newly created test projects folder and use the following command:

cd <NAME OF PROJECT>
dotnet add package bunit --version 1.34.0-preview.gee3e229206

3. Configure project settings

The test projects setting needs to be set to the following:

• the project's SDK needs to be set to Microsoft.NET.Sdk.Razor
• set the <TargetFramework> to net8.0

Note

bUnit works with net7.0, net6.0, net5.0 and netcoreapp3.1/netstandard2.1 test projects as well.

To do so, change the first part of the test projects .csproj file to look like this.:

<Project Sdk="Microsoft.NET.Sdk.Razor">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
  </PropertyGroup>  ...

</Project>

4. Add the test project to your solution

If using Visual Studio, add the test project to your solution (.sln), and add a reference between the test project and the project containing the components that are to be tested:

dotnet sln <NAME OF PROJECT>.sln add <NAME OF TEST PROJECT>
dotnet add <NAME OF TEST PROJECT>.csproj reference <NAME OF COMPONENT PROJECT>.csproj

The result should be a test project with a .csproj that looks like this (non bUnit packages may have different version numbers):

• xUnit
• NUnit
• MSTest

<Project Sdk="Microsoft.NET.Sdk.Razor">

  <PropertyGroup>
    <TargetFramework>net8.0</TargetFramework>
    <Nullable>enable</Nullable>
    <IsPackable>false</IsPackable>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="bunit" Version="1.33.3" />
    <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
		<PackageReference Include="xunit" Version="2.8.1" />
    <PackageReference Include="xunit.runner.visualstudio" Version="2.5.4">
      <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
      <PrivateAssets>all</PrivateAssets>
    </PackageReference>
    <PackageReference Include="coverlet.collector" Version="6.0.0" />
  </ItemGroup>

  <ItemGroup>
    <ProjectReference Include="<PATH TO COMPONENT LIB>.csproj" />
  </ItemGroup>

</Project>