golang testcontainers

AI Community

Skill notes

When to Use

Testing against a real Postgres, Redis, Kafka, NATS, or other containerised dependency Verifying SQL, migrations, indexes, transactions, locking, or driver behaviour Testing cache integration against a real Redis instance Replacing brittle fake environments with hermetic container-based integration tests Designing package-scoped test infrastructure that still allows parallel tests

Default Stance

Unless there is a clear reason not to, prefer these defaults: Use real containers for integration tests, not mocks Prefer module-specific helpers like postgres.Run and redis.Run over lower-level generic setup when a module exists Prefer testcontainers.Run over older GenericContainer patterns for generic services Register cleanup immediately with testcontainers.CleanupContainer(t, ctr) in normal tests

Terminology: Containers Are Not Mocks

For Postgres and Redis integration tests, prefer real Postgres and Redis containers. These are not mocks. Mocks/fakes are best for unit tests and narrow seams Testcontainers are best when you want confidence in the real dependency behaviour If the test is meant to validate SQL, migrations, transactions, Redis commands, TTL behaviour, or networked dependency behaviour, a real container is usually the right tool.

Version and API Notes

github.com/testcontainers/testcontainers-go is the main library Prefer modern Run(...) APIs GenericContainer is the older style; prefer testcontainers.Run(...) for new generic-container examples Module-level RunContainer(ctx, opts...) helpers are deprecated; prefer postgres.Run(...), redis.Run(...), etc. WithReuseByName(...) is experimental; do not make it your default CI/test strategy

Lifecycle Scope Tradeoffs

Choose container lifetime deliberately: Scope · Startup cost · Isolation · Parallel friendliness · Recommended use Per test · Highest · Strongest · Excellent · Small suites, destructive tests, tests that mutate process-wide server state Per package · Moderate · Strong if you isolate test data · Excellent when state is isolated correctly · Default for Postgres, Redis, and similar services Cross-package/shared reusable container · Lowest warm-start cost · Weakest · Risky · Local experimentation only; avoid as the default

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
AI
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@tomevault-io · no license declared
Token usage
Lean
Setup complexity
Manual integration
External API key
Not required
Operating systems
Linux · Docker
Runtime requirements
Docker
Detected file/system behavior
  • Read-only
  • Write / modify
  • Env read
Network behavior
Local-only
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

Output preview golang-testcontainers.preview
# Postgres Module Example

package repo_test

import (
    "context"
    "path/filepath"
    "testing"

    "github.com/stretchr/testify/require"

    "github.com/testcontainers/testcontainers-go"
    "github.com/testcontainers/testcontainers-go/modules/postgres"
)

func TestRepositoryWithPostgres(t *testing.T) {
    t.Parallel()

    ctx := context.Background()

    ctr, err := postgres.Run(ctx,
        "postgres:16-alpine",
        postgres.WithDatabase("app_test"),
        postgres.WithUsername("postgres"),
        postgres.WithPassword("postgres"),
        postgres.WithInitScripts(filepath.Join("testdata", "init.sql")),
        postgres.BasicWaitStrategies(),
    )
    testcontainers.CleanupContainer(t, ctr)
    require.NoError(t, err)

    dsn, err := ctr.ConnectionString(ctx, "sslmode=disable")
    require.NoError(t, err)

    _ = dsn // open your DB client here
}

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.