hesper

Hesper

Hesper manages Apple Container lifecycle for Go integration tests. Run real services like PostgreSQL in lightweight containers during tests.

Requirements

• macOS 15+ on Apple Silicon
• Apple Container CLI v0.10.0+

Install

go get codeberg.org/graphei/hesper

Quick start

func TestDatabase(t *testing.T) {
    ctx := context.Background()

    pg, err := postgres.Run(ctx, "postgres:16-alpine",
        postgres.WithHostPort(15432),
        postgres.WithDatabase("testdb"),
    )
    if err != nil {
        t.Fatal(err)
    }
    defer pg.Stop(ctx)

    pool, err := pgxpool.New(ctx, pg.MustConnectionString())
    // ... run queries
}

Core API

container, err := hesper.Run(ctx, "alpine:latest",
    hesper.WithPort(18080, 8080),
    hesper.WithEnv("KEY", "value"),
    hesper.WithCommand("sleep", "60"),
)
defer container.Stop(ctx)

host, _ := container.Host(8080) // "127.0.0.1:18080"
logs, _ := container.Logs(ctx)

Options

Wait strategies

hesper.NewWaitForLog("Server started")                        // match a log line
hesper.WaitForLogOccurrence("ready", 2)                       // match N occurrences
hesper.NewWaitForExec("pg_isready")                           // run command inside container
hesper.NewWaitForPort(8080)                                   // wait for TCP port
hesper.NewWaitForAll(logWait, portWait)                       // combine strategies
hesper.NoWait{}                                               // skip waiting

PostgreSQL module

import "codeberg.org/graphei/hesper/modules/postgres"

pg, err := postgres.Run(ctx, "postgres:16-alpine",
    postgres.WithHostPort(15432),
    postgres.WithDatabase("mydb"),
    postgres.WithUsername("user"),
    postgres.WithPassword("pass"),
)

dsn := pg.MustConnectionString()
// postgres://user:pass@127.0.0.1:15432/mydb?sslmode=disable

The postgres module waits for readiness via pg_isready by default. Each test should use a unique host port to avoid conflicts when running in parallel.

Errors

Use errors.Is() to check for specific failures:

How it works

Hesper calls container run to start containers with published ports, inspects for port mappings, waits for readiness, then returns a *Container. Access services via Host(containerPort) which returns the 127.0.0.1:hostPort address.

Cleanup happens via Stop() or WithAutoRemove(). A reaper automatically cleans up orphaned containers from previous test runs on startup.

Running tests

# Unit tests (no containers needed)
go test ./...

# Integration tests (requires running container CLI)
go test -tags integration -parallel 7 -timeout 120s ./...

License

AGPL-3.0