Test your code without writing mocks with ephemeral Docker containers 📦 Setup popular services with just a couple lines of code ⏱️ No bash, no yaml, only code 💻
Alternatives To Gnomock
Project NameStarsDownloadsRepos Using ThisPackages Using ThisMost Recent CommitTotal ReleasesLatest ReleaseOpen IssuesLicenseLanguage
Yapi26,458224 days ago8June 15, 20201,565apache-2.0JavaScript
YApi 是一个可本地部署的、打通前后端及QA的、可视化的接口管理平台
2 years ago25mitRuby
Development tool to mock API endpoints quickly and easily (docker image available)
5 months ago64mitJavaScript
A tool to quickly mock out end points, setup delays and more...
Gnomock1,231384 days ago111August 26, 202321mitGo
Test your code without writing mocks with ephemeral Docker containers 📦 Setup popular services with just a couple lines of code ⏱️ No bash, no yaml, only code 💻
6 months ago2April 23, 202129mitTypeScript
Smocker is a simple and efficient HTTP mock server and proxy.
S3mock659264 days ago72June 15, 202214apache-2.0Java
A simple mock implementation of the AWS S3 API startable as Docker image, TestContainer, JUnit 4 rule, JUnit Jupiter extension or TestNG listener
4 years ago7apache-2.0Python
用于辅助安全工程师漏洞挖掘、测试、复现,集合了mock、httplog、dns tools、xss,可用于测试各类无回显、无法直观判断或特定场景下的漏洞。
4 years ago7August 15, 20186otherGo
Smith: A microcontainer builder
3 days ago86apache-2.0Java
Castle Mock is a web application that provides the functionality to mock out RESTful APIs and SOAP web services.
a month ago4mitDockerfile
Golang development container for Visual Studio Code Remote Containers Development
Alternatives To Gnomock
Select To Compare

Alternative Project Comparisons

Gnomock – tests without mocks

🏗️ Spin up entire dependency stack

🎁 Setup initial dependency state – easily!

🏭 Test against actual, close to production software

⏳ Spend no time writing mocks

🕹️ Test actual program behavior and side effects

PkgGoDev Test Go Report Card codecov

Gnomock is an integration and end-to-end testing toolkit. It uses Docker to create temporary containers for application dependencies, setup their initial state and clean them up in the end. Gnomock allows to test the code with no mocks wherever possible.

The power of Gnomock is in a variety of Presets, each implementing a specific database, service or other tools. Each preset provides ways of setting up its initial state as easily as possible: SQL schema creation, test data upload into S3, sending test events to Splunk, etc.

The name "Gnomock" stands for "no mock", with a "G" for "Go" 😼. It also sounds like "gnome", that's why the friendly garden gnome artwork (by Michael Zolotov)


See for yourself how easy and fast it is to write tests that use actual services running in ephemeral Docker containers:


Table of contents

Getting started

Gnomock can be used in two different ways:

  • Imported directly as a package in any Go project
  • Accessed over HTTP running as a daemon in any other language

Both ways require an active Docker daemon running locally in the same environment.

External DOCKER_HOST support is experimental. It cannot be reliably tested at this moment, but it might work.

Using Gnomock in Go applications

See the following example to get started:

go get

Setting up a Postgres container with schema setup example:

package db_test

import (

	_ "" // postgres driver

func TestDB(t *testing.T) {
	p := postgres.Preset(
		postgres.WithUser("gnomock", "gnomick"),
	container, _ := gnomock.Start(p)
	t.Cleanup(func() { _ = gnomock.Stop(container) })

	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)
	// db has the required schema and data, and is ready to use

See package reference. For Preset documentation, refer to Presets section.

Using Gnomock in other languages

If you use Go, please refer to Using Gnomock in Go applications section. Otherwise, refer to documentation.

Official presets

The power of Gnomock is in the Presets. Existing Presets with their supported* versions are listed below.

* Supported versions are tested as part of CI pipeline. Other versions might work as well.

Preset Go package Go API Supported versions arm64
Localstack (AWS) Go package Reference 0.12.2, 0.13.1, 0.14.0
Splunk Go package Reference 8.0.2
Redis Go package Reference 5.0.10, 6.0.9
Memcached Go package Reference 1.6.9
MySQL Go package Reference 5.7.32, 8.0.22
MariaDB Go package Reference 10.5.8
PostgreSQL Go package Reference 10.15, 11.10, 12.5, 13.1
Microsoft SQL Server Go package Reference 2017-latest, 2019-latest
MongoDB Go package Reference 3.6.21, 4.4
RabbitMQ Go package Reference 3.8.9-alpine, 3.8.9-management-alpine
Kafka Go package Reference 3.3.1-L0
Elasticsearch Go package Reference 8.7.0, 7.17.9
Kubernetes Go package Reference v1.26.3-k3s1
CockroachDB Go package Reference v19.2.11, v20.1.10
InfluxDB Go package Reference 2.0.4-alpine
Cassandra Go package Reference 4.0, 3
Vault Go package Reference 1.10.11, 1.11.8, 1.12.4, 1.13
Azurite Go package Reference 3.22.0

It is possible to use Gnomock directly from Go code without any presets. HTTP API only allows to setup containers using presets that exist in this repository.

Similar projects

Gnomock is not the only project that aims to simplify integration and end-to-end testing by using ephemeral docker containers:

  • testcontainers/testcontainers-go
  • ory/dockertest

These projects are amazing, and they give plenty of flexibility and power to their users. There are many things that are possible with them, but are impossible with Gnomock. Still, below is a short list of things that sometimes give Gnomock an advantage:

  • Gnomock tries to provide a batteries-included solution. Gnomock has a growing number of Presets, each one implementing an integration with a popular external service. For every Preset, there already is a number of "invisible" utilities that transparently relieve you from implementing them yourself:
    • Built-in health check function that you don't even need to know it exists. It makes sure you only get control over a container when it is ready to use.
    • Wrappers for some of the configuration exposed by the container, such as default username/password. You can easily provide your own credentials to connect to the container.
    • Seed data ingestion for your convenience. Sometimes you just need to make sure your queries work given some data. Gnomock puts your data in there with a single line of code. Sometimes you only test a program that consumes messages from Kafka, and Gnomock produces the messages for you with another line of code.
  • Simple API that does not expose anything that happens "under the hood" most of the time. Yet Gnomock allows some additional configuration and custom Preset implementation whenever necessary.
  • Gnomock's vision includes being useful not only in Go projects, but in any projects via HTTP. It already supports almost all its features over HTTP layer and has a clear OpenAPI spec.
  • Gnomock has a friendly garden gnome mascot😻


Tests with Gnomock take too long and time-out eventually

It happens a lot locally if your internet isn't fast enough to pull docker images used in tests. In CI, such as in Github Actions, the images are downloaded very quickly. To work around this issue locally, pull the image manually before running the tests. You only need to do it once, the images stay in local cache until deleted. For example, to pull Postgres 11 image, run:

docker pull postgres:11

Tests time-out even when the image exists locally

It can happen if the containers can't become ready to use before they time out. By default, Gnomock uses fairly high timeouts for new containers (for starting and for setting them up). If you choose to change default timeout using WithTimeout (timeout in HTTP), it is possible that the values you choose are too short.

Tests pass when run one-by-one, and fail when run in parallel

It happens when you try to start up a lot of containers at the same time. The system, especially in CI environments such as Github Actions, cannot handle the load, and containers fail to become healthy before they time-out. That's the reason Gnomock has a few separate build jobs, each running only a small subset of tests, one package at a time.

Containers fail to setup with a "File not found" error

If you run gnomock as a server, you need to make sure the files you use in your setup are available inside gnomock container. Use -v $(pwd):$(pwd) argument to docker run to mount the current working directory under the same path inside the gnomock container. If you prefer to keep a permanent gnomock container running, you can mount your entire $HOME directory (or any other directory where you keep the code).

Giving back

This is a free and open source project that hopefully helps its users, at least a little. Even though I don't need donations to support it, I understand that there are people that wish to give back anyway. If you are one of them, I encourage you to plant some trees with Tree Nation 🌲 🌳 🌴

If you want me to know about your contribution, make sure to use [email protected] as the recipient email.

Thank you!

Popular Docker Projects
Popular Mock Projects
Popular Virtualization Categories
Related Searches

Get A Weekly Email With Trending Projects For These Categories
No Spam. Unsubscribe easily at any time.
Sql Server
End To End Testing
Integration Testing