the_beaker_dsl.md

The Beaker DSL

The Beaker Domain-Specific Language (DSL) is a set of Ruby convenience methods provided by Beaker to make testing easier.

Beaker maintains yard documentation covering the DSL to help you use it. That documentation can sometimes be difficult to navigate, however, so this doc has been created to help you find your way around.

DSL Caveats

Note that if you're using a beaker-library, any methods provided there won't be documented here. You can refer to the beaker-libraries listing doc for links to those projects which should include their own documentation.

Another common point of confusion about the Beaker DSL is that there is a similar set of methods that come along in Host objects themselves. You can tell these methods apart in a test by their invocation method. Host methods are Ruby instance methods on Host objects, so they'll be invoked on a Host object like so:

host.host_method_name(host_method_params)

and they'll know by default which hosts to act on because you've provided them that through choosing which hosts to call them on. Beaker DSL methods are called in the wider context of the test itself, however, and often need to be passed the hosts you'd like them to act on:

on(hosts, "cowsay 'the tortoise lives in agony'")

Another way you can tell them apart is their location in the codebase, & thus in the Rubydocs. Beaker DSL methods live under the Beaker::DSL module, whereas Host methods are all included in the Beaker::Host object itself. Follow that link to the Host Rubydoc and checkout the Instance Method Summary to see a listing of Host methods. Note that they won't be listed here though.

Assertions

To be used for confirming the result of a test is as expected. Beaker include all Minitest assertions, plus some custom built assertions.

• Minitest assertions
• assert_output

Helpers

DSL methods designed to help you interact with hosts (like running arbitrary commands on them) or interacting with the web (checking is a given URL is alive or not).

Host

DSL methods for host manipulation.

• on
• shell
• stdout
• stderr
• exit_code
• scp_from
• scp_to
• rsync_to
• create_remote_file
• run_script_on
• run_script
• install_package
• check_for_package
• upgrade_package
• add_system32_hosts_entry
• backup_the_file
• curl_on
• curl_with_retries
• retry_on
• run_cron_on
• create_tmpdir_on As of Beaker 4.0, moved to beaker-puppet. See upgrade_from_3_to_4.md.
• echo_on

Web

Helpers for web actions.

• port_open_within?
• link_exists?
• fetch_http_file
• fetch_http_dir

Test

DSL methods for setting information about the current test.

• current_test_name
• current_test_filename
• current_step_name
• set_current_test_name
• set_current_test_filename
• set_current_step_name

Outcomes

Methods that indicate how the given test completed (fail, pass, skip or pending).

• fail_test
• pass_test
• pending_test
• skip_test
• formatted_message

Patterns

Shared methods used as building blocks of other DSL methods.

• block_on

Roles

DSL methods for accessing hosts of various roles.

• agents
• master
• database
• dashboard
• default
• not_controller
• agent_only
• aio_version?
• aio_agent?
• add_role
• add_role_def
• any_hosts_as?
• hosts_as
• find_host_with_role
• find_only_one
• find_at_most_one

Structure

DSL methods that describe and define how a test is executed.

• step
• test_name
• teardown
• expect_failure
• confine
• confine_block
• tag
• select_hosts
• inspect_host