Integration Tests

This page is the reference for LiteBus integration tests: which projects exist, what infrastructure each one uses, and which behavioral scenarios they prove. It is written for maintainers adding broker or storage coverage and for contributors running the suite locally or in CI.

For handler-level and in-memory processor recipes, see Testing LiteBus. For durable messaging setup snippets, see Testing.

[!NOTE] Project counts, trait names, and container images reflect the repository at the time this page was written. When in doubt, inspect tests/ and .github/workflows/build-and-test.yml.

How Integration Tests Are Organized

LiteBus consolidates integration tests into four executor projects grouped by concern, plus shared helper libraries. Each executor owns many adapter surfaces (brokers, databases, host bridges) organized in subfolders by technology. Tests prove outcomes: store row transitions, wire headers, processor passes, manifest registration, or HTTP responses. Registration smoke and fast InMemory wire cases live in LiteBus.Durable.IntegrationTests. Sample v6 composition smoke lives in LiteBus.Runtime.UnitTests.

flowchart TB
  subgraph fast [No Docker]
    DTFast["Durable.IntegrationTests TransportFast"]
    HC["Extensions.IntegrationTests HealthChecks"]
    OT["Extensions.IntegrationTests OpenTelemetry"]
  end

  subgraph docker [Docker / Testcontainers]
    DTBrokers["Durable.IntegrationTests Kafka, AWS, Azure, AMQP"]
    PG["Storage.IntegrationTests PostgreSql"]
    EF["Storage.IntegrationTests EntityFrameworkCore"]
    AMQPWire["Transport.IntegrationTests Amqp wire"]
    ASP["Extensions.IntegrationTests AspNetCore"]
  end

  subgraph shared [Shared libraries]
    ST["LiteBus.Storage.Testing contract suites"]
    DTT["LiteBus.Transport.IntegrationTesting helpers"]
    LT["LiteBus.Testing.* concern helpers"]
  end

  DTBrokers --> DTT
  PG --> ST
  EF --> ST
  AMQPWire --> DTT

Executor Inventory

Folder Layout

tests/
|-- LiteBus.Durable.IntegrationTests/
|   |-- Ingress/              # broker to IInbox (InMemory, Kafka, AwsSqs, AzureServiceBus, Amqp)
|   |-- Dispatch/
|   |   |-- Inbox/            # inbox processor to broker
|   |   `-- Outbox/           # outbox processor to broker
|   `-- Registration/         # Use*Dispatch / Use*Ingress resolve without live broker
|-- LiteBus.Storage.IntegrationTests/
|   |-- PostgreSql/           # reference PG store, schema, saga, reliable messaging
|   `-- EntityFrameworkCore/
|       |-- Inbox/
|       `-- Outbox/
|-- LiteBus.Transport.IntegrationTests/
|   `-- Amqp/                 # low-level wire protocol (no inbox/outbox)
|-- LiteBus.Extensions.IntegrationTests/
|   |-- AspNetCore/
|   |-- HealthChecks/
|   `-- OpenTelemetry/
|-- LiteBus.Runtime.UnitTests/
|   `-- Runtime/Composition/  # v6 composition smoke (unit test, not integration)
|-- LiteBus.Transport.IntegrationTesting/   # shared fixtures, traits (not an executor)
|-- LiteBus.Transport.Testing/              # published transport contract suite
|-- LiteBus.Storage.Testing/                # abstract store contract suites
`-- LiteBus.Testing*/                       # concern-specific application test helpers

Supporting libraries (not test executors):

Shared Infrastructure Patterns

Testcontainers and Images

All Docker-backed fixtures use Testcontainers for .NET (central version in tests/Directory.Packages.props).

Fixture Lifetime

Docker Unavailable Behavior

Projects differ in how they handle a missing Docker daemon:

CI (.github/workflows/build-and-test.yml) runs unit tests without Docker (FullyQualifiedName!~IntegrationTests), then durable transport in three filtered batches (TransportFast, TransportDocker, TransportAzure), then remaining integration tests (FullyQualifiedName~IntegrationTests excluding those categories and the opt-in TransportLiveAzure category).

Environment Variable Overrides (Local Troubleshooting)

Fixtures can bypass Testcontainers when a connection string is already available:

Emulator-based Azure tests still require Docker; the env vars do not replace the emulator fixture.

Typical Test Shape (Durable Messaging)

Most inbox/outbox integration tests follow the same pipeline:

1. Build ServiceCollection through AddLiteBus(builder => ...).
2. Register contracts, storage (UseInMemoryStorage or PostgreSQL/EF), and dispatch/ingress adapter.
3. Ingress path: publish to broker to wait for consumer to assert store/handler state.
4. Dispatch path: IInbox.AcceptAsync or IOutbox.EnqueueAsync to ProcessPendingAsync to assert broker message or handler side effect.
5. Assert on observable outcomes (row status, headers on wire, handler invocation), not on internal types.

Broker-Backed Transport Integration Tests

Executor: tests/LiteBus.Durable.IntegrationTests/ Shared helpers: tests/LiteBus.Transport.IntegrationTesting/ Subfolders: Ingress/, Dispatch/Inbox/, Dispatch/Outbox/, Registration/ (grouped by broker: InMemory, Kafka, AwsSqs, AzureServiceBus, Amqp)

InMemory scenarios run without Docker. Kafka, AWS SQS (LocalStack), Azure Service Bus, and AMQP use Testcontainers.

xUnit Categories (CI Filters)

Registration smoke (Registration/BrokerDispatchIngressRegistrationTests.cs) has no category trait; it runs in the Integration Tests CI batch.

# Durable matrix only
dotnet test tests/LiteBus.Durable.IntegrationTests --filter "Category=TransportFast"
dotnet test tests/LiteBus.Durable.IntegrationTests --filter "Category=TransportDocker"
dotnet test tests/LiteBus.Durable.IntegrationTests --filter "Category=TransportAzure"
dotnet test tests/LiteBus.Durable.IntegrationTests --filter "Category=TransportDocker&FullyQualifiedName~Kafka"

# Full solution (matches CI)
dotnet test LiteBus.slnx --filter "Category=TransportFast"
dotnet test LiteBus.slnx --filter "Category=TransportDocker"
dotnet test LiteBus.slnx --filter "Category=TransportAzure"
dotnet test LiteBus.slnx --filter "Category=TransportDocker&FullyQualifiedName~Kafka"

Fixtures per Broker

Pre-declared Azure emulator queues: litebus-ingress, litebus-dispatch, litebus-outbox, litebus-fail. ResolveQueue(prefix) maps scenario names to those queues.

Shared Test Messages

Defined in TransportTestMessages.cs under LiteBus.Transport.IntegrationTesting:

Scenario Classes (by Folder)

InMemory (Ingress/InMemory/, Dispatch/Inbox/InMemory/, Dispatch/Outbox/InMemory/)

Kafka (Ingress/Kafka/, Dispatch/Inbox/Kafka/, Dispatch/Outbox/Kafka/)

Shared infrastructure lives in tests/LiteBus.Transport.IntegrationTesting/Kafka/ (KafkaBrokerHost, KafkaBrokerFixture, KafkaIngressTestSupport, KafkaTransportTestInfrastructure).

Ingress tests run production TransportInboxIngressConsumer and InboxProcessorBackgroundService through ExecuteAsync on background tasks. Short-lived test hosts call DisposeProviderSafelyAsync before tearing down Kafka clients because IHostedService orchestration can block on librdkafka shutdown.

Header edge cases, duplicate MessageId idempotency, and full requeue on/off are covered in Ingress/InMemory/ and Ingress/AwsSqs/. The Kafka Docker suite adds end-to-end flow, failure paths, and TransientAcceptFailure_ShouldRedeliverSameOffsetWithoutRestart (partial requeue-enabled redelivery via seek).

AWS SQS (Ingress/AwsSqs/, Dispatch/Inbox/AwsSqs/, Dispatch/Outbox/AwsSqs/)

Azure (Ingress/AzureServiceBus/, Dispatch/Inbox/AzureServiceBus/, Dispatch/Outbox/AzureServiceBus/)

Registration (Registration/)

Ingress Ack Policy (Cross-Broker)

TransportInboxIngressConsumer discards (no requeue) when acceptance throws:

• MessageContractNotRegisteredException
• InboxDispatchException (missing/invalid transport headers)
• InboxStorageException (capacity / persistence rejection)
• InvalidOperationException, ArgumentException, FormatException, JsonException

Other failures honor RequeueOnFailure (default true). Unit reference: LiteBus.Inbox.UnitTests/Ingress/TransportInboxIngressConsumerTests.cs.

Coverage Matrix (Ingress)

Legend: yes = broker Docker/emulator integration test; partial = subset of scenarios or covered via another project; - = no broker-specific test (see InMemory for shared ingress behavior).

Duplicate MessageId: AMQP partial = DuplicateBrokerDelivery_ShouldExecuteHandlerOnce in LiteBus.Storage.IntegrationTests (PostgreSQL + AMQP reliable-messaging chain), not a dedicated ingress-only idempotency test.

Header edge cases: AWS partial = missing contract name, wrong version, invalid MessageId (not missing contract version or wrong CLR shape). AMQP partial = LiteBus.Inbox.UnitTests/Ingress/Amqp/ handler mapping plus failure nack paths in Ingress/Amqp/ (no dedicated header matrix on RabbitMQ).

Requeue on/off: partial = requeue enabled only (RequeueEnabled_WithTransientStoreFailure... or Kafka seek redelivery). Full on/off pairs exist for InMemory and AWS only.

Coverage Matrix (Dispatch)

AMQP ingress and dispatch scenarios live in LiteBus.Durable.IntegrationTests (Ingress/Amqp/, Dispatch/Inbox/Amqp/, Dispatch/Outbox/Amqp/). Low-level AMQP wire behavior is in LiteBus.Transport.IntegrationTests/Amqp/.

PostgreSQL Storage Integration Tests

Project: tests/LiteBus.Storage.IntegrationTests/ Folder: PostgreSql/ Fixture: PostgreSqlFixture (postgres:16-alpine, retry loop, optional LITEBUS_TEST_POSTGRES_CONNECTION_STRING)

What This Project Proves

PostgreSQL is the reference durable store for inbox, outbox, saga, schema management, work signals, and full-stack reliable messaging.

Composite Broker Usage

PostgreSqlReliableMessagingEndToEndTests and PostgreSqlInboxIngressEndToEndTests spin up RabbitMqBrokerFixture inside the test alongside the shared PostgreSQL fixture. That pattern tests storage + broker together without pulling the full durable transport matrix project.

Quarantined Tests

Some work-signal reconnection tests carry [Trait("Category", "Quarantine")] due to timing sensitivity. Exclude them in routine runs if needed:

dotnet test tests/LiteBus.Storage.IntegrationTests --filter "Category!=Quarantine"

Entity Framework Core Storage Integration Tests

Project: tests/LiteBus.Storage.IntegrationTests/ Folders: EntityFrameworkCore/Inbox/, EntityFrameworkCore/Outbox/

Both use the same fixture pattern as PostgreSQL storage (Testcontainers PostgreSQL and SQL Server). Tests use dedicated IntegrationInboxDbContext / IntegrationOutboxDbContext types and EF interceptors where transactional behavior matters.

Inbox EF Core Scenarios

Outbox EF Core Scenarios

Outbox EF Core PostgreSQL tests can share PostgreSqlCollection for collection-scoped fixture reuse.

AMQP Integration Tests

AMQP coverage spans two projects: low-level wire protocol in LiteBus.Transport.IntegrationTests, and inbox/outbox ingress and dispatch in LiteBus.Durable.IntegrationTests. RabbitMQ and LavinMQ are both exercised where broker differences matter.

LiteBus.Transport.IntegrationTests (Amqp/)

Fixtures: RabbitMqFixture, LavinMqFixture Focus: Wire protocol behavior without inbox/outbox LiteBus.

LiteBus.Durable.IntegrationTests: AMQP Ingress (Ingress/AMQP/)

Fixtures: RabbitMqBrokerFixture, LavinMqBrokerFixture Storage: InMemory inbox (fast ingress focus)

LiteBus.Durable.IntegrationTests: AMQP Inbox Dispatch (Dispatch/Inbox/AMQP/)

LiteBus.Durable.IntegrationTests: AMQP Outbox Dispatch (Dispatch/Outbox/AMQP/)

Hosting and Composition Integration Tests

These projects validate host adapters without replacing broker or storage matrices. v6 composition smoke is a unit test in LiteBus.Runtime.UnitTests/Runtime/Composition/LiteBusV6CompositionSmokeTests.cs.

LiteBus.Extensions.IntegrationTests: Health Checks (HealthChecks/)

Docker: No Setup: InMemory inbox + registered IDiagnosticCheck probes + AddHealthChecks().AddLiteBus()

LiteBus.Extensions.IntegrationTests: OpenTelemetry (OpenTelemetry/)

Docker: No Setup: OpenTelemetry SDK builder with AddLiteBusInboxInstrumentation / metrics extensions

Proves public ActivitySourceName, MeterName, and instrument constants are subscribed correctly (stable consumer contract).

LiteBus.Extensions.IntegrationTests: ASP.NET Core (AspNetCore/)

Docker: Yes (PostgreSQL) Setup: TestServer host with management endpoints mapped; real PostgreSQL inbox/outbox storage

Shared Transport Contract Tests

Library: LiteBus.Transport.Testing NuGet package (tests/LiteBus.Transport.Testing/ in this repository)

The abstract TransportContractTests class verifies the common ITransportPublisher and IMessageConsumer contract without depending on a broker SDK. Concrete test classes supply an isolated TransportContractContext containing the adapter instances, consumer endpoint, publish destination and route, and cleanup callback.

LiteBus runs this suite against LiteBus.Transport.InMemory in unit tests and RabbitMQ in Docker integration tests. Custom adapter authors should reference LiteBus.Transport.Testing, derive one concrete xUnit class, and run it against the real broker used by their adapter.

Shared Store Contract Tests

Library: LiteBus.Storage.Testing NuGet package (tests/LiteBus.Storage.Testing/ in this repository)

Abstract test classes define store behavior contracts inherited by InMemory unit tests, PostgreSQL integration tests, and EF Core integration tests. One implementation, many backends.

Direct PostgreSQL and EF Core PostgreSQL suites also pass a caller timestamp ten years ahead of database time. The tests verify that future-visible rows remain hidden and that lease expiry uses the database clock. | InboxRetentionStoreContractTests / OutboxRetentionStoreContractTests | Retention-specific roles |

When adding a custom inbox or outbox store, reference LiteBus.Storage.Testing and inherit these suites in your test project before writing provider-specific tests.

Running Integration Tests Locally

Full Solution (Docker Required for Most Integration Projects)

dotnet test LiteBus.slnx

If Docker is not running, PostgreSQL and AMQP integration tests fail during fixture setup. Durable transport Docker and Azure categories skip individual tests where [SkippableFact] is used. CI runs docker info before these suites and treats unavailable Docker as a failed prerequisite, so local skip behavior does not hide a CI environment error.

Unit Tests Only

dotnet test LiteBus.slnx --filter "FullyQualifiedName!~IntegrationTests"

Exclude PostgreSQL Integration Tests

dotnet test LiteBus.slnx --filter "FullyQualifiedName!~PostgreSql"

By Concern

# Broker transport: durable matrix only (CI category batches)
dotnet test tests/LiteBus.Durable.IntegrationTests --filter "Category=TransportFast"
dotnet test tests/LiteBus.Durable.IntegrationTests --filter "Category=TransportDocker"
dotnet test tests/LiteBus.Durable.IntegrationTests --filter "Category=TransportAzure"
dotnet test tests/LiteBus.Durable.IntegrationTests --filter "Category=TransportDocker&FullyQualifiedName~Kafka"

# Broker transport: full solution (matches CI)
dotnet test LiteBus.slnx --filter "Category=TransportFast"
dotnet test LiteBus.slnx --filter "Category=TransportDocker"
dotnet test LiteBus.slnx --filter "Category=TransportAzure"

# PostgreSQL storage only
dotnet test tests/LiteBus.Storage.IntegrationTests --filter "FullyQualifiedName~PostgreSql"

# AMQP ingress only (durable matrix)
dotnet test tests/LiteBus.Durable.IntegrationTests --filter "FullyQualifiedName~Ingress.Amqp"

# AMQP wire protocol only
dotnet test tests/LiteBus.Transport.IntegrationTests

Optional Live Azure Overlay

Set both variables, then run the live Azure category:

export LITEBUS_TEST_AZURE_SERVICEBUS_CONNECTION_STRING="Endpoint=sb://..."
export LITEBUS_TEST_AZURE_SERVICEBUS_QUEUE="your-queue"
dotnet test LiteBus.slnx --filter "Category=TransportLiveAzure"

What This Does Not Cover

• Unit tests (*UnitTests* projects): handler logic, mappers, module build order, circuit breaker math. Run via the CI unit-test filter.
• Benchmarks (benchmarks/): performance, not correctness contracts.
• Production Azure Service Bus as the default CI path: CI uses the emulator; live namespace is opt-in.
• Every broker on every scenario: see the ingress/dispatch matrices above for intentional gaps (for example Azure duplicate MessageId and header edge cases on emulator, Kafka full requeue on/off, AMQP requeue disabled drain).

Next

• Testing: InMemory processor recipes, ack policy summary, quick CI filters
• Testing LiteBus: handler unit tests, mediation pipeline, WebApplicationFactory
• Hosted services: IStartupTask, IBackgroundService, and manifest registration tested by PostgreSQL hosting integration tests
• Reliable Messaging: outbox to broker to inbox patterns exercised in PostgreSqlReliableMessagingEndToEndTests