Defining Environment¶

Prior to writing tests it is important to define the environment the tests are going to ran on, e.g. hostnames and platforms. Throughout this documentation we will often refer to this as inventory.

goodplay borrows this term from Ansible which already provides various ways to define inventories. When doing a test run, goodplay reads an inventory during setup phase that defines the hosts to be used for the test. These can be hosts you have already available in your environment or Docker containers you have defined via Docker Compose that are automatically created, as we will see in a minute.

The usual and easiest way to define an inventory is to create a file named inventory right beside the test playbook:

## inventory
web ansible_user=root
db ansible_user=root

This example defines two hosts – web and db. The remote user that is used to connect to the host needs to be specified via ansible_user inventory variable.

Single Docker Environment¶

If we would use the inventory example from the previous section together with a test playbook it would not create any Docker containers yet, and thus Ansible would not be able to connect to the hosts web and db. There are multiple reasons this is not done automatically:

goodplay can be used without Docker, e.g. tests can run against localhost or otherwise managed test environment.
Some hostnames defined in the inventory may be used only for configuration purposes (not actually required for test run).
Hosts may require different platforms, so these must be specified explicitly.

The Docker container environment required for a test run is specified with the help of Docker Compose in a docker-compose.yml file right beside the test playbook and inventory.

Note

Please note that Docker Compose uses the term service for what goodplay uses the term host.

Let’s assume we want hosts web and db to run latest CentOS 7. Therefor we create the following docker-compose.yml file:

## docker-compose.yml
version: "2"
services:
  web:
    image: "centos:centos7"
    tty: True

  db:
    image: "centos:centos7"
    tty: True

When executing a test, goodplay …

… recognizes the docker-compose.yml file right beside the test playbook and inventory,
… starts up the test environment,
… connects the Ansible inventory with the instantiated Docker containers,
… executes the test playbook,
… and finally shuts down the test environment.

Multiple Docker Environments¶

Sometimes you want to run the same test playbook against multiple environments. For example when you have an Ansible role that should support more than one platform, you most likely want to test run it against each supported platform.

We could extend our previous example by not only testing against latest CentOS 7, but also against Ubuntu Trusty:

## docker-compose.centos.7.yml
version: "2"
services:
  web:
    image: "centos:centos7"
    tty: True

  db:
    image: "centos:centos7"
    tty: True


## docker-compose.ubuntu.trusty.yml
version: "2"
services:
  web:
    image: "ubuntu-upstart:trusty"
    tty: True

  db:
    image: "ubuntu-upstart:trusty"
    tty: True

goodplay will recognize that there are multiple Docker Compose files, and will run the test playbook against each of these environments.

Docker Compose allows you to work with Multiple Docker Compose files. goodplay takes this one step further by introducing conventions to extending/overriding Docker Compose files.

goodplay sees your docker-compose.yml files as a hierarchy where as docker-compose.yml is the parent of docker-compose.item1.yml which is the parent of docker-compose.item1.item11.yml and so on and so forth. When deciding which ones to use, goodplay only instantiates the leaves in the hierarchy. Thus you could have intermediate Docker Compose files that hold common configuration that can be refered to further down in the hierarchy.

Additionally one can use the extension .override.yml instead of .yml to make goodplay override (merge) the Docker Compose file from the same or upper level.