Beaker is a test harness focused on acceptance testing via interactions between multiple (virtual) machines. It provides platform abstraction between different Systems Under Test (SUTs), and it can also be used as a virtual machine provisioner - setting up machines, running any commands on those machines, and then exiting.

Beaker runs tests written in Ruby, and provides additional Domain-Specific Language (DSL) methods. This gives you access to all standard Ruby along with acceptance testing specific commands.


See Beaker Installation.


Documentation for Beaker can be found in this repository in the docs/ folder.

Table of Contents

  • Tutorials take you by the hand through the steps to setup a beaker run. Start here if you’re new to Beaker or test development.
  • Concepts discuss key topics and concepts at a fairly high level and provide useful background information and explanation.
  • Rubydocs contains the technical reference for APIs and other aspects of Beaker. They describe how it works and how to use it but assume that you have a basic understanding of key concepts.
  • How-to guides are recipes. They guide you through the steps involved in addressing key problems and use-cases. They are more advanced than tutorials and assume some knowledge of how Beaker works.

Beaker Libraries

Beaker functionality has been extended through the use of libraries available as gems. See the complete list for available gems. See the beaker-template documentation for documentation on creating beaker-libraries.


See LICENSE file.

Support & Issues

Please log tickets and issues at our Beaker Issue Tracker. In addition there is an active #puppet-dev channel on Freenode.

For additional information on filing tickets, please check out our CONTRIBUTOR doc, and for ticket lifecycle information, check out our ticket process doc.


If you'd like to contribute improvements to Beaker, please see CONTRIBUTING.


For information on project maintainers, please check out our CODEOWNERS doc.


Since the beaker project has always been the central hub for all beaker testing, its release process has been more involved than most beaker-libraries (ie. beaker-puppet). Historically, the process has been described in Confluence: Beaker Release Process (apologies, most links in this section are Puppet-internal).

To release new versions of beaker, please use this jenkins job. This job lives on internal infrastructure.

To run the job, click on Build with Parameters in the menu on the left. Make sure you verify the checkbox next to PUBLIC is checked and enter the appropriate version. The version should adhere to semantic version standards. When in doubt, consult the maintainers of Beaker for guidance.