Gonzo was inspired by Beaker, but is meant to be a little stupider. I set out to write Gonzo because I just wanted a way to spin up a VM or group of VMs programmatically and run ServerSpec tests on them. I wasn't interested in using the Beaker helpers or matchers. I just wanted something simple and agnostic. This is the hack that ensued.
Install the Gem with the gem
command:
gem install gonzo
Or add it to your Gemfile
:
source 'https://rubygems.org'
gem 'gonzo'
At the root of your project, you'll need to create a .gonzo.yml
file. This is where you'll configure VMs for Gonzo. You'll need to configure a supported provider. As of right now, the only supported providers are vagrant
and docker
. The top-level key will be the name of the provider. Here's an example .gonzo.yml
that contains a single VM:
---
vagrant:
box: 'puppetlabs/centos-7.0-64-puppet'
env:
PUPPET_VERSION: '4.1.0'
commands:
- 'sudo yum -y install git ruby-devel libxml2-devel'
- 'sudo gem install bundler'
- 'rm Gemfile.lock'
- 'bundle install --path vendor'
- 'bundle exec rake spec'
You can configure multiple boxes to run serially by giving them a name:
---
vagrant:
spec_tests:
box: 'puppetlabs/centos-7.0-64-puppet'
env:
PUPPET_VERSION: '4.1.0'
commands:
- 'sudo yum -y install git ruby-devel libxml2-devel'
- 'sudo gem install bundler'
- 'bundle install --path vendor'
- 'bundle exec rake spec'
acceptance_tests:
box: 'puppetlabs/centos-7.0-64-puppet'
env:
PUPPET_VERSION: '4.1.0'
commands:
- 'sudo yum -y install git ruby-devel libxml2-devel'
- 'sudo gem install bundler'
- 'bundle install --path vendor'
- 'bundle exec rake spec_prep'
- 'bundle exec puppet apply examples/init.pp --modulepath spec/fixtures/modules'
- 'bundle exec rake acceptance'
Once you've configured a .gonzo.yml
file, you'll need to include the Rake tasks in your Rakefile
by adding this line:
require 'gonzo/rake_tasks'
This will make the gonzo
rake task available to you. You can run Gonzo by running bundle exec rake gonzo
. This will start all of the VMs serially. If one VM fails, by default Gonzo will continue on to the next VM in the list. You can configure this in .gonzo.yml
by setting stop_on_failure
to true
in the gonzo
section of .gonzo.yml
. For example:
---
gonzo:
stop_on_failure: true
Gonzo will aggregate the exit statuses from all VMs and exit 1 if any of them failed, or 0 if they all succeeded.
Commands will be run sequentially inside the directory where your .gonzo.yml
file is. The vagrant
provider copies the directory to /tmp/gonzo
instead of running in /gonzo
to avoid changing the project in flight. If you want to retrieve test results or generated binaries, simply add a command to copy them into /gonzo
at the end of your run:
---
vagrant:
box: 'puppetlabs/centos-7.0-64-puppet'
env:
PUPPET_VERSION: '4.1.0'
commands:
- 'puppet module install puppetlabs-strings'
- 'puppet strings'
- 'cp -r doc /gonzo'
The env
key allows you to pass environment variables to your commands. The key must be the variable name, and the value the value you wish to assign to that variable.
Gonzo has the ability to support multiple providers. Each provider defines the options available in .gonzo.yml
. The working directory will be available in the VM/container at /gonzo
but will build in /tmp/gonzo
as to not make destructive changes to the project.
All providers implement the env
and commands
parameters.
env
: Hash of string key/value pairs, optional. Theenv
parameter takes a hash of variable names and values that should be available to the commands defined in thecommands
parameter.commands
: Array of strings, required. Thecommands
parameter takes an array of commands to be executed inside the VM/container.
When defining multiple execution environments with multiple providers, they will execute serially:
---
docker:
image: 'centos:centos7'
env:
PUPPET_VERSION: '3.8.0'
commands:
- 'yum -y install rubygem-bundler'
- 'bundle install --path vendor'
- 'bundle exec rake spec'
vagrant:
box: 'puppetlabs/centos-7.0-64-puppet'
env:
PUPPET_VERSION: '4.1.0'
commands:
- 'puppet module install puppetlabs-strings'
- 'puppet strings'
- 'cp -r doc /gonzo'
The example above will run the docker
provider first, followed by the vagrant
provider.
The Docker provider requires the image
parameter to be defined in .gonzo.yml
. This tells docker
what image to run the commands in. If the image is not available, docker
will try and download it.
image
: String, required. The image thatdocker
should use to run the commands defined in thecommands
section.user
: String, optional. The user under which the commands defined in thecommand
array should be run. This user must exist in the container for the command to succeed.
The Vagrant provider requires the box
paramater to be defined in .gonzo.yml
.
box
: String, required. The Vagrant box that should be used.box_url
: String, optional. The URL for the Vagrant box specified in thebox
parameter. If thebox
is not available on the system, this tells Vagrant where to download the box from.sudo
: Boolean, optional. If this is set totrue
the commands specified in thecommands
section will be run asroot
instead ofvagrant
. Defaults tofalse
.