Floci.Testcontainers.Core 1.0.1

<p align="center"> <img src="https://raw.githubusercontent.com/floci-io/.github/main/floci.svg#gh-light-mode-only" alt="Floci" width="500" /> <img src="https://github.com/user-attachments/assets/edfff8b3-926c-471e-9549-77fb90a21b49#gh-dark-mode-only" alt="Floci" width="500" /> </p>

<p align="center"> <strong>Any Cloud. Locally.</strong><br /> Light, fluffy, and always free: Testcontainers for .NET<br /> No account. No auth token. No feature gates. </p>

<p align="center"> <a href="https://github.com/floci-io/testcontainers-floci-dotnet/actions/workflows/release-please.yml"><img src="https://github.com/floci-io/testcontainers-floci-dotnet/actions/workflows/release-please.yml/badge.svg" alt="publish"></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/license-MIT-green" alt="License: MIT"></a> <a href="https://github.com/floci-io/testcontainers-floci-dotnet/stargazers"><img src="https://img.shields.io/github/stars/floci-io/testcontainers-floci-dotnet?style=flat" alt="GitHub Stars"></a> </p>

<p align="center"> <a href="#quick-start">Quick Start</a> · <a href="#service-configuration">Configuration</a> · <a href="#the-floci-emulators">Emulators</a> · <a href="https://floci.io/floci/testcontainers/dotnet/">Docs</a> </p>

What is this?

A Testcontainers for .NET module for Floci, the free, open-source local AWS emulator.

It runs the floci/floci container for your integration tests, gives you an endpoint to point the AWS SDK for .NET at, and adds a typed, per-service configuration API over Floci's environment-variable surface, including the container-based services (RDS, Lambda, ElastiCache, ECS, EC2, ECR and others) that spawn real backing containers. No AWS account, no token.

This module mirrors the API of the official testcontainers-floci (Java) and testcontainers-floci-python modules. It adds no emulation logic of its own: Floci does all the AWS emulation, and this is the typed .NET front door to it.

Targets net8.0, net9.0, net10.0, netstandard2.0, netstandard2.1.

The Floci emulators

testcontainers-floci-dotnet is the .NET member of the Floci Testcontainers family. Floci is named after floccus, the cloud formation that looks like popcorn.

Installation

dotnet add package Floci.Testcontainers.Aws

Floci.Testcontainers.Aws brings in Floci.Testcontainers.Core, the shared part every Floci cloud package builds on. Code lives in the Floci.Testcontainers.Aws namespace.

The packages are published to nuget.org, so no feed or token setup is needed.

Migrating from Testcontainers.Floci

Up to 0.16.x the package was Testcontainers.Floci, an id that belongs to the official testcontainers-dotnet module on nuget.org. From 1.0.0 it is Floci.Testcontainers.Aws:

1. Replace the package reference: dotnet remove package Testcontainers.Floci, then dotnet add package Floci.Testcontainers.Aws. The 0.16.x line was published to the floci-io GitHub Packages feed; 1.0.0 and later come from nuget.org, so the floci-io feed, its credentials and its packageSourceMapping entry can be removed from nuget.config. Without that mapping, NuGet could also resolve Testcontainers.Floci from nuget.org, where that id is the unrelated official module.
2. Replace using Testcontainers.Floci; with using Floci.Testcontainers.Aws;.

The types (FlociBuilder, FlociContainer, every *Config) keep their names and behaviour, with one difference: the Docker socket is now decided from the container's final environment, so it is mounted by default (see Container-based services).

Versioning

Releases are cut with release-please, as in the Java module. Each Conventional Commit merged to main updates one release PR (feat: → minor, fix:/perf: → patch, !/BREAKING CHANGE → major). A release happens when a maintainer merges that PR.

Quick start

Use it from an xUnit test via IAsyncLifetime. The builder takes the image, optional global settings (region/account), and per-service config; GetEndpoint() plus the dummy credentials wire up any AWS SDK client:

public sealed class OrderTests : IAsyncLifetime
{
    private readonly FlociContainer _floci = new FlociBuilder("floci/floci:latest")
        .WithRegion("eu-west-2")
        .WithSqs(new SqsConfig { VisibilityTimeout = 60 })
        .Build();

    public Task InitializeAsync() => _floci.StartAsync();
    public Task DisposeAsync() => _floci.DisposeAsync().AsTask();

    [Fact]
    public async Task SendsAndReceives()
    {
        using var sqs = new AmazonSQSClient(
            _floci.AccessKey,
            _floci.SecretKey,
            new AmazonSQSConfig
            {
                ServiceURL = _floci.GetEndpoint(),
                AuthenticationRegion = _floci.Region,
            });

        var queueUrl = (await sqs.CreateQueueAsync("orders")).QueueUrl;
        await sqs.SendMessageAsync(queueUrl, "hello from floci");

        var received = await sqs.ReceiveMessageAsync(queueUrl);
        Assert.Single(received.Messages);
    }
}

Service configuration

Each service has a typed XxxConfig record exposing its settings (mirroring Floci's FLOCI_SERVICES_* env vars), applied via builder.WithXxx(...). Enabling a service is just adding its WithXxx; Floci enables most services by default regardless. See the Floci documentation for the full list of services the emulator supports.

Supported services

Flat services (single endpoint), for example S3, SQS, SNS, DynamoDB, Secrets Manager, SSM, KMS, EventBridge (plus Pipes and Scheduler), IAM, Kinesis, Firehose, CloudWatch Logs and Metrics, SES and SES v2, Step Functions, Glue, Cognito, CloudFormation, API Gateway (v1 & v2), Route 53, CloudFront, ELBv2, Athena, AppConfig, AppSync, Textract, Transcribe, AWS Config, Auto Scaling, Backup, Transfer Family, CloudTrail, Cloud Map, EMR, WAFv2, RDS Data, and the billing APIs (Cost Explorer, CUR, Pricing, BCM Data Exports).

Container-based services (spawn real backing containers): RDS (Postgres/MySQL/MariaDB), ElastiCache (Valkey/Redis & Memcached), Lambda (real function execution), ECS, EC2, ECR, MSK (Redpanda), OpenSearch, Neptune (Gremlin), EKS (k3s), CodeBuild, Batch.

STS works out of the box (always on; no config). The authoritative list of config records is the set of *Config.cs files in src/Floci.Testcontainers.Aws.

Container-based services

Container-based services make Floci spawn sibling containers (a real Postgres, a Lambda runtime, a Valkey, a Redpanda broker, an OpenSearch node, a k3s cluster, etc.). The module mounts the Docker socket when an enabled service needs it and publishes the needed ports automatically. The decision reads the container's final environment, including raw WithEnvironment overrides. Floci enables every service by default, so the socket is mounted unless those services are disabled or mocked; WithoutDockerSocket() and WithDockerSocket(path) force the choice either way. Each container also gets a unique resource namespace (tc-xxxxxxxx) that prefixes the sibling containers' names, so parallel test runs never collide. A few practical notes when using them:

• Connect to spawned backends via 127.0.0.1 (not localhost) to avoid IPv6 resolution.
• On macOS, RDS's default proxy base port 7000 collides with Control Center (AirPlay); set new RdsConfig { ProxyBasePort = 7010 }.
• Delete resources you create in test teardown (DeleteDBInstance, DeleteReplicationGroup, DeleteFunction) so Floci removes their sibling containers. They are managed by Floci, not tracked by the Testcontainers resource reaper.
• ECS and EC2 support a Mock mode (new EcsConfig { Mock = true }) that returns RUNNING without launching containers, handy for deterministic tests.

Container options

Builder options beyond the per-service configs: WithRegion, WithAccountId, WithAvailabilityZone, WithResourceNamespace, WithDockerSocket(path) and WithoutDockerSocket().

Readiness is determined by polling Floci's /_floci/health endpoint on port 4566, which is mapped to a random host port.

Docker image tags

Always pass the image explicitly, e.g. new FlociBuilder("floci/floci:latest"). Every Floci emulator publishes latest, x.y.z and nightly tags, so you can pin a release, follow latest, or test against main with nightly:

new FlociBuilder("floci/floci:x.y.z");   // a specific release (recommended for CI)
new FlociBuilder("floci/floci:latest");  // the current emulator
new FlociBuilder("floci/floci:nightly"); // built from main every night

This module deliberately diverges from the rest of the family here. The other modules default to the floating latest tag; the .NET builder's baked-in default is a pinned tag (a specific x.y.z release), exposed through the parameterless FlociBuilder() constructor and the FlociBuilder.FlociImage constant. Both are marked [Obsolete] and will be removed in a future version in favour of always passing the image, so new code should not rely on them.

The tag this repository's integration tests run against is declared in TestImages.cs. The images cached by CI are listed in .github/docker-images.txt.

Requirements

• A target framework supported by the package (net8.0+ or any netstandard2.0/2.1 consumer)
• Docker

Building and testing

dotnet build -warnaserror
dotnet test   # requires a running Docker daemon

Unit tests (*ConfigTest, no Docker) live in tests/Floci.Testcontainers.Aws.Tests and integration tests (*ServiceTest, real Floci containers) in tests/Floci.Testcontainers.Aws.IntegrationTests. Test parallelization is disabled in the integration project on purpose: container-backed tests flake under Docker daemon load. See CONTRIBUTING.md for the project layout, the branching model, and how to add a service.

Running on Colima

The module itself is environment-agnostic. Colima exposes the Docker socket over virtiofs, so its macOS host socket path can't be bind-mounted into a container (this otherwise breaks the Testcontainers resource reaper). Point Testcontainers at the in-VM socket path instead:

export TESTCONTAINERS_DOCKER_SOCKET_OVERRIDE="/var/run/docker.sock"
# and, if your DOCKER_HOST isn't already set to the Colima socket:
export DOCKER_HOST="unix://$HOME/.colima/default/docker.sock"

On native Linux Docker (e.g. CI), neither variable is needed.

Other languages

Community

• 💬 Slack: quick questions and community chat
• 🗣️ GitHub Discussions: ideas, design tradeoffs, and proposals
• CONTRIBUTING.md · SECURITY.md · CODE_OF_CONDUCT.md · MAINTAINERS.md

License

MIT. See LICENSE.

<div align="center">

Floci™ is a trademark of Hector Ventura. Code is MIT-licensed; see TRADEMARK.md for name and logo use.

</div>