Skip to content
Switch branches/tags
Go to file


ansible-test: Ansible Local Testing Framework

Ansible-test is a tool for testing your automation on local docker images. You can think of this as a slim version of Chef's test-kitchen.

$ cd /my/ansible/repository
$ ansible-test my_ansible_role

The above command will drop a Dockerfile at the root of your ansible repo and initialize a docker image with ansible installed. It will then run the ansible role "my_ansible_role".

Note that ansible-test also accepts arbitrary arguments. These arguments will be passed on to the ansible-playbook command while running tests:

ansible-test my_ansible_role --ask-vault-pass

Ansible test also accepts an image argument to specify the base docker image:

ansible-test my_ansible_role --image ubuntu:latest

See the example ansible flask project, which tests with ansible-test out-of-the-box


To install ansible-test:

$ pip install ansible-test


ansible-test requires that you have docker installed locally. If you are using Mac OSX, I recommend you use boot2docker.

NOTE: Given docker's inflexibility with Dockerfiles, ansible-test will overwrite the Dockerfile in the current working directory from which you run ansible-test. This is currently the simplest way to integrate docker as a testing tool.


usage: ansible-test [-h] [--image IMAGE] [--family {Debian,RedHat,Gentoo}]

positional arguments:
  role                  Role to test

optional arguments:
  -h, --help            show this help message and exit
  --image IMAGE, -i IMAGE
                        Docker Base Image
  --family {Debian,RedHat,Gentoo}, -f {Debian,RedHat,Gentoo}
                        ansible_os_family value for Base Image

Tested image/family combinations:

image debian:7.7 / family Debian <-- default values if not specified
image centos:centos7.2.1511 / family RedHat
image gentoo-amd64-plus-portage / family Gentoo

Gentoo notes

Rather than being able to simply pull official gentoo docker images, it was necessary to merge the stage3 and portage images to work around a docker limitation: docker currently has no way to mount volumes while building an image, only when starting up a container from an already-built image (see for further discussion of this limitation).

See base-images/Dockerfile.gentoo-amd64-portage as example for creating base image for testing on Gentoo. This Dockerfile inherits from gentoo/stage3-amd64 Dockerfile and adds the commands from gentoo/portage Dockerfile in order to create a full stage3 image with /usr/portage included rather than relying on a separage image containing a portage volume.


An Ansible Testing Framework for Humans




No releases published


No packages published