Add Common Test docs and tests

Also fixes issues with multi application repositories,
and add support for running a specific group/case in a
given test suite.

1 files changed, 87 insertions, 2 deletions

diff --git a/doc/src/guide/common_test.asciidoc b/doc/src/guide/common_test.asciidoc
index 7daeae5..3f00baf 100644
--- a/doc/src/guide/common_test.asciidoc
+++ b/doc/src/guide/common_test.asciidoc
@@ -1,5 +1,90 @@
 == Common Test
 
-// @todo Write it.
+Common Test is Erlang's functional testing framework.
+Erlang.mk automates the discovery and running of Common
+Test suites.
 
-Placeholder chapter.
+=== Writing tests
+
+The http://www.erlang.org/doc/apps/common_test/write_test_chapter.html[Common Test user guide]
+is the best place to learn how to write tests. Erlang.mk
+requires that file names for test suites end with '_SUITE.erl'
+and that the files be located in the '$(TEST_DIR)' directory.
+This defaults to 'test/'.
+
+=== Configuration
+
+The `CT_OPTS` variable allows you to set extra Common Test
+options. Options are documented in the
+http://www.erlang.org/doc/apps/common_test/run_test_chapter.html[Common Test user guide].
+You can use it to set Common Test hooks, for example:
+
+[source,make]
+CT_OPTS = -ct_hooks cowboy_ct_hook
+
+The `CT_SUITES` variable can be used to override what
+Common Test suites Erlang.mk will be aware of. It does
+not normally need to be set as Erlang.mk will find the
+test suites automatically.
+
+The name of the suite is the part before `_SUITE.erl`.
+If the file is named 'http_SUITE.erl', the test suite
+is `http`:
+
+[source,make]
+CT_SUITES = http ws
+
+=== Usage
+
+To run all tests (including Common Test):
+
+[source,bash]
+$ make tests
+
+To run all tests and static checks (including Common Test):
+
+[source,bash]
+$ make check
+
+You can also run Common Test separately:
+
+[source,bash]
+$ make ct
+
+Erlang.mk will create targets for all test suites it finds.
+If you have a file named 'test/http_SUITE.erl', then the
+target `ct-http` will run that specific test suite:
+
+[source,bash]
+$ make ct-http
+
+Erlang.mk provides a convenient way to run a specific
+group or a specific test case within a specific group,
+using the variable `t`. Note that this only applies to
+suite-specific targets, like the `ct-http` example above.
+
+To run all tests from the `http_compress` group in the
+`http_SUITE` test suite, write:
+
+[source,bash]
+$ make ct-http t=http_compress
+
+Similarly, to run a specific test case in that group:
+
+[source,bash]
+$ make ct-http t=http_compress:headers_dupe
+
+To do the same against a multi-application repository,
+you can use the `-C` option:
+
+[source,bash]
+$ make -C apps/my_app ct-http t=my_group:my_case
+
+Note that this also applies to dependencies. When using Cowboy
+as a dependency, you can run the following directly:
+
+[source,bash]
+$ make -C deps/cowboy ct-http t=http_compress
+
+Finally, link:coverage.asciidoc[code coverage] is available,
+but covered in its own chapter.