docket

Docket helps you use Docker Compose to manage test environments.

⚠ Stability warning: API might change ⚠

This pre-1.0.0 API is subject to change as we make improvements.

Contents

• Overview
• Examples
• Help
• Testing Docket
• Code of Conduct
• Contributing
• License
• Security Policy

Overview

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 testgroup and 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
98_testgroup	Use docket with a test group.
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: none

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.

Module-aware mode and GOPATH-mode

Docket works in both GOPATH mode and module-aware mode, but its tests only run in one mode at a time. As of Go 1.13, if you haven't overridden GO111MODULE, Go will run in module-aware mode.

To run tests (or other tools) in GOPATH mode, you can use the run_in_temp_gopath_with_go_modules_disabled helper script, which creates a temporary GOPATH at .TEMP_GOPATH, sets GO111MODULE=off, and runs the script's arguments inside the corresponding docket package directory (.TEMP_GOPATH/src/github.com/bloomberg/docket).

# module-aware mode, by default
go test ./...

# GOPATH mode (GO111MODULE=off)
./run_in_temp_gopath_with_go_modules_disabled go test ./...

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))

Note: If you're gathering coverage using run_in_temp_gopath_with_go_modules_disabled, the COVERAGE_DIR will be relative to the temporary docket directory inside .TEMP_GOPATH (see above) unless you give an absolute path as your COVERAGE_DIR.

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. 😄

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.