Testcontainers for Swift

A lightweight Swift library for writing tests with throwaway Docker containers, inspired by testcontainers-dotnet.

Requirements

• Swift 6.1+, macOS 13.0+ (or Linux)
• Docker or Docker Desktop running

Installation

Add to your Package.swift:

.package(url: "https://github.com/dragosv/testcontainers-swift.git", from: "0.1.0")

Quick Start

See QUICKSTART.md for a step-by-step guide.

import Testcontainers

let container = try await ContainerBuilder("nginx:latest")
    .withPortBinding(80, assignRandomHostPort: true)
    .withWaitStrategy(Wait.http(path: "/", port: 80))
    .buildAsync()

try await container.start()
defer { Task { try? await container.stop() } }

let port = try container.getMappedPort(80)

Modules

Pre-configured containers for common services — each exposes a getConnectionString() convenience method:

Module	Image
PostgresContainer	postgres
MySqlContainer	mysql
RedisContainer	redis
MongoDbContainer	mongo
MsSqlContainer	mcr.microsoft.com/mssql/server
RabbitMqContainer	rabbitmq
KafkaContainer	confluentinc/cp-kafka
ElasticsearchContainer	elasticsearch
AzuriteContainer	mcr.microsoft.com/azure-storage/azurite
LocalStackContainer	localstack/localstack

let postgres = try await PostgresContainer().withDatabase("testdb").start()
let connectionString = try postgres.getConnectionString()

Wait Strategies

Wait.http(port: 8080)          // HTTP 2xx response
Wait.tcp(port: 5432)           // TCP port open
Wait.log(message: "started")  // Log line match
Wait.exec(command: ["pg_isready"])
Wait.all(Wait.tcp(port: 5432), Wait.http(port: 8080))

XCTest Integration

final class DatabaseTests: XCTestCase {
    var postgres: PostgresContainerReference!

    override func setUp() async throws {
        postgres = try await PostgresContainer().withDatabase("testdb").start()
    }

    override func tearDown() async throws {
        try await postgres.stop()
    }

    func testConnection() async throws {
        let connectionString = try postgres.getConnectionString()
        XCTAssertNotNil(connectionString)
    }
}

Documentation

Document	Description
QUICKSTART.md	5-minute getting-started guide
ARCHITECTURE.md	Design decisions and component overview
PROJECT_SUMMARY.md	Full feature inventory and implementation stats
CONTRIBUTING.md	How to contribute
Examples/main.swift	Runnable usage examples

Contributing

Contributions are welcome — please read CONTRIBUTING.md first.

Acknowledgments

This project includes code derived from docker-client-swift by Alexander Steiner, licensed under MIT.

License

MIT — see LICENSE.

Support

Slack · Stack Overflow · GitHub Issues

---

Copyright © 2026 Dragos Varovici and contributors.