README
¶
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
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.yamldocket.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 testinside aGOPATHwill run both kinds of tests.go test -run /GOPATH/will run onlyGOPATHmode tests.go test -run /module/will run only module-aware mode tests.
go testoutside aGOPATHwill 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 opensource@bloomberg.net.
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 opensource@bloomberg.net 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.
Documentation
¶
Overview ¶
Package docket helps you use Docker Compose to manage test environments.
See the README in https://github.com/bloomberg/docket for usage examples.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Run ¶
Run executes testFunc in the proper test environment.
If DOCKET_MODE is set, docket looks for files matching 'docket.yaml', 'docket.MODE.yaml', and 'docket.MODE.*.yaml' (.yml files are also allowed). It uses `docker-compose` with the docket files (in that order) to set up a test environment, run testFunc, and optionally tear down the environment.
If docketCtx is non-nil, it will be populated so that it is usable inside testFunc.
For more documentation and usage examples, see the package's source repository.
Types ¶
type Context ¶
type Context struct {
// contains filtered or unexported fields
}
Context can tell you information about the active docket environment.
It is not related to context.Context.
func (Context) Mode ¶
Mode returns the name of the active mode or a blank string if no mode is being used.
Caveat: When docket runs a test inside a docker container, mode will be empty, since the inner test execution is running without an active docket mode.
func (Context) PublishedPort ¶
PublishedPort returns the publicly exposed host port number corresponding to the privatePort for a service. If that service does not publish privatePort, it will return an error.
Source Files
Directories