github.com/lacework-dev/go-moby@v20.10.12+incompatible/TESTING.md (about) 1 # Testing 2 3 This document contains the Moby code testing guidelines. It should answer any 4 questions you may have as an aspiring Moby contributor. 5 6 ## Test suites 7 8 Moby has two test suites (and one legacy test suite): 9 10 * Unit tests - use standard `go test` and 11 [gotest.tools/assert](https://godoc.org/gotest.tools/assert) assertions. They are located in 12 the package they test. Unit tests should be fast and test only their own 13 package. 14 * API integration tests - use standard `go test` and 15 [gotest.tools/assert](https://godoc.org/gotest.tools/assert) assertions. They are located in 16 `./integration/<component>` directories, where `component` is: container, 17 image, volume, etc. These tests perform HTTP requests to an API endpoint and 18 check the HTTP response and daemon state after the call. 19 20 The legacy test suite `integration-cli/` is deprecated. No new tests will be 21 added to this suite. Any tests in this suite which require updates should be 22 ported to either the unit test suite or the new API integration test suite. 23 24 ## Writing new tests 25 26 Most code changes will fall into one of the following categories. 27 28 ### Writing tests for new features 29 30 New code should be covered by unit tests. If the code is difficult to test with 31 unit tests, then that is a good sign that it should be refactored to make it 32 easier to reuse and maintain. Consider accepting unexported interfaces instead 33 of structs so that fakes can be provided for dependencies. 34 35 If the new feature includes a completely new API endpoint then a new API 36 integration test should be added to cover the success case of that endpoint. 37 38 If the new feature does not include a completely new API endpoint consider 39 adding the new API fields to the existing test for that endpoint. A new 40 integration test should **not** be added for every new API field or API error 41 case. Error cases should be handled by unit tests. 42 43 ### Writing tests for bug fixes 44 45 Bugs fixes should include a unit test case which exercises the bug. 46 47 A bug fix may also include new assertions in existing integration tests for the 48 API endpoint. 49 50 ### Writing new integration tests 51 52 Note the `integration-cli` tests are deprecated; new tests will be rejected by 53 the CI. 54 55 Instead, implement new tests under `integration/`. 56 57 ### Integration tests environment considerations 58 59 When adding new tests or modifying existing tests under `integration/`, testing 60 environment should be properly considered. `skip.If` from 61 [gotest.tools/skip](https://godoc.org/gotest.tools/skip) can be used to make the 62 test run conditionally. Full testing environment conditions can be found at 63 [environment.go](https://github.com/moby/moby/blob/6b6eeed03b963a27085ea670f40cd5ff8a61f32e/testutil/environment/environment.go) 64 65 Here is a quick example. If the test needs to interact with a docker daemon on 66 the same host, the following condition should be checked within the test code 67 68 ```go 69 skip.If(t, testEnv.IsRemoteDaemon()) 70 // your integration test code 71 ``` 72 73 If a remote daemon is detected, the test will be skipped. 74 75 ## Running tests 76 77 ### Unit Tests 78 79 To run the unit test suite: 80 81 ``` 82 make test-unit 83 ``` 84 85 or `hack/test/unit` from inside a `BINDDIR=. make shell` container or properly 86 configured environment. 87 88 The following environment variables may be used to run a subset of tests: 89 90 * `TESTDIRS` - paths to directories to be tested, defaults to `./...` 91 * `TESTFLAGS` - flags passed to `go test`, to run tests which match a pattern 92 use `TESTFLAGS="-test.run TestNameOrPrefix"` 93 94 ### Integration Tests 95 96 To run the integration test suite: 97 98 ``` 99 make test-integration 100 ``` 101 102 This make target runs both the "integration" suite and the "integration-cli" 103 suite. 104 105 You can specify which integration test dirs to build and run by specifying 106 the list of dirs in the TEST_INTEGRATION_DIR environment variable. 107 108 You can also explicitly skip either suite by setting (any value) in 109 TEST_SKIP_INTEGRATION and/or TEST_SKIP_INTEGRATION_CLI environment variables. 110 111 Flags specific to each suite can be set in the TESTFLAGS_INTEGRATION and 112 TESTFLAGS_INTEGRATION_CLI environment variables. 113 114 If all you want is to specify a test filter to run, you can set the 115 `TEST_FILTER` environment variable. This ends up getting passed directly to `go 116 test -run` (or `go test -check-f`, depending on the test suite). It will also 117 automatically set the other above mentioned environment variables accordingly. 118 119 ### Go Version 120 121 You can change a version of golang used for building stuff that is being tested 122 by setting `GO_VERSION` variable, for example: 123 124 ``` 125 make GO_VERSION=1.12.8 test 126 ```