simp-beaker-helpers

Methods to assist beaker acceptance tests for SIMP.

Table of Contents

  1. Overview
  2. Setup
  3. General Enhancements
  4. Nodeset Enhancements
  5. Methods
  6. Environment variables
  7. Examples
  8. License

Overview

Setup

Beginning with simp-beaker-helpers

Add this to your project's Gemfile:

gem 'simp-beaker-helpers'

Add this to your project's spec/spec_helper_acceptance.rb:

require 'simp/beaker_helpers'
include Simp::BeakerHelpers

General Enhancements

Suites

The 'beaker:suites' rake task provides the ability to run isolated test sets with a full reset of the Beaker environment.

These are entirely isolated runs of Beaker and have been designed to be used for situations where you need to eliminate all of the cruft from your previous runs to perform a new type of test.

Suite Execution

By default the only suite that will be executed is default. Since each suite is executed in a new environment, spin up can take a lot of time. Therefore, the default is to only run the default suite.

If there is a suite where the metadata contains default_run set to the Boolean true, then that suite will be part of the default suite execution.

You can run all suites by setting the passed suite name to ALL (case sensitive).

Environment Variables

  • BEAKER_suite_runall

    • Run all Suites

  • BEAKER_suite_basedir

    • The base directory where suites will be defined
    • Default: spec/acceptance

Global Suite Configuration

A file config.yml can be placed in the suites directory to control certain aspects of the suite run.

Supported Config:
---
# Fail the entire suite at the first failure
'fail_fast' : <true|false> => Default: true

Individual Suite Configuration

Each suite may contain a YAML file, metadata.yml, which will be used to provide information to the suite of tests.

Supported Config:
---
'name' : '<User friendly name for the suite>'

# Run this suite by default
'default_run' : <true|false> => Default: false

Nodeset Enhancements

YUM Repo Support

Nodes in your nodesets will create YUM repository entries according to the following Hash:

---
yum_repos:
   <repo_name>:
     <yum_resource_parameter>: <value>

The baseurl and gpgkey parameters can also take an Array if you need to point at more than one location.

This would look like the following:

---
yum_repos:
   <repo_name>:
     baseurl:
       - http://some.random.host
       - https://some.other.random.host
     gpgkey:
       - https://my.gpg.host
       - https://my.other.gpg.host

Methods

copy_fixture_modules_to

Copies the local fixture modules (under spec/fixtures/modules) onto a list of SUTs.

copy_fixture_modules_to( suts = hosts, opts = {} )
  • suts = (Array,String) list of SUTs to copy modules to
  • opts = (Hash) Options passed on to copy_module_to() for each SUT

By default, this will copy modules to the first path listed in each SUT's modulepath and simulate a pluginsync so the Beaker DSL's facter_on will still work.

If you need to use a non-default module path:

# WARNING: this will use the same :target_module_dir for each SUT
copy_fixture_modules_to( hosts, {
   :target_module_dir => '/path/to/my/modules',
})

If you want to disable pluginsync:

# WARNING: `fact_on` will not see custom facts
copy_fixture_modules_to( hosts, {
   :pluginsync => false
})

fix_errata_on

Apply any OS fixes we need on each SUT fix_errata_on( suts = hosts )

run_fake_pki_ca_on

Generate a fake openssl CA + certs for each host on a given SUT and copy the files back to a local directory.

NOTE: this needs to generate everything inside an SUT. It is assumed the SUT will have the appropriate openssl in its environment.

run_fake_pki_ca_on( ca_sut = master, suts = hosts, local_dir = '' )

  • ca_sut = the SUT to generate the CA & certs on
  • suts = list of SUTs to generate certs for
  • local_dir = local path where the CA+cert directory tree should copied back to

copy_pki_to

Copy a single SUT's PKI certs (with cacerts) onto the SUT. This simulates the result of pki::copy without requiring a full master and simp-pki module.

The directory structure copied to the SUT is:

  SUT_BASE_DIR/
              pki/
                  cacerts/cacerts.pem
                  public/fdqn.pub
                  private/fdqn.pem

copy_pki_to(sut, local_pki_dir, sut_base_dir = '/etc/pki/simp-testing')

copy_keydist_to

Copy a CA keydist/ directory of CA+host certs into an SUT.

This simulates the output of FakeCA's gencerts_nopass.sh into keydist/ and is useful for constructing a Puppet master SUT that will distribute PKI keys via agent runs.

copy_keydist_to( ca_sut = master )

pfact_on

Look up a fact on a given SUT using the puppet fact face. This honors whatever facter-related settings the SUT's Puppet installation has been configured to use (i.e., factpath, stringify_facts, etc).

pfact_on( sut, fact_name )

pluginsync_on

Simulates a pluginsync (useful for deploying custom facts) on given SUTs.

pluginsync_on( suts = hosts )

set_hieradata_on

Set the hiera data file on the provided host to the passed data structure

NOTE: This is authoritative; you cannot mix this with other hieradata copies

set_hieradata_on(host, hieradata, data_file='default')

  • host = (Array,String,Symbol) One or more hosts to act upon
  • hieradata = (Hash) The full hiera data structure to write to the system
  • data_file = (String) The filename (not path) of the hiera data

clear_temp_hieradata

Clean up all temporary hiera data files; meant to be called from after(:all)

clear_temp_hieradata

Environment variables

BEAKER_fips

(Default: no) When set to yes, Beaker will enable FIPS mode on all SUTs before running tests.

NOTE: FIPS mode is only enabled on RedHat family hosts.

BEAKER_spec_prep

(Default: yes) Ensures that each fixture module is present under spec/fixtures/modules. If any fixture modules are missing, it will run rake spec_prep to populate the missing modules using .fixtures.yml. Note that this will not update modules that are already present under spec/fixtures/modules.

BEAKER_stringify_facts

BEAKER_use_fixtures_dir_for_modules

Examples

Prep OS, Generate and copy PKI certs to each SUT

This pattern serves to prepare component modules that use PKI

# spec/spec_acceptance_helpers.rb
require 'beaker-rspec'
require 'tmpdir'
require 'simp/beaker_helpers'
include Simp::BeakerHelpers

unless ENV['BEAKER_provision'] == 'no'
  hosts.each do |host|
    # Install Puppet
    if host.is_pe?
      install_pe
    else
      install_puppet
    end
  end
end


RSpec.configure do |c|
  # ensure that environment OS is ready on each host
  fix_errata_on hosts

  # Readable test descriptions
  c.formatter = :documentation

  # Configure all nodes in nodeset
  c.before :suite do
    begin
      # Install modules and dependencies from spec/fixtures/modules
      copy_fixture_modules_to( hosts )
      Dir.mktmpdir do |cert_dir|
        run_fake_pki_ca_on( default, hosts, cert_dir )
        hosts.each{ |host| copy_pki_to( host, cert_dir, '/etc/pki/simp-testing' )}
      end
    rescue StandardError, ScriptError => e
      require 'pry'; binding.pry if ENV['PRY']
    end
  end
end

License

See LICENSE