Quick Start

Eager to get started? This page gives a good introduction in how to get started with goodplay.

For our basic example we assume we want to test our existing Ansible playbook that is responsible for installing a plain nginx web server on Ubuntu:

## nginx_install.yml
- hosts: web
  tasks:
    - name: install nginx package
      apt:
        name: nginx
        state: latest
        update_cache: yes

Briefly summarized, when running the playbook via ansible-playbook, Ansible will:

  1. Connect to host web.
  2. Update the cache of apt, which is Ubuntu’s default package manager.
  3. Install the latest nginx – one of the most used web servers – package via apt.

At a first glance this looks fine but it is not clear if the following holds true:

  1. The nginx service is automatically started after the installation.
  2. The nginx service is started at boot time.
  3. The nginx service is running on port 80.

Let’s turn these assumptions into requirements which we are going to test with goodplay. But, first things first... we need to install goodplay.

Installing

Before installing goodplay make sure you have Docker installed, which is a prerequisite for this quick start tutorial. Check out the official Install Docker Engine guide.

Afterwards, to install goodplay with pip, just run this in your terminal:

$ pip install goodplay

Please consult the Installation Guide for detailed information and alternative installation options.

Defining Environment

Before writing the actual tests we need to define our test environment which is created as Docker containers behind the scenes. This is done via a Docker Compose file and an Ansible inventory where we define all hosts and groups required for the test run.

In our case we want to test our nginx installation on a single host with Ubuntu Trusty:

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

## tests/inventory
web ansible_user=root

In this example we define a host (in Docker Compose terminology this is a service) with name web that runs the official Docker Ubuntu image ubuntu-upstart:trusty.

Writing Tests

Now, let’s write some tests that ensure nginx is installed according to our requirements:

## tests/test_nginx_install.yml
- include: ../nginx_install.yml

- hosts: web
  tasks:
    - name: nginx service is running
      service:
        name: nginx
        state: started
      tags: test

    - name: nginx service is enabled
      service:
        name: nginx
        enabled: yes
      tags: test

    - name: nginx service is listening on port 80
      wait_for:
        port: 80
        timeout: 10
      tags: test

You may have noticed that all we have to do is use the same Ansible modules we’re already used to. In case you are new to all this playbook stuff, the official Ansible playbook guide will help you getting started.

Labeling a playbook’s task with a test tag makes goodplay recognize it as a test task. A test task is meant to be successful (passes) when it does not result in a change and does not fail.

Running Tests

Note

First-time run may take some more seconds or minutes (depending on your internet connection) as the required Docker images need to be downloaded.

The following command will kick-off the test run:

$ goodplay -v
============================= test session starts ==============================
platform darwin -- Python 2.7.6, pytest-2.9.1, py-1.4.31, pluggy-0.3.1 -- /Users
/benjixx/.virtualenvs/goodplay/bin/python2.7
rootdir: /Users/benjixx/src/goodplay/examples/quickstart
plugins: goodplay-0.6.0
collected 3 items

tests/test_nginx_install.yml::nginx service is running PASSED
tests/test_nginx_install.yml::nginx service is enabled PASSED
tests/test_nginx_install.yml::nginx service is listening on port 80 PASSED

========================== 3 passed in 43.13 seconds ===========================