Gnomock integration testing with temporary Docker services

Why Gnomock replaces dependency mocks in Go tests

Gnomock addresses the gap between unit tests that replace dependencies with mocks and integration tests that exercise real application behavior. Code that reads and writes PostgreSQL, publishes Kafka events, stores objects through S3-compatible services, or sends data to Splunk can behave differently when tested only against a substitute. Gnomock starts the real dependency in a temporary Docker container, configures selected initial state, exposes a connection endpoint, and cleans up the container after the test.

The primary audience is Go developers writing integration or end-to-end tests. The README says Gnomock can also run as an HTTP daemon for applications written in other languages, although that usage is documented separately in `docs/server.md`. The project description emphasizes setup through code rather than Bash or YAML. That applies to the Go package workflow, where Presets and options are expressed in Go source. It does not remove the need for Docker.

The “no mocks” promise has a specific boundary. Gnomock removes the need to simulate supported dependencies when an actual container is useful. It does not remove the need to design test data, assert outcomes, inspect side effects, or isolate tests from one another. Those responsibilities remain with the test, even though service setup moves into the library.

How a Gnomock Preset controls a temporary service

The central abstraction is a Preset. A Go test constructs a service-specific Preset, starts it through `gnomock.Start`, and receives a container object. Preset options describe configuration and initial state before startup. In the PostgreSQL example, the options create a user, create a database, and load a SQL file. Other Presets apply different setup mechanisms, such as uploading test data into S3 or sending test events to Splunk.

After startup, the returned container supplies the connection details required by the client library. In the documented PostgreSQL flow, the test reads `container.Host` and `container.DefaultPort()` and builds a `database/sql` connection string. This keeps service-specific orchestration in the Preset while the test exercises application behavior.

Cleanup is explicit. The README registers `gnomock.Stop(container)` with `t.Cleanup`, linking container removal to the test lifecycle. The short example discards errors from startup, shutdown, and `sql.Open`. That is readable as a demonstration, but it is not a complete error-handling pattern. A suite that needs reliable diagnosis must check failures instead of copying the ignored returns unchanged. The documented contract itself remains straightforward: configure a Preset, start the container, connect through its endpoint, and stop it when the test completes.

Installing Gnomock and running a PostgreSQL test

Gnomock can be imported directly into a Go project. The README gives this installation command:

go get github.com/orlangure/gnomock

The command adds the Gnomock module to the Go project. Gnomock also requires an active Docker daemon running locally in the same environment. The following example configures a PostgreSQL Preset with a user, database, and schema file, starts it, and registers cleanup with `t.Cleanup`:

p := postgres.Preset(
    postgres.WithUser("gnomock", "gnomick"),
    postgres.WithDatabase("mydb"),
    postgres.WithQueriesFile("/var/project/db/schema.sql"),
)
container, _ := gnomock.Start(p)
t.Cleanup(func() { _ = gnomock.Stop(container) })

The schema path in this example belongs to the documented project layout. A reader must replace it with the path to an existing SQL file in the local project. The README then uses the container endpoint to create a PostgreSQL connection string:

connStr := fmt.Sprintf(
    "host=%s port=%d user=%s password=%s  dbname=%s sslmode=disable",
    container.Host, container.DefaultPort(),
    "gnomock", "gnomick", "mydb",
)
db, _ := sql.Open("postgres", connStr)

The example imports `_ "github.com/lib/pq"` for the PostgreSQL driver. According to the README, the database is ready with the requested schema and data after the Preset starts. The example ignores errors for brevity, so a real test should check startup, cleanup, and database connection failures. The command and code above come directly from the README and should not be treated as a complete production test template.

Gnomock Preset versions and arm64 coverage

Gnomock is useful only when its Preset matches the dependency needed by the test. The README lists PostgreSQL versions from `10.15` through `16.2`, MySQL `5.7.32` and `8.0.22`, MariaDB `10.5.8` and `11.2.2`, MongoDB `3.6.21`, `4.4`, and `5.0`, Redis `5.0.10`, `6.0.9`, and `7.2.4`, and Memcached `1.6.9` and `1.6.23`. It also lists Localstack, Splunk, Kafka, Elasticsearch, RabbitMQ, and Microsoft SQL Server.

The README defines supported service versions as versions tested in the CI pipeline. It also warns that other versions might work. That distinction matters because an image outside the listed set may start but may not behave as the Preset expects. A team using a newer database or broker should check the Preset package documentation and release changes rather than assuming compatibility from the name alone.

Architecture support is uneven in the documented table. Localstack, Redis, Memcached, MySQL, MariaDB, PostgreSQL, MongoDB, RabbitMQ, and Kafka are marked as supporting arm64. Splunk and Microsoft SQL Server are marked as unsupported on arm64. Because Docker executes the service image locally, a developer on an arm64 workstation must check the architecture entry for the required Preset. The supported version list alone does not establish that a service can start on that host.

Docker locality and the experimental remote-host path

The main operational constraint is environmental. Both usage modes require an active Docker daemon in the same environment as Gnomock. Tests therefore depend on Docker availability, container permissions, image access, and the local capacity needed to run the selected services. A test that works on one workstation can fail on another because the daemon is missing, even when the Go code has not changed.

External `DOCKER_HOST` support is described as experimental. The README says it cannot be reliably tested at that time and might work. That is not a firm basis for remote Docker execution in a shared CI service or on a remote test host. A team considering that arrangement should treat local daemon operation as the supported baseline unless it verifies the remote setup for its own environment.

The HTTP daemon provides a route for non-Go languages, but the README points users to `docs/server.md` instead of documenting the request format or startup configuration. The repository Dockerfile builds `./cmd/server` and exposes it as `/gnomockd`, but it does not provide a user-facing command with a port or environment variable. The Go package is therefore the better documented first path. An engineer who needs the HTTP mode must consult `docs/server.md` rather than infer an API from the Dockerfile.

Gnomock compared with direct Docker orchestration

Direct Docker orchestration is a practical alternative. A test can create containers through the Docker API or a command-line tool, publish ports, initialize data, wait for readiness, and remove the container itself. That approach keeps lifecycle steps in the test suite and avoids adding Gnomock as a Go package. It also makes the test responsible for every service-specific detail.

Gnomock moves those operations into Presets and provides a Go-oriented lifecycle through `gnomock.Start` and `gnomock.Stop`. The PostgreSQL example shows how this reduces setup code by expressing user, database, and schema-file options in Go. The cost is an abstraction layer between the test and Docker, plus compatibility boundaries based on the Preset and the service versions documented as tested.

Neither approach replaces Docker with an in-process service. Gnomock creates a temporary container around the actual software. It is a poor fit for pure unit tests where a narrow interface is sufficient and container startup adds unnecessary work. The README provides no startup measurements or formal comparison with direct Docker scripts, so the defensible difference is code organization and Preset coverage, not a performance claim.

Maintenance, upgrades, and MIT licence considerations

The repository is not archived, and its last push was on 2026-04-13. The latest listed release is `v0.32.0`, dated 2025-06-07. Earlier releases are `v0.31.0` from 2024-06-04 and `v0.30.0` from 2023-08-26. The recent push date shows repository activity after the latest listed release, but it does not prove that every Preset is compatible with every Docker image or service version.

An upgrade can affect more than the application module. The repository declares `go 1.24.0` and contains client dependencies for PostgreSQL, MySQL, MongoDB, Kafka, Redis, RabbitMQ, Elasticsearch, Microsoft SQL Server, Azure, AWS, and other Presets. A team should review changes to the selected Preset, its documented service versions, and its initialization behavior. The README's CI-based version list provides a concrete compatibility target.

The project uses the MIT licence. That identifier is relevant when reviewing redistribution and modification terms, but this article does not interpret the licence text or provide legal advice. Engineers should read the repository `LICENSE` file and apply their organization's dependency and notice policy. The main upgrade cost is test maintenance: changes to a Preset, driver, image, or startup contract may require corresponding test changes.

Editorial conclusion

Adopt Gnomock when a Go test needs a real service through a Preset and can use a local Docker daemon. Do not adopt it for fast tests without Docker, unsupported arm64 services, or remote Docker hosts that must behave reliably. Verify the required Preset, tested service version, architecture support, initialization files, and cleanup behavior in the target test environment.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. orlangure/gnomock on GitHub
4. README
5. Releases