Xunit.DependencyInjection 11.3.0

Use Microsoft.Extensions.DependencyInjection to resolve xUnit test cases

XUnit v2 users: please use v2 branch.

Xunit.DependencyInjection.SkippableFact are obsoleted on xunit.v3.

How to use

👁 Xunit.DependencyInjection NuGet

Install the NuGet package.

dotnet add package Xunit.DependencyInjection

In your testing project, add the following framework

namespace Your.Test.Project
{
 public class Startup
 {
 public void ConfigureServices(IServiceCollection services)
 {
 services.AddTransient<IDependency, DependencyClass>();
 }
 }
}

Example test class.

public interface IDependency
{
 int Value { get; }
}

internal class DependencyClass : IDependency
{
 public int Value => 1;
}

public class MyAwesomeTests
{
 private readonly IDependency _d;

 public MyAwesomeTests(IDependency d) => _d = d;

 [Fact]
 public void AssertThatWeDoStuff()
 {
 Assert.Equal(1, _d.Value);
 }
}

Xunit.DependencyInjection is built into the generic host and fully supports its lifecycle, allowing you to use all features supported by the generic host, including but not limited to IHostedService.

Integration asp.net core TestHost(3.0+)

Asp.Net Core Startup

dotnet add package Microsoft.AspNetCore.TestHost

public class Startup
{
 public void ConfigureHost(IHostBuilder hostBuilder) => hostBuilder
 .ConfigureWebHost[Defaults](webHostBuilder => webHostBuilder
 .UseTestServer(options => options.PreserveExecutionContext = true)
 .UseStartup<AspNetCoreStartup>());
}

MinimalApi

If you use MinimalApi rather than asp.net core Startup class.

Add package reference for Xunit.DependencyInjection.AspNetCoreTesting

dotnet add package Xunit.DependencyInjection.AspNetCoreTesting

public class Startup
{
 public IHostBuilder CreateHostBuilder() => MinimalApiHostBuilderFactory.GetHostBuilder<Program>();
}

Maybe your asp.net core project should InternalsVisibleTo or add public partial class Program {} in the end of Program.cs;

Detail see Xunit.DependencyInjection.Test.AspNetCore

Startup limitation

Startup supports two configuration styles, and the Configure method is supported by both.

HostApplicationBuilder-style

• CreateHostApplicationBuilder method

  NOTE: If this method signature is not found, the host is built by simply calling Host.CreateEmptyApplicationBuilder(new() { ApplicationName = assemblyName.Name });.

  public HostApplicationBuilder CreateHostApplicationBuilder([AssemblyName assemblyName]) { }
  

• ConfigureHostApplicationBuilder method (distinguish by this method)

  public void ConfigureHostApplicationBuilder(IHostApplicationBuilder hostApplicationBuilder) { }
  

• BuildHostApplicationBuilder method

  NOTE: If this method signature is not found, the host is built by simply calling hostApplicationBuilder.Build();.

  public IHost BuildHostApplicationBuilder(HostApplicationBuilder hostApplicationBuilder)
  {
   return hostApplicationBuilder.Build();
  }
  

Startup-style

• CreateHostBuilder method

  public class Startup
  {
   public IHostBuilder CreateHostBuilder([AssemblyName assemblyName]) { }
  }
  

• ConfigureHost method

  public class Startup
  {
   public void ConfigureHost(IHostBuilder hostBuilder) { }
  }
  

• ConfigureServices method

  public class Startup
  {
   public void ConfigureServices(IServiceCollection services[, HostBuilderContext context]) { }
  }
  

• BuildHost method

  NOTE: If this method signature is not found, the host is built by simply calling hostBuilder.Build();.

  public class Startup
  {
   public IHost BuildHost([IHostBuilder hostBuilder]) { return hostBuilder.Build(); }
  }
  

How to find Startup?

1. Specific startup

Declare [Startup] on test class

2. Nested startup

public class TestClass1
{
 public class Startup
 {
 public void ConfigureServices(IServiceCollection services) { }
 }

3. Closest startup

If the class type full name is "A.B.C.TestClass", find Startup in the following order:

1. A.B.C.Startup
2. A.B.Startup
3. A.Startup
4. Startup

4. Default startup

Default startup is required before 8.7.0, is optional in some case after 8.7.0.

If is required, please add a startup class in your test project.

Default is find Your.Test.Project.Startup, Your.Test.Project.

If you want to use a special Startup, you can define XunitStartupAssembly and XunitStartupFullName in the PropertyGroup section

<Project>
 <PropertyGroup>
 <XunitStartupAssembly>Abc</XunitStartupAssembly>
 <XunitStartupFullName>Xyz</XunitStartupFullName>
 </PropertyGroup>
</Project>

Parallel

By default, xUnit runs all test cases in a test class synchronously. This package can extend the test framework to execute tests in parallel.

If you register a custom ITestCollectionOrderer, test collections will be run in the specified order, which may be slower than running without the custom ITestCollectionOrderer.

<Project>

 <PropertyGroup>
 <ParallelizationMode></ParallelizationMode>
 </PropertyGroup>

</Project>

This package has two policies to run test cases in parallel.

1. Enhance or true

   Respect xunit parallelization behavior.

2. Force

   Ignore xunit parallelization behavior and force running tests in parallel.

If [Collection](if ParallelizationMode is not Force), [CollectionDefinition(DisableParallelization = true)], [DisableParallelization] declared on the test class, the test class will run sequentially. If [DisableParallelization], [MemberData(DisableDiscoveryEnumeration = true)] declared on the test method, the test method will run sequentially.

It is recommended without setting parallelAlgorithm

Thanks Meziantou.Xunit.ParallelTestFramework

How to disable Xunit.DependencyInjection

<Project>
 <PropertyGroup>
 <EnableXunitDependencyInjectionDefaultTestFrameworkAttribute>false</EnableXunitDependencyInjectionDefaultTestFrameworkAttribute>
 </PropertyGroup>
</Project>

How to inject ITestOutputHelper

internal class DependencyClass : IDependency
{
 private readonly ITestOutputHelperAccessor _testOutputHelperAccessor;

 public DependencyClass(ITestOutputHelperAccessor testOutputHelperAccessor)
 {
 _testOutputHelperAccessor = testOutputHelperAccessor;
 }
}

Write Microsoft.Extensions.Logging to ITestOutputHelper

Add package reference for Xunit.DependencyInjection.Logging

dotnet add package Xunit.DependencyInjection.Logging

The call chain must be from the test case. If not, this feature will not work.

public class Startup
{
 public void ConfigureServices(IServiceCollection services) => services
 .AddLogging(lb => lb.AddXunitOutput());
}

How to inject IConfiguration or IHostEnvironment into Startup?

public class Startup
{
 public void ConfigureHost(IHostBuilder hostBuilder) => hostBuilder
 .ConfigureServices((context, services) => { context.XXXX });
}

or

public class Startup
{
 public void ConfigureServices(IServiceCollection services, HostBuilderContext context)
 {
 context.XXXX;
 }
}

How to configure IConfiguration?

public class Startup
{
 public void ConfigureHost(IHostBuilder hostBuilder) => hostBuilder
 .ConfigureHostConfiguration(builder => { })
 .ConfigureAppConfiguration((context, builder) => { });
}

[MemberData] how to inject?

Use [MethodData]

Integrate OpenTelemetry

TracerProviderBuilder builder;

builder.AddSource("Xunit.DependencyInjection");

Do something before and after test case

Inherit BeforeAfterTest and register as BeforeAfterTest service.

See demo.

Initialize some data on startup.

If it is synchronous initialization, you can use the Configure method. If it is asynchronous initialization, you should use IHostedService.