[[ct]]
== Common Test

Common Test is Erlang's functional testing framework.
Erlang.mk automates the discovery and running of Common
Test suites.

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

The `CT_LOGS_DIR` variable can be used to set where HTML
log files are to be written. This defaults to 'logs/'.

[source,make]
CT_LOGS_DIR = ct_output_log_dir

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

The variable `c` can be used to run a specific test when
the test suite does not group test cases:

[source,bash]
$ make ct-http c=headers_dupe

A test within a specific subgroup can be run by providing a
group path:

[source,bash]
$ make ct-http t=[top_level_group,second_level_group,third_level_group]:my_case

Finally, xref:coverage[code coverage] is available,
but covered in its own chapter.