Test support Testcontainers RabbitMQ

Overview

Contains support for using a RabbitMQ testcontainer in integration tests. Provides extension methods that wire up a RabbitMqContainer instance to either an application container builder or an IConfigurationBuilder, so that the containerised RabbitMQ broker is automatically connected to the service under test.

Install

• ASOL.Core.QA.TestSupport.Testcontainers.RabbitMq

WithRabbitMq (IContainerBuilder)

Use ContainerBuilderExtensions.WithRabbitMq to wire a RabbitMQ testcontainer into another testcontainer that acts as a test tool — for example, a service container spun up as a dependency to support a test. The method injects RabbitMQ connection details as environment variables into that testcontainer and declares a startup dependency so the RabbitMQ container is started first.

Note: The RabbitMQ test container does not need to be started before calling this method. The dependency is resolved automatically when the target container starts.

Signature

public static TBuilderEntity WithRabbitMq<TBuilderEntity, TContainerEntity, TConfigurationEntity>(
    this IContainerBuilder<TBuilderEntity, TContainerEntity, TConfigurationEntity> builder,
    RabbitMqContainer rabbitMqContainer,
    string messagingSectionName = "Messaging",
    string rabbitMqSectionName = "RabbitMq",
    PartialRabbitMqConnectionOptions? options = null)

Parameter	Description
builder	The IContainerBuilder for the testcontainer acting as a test tool (e.g. a service container used as a test dependency, not the SUT).
rabbitMqContainer	The RabbitMqContainer instance to connect to. The container must have a name or a network alias.
messagingSectionName	Top-level configuration section name (default: "Messaging").
rabbitMqSectionName	Nested section name under messagingSectionName (default: "RabbitMq").
options	Optional connection overrides. See PartialRabbitMqConnectionOptions.

The following environment variables are injected into the target container (using __ as the section separator):

Environment Variable	Value
{messagingSection}__{rabbitMqSection}__HostName	Container name or network alias
{messagingSection}__{rabbitMqSection}__Port	5672
{messagingSection}__{rabbitMqSection}__UserName	Container username
{messagingSection}__{rabbitMqSection}__Password	Container password
{messagingSection}__{rabbitMqSection}__VirtualHost	From options (default "/")
{messagingSection}__{rabbitMqSection}__ClientName	From options (if set)
{messagingSection}__{rabbitMqSection}__HealthCheckMode	From options (if set)
{messagingSection}__{rabbitMqSection}__Ssl__Enabled	From options.Ssl (if set)
{messagingSection}__{rabbitMqSection}__Ssl__ServerName	From options.Ssl (if set)
{messagingSection}__{rabbitMqSection}__Ssl__Protocol	From options.Ssl (if set)

Example

var network = new NetworkBuilder().Build();

var rabbitMqContainer = new RabbitMqBuilder("rabbitmq:3.11")
    .WithName($"test-rabbitmq-{Guid.NewGuid():N}")
    .WithNetwork(network)
    .Build();

var testApiContainerBuilder = new ContainerBuilder(testApiImage)
    .WithNetwork(network)
    .WithPortBinding(80, true)
    .WithWaitStrategy(Wait.ForUnixContainer().UntilInternalTcpPortIsAvailable(80))
    .WithRabbitMq(rabbitMqContainer);

var testAppContainer = testApiContainerBuilder.Build();
await testAppContainer.StartAsync(cancellationToken);

With custom section names and options:

testApiContainerBuilder = testApiContainerBuilder
    .WithRabbitMq(
        rabbitMqContainer,
        messagingSectionName: "Messaging",
        rabbitMqSectionName: "RabbitMq",
        options: new PartialRabbitMqConnectionOptions
        {
            ClientName = "MyService",
            VirtualHost = "/my-vhost"
        });

The application reads the connection using the ASOL Messaging registration:

AddRabbitMq (IConfigurationBuilder)

Use ConfigurationBuilderExtensions.AddRabbitMq when the application under test uses standard Core RabbitMQ connection patter. The method reads the connection details from the already-running RabbitMQ testcontainer and adds them to the IConfigurationBuilder.

Note: The RabbitMQ test container must be started before calling this method.

Signature

public static IConfigurationBuilder AddRabbitMq(
    this IConfigurationBuilder configurationBuilder,
    RabbitMqContainer rabbitMqContainer,
    string messagingSectionName = "Messaging",
    string rabbitMqSectionName = "RabbitMq",
    PartialRabbitMqConnectionOptions? options = null)

Parameter	Description
configurationBuilder	The configuration builder to add RabbitMQ settings to.
rabbitMqContainer	A started RabbitMqContainer instance.
messagingSectionName	Top-level section name (default: "Messaging").
rabbitMqSectionName	Nested section name (default: "RabbitMq").
options	Optional connection overrides.

Example

// In a WebApplicationFactory override
protected override void ConfigureWebHost(IWebHostBuilder builder)
{
    builder.ConfigureAppConfiguration(config =>
    {
        config.AddRabbitMq(
            rabbitMqContainer,
            options: new PartialRabbitMqConnectionOptions
            {
                ClientName = "MyService.Tests"
            });
    });
}

PartialRabbitMqConnectionOptions

Allows overriding individual RabbitMQ connection properties. Only non-null values are applied.

Property	Type	Default	Description
VirtualHost	string	"/"	The RabbitMQ virtual host to connect to.
ClientName	string?	null	A human-readable name for this connection, visible in the RabbitMQ management UI.
HealthCheckMode	HealthCheckMode?	null	Controls how RabbitMQ health checks are reported.
Ssl	RabbitMqSslConnectionOptions?	null	TLS/SSL configuration. See RabbitMqSslConnectionOptions.

RabbitMqSslConnectionOptions

Property	Type	Default	Description
Enabled	bool?	null	Enables or disables SSL for the connection.
ServerName	string?	null	The server name for TLS SNI verification.
Protocol	SslProtocols?	null	The TLS protocol version to use (e.g. SslProtocols.Tls12).