Clean, isolated, and maintainable integration testing for .NET

If you plan to use this NuGet package, let me know in the Tell me if you use that package ! discussion on Github ! Gaining insight into its usage is very important to me!

• The problem with integration testing in .NET
• NotoriousTest: The solution
• Why use NotoriousTest
• Hello World
• Resources & Community
  • Documentation
  • Changelog
  • Contact
• Other packages i'm working on

When testing an application that relies on multiple infrastructures (databases, message buses, blob storage, FTP, SMTP...), the common approach looks like this:

• Create a WebApplicationFactory and use it as a fixture.
• Implement IAsyncLifetime to initialize and dispose of infrastructures.
• Manage each infrastructure (SQL Server, RabbitMQ, Redis, MongoDB, etc.) within Initialize and Dispose.
• Add specific setup code inside the test constructors.

👉 This works for small projects, but as complexity increases, it becomes a nightmare:

🔥 The WebApplicationFactory turns into an unmanageable beast.
🔄 Everything needs to be manually refactored and structured → resulting in messy, hard-to-maintain code.
🏗️ Tests become slow to write and complex to maintain.
⏳ Setup time skyrockets, reducing productivity.

And that’s the real problem—integration tests are meant to ensure the quality of our code. But if they themselves become unmanageable, the enemy of our enemy becomes our enemy.

NotoriousTest introduces a modular and structured approach to isolating and managing your test infrastructures effortlessly.

✅ Each infrastructure (database, message bus, etc.) is encapsulated in its own class with a proper lifecycle (Init, Reset, Destroy).
✅ Test environments are composable → you assemble infrastructures like Lego blocks.
✅ Automatic reset between tests ensures proper isolation.
✅ No need to bloat your WebApplicationFactory → each infrastructure is cleanly defined.
✅ Works seamlessly with TestContainers, SQL Server, and more.

👉 The result? A testing framework that is clean, modular, maintainable, and scalable.

🔹 Designed for complex integration tests
Seamlessly manage multiple infrastructures like databases, message buses, blob storage, and more, without turning your test setup into a nightmare.

🔹 Fully isolated and resettable environments
Ensure clean, independent tests by automatically resetting infrastructures between each run—no leftover data, no hidden side effects.

🔹 Modular & reusable infrastructure components
Define each infrastructure separately and compose test environments like Lego blocks. No more bloated WebApplicationFactories!

🔹 Effortless setup & minimal boilerplate
Forget complex test initialization logic—NotoriousTest takes care of instantiating, resetting, and destroying your infrastructures automatically.

🔹 Compatible with TestContainers & SQL Server
Seamlessly integrates with Dockerized test environments, allowing you to spin up databases, message queues, and more in seconds.

🔹 Powered by XUnit & Async Support
Leverage the flexibility of XUnit’s dependency injection and fully async infrastructure lifecycles for faster and more scalable tests.

First, install NuGet. Then, install NotoriousTest from the package manager console:

PM> Install-Package NotoriousTest

Or from the .NET CLI as:

dotnet add package NotoriousTest

An infrastructure represents an external dependency (database, message bus, etc.).

For now, we’ll define an empty infrastructure to illustrate the setup. You can replace MyInfrastructure with any real infrastructure later.

public class MyInfrastructure : AsyncInfrastructure
{
    public override Task Initialize()
    {
        // Setup logic here (e.g., start a database, configure an API)
        Console.WriteLine($"Setup of {nameof(MyInfrastructure)}");
        return Task.CompletedTask;
    }

    public override Task Reset()
    {
        // Reset logic here (e.g., clear data, reset state)
        Console.WriteLine($"Reset of {nameof(MyInfrastructure)}");
        return Task.CompletedTask;
    }

    public override Task Destroy()
    {
        // Cleanup logic here (e.g., shut down services)
        Console.WriteLine($"Shutdown of {nameof(MyInfrastructure)}");
        return Task.CompletedTask;
    }
}

📌 What this does:

• Defines a basic infrastructure with lifecycle methods.
• This is where you would add setup logic for databases, APIs, queues, etc.

Now, let's create a basic web application for our tests.

public class SampleWebApp : WebApplication<Program>
{
    // Override WebApplicationFactory methods.
}

❗ This is a WebApplicationFactory customized for NotoriousTest.

📌 What this does:

• Defines a minimal web application factory for testing.

A test environment groups infrastructures together.

public class MyTestEnvironment : AsyncWebEnvironment
{
    public override async Task ConfigureEnvironmentAsync()
    {
        AddInfrastructure(new MyInfrastructure()); // Register the test infrastructure
        AddWebApplication(new SampleWebApp()); // Register the web app
    }
}

📌 What this does:

• Registers MyInfrastructure and SampleWebApp inside the test environment.
• Ensures all tests run in a clean and isolated setup.

Now, let's write a basic integration test using our environment.

public class MyIntegrationTests : AsyncIntegrationTest<MyTestEnvironment>
{
    public MyIntegrationTests(MyTestEnvironment environment) : base(environment) { }

    [Fact]
    public async Task ExampleTest()
    {
        // Retrieve the infrastructure
        var infra = await CurrentEnvironment.GetInfrastructureAsync<MyInfrastructure>();

        // Add test logic here (e.g., verify database state, call an API)

        Assert.NotNull(infra); // Basic validation to confirm setup works
    }
}

📌 What this does:

• Retrieves the test infrastructure from the environment.
• You can add real test logic (API calls, database assertions, etc.).

Now, let's run the test:

dotnet test

You should see something like:

Passed! 1 test successful.

If everything works, congrats! 🎉 You’ve successfully set up NotoriousTest.

• 📖 Core Concepts – Learn how infrastructures and environments work.
• ⚡ Advanced Features – Discover ordering, reset behaviors, and more. \
• 🔌 Integrations – See how to integrate SQL Server, TestContainers, and more.
• 📚 Examples – Hands-on use cases with real-world setups.

You can find the changelog here.

Have questions, ideas, or feedback about NotoriousTests? Feel free to reach out! I'd love to hear from you. Here's how you can get in touch:

• GitHub Issues: Open an issue to report a problem, request a feature, or share an idea.
• Email: [email protected]
• LinkedIn : Brice SCHUMACHER

The discussions tabs is now opened ! Feel free to tell me if you use the package here : #1 !

• NotoriousClient : Notorious Client is meant to simplify the sending of HTTP requests through a fluent builder and an infinitely extensible client system.
• NotoriousModules : Notorious Modules provide a simple way to separate monolith into standalone modules.