Repository files navigation

Xunit does not support any built-in dependency injection features, therefore developers have to come up with a solution to recruit their favourite dependency injection framework in their tests.

This library bringsMicrosoft's dependency injection container to Xunit by leveraging Xunit's fixture pattern and providesthree approaches for dependency injection in your tests:

1. 🆕 Property Injection (Recommended) - Clean, declarative syntax using[Inject] attributes on properties
2. 🔧 Traditional Fixture-Based - Access services via_fixture.GetService<T>(_testOutputHelper) (fully backward compatible)
3. ⚡ Factory Pattern - True constructor injection into service classes (experimental)

• 🎯Multiple injection patterns - Choose the approach that fits your team's style
• 🔑Keyed services support - Full .NET 10.0 keyed services integration
• ⚙️Configuration integration - Support forappsettings.json, user secrets, and environment variables
• 🧪Service lifetime management - Transient, Scoped, and Singleton services work as expected
• 📦Microsoft.Extensions ecosystem - Built on the same DI container used by ASP.NET Core
• 🔄Gradual migration - Adopt new features incrementally without breaking existing tests
• 🏗️Production-ready - Used byDigital Silo and other production applications

• ForxUnit packages use Xunit.Microsoft.DependencyInjection versionsup to 9.0.5
• ForxUnit.v3 packages use Xunit.Microsoft.DependencyInjection versionsfrom 9.1.0
• For.NET 10.0 use Xunit.Microsoft.DependencyInjection version10.0.0 or later

Also please check themigration guide from xUnit for test authors.

<PackageReferenceInclude="xunit.v3"Version="3.2.0" />

Before you begin, ensure you have:

• .NET 10.0 SDK installed on your development machine
• Visual Studio 2022 orVisual Studio Code with C# extension
• Basic understanding of dependency injection concepts
• Familiarity with xUnit testing framework

First add the followingnuget package to your Xunit test project:

Install-PackageXunit.Microsoft.DependencyInjection

dotnet add package Xunit.Microsoft.DependencyInjection

<PackageReferenceInclude="Xunit.Microsoft.DependencyInjection"Version="9.2.0" />

✨ That's it! All required Microsoft.Extensions dependencies are now automatically included with the package, so you don't need to manually add them to your test project.

Here's a minimal example to get you started quickly:

usingMicrosoft.Extensions.Configuration;usingMicrosoft.Extensions.DependencyInjection;usingXunit.Microsoft.DependencyInjection.Abstracts;publicclassMyTestFixture:TestBedFixture{protectedoverridevoidAddServices(IServiceCollectionservices,IConfiguration?configuration)=>services.AddTransient<IMyService,MyService>().AddScoped<IMyScopedService,MyScopedService>();protectedoverrideValueTaskDisposeAsyncCore()=>new();protectedoverrideIEnumerable<TestAppSettings>GetTestAppSettings(){yieldreturnnew(){Filename="appsettings.json",IsOptional=true};}}

usingXunit.Microsoft.DependencyInjection.Abstracts;usingXunit.Microsoft.DependencyInjection.Attributes;[Collection("Dependency Injection")]publicclassMyTests:TestBedWithDI<MyTestFixture>{[Inject]privateIMyServiceMyService{get;set;}=null!;[Inject]privateIMyScopedServiceMyScopedService{get;set;}=null!;publicMyTests(ITestOutputHelpertestOutputHelper,MyTestFixturefixture):base(testOutputHelper,fixture){}[Fact]publicasyncTaskTestMyService(){// Your services are automatically injected and ready to usevarresult=awaitMyService.DoSomethingAsync();Assert.NotNull(result);}}

[CollectionDefinition("Dependency Injection")]publicclassMyTraditionalTests:TestBed<MyTestFixture>{publicMyTraditionalTests(ITestOutputHelpertestOutputHelper,MyTestFixturefixture):base(testOutputHelper,fixture){}[Fact]publicasyncTaskTestMyService(){// Get services from the fixturevarmyService=_fixture.GetService<IMyService>(_testOutputHelper)!;varresult=awaitmyService.DoSomethingAsync();Assert.NotNull(result);}}

The abstract class ofXunit.Microsoft.DependencyInjection.Abstracts.TestBedFixture contains the necessary functionalities to add services and configurations to Microsoft's dependency injection container. Your concrete test fixture class must derive from this abstract class and implement the following two abstract methods:

protectedabstractvoidAddServices(IServiceCollectionservices,IConfiguration?configuration);protectedabstractIEnumerable<TestAppSettings>GetTestAppSettings();protectedabstractValueTaskDisposeAsyncCore();

GetConfigurationFiles(...) method returns a collection of the configuration files in your Xunit test project to the framework.AddServices(...) method must be used to wire up the implemented services.

Secret manager is a great tool to store credentials, API keys, and other secret information for development purposes. This library has started supporting user secrets from version 8.2.0 onwards. To utilize user secrets in your tests, simply override thevirtual method below from theTestBedFixture class:

protectedoverridevoidAddUserSecrets(IConfigurationBuilderconfigurationBuilder);

There are two method that you can use to access the wired up service depending on your context:

publicTGetScopedService<T>(ITestOutputHelpertestOutputHelper);publicTGetService<T>(ITestOutputHelpertestOutputHelper);

To access async scopes simply call the following method in the abstract fixture class:

publicAsyncServiceScopeGetAsyncScope(ITestOutputHelpertestOutputHelper);

You can call the following method to access the keyed already-wired up services:

T?GetKeyedService<T>([DisallowNull]stringkey,ITestOutputHelpertestOutputHelper);

New in this version (ver 9.2.0 and beyond): The library now supports constructor-style dependency injection while maintaining full backward compatibility with the existing fixture-based approach.

For cleaner test code, inherit fromTestBedWithDI<TFixture> instead ofTestBed<TFixture> and use the[Inject] attribute:

publicclassPropertyInjectionTests:TestBedWithDI<TestProjectFixture>{[Inject]publicICalculator?Calculator{get;set;}[Inject]publicIOptions<Options>?Options{get;set;}publicPropertyInjectionTests(ITestOutputHelpertestOutputHelper,TestProjectFixturefixture):base(testOutputHelper,fixture){// Dependencies are automatically injected after construction}[Fact]publicasyncTaskTestWithCleanSyntax(){// Dependencies are immediately available - no fixture calls neededAssert.NotNull(Calculator);varresult=awaitCalculator.AddAsync(5,3);Assert.True(result>0);}}

Use the[Inject("key")] attribute for keyed services:

publicclassPropertyInjectionTests:TestBedWithDI<TestProjectFixture>{[Inject("Porsche")]internalICarMaker?PorscheCarMaker{get;set;}[Inject("Toyota")]internalICarMaker?ToyotaCarMaker{get;set;}[Fact]publicvoidTestKeyedServices(){Assert.NotNull(PorscheCarMaker);Assert.NotNull(ToyotaCarMaker);Assert.Equal("Porsche",PorscheCarMaker.Manufacturer);Assert.Equal("Toyota",ToyotaCarMaker.Manufacturer);}}

TheTestBedWithDI class provides convenience methods that don't require the_testOutputHelper parameter:

protectedT?GetService<T>()protectedT?GetScopedService<T>()protectedT?GetKeyedService<T>(stringkey)

• ✅Clean, declarative syntax - Use[Inject] attribute on properties
• ✅No manual fixture calls - Dependencies available immediately in test methods
• ✅Full keyed services support - Both regular and keyed services work seamlessly
• ✅Backward compatible - All existingTestBed<TFixture> code continues to work unchanged
• ✅Gradual migration - Adopt new approach incrementally without breaking existing tests

You can migrate existing tests gradually:

1. Keep existing approach - Continue usingTestBed<TFixture> with fixture methods
2. Hybrid approach - Change toTestBedWithDI<TFixture> and use both[Inject] properties and fixture methods
3. Full migration - Use property injection for all dependencies for cleanest code

For true constructor injection into service classes, seeCONSTRUCTOR_INJECTION.md for the factory-based approach.

Test developers can add their own desired logger provider by overridingAddLoggingProvider(...) virtual method defined inTestBedFixture class.

Your Xunit test class must be derived fromXunit.Microsoft.DependencyInjection.Abstracts.TestBed<T> class whereT should be your fixture class derived fromTestBedFixture.

Also, the test class should be decorated by the following attribute:

[CollectionDefinition("Dependency Injection")]

To have managed resources cleaned up, simply override the virtual method ofClear(). This is an optional step.

Simply override the virtual method ofDisposeAsyncCore() for this purpose. This is also an optional step.

The library also has a bonus feature that simplifies running tests in order. The test class does not have to be derived fromTestBed<T> class though and it can apply to all Xunit classes.

Decorate your Xunit test class with the following attribute and associateTestOrder(...) withFact andTheory:

[TestCaseOrderer("Xunit.Microsoft.DependencyInjection.TestsOrder.TestPriorityOrderer","Xunit.Microsoft.DependencyInjection")]

This library'sTestBedFixture abstract class exposes an instance ofIConfigurationBuilder that can be used to supportUserSecrets when configuring the test projects:

publicIConfigurationBuilderConfigurationBuilder{get;privateset;}

📖Complete Examples Documentation - Comprehensive guide with working code examples

• Live Examples - View the complete working examples that demonstrate all features
• Traditional approach: See examples usingTestBed<TFixture> and_fixture.GetService<T>(_testOutputHelper)
• Property injection: SeePropertyInjectionTests.cs for examples usingTestBedWithDI<TFixture> with[Inject] attributes
• Factory pattern: SeeFactoryConstructorInjectionTests.cs for experimental constructor injection scenarios
• Keyed services: SeeKeyedServicesTests.cs for .NET 9.0 keyed service examples
• Configuration: SeeUserSecretTests.cs for configuration and user secrets integration
• Advanced patterns: SeeAdvancedDependencyInjectionTests.cs forIOptions<T>,Func<T>, andAction<T> examples

🏢Digital Silo's unit tests and integration tests are using this library in production.

If you encounter build errors, ensure all required Microsoft.Extensions packages are installed with compatible versions.

• Ensureappsettings.json is set to "Copy to Output Directory: Copy if newer" in file properties
• Configuration files must be valid JSON format

• Initialize user secrets:dotnet user-secrets init
• Set secrets:dotnet user-secrets set "SecretKey" "SecretValue"

• ForxUnit packages use Xunit.Microsoft.DependencyInjection versionsup to 9.0.5
• ForxUnit.v3 packages use Xunit.Microsoft.DependencyInjection versionsfrom 9.1.0

• 📖Complete Examples Documentation - Step-by-step examples for all features
• 🐛GitHub Issues - Report bugs or request features
• 📦NuGet Package - Latest releases and changelog
• 📋Migration Guide - For xUnit.v3 migration