ansible-role-test

ansible-role-test is a tool that uses docker containers to quickly create disposable boxes that can be provisioned by a test ansible playbook via ssh.

Requirements

• docker
• python 2.7+, 3.x
• a host running systemd is highly recommended, see notice below

Installation

• Clone repository
• Optional: Activate your virtualenv or run make venv to create a local one
• Run make install
• Either run ansible-role-test or venv/bin/ansible-role-test

Notice for users not running on systemd-enabled systems

When using boot2docker or a linux distribution not running systemd, CentOS 7 might not start properly due to missing cgroups. The course of action in this case is to create manually the /sys/fs/cgroup/systemd folder either on your host (if running linux) or inside your boot2docker VM.

OSX:

boot2docker ssh
sudo mkdir /sys/fs/cgroup/systemd

Linux (without systemd):

sudo mkdir /sys/fs/cgroup/systemd

Development

Instead of running make install, run make dev and use venv/bin/ansible-role-test.

Usage

Usage: ansible-role-test [OPTIONS] COMMAND [ARGS]...

  ansible-role-test is a docker based testing utility for ansible roles.

Options:
  --help  Show this message and exit.

Commands:
  init       Create the test folder with a default test...
  snapshots  Manipulate saved containers
  test       Run tests ROLE can be either be a local path,...

init command

Creates a tests folder with a default main.yml file that looks like the one shown in the [Writing tests] section below.

Usage: ansible-role-test init [OPTIONS] [PATH]

  Create the test folder with a default test file

Options:
  -h, --help  Show this message and exit.

test command

Usage: ansible-role-test test [OPTIONS] ROLE

  Run tests

  ROLE can be either be a local path, a git repository or an ansible-galaxy
  role name.

Options:
  -c, --config FILENAME           Config file to use for the tests
  --roles-path ROLES_PATH         Search path for non-galaxy roles that might
                                  be required as dependencies
  --library-path LIBRARY_PATH     Search path for custom ansible modules
  --plugins-action-path PLUGINS_ACTION_PATH
                                  Search path for custom action plugins
  --plugins-filter-path PLUGINS_FILTER_PATH
                                  Search path for custom filter plugins
  --plugins-lookup-path PLUGINS_LOOKUP_PATH
                                  Search path for custom lookup plugins
  -e, --extra-vars EXTRA_VARS     Set additional variables as key=value or
                                  YAML/JSON
  -l, --limit SUBSET              Limit selected hosts to a given pattern
  --skip-tags SKIP_TAGS           Only run plays and tasks whose tags do not
                                  match these values
  -t, --tags TAGS                 Only run plays and tasks tagged with these
                                  values
  -v                              Verbose mode (-vvv for more, -vvvv to enable
                                  connection debugging)
  --ansible-version ANSIBLE_VERSION
                                  The ansible version to use (either 1.8, 1.9
                                  or latest)
  --privileged                    Run test containers in privileged mode
                                  (dangerous)
  --cache                         Cache yum/apt folders on the host
  --save [failed|successful|all]  Save containers, can be either one of
                                  "failed", "successful" and "all"
  -h, --help                      Show this message and exit.

# Create a default test file and run it on a local role
ansible-role-test init /path/to/role
ansible-role-test test --save=failed /path/to/role
# Test a git repository
ansible-role-test test https://github.com/org/repo.git
# Test a branch on a git repository
ansible-role-test test https://github.com/org/repo.git#my-branch
# Test an ansible-galaxy role
ansible-role-test test user.role

snapshots command

Helper commands to inspect saved images generated by the test command.

Usage: ansible-role-test snapshots [OPTIONS] COMMAND [ARGS]...

  Manipulate saved containers

Options:
  -h, --help  Show this message and exit.

Commands:
  list   List all snapshots and whether they failed or...
  purge  Delete all snapshots
  rm     Remove a specific snapshot
  view   Display the output of the ansible play that...

snapshots list command

List all snapshots currently saved in the local repository.

Example output:

ROLE NAME               CONTAINER           STATUS          DATE                    IMAGE NAME
aeriscloud.nodejs       centos-6            successful      2015-06-10T12:58:52     aeriscloud.nodejs.centos-6:successful-1433908732
aeriscloud.nodejs       centos-7            failed          2015-06-10T12:58:47     aeriscloud.nodejs.centos-7:failed-1433908727

snapshots view command

Display the output of the ansible job that was run on this host.

snapshots rm command

Removes a stored snapshot by name, eg ansible-role-test snapshots rm aeriscloud.nodejs.centos-6:successful-1433908732

snapshots purge command

Deletes all stored snapshots.

Writing tests

Create a tests folder in your role, then in that folder create a yaml file that looks like that one:

---
# The name of your test
name: "My test name"
# The containers you will use for this test, you could for example spawn a debian
# centos, ubuntu, etc... and run the tests on "all" hosts
# If skipped, tests will be run on every containers available
#containers:
#  master1: 'centos:6'
#  slave1:
#    image: 'centos:7'
#    vars:
#      host_var1: foobar # defines host_var1 on this host on particular
#  slave2: 'centos:7'
#  slave3: 'debian:wheezy'
# You can also setup custom inventory groups to be declared in the inventory, if
# no containers are declared above, they will be merged with the default groups.
# For exemple the following declaration will create 2 groups, master and slaves.
#groups:
#  masters:
#  - master1
#  slaves:
#  - slave1
#  - slave2
#  - slave3
# This is your test playbook
playbook:
- hosts: all
# You should have your role called in roles, with the proper variables set, you
# can call the same role several times in a row but I'd rather recommend creating
# separate test files for each call to ensure that they run in a clean env
  roles:
# "@ROLE_NAME@" is a magic variable that will be replaced by the name of the role
# on your filesystem before running the tests
  - role: "@ROLE_NAME@"
    var1: something
    var2: something
# You should verify that your role executed properly here, using tasks
  tasks:
  - name: "Check that my-role did that thing properly"
    module: do-something

Saving containers

If desired, it is possible to use the --save option to save containers at the end of each test. Possible values for this option are failed, successful and all and will filters which containers to save. One useful use case is to save failed containers to inspect what file/package could be missing.

Containers are saved as art/{ROLE NAME}.{CONTAINER NAME} with the tag {STATUS}-{STAMP}.

Saved images can be found by running ansible-role-test snapshots list. It is possible to inspect the image by running:

$ docker run -t -i art/role-name.system:tag bash
[root@671165bdfcb0 /]#

Once done, one can removed failed containers by running docker rmi art/foo:tag or ansible-role-test snapshots rm art/foo:tag. A faster way to remove all the corresponding images is to run ansible-role-test snapshots purge.

Paths and config file

Most of the time, your roles might depend on other local roles or plugins, in which case you can use the --role-path, --library-path, etc... flags to help ansible find those. In some cases though it might result in unwieldy commands due to the sheer amount of flags passed around. When that happens you can use a config file that follows this format to provide the proper information to ansible:

---
roles: ansible/roles
library: ansible/library
plugins:
  action: ansible/plugins/actions
  filter: ansible/plugins/filters

Then call ansible-role-test with the --config flag pointing to this file. The given paths are relative to the config file's location.

Available test containers

You can find them on the wizcorp user on the docker registry, they should be named ansible-<distro>:<version>.

image name	name in playbook
centos:6	centos-6
centos:7	centos-7
debian:wheezy	debian-wheezy
debian:jessie	debian-jessie
ubuntu:14.04	ubuntu-lts
ubuntu:15.04	ubuntu-15

They are also automatically separated in 3 groups centos, debian and ubuntu.

Please check aeriscloud@docker for the current list of available images.

If you wish to build all the images locally, you can run make docker.

Known issues/caveats

• Any role that deals with kernel modules or raw hardware (eg. iptables or formatting disks) will run into issues while running in docker. iptables seems to work in privileged mode with no side effects but anything that does destructive operations should not be tested with privileged mode on.
• While the centos boxes are running systemd-container, debian and ubuntu boxes are not and as such calls to systemctl/initd might not behave the same way as a real system.

Disclaimer

This is currently a work in progress, I am not responsible and shall not be held responsible in any manner if this tool causes loss of data, hardware faults, act of gods, invocation of old or ancient ones, elder gods and other horrors from the depths.