Integration Tests

WIP

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

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
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
11
12
13
public Task DisposeAsync()
{
_client?.Dispose();
return Task.CompletedTask;
}

public Task InitializeAsync()
{
// seed data for your tests

// then return
return Task.CompletedTask;
}

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

1
2
3
4
5
[CollectionDefinition("Shared Collection Fixture")]
public class SharedCollectionFixture : ICollectionFixture<CollectionFixture>
{
// no implementation
}

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 in the class, and have it cleaned up after all the tests in the class have finished. - xunit.net/docs/shared-context

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
public class FindStuffFixture : IAsyncLifetime
{
// ... private state

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>. Note that [Collection("Shared Collection Fixture")] was only added to allow the test access to CollectionFixture which is where the clients are constructed.

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