Skip to content

Commit

Permalink
Update README
Browse files Browse the repository at this point in the history
  • Loading branch information
@orlangure
orlangure committed May 4, 2022
1 parent e6cb897 commit 52af13b
Show file tree
Hide file tree
Showing 2 changed files with 26 additions and 124 deletions.
36 changes: 0 additions & 36 deletions .circleci/config.yml
View file
Expand Up @@ -37,41 +37,6 @@ jobs:
name: Test gnomockd
command: go test -race -cover -v ./internal/gnomockd -run TestGnomockd

test-sdk-python:
machine: true
steps:
- checkout
- run:
name: Install Python
command: |
cd /opt/circleci/.pyenv/plugins/python-build/../.. && git pull && cd -
pyenv install 3.6.9
pyenv local 3.6.9
- run:
name: Get dependencies
command: |
cd sdktest/python
pip3 install -r requirements.txt
- run:
name: Generate python sdk
command: swagger/bin/generate-python.sh
- run:
name: Build docker image
command: docker build --tag gnomock .
- run:
name: Run gnomock
command: |
docker run -itd \
-p 23042:23042 \
-v /var/run/docker.sock:/var/run/docker.sock \
-v `pwd`:`pwd` \
gnomock
- run:
name: Test
command: |
cd sdktest/python
python3 -m pytest -n 3 -v -k TestSDK
test-localstack:
machine: true
steps:
Expand Down Expand Up @@ -255,7 +220,6 @@ workflows:
jobs:
- lint
- test-core
- test-sdk-python
- test-localstack
- test-elastic
- test-memcached
Expand Down
114 changes: 26 additions & 88 deletions README.md
View file
Expand Up @@ -16,24 +16,15 @@

## <div align="center">[![PkgGoDev](https://pkg.go.dev/badge/github.com/orlangure/gnomock)](https://pkg.go.dev/github.com/orlangure/gnomock) ![Test](https://github.com/orlangure/gnomock/workflows/Test/badge.svg) [![Go Report Card](https://goreportcard.com/badge/github.com/orlangure/gnomock)](https://goreportcard.com/report/github.com/orlangure/gnomock) [![codecov](https://codecov.io/gh/orlangure/gnomock/branch/master/graph/badge.svg?token=F0XYPSEIMK)](https://codecov.io/gh/orlangure/gnomock)</div>

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.
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](#official-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 power of Gnomock is in a variety of [Presets](#official-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](https://www.mzolotov.com/))
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](https://www.mzolotov.com/))

## Demo

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

[![asciicast](https://asciinema.org/a/jSJJGk0n3q1g4Fc4bvZYYyifN.svg)](https://asciinema.org/a/jSJJGk0n3q1g4Fc4bvZYYyifN)

Expand All @@ -54,11 +45,9 @@ 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.
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.
External `DOCKER_HOST` support is experimental. It cannot be reliably tested at this moment, but it might work.

### Using Gnomock in Go applications

Expand Down Expand Up @@ -102,23 +91,17 @@ func TestDB(t *testing.T) {
}
```

See package
[reference](https://pkg.go.dev/github.com/orlangure/gnomock?tab=doc). For
Preset documentation, refer to [Presets](#official-presets) section.
See package [reference](https://pkg.go.dev/github.com/orlangure/gnomock?tab=doc). For Preset documentation, refer to [Presets](#official-presets) section.

### Using Gnomock in other languages

If you use Go, please refer to [Using Gnomock in Go
applications](#using-gnomock-in-go-applications) section. Otherwise, refer to
[documentation](docs/server.md).
If you use Go, please refer to [Using Gnomock in Go applications](#using-gnomock-in-go-applications) section. Otherwise, refer to [documentation](docs/server.md).

## Official presets

The power of Gnomock is in the Presets. Existing Presets with their
supported<sup>\*</sup> versions are listed below.
The power of Gnomock is in the Presets. Existing Presets with their supported<sup>\*</sup> versions are listed below.

<small>*\* **Supported** versions are tested as part of CI pipeline. Other
versions might work as well.*</small>
<small>*\* **Supported** versions are tested as part of CI pipeline. Other versions might work as well.*</small>


| Preset | Go package | HTTP API | Go API | Supported versions |
Expand All @@ -141,96 +124,51 @@ InfluxDB | [Go package](https://github.com/orlangure/gnomock/tree/master/preset/
Cassandra | [Go package](https://github.com/orlangure/gnomock/tree/master/preset/cassandra) | [Docs](https://app.swaggerhub.com/apis/orlangure/gnomock/1.20.0#/presets/startCassandra) | [Reference](https://pkg.go.dev/github.com/orlangure/gnomock/preset/cassandra?tab=doc) | `4.0`, `3`
<!-- new presets go here -->

It is possible to use Gnomock [directly from
Go](https://pkg.go.dev/github.com/orlangure/gnomock#StartCustom) code without
any presets. HTTP API only allows to setup containers using presets that exist
in this repository.
It is possible to use Gnomock [directly from Go](https://pkg.go.dev/github.com/orlangure/gnomock#StartCustom) 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:
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.
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**馃樆

## Troubleshooting

### 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:
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.
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.
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).
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](https://tree-nation.com/plant/offer) 馃尣 馃尦 馃尨
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](https://tree-nation.com/plant/offer) 馃尣 馃尦 馃尨

If you want me to know about your contribution, make sure to use
`orlangure+gnomock@gmail.com` as the recipient email.
If you want me to know about your contribution, make sure to use `orlangure+gnomock@gmail.com` as the recipient email.

Thank you!

0 comments on commit 52af13b

Please sign in to comment.