Integration Tests With Collection & Class Fixtures

Every team you work in will have their own understanding of integration tests, I tried to explain this better in my post on Testing Strategies

A general explanation of integration tests could be as follows:

Code that invokes a unit of work that crosses project boundaries, uses actual external dependencies, and/or validates many different aspects about the code under test.

This can visually be understood as

Integration test crosses project boundaries

That said, the integration can also be seen as the integration of units of work with-in your application. These units of work could be services or command/queries. Depending on what these units actually do they could be crossing project boundaries.

Examples

  • Unit b may implement a http client that interacts with an external API - thats outside of your projects boundary. So the above image reflects this.
  • Unit b may implement some math calculations like return 42 + 0; - thats inside your projects boundary but it still integrates with Unit a

Integration test crossing unit boundaries

Integration Test example

I’ve worked in teams where Integration Tests are re-used, the external dependencies are mocked out with another appsettings file. This is in my opinion then a Component Test, I view the two units above unit a and unit b together as a component.

Depending on what the test actually does it could be an E2E test (End to End)

Naming is tricky, however as a team we decided on the terminology Mock Integration Test as a component in front end development means something else. As our app was .Net the example appsettings name was appsettings.Mock.json - its important to define the terms as a team and then stick to them.

Using a fixture

It makes sense to break the tests down but still group them by Features - these should be already grouped by your controllers. By design controllers are allowed to do too much, you can add as many endpoints in them as you like - thats a different topic, see MVC Controllers are Dinosaurs - Embrace API Endpoints. For my features examples however grouping responsability makes integration testing by feature easier.

Consider these controllers, Artists has simple CRUD operations and so does Songs, these operations are abstracted away and then injected as an interface, using the Controllers folder is simply following convention over configuration.

I would understand this as one Artist has many Songs.

1
2
Foo.Api/Controllers/ArtistsController.cs
Foo.Api/Controllers/SongsController.cs

The integration tests could then be created as Features/Artists and Features/Songs, understandably there could be overlap if a Artist is persisted with some songs - ideally the link would just be the foreign key and not the whole implementation so design considerations need to thought out.

1
2
Foo.Api.IntegrationTests/Features/Artists/
Foo.Api.IntegrationTests/Features/Songs/

The abstractions the controller instantiates though dependency injection would still be injected by the applications framework, their behavior also doesnt change however the configuration (appsettings in .Net) can be changed by environment. This means the application needs to have the same appsettings values as the integration tests.

Collection Fixtures

When to use: when you want to create a single test context and share it among tests in SEVERAL TEST CLASSES, and have it cleaned up after all the tests in the test classes have finished. - xunit.net/docs/shared-context

Examples of data it could share

  • Options values (config)
  • Clients (classes that use HttpClient to call APIs)

The tests can use something called a Fixture to instantiate their dependencys. One or more fixtures are then injected into our tests. So below the CollectionFixture is really a base class to share context between tests.

Example Foo.Api.IntegrationTests/Fixtures/CollectionFixture.cs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
/// <summary>
/// A base class for any tests that want to implement xunit's ICollectionFixture functionality to share context between tests.
/// Test classes that use this fixture should be decorated with [Collection("Shared Collection Fixture")]
/// </summary>
public class CollectionFixture : IAsyncLifetime
{
    private FooServiceClient _client;
    private readonly FooBarOptions _fooBar;

    public CollectionFixture()
    {
        var appSettings = "appsettings.Mock.json";
        
        if (Environment.GetEnvironmentVariable("DOTNET_ENVIRONMENT") == "Uat")
            appSettings = "appsettings.Uat.json";

        var configuration = new ConfigurationBuilder()
            .AddJsonFile(appSettings)
            .Build();

        _fooBar = configuration
            .GetSection(FooBarOptions.FooBar)
            .Get<List<FooBarOptions>>();
    }

    public FooServiceClient FooServiceClient
    {
        get
        {
            if (_client != null)
                return _client;

            _client = new FooService(_fooBar);
            return _client;
        }
    }

    // ... DisposeAsync, InitializeAsync
}

We use IAsyncLifetime to call into the services to dispose of resources. If you use InitializeAsync here to seed any data you must remember its for all tests. If you want to seed data just for a subset then see Class Fixtures below.

1
2
3
4
5
6
7
8
9
10
public Task DisposeAsync()
{
    // clean up test data if the database was not brought up as part of the environment, ie: its not in a test container

    // dispose of clients
    _client?.Dispose();
    return Task.CompletedTask;
}

public Task InitializeAsync() => Task.CompletedTask;

To then allow the CollectionFixture to be instanciated and managed we need to create a SharedCollectionFixture

1
2
3
4
5
6
7
[CollectionDefinition("Shared Collection Fixture")]
public class SharedCollectionFixture : ICollectionFixture<CollectionFixture>
{
    // This class has no implementation as is never created. 
    // Its purpose is simply to be the place to apply [CollectionDefinition] and all the ICollectionFixture<> interfaces.
    // See https://xunit.net/docs/shared-context    
}

Test classes that want to use CollectionFixture should be decorated with [Collection("Shared Collection Fixture")]. Their constructor parameters can then include CollectionFixture collectionFixture. The facts can then access _collectionFixture.FooServiceClient

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
[Collection("Shared Collection Fixture")]
public class ArtistTests
{
    private readonly CollectionFixture _collectionFixture;

    public ArtistTests(CollectionFixture collectionFixture)
    {
        _collectionFixture = collectionFixture;
    }

    [Fact]
    public async Task U_I_E()
    {
        // Arrange
        // Act
        // Assert
    }
}

FooServiceClient

The FooServiceClient should inherit/implement IDisposable to dispose of any clients it may have. This is called from the fixtures DisposeAsync method to ensure all state is disposed of.

GC.SuppressFinalize(this) will prevent derived types that introduce a finalizer from needing to re-implement IDisposable to call it. See CA1816: Call GC.SuppressFinalize correctly

Alternatively the client FooServiceClient could use the sealed keyword to prevent inheritance.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
public class FooServiceClient : IDisposable
{
    private readonly HttpClient _client;

    public FooServiceClient(FooServiceOptions fooServiceOptions)
    {
        _client = new HttpClient { BaseAddress = new Uri(fooServiceOptions.Url) };
    }

    public async Task<ArtistDto> GetArtistAsync(Guid artistId)
    {
        // ... 
    }

    public void Dispose()
    {
        _client.Dispose();
        GC.SuppressFinalize(this);
    }
}

Class Fixtures

When to use: when you want to create a single test context and share it among all the tests ONE TEST CLASS, and have it cleaned up after all the tests in the class have finished. - xunit.net/docs/shared-context

Examples of what it can do

  • Seed data before each test, ie: in an integration test call your API under test and seed data
  • Provide IDs (often GUIDs) for the seeded data, you would then use this in your tests

Create the fixture the same as above but it will not need the CollectionDefinition class.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
/// <summary>
/// A base class for any tests that want to implement xunit's IClassFixture functionality to share context between tests.
/// This class should be inherited by a child class to be used with IClassFixture<T>
/// </summary>
public class FindStuffFixture : IAsyncLifetime
{
    // ... private state

    //Note that if you wanted to use the class fixture that provides for example test clients to do http calls you would just as for it in the class fixtures constructor
    public FindStuffFixture(CollectionFixture collectionFixture)
    {
        // ... set private state
    }

    public async Task InitializeAsync()
    {
        // ... seed data using `collectionFixture` clients

        var tasks = new List<Task>
        {
            // ... collection of tasks to run in parallel
        };
        await Task.WhenAll(tasks);

        // ... its sensible to still wait a 1 to 10 seconds
        await Task.Delay(1000);
    }

    public Task DisposeAsync()
    {
        // ... cleanup if needed 

        // then return
        return Task.CompletedTask;
    }    
}

Create the tests and inherit/implement IClassFixture<T> and IAsyncLifetime.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
public class FindStuffTests : IClassFixture<FindStuffFixture>, IAsyncLifetime
{
    public FindStuffTests(FindStuffFixture findStuffFixture)
    {
        _findStuffFixture = findStuffFixture;
    }

    [Fact]
    public async Task U_I_E()
    {
        // Arrange
        // Act
        // Assert
    } 
}

Using Collection Fixtures And Class Fixtures together

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
[Collection("Shared Collection Fixture")]
public class FindStuffTests : IClassFixture<FindStuffFixture>, IAsyncLifetime
{
    public FindStuffTests(CollectionFixture collectionFixture, FindStuffFixture findStuffFixture)
    {
        _findStuffFixture = findStuffFixture;
        _collectionFixture = collectionFixture;
    }

    [Fact]
    public async Task U_I_E()
    {
        // Arrange
        // Act
        // Assert
    } 
}

References