github.com/etecs-ru/gnomock@v0.13.2/README.md (about) 1 ## The fork of https://github.com/orlangure/gnomock with updated `docker/docker` and other updated dependencies. 2 3 ### All CI tests in this fork works the same as in the original repo. 4 5 6 <div align="center"> 7 <img src="https://github.com/etecs-ru/gnomock/raw/master/gnomock.png"> 8 </div> 9 10 # <div align="center">Gnomock â tests without mocks</div> 11 12 đī¸ Spin up entire dependency stack 13 14 đ Setup initial dependency state â easily! 15 16 đ Test against actual, close to production software 17 18 âŗ Spend no time writing mocks 19 20 đšī¸ Test actual program behavior and side effects 21 22 ## <div align="center">[![PkgGoDev](https://pkg.go.dev/badge/github.com/etecs-ru/gnomock)](https://pkg.go.dev/github.com/etecs-ru/gnomock) [![Test](https://github.com/etecs-ru/gnomock/actions/workflows/test.yaml/badge.svg)](https://github.com/etecs-ru/gnomock/actions/workflows/test.yaml) [![Go Report Card](https://goreportcard.com/badge/github.com/etecs-ru/gnomock)](https://goreportcard.com/report/github.com/etecs-ru/gnomock) [![codecov](https://codecov.io/gh/etecs-ru/gnomock/branch/master/graph/badge.svg?token=F0XYPSEIMK)](https://codecov.io/gh/etecs-ru/gnomock)</div> 23 24 Gnomock is an integration and end-to-end testing toolkit. It uses Docker to create **temporary containers** for 25 application dependencies, **setup** their 26 **initial state** and **clean them up** in the end. Gnomock allows to test the code with **no mocks** wherever possible. 27 28 The power of Gnomock is in a variety of [Presets](#official-presets), each implementing a specific database, service or 29 other tools. Each preset provides ways of setting up its initial state as easily as possible: SQL schema creation, test 30 data upload into S3, sending test events to Splunk, etc. 31 32 The name "Gnomock" stands for "no mock", with a "G" for "Go" đŧ. It also sounds like "gnome", that's why the friendly 33 garden gnome artwork (by [Michael Zolotov](https://www.mzolotov.com/)) 34 35 ## Demo 36 37 See for yourself how easy and fast it is to write tests that use actual services running in ephemeral Docker containers: 38 39 [![asciicast](https://asciinema.org/a/jSJJGk0n3q1g4Fc4bvZYYyifN.svg)](https://asciinema.org/a/jSJJGk0n3q1g4Fc4bvZYYyifN) 40 41 ## Table of contents 42 43 - [Getting started](#getting-started) 44 - [Using Gnomock in Go applications](#using-gnomock-in-go-applications) 45 - [Using Gnomock in other languages](#using-gnomock-in-other-languages) 46 - [Official presets](#official-presets) 47 - [Similar projects](#similar-projects) 48 - [Troubleshooting](#troubleshooting) 49 50 ## Getting started 51 52 Gnomock can be used in two different ways: 53 54 - Imported directly as a package in any **Go** project 55 - Accessed over HTTP running as a daemon in **any other language** 56 57 â ī¸ Both ways **require** an active Docker daemon running locally in the same environment. 58 59 ### Using Gnomock in Go applications 60 61 See the following example to get started: 62 63 ``` 64 go get github.com/etecs-ru/gnomock 65 ``` 66 67 Setting up a **Postgres** container with schema setup example: 68 69 ```go 70 import ( 71 "database/sql" 72 73 _ "github.com/lib/pq" // postgres driver 74 "github.com/etecs-ru/gnomock" 75 "github.com/etecs-ru/gnomock/preset/postgres" 76 ) 77 78 p := postgres.Preset( 79 postgres.WithUser("gnomock", "gnomick"), 80 postgres.WithDatabase("mydb"), 81 postgres.WithQueriesFile("/var/project/db/schema.sql"), 82 ) 83 container, _ := gnomock.Start(p) 84 defer func () { _ = gnomock.Stop(container) }() 85 86 connStr := fmt.Sprintf( 87 "host=%s port=%d user=%s password=%s dbname=%s sslmode=disable", 88 container.Host, container.DefaultPort(), 89 "gnomock", "gnomick", "mydb", 90 ) 91 db, _ := sql.Open("postgres", connStr) 92 // db has the required schema and data, and is ready to use 93 ``` 94 95 See package 96 [reference](https://pkg.go.dev/github.com/etecs-ru/gnomock?tab=doc). For Preset documentation, refer 97 to [Presets](#official-presets) section. 98 99 ### Using Gnomock in other languages 100 101 If you use Go, please refer to [Using Gnomock in Go applications](#using-gnomock-in-go-applications) section. Otherwise, 102 refer to 103 [documentation](docs/server.md). 104 105 ## Official presets 106 107 The power of Gnomock is in the Presets. Existing Presets with their supported<sup>\*</sup> versions are listed below. 108 109 <small>*\* **Supported** versions are tested as part of CI pipeline. Other versions might work as well.*</small> 110 111 | Preset | Go package | HTTP API | Go API | Supported versions | 112 |--------|------------|----------|--------|---------------------| 113 Localstack (AWS) | [Go package](https://github.com/etecs-ru/gnomock/tree/master/preset/localstack) | [Docs](https://app.swaggerhub.com/apis/orlangure/gnomock/1.4.7#/presets/startLocalstack) | [Reference](https://pkg.go.dev/github.com/etecs-ru/gnomock/preset/localstack?tab=doc) | `0.12.2` 114 Splunk | [Go package](https://github.com/etecs-ru/gnomock/tree/master/preset/splunk) | [Docs](https://app.swaggerhub.com/apis/orlangure/gnomock/1.4.7#/presets/startSplunk) | [Reference](https://pkg.go.dev/github.com/etecs-ru/gnomock/preset/splunk?tab=doc) | `8.0.2` 115 Redis | [Go package](https://github.com/etecs-ru/gnomock/tree/master/preset/redis) | [Docs](https://app.swaggerhub.com/apis/orlangure/gnomock/1.4.7#/presets/startRedis) | [Reference](https://pkg.go.dev/github.com/etecs-ru/gnomock/preset/redis?tab=doc) | `5.0.10`, `6.0.9` 116 Memcached | [Go package](https://github.com/etecs-ru/gnomock/tree/master/preset/memcached) | [Docs](https://app.swaggerhub.com/apis/orlangure/gnomock/1.4.7#/presets/startMemcached) | [Reference](https://pkg.go.dev/github.com/etecs-ru/gnomock/preset/memcached?tab=doc) | `1.6.9` 117 MySQL | [Go package](https://github.com/etecs-ru/gnomock/tree/master/preset/mysql) | [Docs](https://app.swaggerhub.com/apis/orlangure/gnomock/1.4.7#/presets/startMysql) | [Reference](https://pkg.go.dev/github.com/etecs-ru/gnomock/preset/mysql?tab=doc) | `5.7.32`, `8.0.22` 118 MariaDB | [Go package](https://github.com/etecs-ru/gnomock/tree/master/preset/mariadb) | [Docs](https://app.swaggerhub.com/apis/orlangure/gnomock/1.4.7#/presets/startMariadb) | [Reference](https://pkg.go.dev/github.com/etecs-ru/gnomock/preset/mariadb?tab=doc) | `10.5.8` 119 PostgreSQL | [Go package](https://github.com/etecs-ru/gnomock/tree/master/preset/postgres) | [Docs](https://app.swaggerhub.com/apis/orlangure/gnomock/1.4.7#/presets/startPostgres) | [Reference](https://pkg.go.dev/github.com/etecs-ru/gnomock/preset/postgres?tab=doc) | `10.15`, `11.10`, `12.5`, `13.1` 120 Microsoft SQL Server | [Go package](https://github.com/etecs-ru/gnomock/tree/master/preset/mssql) | [Docs](https://app.swaggerhub.com/apis/orlangure/gnomock/1.4.7#/presets/startMssql) | [Reference](https://pkg.go.dev/github.com/etecs-ru/gnomock/preset/mssql?tab=doc) | `2017-latest`, `2019-latest` 121 MongoDB | [Go package](https://github.com/etecs-ru/gnomock/tree/master/preset/mongo) | [Docs](https://app.swaggerhub.com/apis/orlangure/gnomock/1.4.7#/presets/startMongo) | [Reference](https://pkg.go.dev/github.com/etecs-ru/gnomock/preset/mongo?tab=doc) | `3.6.21`, `4.4` 122 RabbitMQ | [Go package](https://github.com/etecs-ru/gnomock/tree/master/preset/rabbitmq) | [Docs](https://app.swaggerhub.com/apis/orlangure/gnomock/1.4.7#/presets/startRabbitMq) | [Reference](https://pkg.go.dev/github.com/etecs-ru/gnomock/preset/rabbitmq?tab=doc) | `3.8.9-alpine`, `3.8.9-management-alpine` 123 Kafka | [Go package](https://github.com/etecs-ru/gnomock/tree/master/preset/kafka) | [Docs](https://app.swaggerhub.com/apis/orlangure/gnomock/1.4.7#/presets/startKafka) | [Reference](https://pkg.go.dev/github.com/etecs-ru/gnomock/preset/kafka?tab=doc) | `2.5.1-L0` 124 Elasticsearch | [Go package](https://github.com/etecs-ru/gnomock/tree/master/preset/elastic) | [Docs](https://app.swaggerhub.com/apis/orlangure/gnomock/1.4.7#/presets/startElastic) | [Reference](https://pkg.go.dev/github.com/etecs-ru/gnomock/preset/elastic?tab=doc) | `5.6`, `6.8.13`, `7.9.3` 125 Kubernetes | [Go package](https://github.com/etecs-ru/gnomock/tree/master/preset/k3s) | [Docs](https://app.swaggerhub.com/apis/orlangure/gnomock/1.4.7#/presets/startKubernetes) | [Reference](https://pkg.go.dev/github.com/etecs-ru/gnomock/preset/k3s?tab=doc) | `v1.19.3` 126 CockroachDB | [Go package](https://github.com/etecs-ru/gnomock/tree/master/preset/cockroachdb) | [Docs](https://app.swaggerhub.com/apis/orlangure/gnomock/1.4.7#/presets/startCockroachDB) | [Reference](https://pkg.go.dev/github.com/etecs-ru/gnomock/preset/cockroachdb?tab=doc) | `v19.2.11`, `v20.1.10` 127 128 <!-- new presets go here --> 129 130 It is possible to use Gnomock [directly from Go](https://pkg.go.dev/github.com/etecs-ru/gnomock#StartCustom) code 131 without any presets. HTTP API only allows to setup containers using presets that exist in this repository. 132 133 ## Similar projects 134 135 Gnomock is not the only project that aims to simplify integration and end-to-end testing by using ephemeral docker 136 containers: 137 138 - `testcontainers/testcontainers-go` 139 - `ory/dockertest` 140 141 These projects are amazing, and they give plenty of flexibility and power to their users. There are many things that are 142 possible with them, but are impossible with Gnomock. Still, below is a short list of things that sometimes give Gnomock 143 an advantage: 144 145 - **Gnomock tries to provide a batteries-included solution**. Gnomock has a growing number of Presets, each one 146 implementing an integration with a popular external service. For every Preset, there already is a number of 147 "invisible" utilities that transparently relieve you from implementing them yourself: 148 - __Built-in health check function__ that you don't even need to know it exists. It makes sure you only get control 149 over a container when it is ready to use. 150 - __Wrappers for some of the configuration__ exposed by the container, such as default username/password. You can 151 easily provide your own credentials to connect to the container. 152 - __Seed data ingestion__ for your convenience. Sometimes you just need to make sure your queries work given some 153 data. Gnomock puts your data in there with a single line of code. Sometimes you only test a program that consumes 154 messages from Kafka, and Gnomock produces the messages for you with another line of code. 155 - **Simple API** that does not expose anything that happens "under the hood" 156 most of the time. Yet Gnomock allows some additional configuration and custom Preset implementation whenever 157 necessary. 158 - Gnomock's vision includes **being useful not only in Go** projects, but in any projects via HTTP. It already supports 159 almost all its features over HTTP layer, has a clear OpenAPI spec, and even a proof of concept wrapper in Python. 160 - Gnomock has a friendly **garden gnome mascot**đģ 161 162 ## Troubleshooting 163 164 ### Tests with Gnomock take too long and time-out eventually 165 166 It happens a lot locally if your internet isn't fast enough to pull docker images used in tests. In CI, such as in 167 Github Actions, the images are downloaded very quickly. To work around this issue locally, pull the image manually 168 before running the tests. You only need to do it once, the images stay in local cache until deleted. For example, to 169 pull Postgres 11 image, run: 170 171 ``` 172 docker pull postgres:11 173 ``` 174 175 ### Tests time-out even when the image exists locally 176 177 It can happen if the containers can't become ready to use before they time out. By default, Gnomock uses fairly high 178 timeouts for new containers (for starting and for setting them up). If you choose to change default timeout using 179 `WithTimeout` (`timeout` in HTTP), it is possible that the values you choose are too short. 180 181 ### Tests pass when run one-by-one, and fail when run in parallel 182 183 It happens when you try to start up **a lot** of containers at the same time. The system, especially in CI environments 184 such as Github Actions, cannot handle the load, and containers fail to become healthy before they time-out. That's the 185 reason Gnomock has a few separate build jobs, each running only a small subset of tests, one package at a time. 186 187 ### Containers fail to setup with a "File not found" error 188 189 If you run `gnomock` as a server, you need to make sure the files you use in your setup are available inside `gnomock` 190 container. Use `-v $(pwd):$(pwd)` 191 argument to `docker run` to mount the current working directory under the same path inside the `gnomock` container. If 192 you prefer to keep a permanent 193 `gnomock` container running, you can mount your entire `$HOME` directory (or any other directory where you keep the 194 code).