Docket helps you run a test or test suite inside a multi-container Docker application using Docker Compose. If requested, docket will run bring up a Docker Compose app, run the test suite, and optionally shut down the app. If you don't activate docket, the test will run as if you weren't using docket at all.

Docket is compatible with the standard testing package (including T.Run subtests) as well as testify/suite.

dkt

Docket includes a command-line utility named dkt that helps you run docker-compose commands on your files.

Examples

You can learn how to use docket by following the examples in the testdata directory.

`testdata/`	Description
`01_hello`	Read an environment variable.
`02_ping-redis`	Test a function to ping a Redis server
`03_redispinger-service`	Test an HTTP service that pings a Redis server
`99_testify-suite`	Use docket with a testify suite.

Help

If your tests import docket, you can run go test -help-docket to get help.

DOCKET_MODE

To enable docket, you'll need to set DOCKET_MODE in your environment when you run go test.

For a tutorial on docket modes, see the 02_ping-redis example.

When you set DOCKET_MODE=awesome, docket will look for YAML files (files with a .yaml or .yml extension) with names like

docket.yaml (matches any mode)
docket.awesome.yaml
docket.awesome.*.yaml

For more detailed examples, refer to the tests.

Optional

DOCKET_DOWN

Default: false

If DOCKET_DOWN is non-empty, docket will run docker-compose down at the end of each docket.Run().

DOCKET_PULL

Default: false

If DOCKET_PULL is non-empty, docket will run docker-compose pull at the start of each docket.Run().

DOCKET_PULL_OPTS

Default: ``

If DOCKET_PULL_OPTS is non-empty, docket will add its contents to the invocation of the docker-compose pull command.

For example, to avoid pulling images in parallel, you can set DOCKET_PULL_OPTS=--no-parallel so that docket will run docker-compose pull --no-parallel.

Setting DOCKET_PULL_OPTS has no effect if you do not set DOCKET_PULL=1.

Using a custom file prefix

If you need to keep multiple independent docket configurations in the same directory, you can call docket.RunPrefix() to have docket look for YAML files starting with your custom prefix instead of the default prefix ("docket").

For more detailed examples, refer to the tests.

Testing Docket

Docket has unit tests as well as integration tests that run the examples in the testdata directory.

GOPATH and go modules

Docket tries to test itself in both GOPATH mode and module-aware mode if possible.

go test inside a GOPATH will run both kinds of tests.
- go test -run /GOPATH/ will run only GOPATH mode tests.
- go test -run /module/ will run only module-aware mode tests.
go test outside a GOPATH will only run tests in module-aware mode.

Coverage

To gather coverage, use -coverprofile for the main in-process tests, and set COVERAGE_DIR to gather coverage from the go test child processes. Then, use gocovmerge to merge the coverage data.

COVERAGE_DIR=COVERAGE go test -v -coverprofile=coverage.root ./... && \
go tool cover -func <(gocovmerge coverage.root $(find COVERAGE -type f))

Code of Conduct

Docket has adopted a Code of Conduct. If you have any concerns about the Code or behavior which you have experienced in the project, please contact us at [email protected].

Contributing

We'd love to hear from you, whether you've found a bug or want to suggest how docket could be better. Please open an issue and let us know what you think!

If you want to contribute code to the docket project, please be sure to read our contribution guidelines. We highly recommend opening an issue before you start working on your pull request. We'd like to talk with you about the change you want to make before you start making it. :smile:

License

Docket is licensed under the Apache License, Version 2.0.

Security Policy

If you believe you have identified a security vulnerability in this project, please send an email to the project team at [email protected] detailing the suspected issue and any methods you've found to reproduce it.

Please do not open an issue in the GitHub repository, as we'd prefer to keep vulnerability reports private until we've had an opportunity to review and address them. Thank you.