gnomock
Gnomock is a Go testing toolkit that spins up real Docker containers for dependencies (databases, caches, message queues) instead of using mocks, enabling integration tests against actual services. It provides preset configurations for 20+ popular services with automatic cleanup, reducing test setup boilerplate while improving test fidelity.
Key facts
Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.
| Field | Value |
|---|---|
| Repository | orlangure/gnomock |
| Owner | orlangure |
| Primary language | Go |
| License | MIT — OSI-approved |
| Stars | 1.5k |
| Forks | 79 |
| Open issues | 39 |
| Latest release | v0.32.0 (2025-06-07) |
| Last updated | 2026-04-13 |
| Source | https://github.com/orlangure/gnomock |
What gnomock is
Gnomock manages ephemeral Docker containers and exposes Go APIs (or HTTP daemon mode) to instantiate services with configurable initial state via presets. It supports 20+ services including PostgreSQL, MongoDB, Kafka, Redis, Elasticsearch, and others, with port mapping and lifecycle management. Go applications import it directly; non-Go projects use the HTTP server interface.
Get the gnomock source
Clone the repository and explore it locally.
git clone https://github.com/orlangure/gnomock.gitcd gnomock# follow the project's README for install & configurationNeed it deployed, integrated, or customized instead? DEV.co ships production installs.
Best use cases
Implementation considerations
- Ensure Docker daemon is accessible in your CI/CD pipeline; GitHub Actions, local development, and most cloud CI systems support this, but serverless or sandboxed environments do not.
- Port allocation must be managed: Gnomock assigns dynamic ports to avoid conflicts. Verify your application code reads container.DefaultPort() or explicit port properties, not hardcoded localhost ports.
- Test startup time increases due to container pull, boot, and schema initialization. Cache Docker images in CI and use minimal preset configurations to reduce overhead.
- Memory and resource constraints: Each test spawning a container consumes RAM and disk. Use t.Cleanup() or context managers to guarantee container teardown; orphaned containers will exhaust resources.
- Preset configuration flexibility varies: Some services (e.g., Postgres) offer rich setup options (schema files, users, databases); others are minimal. Review preset documentation to confirm your setup requirements are supported.
When to avoid it — and what to weigh
- Docker daemon unavailable in test environment — Gnomock requires a local Docker daemon. It cannot run in sandboxed or serverless test environments (e.g., GitHub Actions without Docker, or Lambda). Requires `DOCKER_HOST` setup for remote daemons, which is marked experimental and unreliable.
- Testing non-Go applications natively — While HTTP server mode exists for other languages, it is less documented and the Go library is the primary interface. Non-Go projects will have additional operational overhead running the daemon separately.
- Unit testing with strict isolation requirements — Gnomock is designed for integration and end-to-end tests. Unit tests that must run offline, in parallel without port conflicts, or in heavily containerized CI environments may face complexity managing ephemeral services and port mapping.
- Testing unsupported services — Only 20+ preset services are officially supported. Custom services require building a preset or using raw Docker APIs, increasing maintenance burden. No preset exists for some niche databases or services.
License & commercial use
Gnomock is licensed under the MIT License (OSI-approved, permissive open source). No attribution required; commercial use, modification, and distribution permitted under standard MIT terms.
MIT License explicitly permits commercial use without restriction. No proprietary or enterprise license exists. The software may be used in commercial products without payment or special agreement. However, the project is community-maintained; production use should account for the volunteer maintenance model and response times for critical issues.
DEV.co evaluation signals
Editorial assessment — not user reviews. Directional, with an explicit confidence level.
| Signal | Assessment |
|---|---|
| Maintenance | Active |
| Documentation | Adequate |
| License clarity | Clear |
| Deployment complexity | Low |
| DEV.co fit | Strong |
| Assessment confidence | High |
Gnomock spawns ephemeral containers running real services; containers inherit Docker daemon permissions and networking. Consider: (1) Image source trust—presets pull public Docker images; verify upstream image security. (2) Network exposure—containers listen on localhost ports; in multi-tenant CI, port isolation must be validated. (3) Credential handling—seed data may include test credentials; store in environment variables or secrets managers, not in code. (4) No built-in secrets rotation or isolation per test; use preset options (e.g., WithUser) to vary credentials. Review your organization's container security and image scanning policies.
Alternatives to consider
testcontainers (Java/JVM primary, polyglot support)
Mature multi-language library (Go, Python, Node.js modules exist) for container-based testing. More mature ecosystem and documentation for polyglot teams, but Go support is less idiomatic than Gnomock.
docker-compose + manual container orchestration
Full control over service versions, networking, and configuration via declarative YAML. No library lock-in, but requires bash scripting for setup/teardown and lacks programmatic preset configuration.
Mock libraries (testify/mock, gomock, etc.) + dependency injection
Lightweight, no Docker dependency, instant test execution. Suitable for unit tests and controlled integration tests, but cannot validate real service behavior, transactions, or side effects that Gnomock excels at.
Build on gnomock with DEV.co software developers
Gnomock makes it easy to test against real services. Evaluate whether Docker availability and test startup time align with your testing strategy, then integrate into your Go test suite.
Talk to DEV.coRelated open-source tools
Surfaced by semantic similarity across the DEV.co open-source index.
Related on DEV.co
Explore the category and the services that help you build with it.
gnomock FAQ
Can I use Gnomock in CI/CD pipelines without Docker?
Do I need to manage port conflicts when running tests in parallel?
Which languages can use Gnomock?
How much slower are tests with Gnomock vs. mocks?
Work with a software development agency
Need help beyond evaluating gnomock? DEV.co is a software development agency offering software development services and web development for teams of every size. Our software developers and web developers build custom software, web applications, APIs, and open-source testing integrations — and maintain them long-term.
Ready to eliminate mocks from your integration tests?
Gnomock makes it easy to test against real services. Evaluate whether Docker availability and test startup time align with your testing strategy, then integrate into your Go test suite.