Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/tsloughter/docker_compose_cth

Erlang Common Test Hook for starting docker-compose services before running test suites
https://github.com/tsloughter/docker_compose_cth

common-test docker docker-compose erlang erlang-common-test

Last synced: 3 months ago
JSON representation

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

Awesome Lists containing this project

README 

        
Common Test Docker Compose Hook

=====



A [Common Test](http://erlang.org/doc/apps/common_test/) hook for starting and stopping [docker-compose](https://docs.docker.com/compose/) services.



To use this hook simply place a `docker-compose.yml` file in the [suite's `data_dir`](http://erlang.org/doc/apps/common_test/write_test_chapter.html#data-and-private-directories), 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](http://erlang.org/doc/apps/common_test/run_test_chapter.html#test_specifications). 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](http://erlang.org/doc/apps/common_test/ct_hooks_chapter.html#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:



``` erlang

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

```



Hooks can be declared in `rebar.config` with `ct_opts`:



``` erlang

{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:



``` erlang

suite() ->

    [{ct_hooks, [docker_compose_cth]}].

```



or in the return of `init_per_suite/1`:



``` erlang

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:



``` erlang

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..`. 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..` 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](http://erlang.org/doc/man/os.html#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.