1. docker
  2. Commit 867a5999cefccefb3e0fb79ffa22f01dd7c1a5e1
Browse code

Merge pull request #34407 from dnephin/add-TESTING-doc

[Proposal] Document testing guidelines

Tibor Vass authored on 2017/08/18 04:33:43
Showing 2 changed files
CONTRIBUTING.md
History View file @ 867a599
... ... 
@@ -155,10 +155,7 @@ Fork the repository and make changes on your fork in a feature branch:
155 155 
 	your intentions, and name it XXXX-something where XXXX is the number of the
156 156 
 	issue.
157 157
158 
-Submit unit tests for your changes. Go has a great test framework built in; use
159 
-it! Take a look at existing tests for inspiration. [Run the full test
160 
-suite](https://docs.docker.com/opensource/project/test-and-docs/) on your branch before
161 
-submitting a pull request.
158 
+Submit tests for your changes. See [TESTING.md](./TESTING.md) for details.
162 159
163 160 
 If your changes need integration tests, write them against the API. The `cli`
164 161 
 integration tests are slowly either migrated to API tests or moved away as unit
... ... 
@@ -255,10 +252,9 @@ calling it in another file constitute a single logical unit of work. The very
255 255 
 high majority of submissions should have a single commit, so if in doubt: squash
256 256 
 down to one.
257 257
258 
-After every commit, [make sure the test suite passes]
259 
-(https://docs.docker.com/opensource/project/test-and-docs/). Include documentation
260 
-changes in the same pull request so that a revert would remove all traces of
261 
-the feature or fix.
258 
+After every commit, [make sure the test suite passes](./TESTING.md). Include
259 
+documentation changes in the same pull request so that a revert would remove
260 
+all traces of the feature or fix.
262 261
263 262 
 Include an issue reference like `Closes #XXXX` or `Fixes #XXXX` in commits that
264 263 
 close an issue. Including references automatically closes the issue on a merge.
TESTING.md
History View file @ 867a599
265 264 
new file mode 100644
... ... 
@@ -0,0 +1,71 @@
0 
+# Testing
1 
+
2 
+This document contains the Moby code testing guidelines. It should answer any
3 
+questions you may have as an aspiring Moby contributor.
4 
+
5 
+## Test suites
6 
+
7 
+Moby has two test suites (and one legacy test suite):
8 
+
9 
+* Unit tests - use standard `go test` and
10 
+  [testify](https://github.com/stretchr/testify) assertions. They are located in
11 
+  the package they test. Unit tests should be fast and test only their own
12 
+  package.
13 
+* API integration tests - use standard `go test` and
14 
+  [testify](https://github.com/stretchr/testify) assertions. They are located in
15 
+  `./integration/<component>` directories, where `component` is: container,
16 
+  image, volume, etc. These tests perform HTTP requests to an API endpoint and
17 
+  check the HTTP response and daemon state after the call.
18 
+
19 
+The legacy test suite `integration-cli/` is deprecated. No new tests will be
20 
+added to this suite. Any tests in this suite which require updates should be
21 
+ported to either the unit test suite or the new API integration test suite.
22 
+
23 
+## Writing new tests
24 
+
25 
+Most code changes will fall into one of the following categories.
26 
+
27 
+### Writing tests for new features
28 
+
29 
+New code should be covered by unit tests. If the code is difficult to test with
30 
+a unit tests then that is a good sign that it should be refactored to make it
31 
+easier to reuse and maintain. Consider accepting unexported interfaces instead
32 
+of structs so that fakes can be provided for dependencies.
33 
+
34 
+If the new feature includes a completely new API endpoint then a new API
35 
+integration test should be added to cover the success case of that endpoint.
36 
+
37 
+If the new feature does not include a completely new API endpoint consider
38 
+adding the new API fields to the existing test for that endpoint. A new
39 
+integration test should **not** be added for every new API field or API error
40 
+case. Error cases should be handled by unit tests.
41 
+
42 
+### Writing tests for bug fixes
43 
+
44 
+Bugs fixes should include a unit test case which exercises the bug.
45 
+
46 
+A bug fix may also include new assertions in an existing integration tests for the
47 
+API endpoint.
48 
+
49 
+## Running tests
50 
+
51 
+To run the unit test suite:
52 
+
53 
+```
54 
+make test-unit
55 
+```
56 
+
57 
+or `hack/test/unit` from inside a `BINDDIR=. make shell` container or properly
58 
+configured environment.
59 
+
60 
+The following environment variables may be used to run a subset of tests:
61 
+
62 
+* `TESTDIRS` - paths to directories to be tested, defaults to `./...`
63 
+* `TESTFLAGS` - flags passed to `go test`, to run tests which match a pattern
64 
+  use `TESTFLAGS="-test.run TestNameOrPrefix"`
65 
+
66 
+To run the integration test suite:
67 
+
68 
+```
69 
+make test-integration
70 
+```