srijan / docker_compose_cth

Erlang Common Test Hook for starting docker-compose services before running test suites

Common Test Docker Compose Hook

A Common Test hook for starting and stopping docker-compose services.

To use this hook simply place a docker-compose.yml file in the suite's data_dir, the top level of the project or declare the path explicitly with docker_compose_file -- see the configuration section below for more on how the compose file is found.

Then hooks must be declared in the ct_opts, the config returned by a function in the test suite or in a test spec. Some examples of enabling the hook are in the next section.

Shutdown of the services happens in the hook's terminate function which is called depending on when the hook was installed: CTH Scope. But the configuration for the hook can include #{stop => never} and the hook will not shutdown the services during terminate.

Examples

First, the hook must be included as a dependency of the rebar3 project. Since the hook is only used by Common Test it can be put in the test profile:

{profiles, [{test, [{deps, [docker_compose_cth]}]}]}.

Hooks can be declared in rebar.config with ct_opts:

{ct_opts, [{ct_hooks, [docker_compose_cth]}]}.

It can be added on a per-suite either with the suite/0 function in the suite module:

suite() ->
    [{ct_hooks, [docker_compose_cth]}].

or in the return of init_per_suite/1:

init_per_suite(Config) ->
    [{ct_hooks, [docker_compose_cth]} | Config].

For groups it can be added per-group in the return of init_per_group/2 function in the suite module:

init_per_group(Group, Config) ->
    [{ct_hooks, [docker_compose_cth]} | Config].

Configuration

• docker_compose_file: The path to a docker-compose.yml file to use. If it isn't an absolute path then it is relative to what will be the current working directory during the test run which is _build/test/logs/ct_run.<node>.<timestamp>. If no path is given then the hook first checks the suite's data_dir, see test/post_group_SUITE_data/docker-compose.yml as an example. If no compose file is found in the suite's data_dir it will pass no -f ... argument to docker-compose, this results in docker-compose searching up the directory tree (starting at the cwd which in this case is that ct_run.<node>.<timestamp> directory mentioned above) until it finds a compile file.
• executable_search_paths: Path to search for the docker-compose executable. If it is not set the regular path is searched as described in the docs for os:find_executable/1.
• check_if_running: A string that is the name of the service to check for before running docker-compose up. If defined the hook will check if a service is already up and not call docker-compose up if it is. By default this is done by attempting exec ls in the service's container, but the command can be set to anything by passing a tuple {Service, Command}
• skip_or_fail: The atom skip or fail (default is fail). If the hook is unable to bring up the service with docker-compose then the suite will either skip or fail, depending on this configuration.
• stop: Boolean value that if false means the services with not be shutdown when the hook terminates.
• remove_volumes: Boolean value. If true, the flag -v will be passed to docker-compose down which deletes volumes not specifically defined as external in the compose file.