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:
- Connect to host
web
. - Update the cache of
apt
, which is Ubuntu's default package manager. - Install the latest
nginx
-- one of the most used web servers -- package viaapt
.
At a first glance this looks fine but it is not clear if the following holds true:
- The nginx service is automatically started after the installation.
- The nginx service is started at boot time.
- 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.
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 :ref:`Installation Guide <installation>` for detailed information and alternative installation options.
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
.
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.
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 ===========================