Skip to content

Toxiproxy

Toxiproxy is a proxy to simulate network and system conditions for chaos and resiliency testing. It can simulate latency, timeouts, bandwidth limits, and connection issues between services.

Add the following dependency to your project file:

NuGet
1
dotnet add package Testcontainers.Toxiproxy

You can start a Toxiproxy container instance from any .NET application. This example demonstrates how to test network conditions by proxying traffic through Toxiproxy to a Redis container. The test creates both containers in the same network and configures Toxiproxy to redirect traffic from the test host to the Redis container.

 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
private readonly INetwork _network = new NetworkBuilder().Build();

private readonly IContainer _redisContainer;

private readonly IContainer _toxiproxyContainer;

public ToxiproxyContainerTest()
{
    _redisContainer = new RedisBuilder()
        .WithNetwork(_network)
        .WithNetworkAliases(RedisNetworkAlias)
        .Build();

    _toxiproxyContainer = new ToxiproxyBuilder()
        .WithNetwork(_network)
        .Build();
}

public async ValueTask InitializeAsync()
{
    await _redisContainer.StartAsync()
        .ConfigureAwait(false);

    await _toxiproxyContainer.StartAsync()
        .ConfigureAwait(false);
}

public async ValueTask DisposeAsync()
{
    await _toxiproxyContainer.DisposeAsync()
        .ConfigureAwait(false);

    await _redisContainer.DisposeAsync()
        .ConfigureAwait(false);

    await _network.DisposeAsync()
        .ConfigureAwait(false);
}

This example uses xUnit.net's IAsyncLifetime interface to manage the lifecycle of the containers. Both the Redis and Toxiproxy containers are started in the InitializeAsync method before the test method runs, ensuring that the environment is ready for testing. After the test completes, the containers are removed in the DisposeAsync method.

 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
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
[Fact]
[Trait(nameof(DockerCli.DockerPlatform), nameof(DockerCli.DockerPlatform.Linux))]
public async Task LatencyToxicIncreasesResponseTime()
{
    // Given

    // The Toxiproxy module initializes 32 ports during startup that we can
    // use to configure the proxy and redirect traffic.
    const ushort redisProxyPort = ToxiproxyBuilder.FirstProxiedPort;

    const string key = "key";

    const string value = "value";

    // GetMappedPublicPort() retrieves the first bound port, which corresponds
    // to Toxiproxy's control port.
    using var connection = new Connection(_toxiproxyContainer.Hostname, _toxiproxyContainer.GetMappedPublicPort());
    var client = connection.Client();

    // The proxy configuration forwards traffic from the test host to the
    // Toxiproxy container and then to the Redis container.
    var proxy = new Proxy();
    proxy.Name = "redis";
    proxy.Enabled = true;
    proxy.Listen = "0.0.0.0:" + redisProxyPort;
    proxy.Upstream = RedisNetworkAlias + ":6379";
    var redisProxy = client.Add(proxy);

    // Don't establish a connection directly to the Redis container.
    // Instead, connect through the Toxiproxy container using the first of
    // the 32 ports initialized during the Toxiproxy module startup.
    var connectionString = new UriBuilder("redis", _toxiproxyContainer.Hostname, _toxiproxyContainer.GetMappedPublicPort(redisProxyPort)).Uri.Authority;

    using var redis = await ConnectionMultiplexer.ConnectAsync(connectionString)
        .ConfigureAwait(true);

    var db = redis.GetDatabase();

    await db.StringSetAsync(key, value)
        .ConfigureAwait(true);

    // When
    var latencyWithoutToxic = await MeasureLatencyAsync(db, key, value)
        .ConfigureAwait(true);

    // Apply the toxic to the proxy. In this case, add additional
    // latency to the downstream traffic.
    var latencyToxic = new LatencyToxic();
    latencyToxic.Name = "latency_downstream";
    latencyToxic.Stream = ToxicDirection.DownStream;
    latencyToxic.Toxicity = 1;
    latencyToxic.Attributes.Latency = 1100;
    latencyToxic.Attributes.Jitter = 100;
    redisProxy.Add(latencyToxic);

    var latencyWithToxic = await MeasureLatencyAsync(db, key, value)
        .ConfigureAwait(true);

    // Then
    Assert.InRange(latencyWithoutToxic, 0, 250);
    Assert.InRange(latencyWithToxic, 1000, 1500);
}

How it works

To test network conditions with Toxiproxy, you need to configure the communication between your test host, Toxiproxy, and the service you want to test:

  1. Place both containers in the same network so the Toxiproxy container and the service container (Redis in this example) can communicate with each other.

  2. Configure the Toxiproxy proxy to redirect traffic from the test host to the service container. The proxy's Listen address specifies where Toxiproxy listens for incoming connections, and the Upstream address specifies the target service.

    1
2
3
4
5
6
    var proxy = new Proxy();
proxy.Name = "redis";
proxy.Enabled = true;
proxy.Listen = "0.0.0.0:" + redisProxyPort;
proxy.Upstream = RedisNetworkAlias + ":6379";
var redisProxy = client.Add(proxy);

  3. Connect through Toxiproxy using its hostname and one of its proxied ports. The Toxiproxy module initializes 32 ports starting from 8666 that can be used to configure proxies and redirect traffic. In the example, the Redis connection uses the Toxiproxy container's hostname and port instead of connecting directly to Redis.

    1
    var connectionString = new UriBuilder("redis", _toxiproxyContainer.Hostname, _toxiproxyContainer.GetMappedPublicPort(redisProxyPort)).Uri.Authority;

  4. Apply toxics to the proxy to simulate network conditions. For example, a latency toxic to the downstream traffic.

    1
2
3
4
5
6
7
    var latencyToxic = new LatencyToxic();
latencyToxic.Name = "latency_downstream";
latencyToxic.Stream = ToxicDirection.DownStream;
latencyToxic.Toxicity = 1;
latencyToxic.Attributes.Latency = 1100;
latencyToxic.Attributes.Jitter = 100;
redisProxy.Add(latencyToxic);

Tip

Toxiproxy allows you to configure the Toxicity property, which determines the probability (0.0 to 1.0) that a toxic will be applied to the connection. A value of 1.0 means the toxic is applied 100% of the time, while 0.5 would apply it to approximately 50% of requests.

The test example uses the following NuGet dependencies:

1
2
3
4
5
6
<PackageReference Include="Microsoft.NET.Test.Sdk"/>
<PackageReference Include="coverlet.collector"/>
<PackageReference Include="xunit.runner.visualstudio"/>
<PackageReference Include="xunit.v3"/>
<PackageReference Include="Toxiproxy.Net"/>
<PackageReference Include="StackExchange.Redis"/>

To execute the tests, use the command dotnet test from a terminal.

Tip

For the complete source code of this example and additional information, please refer to our test projects.