DOCSEARCHbyAlgolia
Submit Docs

Testcontainers for Go

repository·main·Indexed 26 days ago

https://github.com/testcontainers/testcontainers-go

A Go library for programmatically managing Docker containers as dependencies for integration and smoke testing, providing automated lifecycle management for setup and cleanup. Includes specialized modules such as the Dex module for managing OIDC containers with support for OAuth2 clients, users, and gRPC runtime management.

Tokens
89K
Snippets
252
Records
834
Agent score
90%

What's inside testcontainers-go

  1. Overview of Testcontainers for Go

    main
    Testcontainers for Go is a Go package designed to simplify the creation and cleanup of container-based dependencies for automated integration and smoke tests. It provides a programmatic API to define containers that run during your tests and ensures those resources are cleaned up once the tests are complete.

  2. Overview of Azure modules

    main

    The Azure module provides Testcontainers implementations for several Azure services. The available packages are:

    • github.com/testcontainers/testcontainers-go/modules/azure/azurite: Azurite (Azure Storage emulator)
    • github.com/testcontainers/testcontainers-go/modules/azure/eventhubs: EventHubs (Note: Requires explicit EULA acceptance via WithAcceptEULA)
    • github.com/testcontainers/testcontainers-go/modules/azure/servicebus: ServiceBus
    • github.com/testcontainers/testcontainers-go/modules/azure/cosmosdb: CosmosDB
    • github.com/testcontainers/testcontainers-go/modules/azure/lowkeyvault: Lowkey Vault
    • github.com/testcontainers/testcontainers-go/modules/azure/sqledge: Azure SQL Edge

  4. Use Ryuk for automatic resource cleanup

    main

    Ryuk (also known as the Reaper) is a sidecar container that automatically removes containers, networks, and volumes created by Testcontainers for Go. It identifies resources via container labels and ensures the environment stays clean even if Terminate is not explicitly called.

    Note: If a container is running for more than 10 seconds, Ryuk will kill it.

  5. Available GCloud modules

    main

    The GCloud module provides emulators for several Google Cloud services via dedicated Go packages:

    • BigQuery: github.com/testcontainers/testcontainers-go/modules/gcloud/bigquery
    • BigTable: github.com/testcontainers/testcontainers-go/modules/gcloud/bigtable
    • Datastore: github.com/testcontainers/testcontainers-go/modules/gcloud/datastore
    • Firestore: github.com/testcontainers/testcontainers-go/modules/gcloud/firestore
    • Pubsub: github.com/testcontainers/testcontainers-go/modules/gcloud/pubsub
    • Spanner: github.com/testcontainers/testcontainers-go/modules/gcloud/spanner

    Default Docker Images:

    • Most emulators use gcr.io/google.com/cloudsdktool/cloud-sdk:367.0.0-emulators.
    • BigQuery uses ghcr.io/goccy/bigquery-emulator:0.6.1.
    • Spanner uses gcr.io/cloud-spanner-emulator/emulator:1.4.0.

  6. Configure Wait Strategies in Testcontainers for Go

    main

    Wait strategies allow your tests to pause execution until a container reaches a specific state (e.g., a network port is open, a log message appears, or a file exists). Wait strategies are implemented in the wait package.

    Available strategies include:

    • Exec: Wait for a command to execute successfully.
    • Exit: Wait for the container to exit.
    • File: Wait for a file to appear.
    • Health: Wait for a container health check to pass.
    • HostPort: Wait for a port to become available on the host.
    • HTTP: Wait for an HTTP response.
    • Log: Wait for a specific log message.
    • SQL: Wait for a database to be ready.
    • TLS: Wait for a TLS connection.
    • ForAll: Wait for all provided strategies to satisfy.
    • ForAny: Wait for any one of the provided strategies to satisfy.

  7. Understand Test Session Semantics in Testcontainers for Go

    main

    Testcontainers for Go uses 'Test Session Semantics' to identify and group container creations within a single test execution. This allows the library to aggregate tests across multiple Go packages that are part of the same execution context.

    A 'test session' is defined as:

    • A single go test invocation (including flags).
    • A single go test ./... invocation for all subpackages.
    • The execution of a single test or a set of tests via an IDE.

    To ensure uniqueness across different processes, Testcontainers for Go generates a unique sessionID by hashing the string testcontainers-go: combined with the parent process ID (PID) and the creation date of that parent process. This sessionID is used to:

    1. Aggregate test executions across multiple packages in the same session.
    2. Pass the sessionID to the container runtime via an HTTP header to the daemon.
    3. Tag created containers with a label containing the sessionID.