beaker 2.27.0 → 2.28.0

data/docs/How-To-Beaker.md

@@ -0,0 +1,7 @@
+* [Overview](Overview.md)
+* [Beaker Installation](Beaker-Installation.md)
+* [Creating A Test Environment](Creating-A-Test-Environment.md)
+* [The Command Line](The-Command-Line.md)
+* [The Beaker DSL](The-Beaker-DSL.md)
+* [Let's Write a Test!](Lets-Write-a-Test.md)
+* [Access The Live Test Console with Pry](Access-the-Live-Test-Console-with-Pry.md)

data/docs/How-To-Use-User-Password-Authentication-with-Beaker.md

@@ -0,0 +1,53 @@
+By default Beaker connects to hosts using public key authentication, but that may not be correct method for your particular testing set up.  To have beaker connect to a host using a username/password combination edit your hosts configuration file.  You will need to create a new ssh hash to be used for logging into your SUT that includes (at least) entries for _user_, _password_, and _auth_method_.  You may also include any additional supported [Net::SSH Options](http://net-ssh.github.io/ssh/v1/chapter-2.html#s3).
+
+## Example 1: Use 'password' authentication
+```
+HOSTS:
+  pe-centos6:
+    roles:
+      - master
+      - agent
+      - dashboard
+      - database
+      - myrole
+    platform: el-6-i386
+    snapshot : clean-w-keys
+    hypervisor : fusion
+    ssh:
+      password : anode
+      user: anode
+      auth_methods:
+        - password
+```
+
+The log will then read as:
+
+_snip_
+```
+pe-centos6 20:19:16$ echo hello!
+Attempting ssh connection to pe-centos6, user: anode, opts: {:config=>false, :paranoid=>false, :timeout=>300, :auth_methods=>["password"], :port=>22, :forward_agent=>true, :keys=>["/Users/anode/.ssh/id_rsa"], :user_known_hosts_file=>"/Users/anode/.ssh/known_hosts", :password=>"anode", :user=>"anode"}
+```
+_/snip_
+
+## Example 2: Use a list of authentication methods
+If you want to try a sequence of authentication techniques that fall through on failure simply include them (in their desired order) in your list of _auth_methods_.  If one of your methods is user/password be warned, after a failure Net::SSH will attempt keyboard-interactive password entry - if you do not want this behavior add _number_of_password_prompts: 0_.
+```
+HOSTS:
+  pe-centos6:
+    roles:
+      - master
+      - agent
+      - dashboard
+      - database
+      - myrole
+    platform: el-6-i386
+    snapshot : clean-w-keys
+    hypervisor : fusion
+CONFIG:
+  ssh:
+    auth_methods:
+      - password
+      - publickey
+    number_of_password_prompts: 0
+    password : wootwoot
+```

data/docs/How-to-Write-a-Beaker-Test-for-a-Module.md

@@ -0,0 +1,145 @@
+#Beaker for Modules
+##Read the Beaker Docs
+
+[Beaker How To](https://github.com/puppetlabs/beaker/wiki)
+
+<a href = "http://rubydoc.info/github/puppetlabs/beaker/frames">Beaker DSL API</a>
+
+##Understand the Difference Between beaker and beaker-rspec
+[beaker vs. beaker-rspec](https://github.com/puppetlabs/beaker/wiki/beaker-vs.-beaker-rspec)
+
+##beaker-rspec Details
+###Supported ENV variables
+
+`BEAKER_debug` - turn on extended debug logging
+
+`BEAKER_set` - set to the name of the node file to be used during testing (exclude .yml file extension, it will be added by beaker-rspec), assumed to be in module's spec/acceptance/nodesets directory
+
+`BEAKER_setfile` - set to the full path to a node file be used during testing (be sure to include full path and file extensions, beaker-rspec will use this path without editing/altering it in any way)
+
+`BEAKER_destroy` - set to `no` to preserve test boxes after testing, set to `onpass` to destroy only if tests pass
+
+`BEAKER_provision` - set to `no` to skip provisioning boxes before testing, will then assume that boxes are already provisioned and reachable
+
+##Typical Workflow
+
+1. Run tests with `BEAKER_destroy=no`, no setting for `BEAKER_provision`
+  * beaker-rspec will use spec/acceptance/nodesets/default.yml node file
+  * boxes will be newly provisioned
+  * boxes will be preserved post-testing
+* Run tests with `BEAKER_destroy=no` and `BEAKER_provision=no`
+  * beaker-rspec will use spec/acceptance/nodesets/default.yml node file
+  * boxes will be re-used from previous run
+  * boxes will be preserved post-testing
+* Nodes become corrupted with too many test runs/bad data and need to be refreshed then GOTO step 1
+* Testing is complete and you want to clean up, run once more with `BEAKER_destroy` unset
+  * you can also:
+
+        cd .vagrant/beaker_vagrant_files/default.yml ; vagrant destroy --force
+
+##Building your Module Testing Environment
+
+Using puppetlabs-mysql as an example module.
+
+###Clone the module repository of the module that you wish to test
+
+    git clone https://github.com/puppetlabs/puppetlabs-mysql
+    cd puppetlabs-mysql
+
+###Create the spec_helper_acceptance.rb
+
+Create example file spec_helper_acceptance.rb:
+```ruby
+require 'beaker-rspec'
+require 'pry'
+
+hosts.each do |host|
+  # Install Puppet
+  on host, install_puppet
+end
+
+RSpec.configure do |c|
+  module_root = File.expand_path(File.join(File.dirname(__FILE__), '..'))
+
+  c.formatter = :documentation
+
+  # Configure all nodes in nodeset
+  c.before :suite do
+    # Install module
+    puppet_module_install(:source => module_root, :module_name => 'mysql')
+    hosts.each do |host|
+      on host, puppet('module','install','puppetlabs-stdlib'), { :acceptable_exit_codes => [0,1] }
+    end
+  end
+end
+```
+
+Update spec_helper_acceptance.rb to reflect the module under test.  You will need to set the correct module name and add any module dependencies.  Place the file in the /spec directory (in this case puppetlabs-mysql/spec)
+
+###Install beaker-rspec
+####From Gem (preferred)
+
+    gem install beaker-rspec
+
+###Update the module's Gemfile
+
+In module's top level directory edit Gemfile.
+
+Add `gem 'beaker-rspec', :require => false` under `group :development, :test do`.
+
+    bundle install
+
+###Create node files
+
+These files indicate the nodes (or hosts) that the tests will be run on.  By default, any node file called `default.yml` will be used.  You can override this using the `BEAKER_set` environment variable to indicate an alternate file.  Do not provide full path or the '.yml' file extension to `BEAKER_set`, it is assumed to be located in 'spec/acceptance/nodesets/${NAME}.yml' by beaker-rspec.  If you wish to use a completely different file location use `BEAKER_setfile` and set it to the full path (including file extension) of your hosts file.
+
+Nodes are pulled from <a href = "https://vagrantcloud.com/puppetlabs">Puppet Labs Vagrant Boxes</a>.
+
+Example node files can be found here:
+
+*[Puppet Labs example Vagrant node files](Example-Vagrant-Hosts-Files.md)
+
+Create the nodesets directory.  From module's top level directory:
+
+    mkdir -p spec/acceptance/nodesets
+
+Copy any nodesets that you wish to use into the nodesets directory.
+
+###Create spec tests for your module
+
+Spec tests are written in <a href = "http://rspec.info/">RSpec</a>.
+
+Example spec file (mysql_account_delete_spec.rb):
+
+```ruby
+require 'spec_helper_acceptance'
+
+describe 'mysql::server::account_security class' do
+  describe 'running puppet code' do
+    it 'should work with no errors' do
+      pp = <<-EOS
+        class { 'mysql::server': remove_default_accounts => true }
+      EOS
+
+      # Run it twice and test for idempotency
+      apply_manifest(pp, :catch_failures => true)
+      expect(apply_manifest(pp, :catch_failures => true).exit_code).to be_zero
+    end
+
+    describe 'accounts' do
+      it 'should delete accounts' do
+        shell("mysql -e 'show grants for root@127.0.0.1;'", :acceptable_exit_codes => 1)
+      end
+
+      it 'should delete databases' do
+        shell("mysql -e 'show databases;' |grep test", :acceptable_exit_codes => 1)
+      end
+    end
+  end
+end
+```
+###Run your spec tests
+
+From module's top level directory
+
+    bundle exec rspec spec/acceptance

data/docs/Lets-Write-a-Test.md

@@ -0,0 +1,73 @@
+###The Task
+
+Consider if mcollectived incorrectly spawned a new process with every puppet agent run on Ubuntu 10.04.  We need an acceptance test to check that a new process is not spawned and to ensure that this issue does not regress in new builds.
+
+###Figure Out Test Steps
+
+What needs to happen in this test:
+
+* Install PE
+* Restart mcollective twice
+* Check to see if more than one mcollective process is running
+
+###Install PE
+
+We prefer to install PE once and then run a set of tests, so PE installation should not be part of the actual acceptance test.
+
+    $ mkdir setup
+    $ cd setup
+    $ cat > install.rb << RUBY
+    test_name "Installing Puppet Enterprise" do
+    install_pe      
+    RUBY
+    $ cd ..
+
+XXX - Will beaker just pick this up? Is the setup dir magic?
+
+## Create a test file
+
+We need to create a test file to run.
+
+### Define some test commands to run
+####Restart mcollective twice
+
+Here's our magic command that restarts mcollective:
+
+    restart_command = "bash -c '[[ -x /etc/init.d/pe-mcollective ]] && /etc/init.d/pe-mcollective restart'"
+
+####Check to see if more than one mcollective process is running
+
+Here's our magic command that throws an error if more than one mcollective process is running:
+```
+process_count_check = "bash -c '[[ $(ps auxww | grep [m]collectived | wc -l) -eq 1 ]]'"
+```
+###Put it all together
+
+Here's the finished acceptance test.
+```
+test_name "/etc/init.d/pe-mcollective restart check"
+
+# Don't run these tests on the following platforms
+confine :except, :platform => 'solaris'
+confine :except, :platform => 'windows'
+confine :except, :platform => 'aix'
+
+step "Make sure the service restarts properly"
+hosts.each do |host|
+  # Commands to execute on the target system.
+  restart_command = "bash -c '[[ -x /etc/init.d/pe-mcollective ]] && /etc/init.d/pe-mcollective restart'"
+  process_count_check = "bash -c '[[ $(ps auxww | grep [m]collectived | wc -l) -eq 1 ]]'"
+
+  # Restart once
+  on(host, restart_command) { assert_equal(0, exit_code) }
+  # Restart again
+  on(host, restart_command) { assert_equal(0, exit_code) }
+  # Check to make sure only one process is running
+  on(host, process_count_check) { assert_equal(0, exit_code) }
+end
+```
+You can now run this with
+
+  `beaker --host myhost.cfg --test mytest.rb`
+
+Next up you may want to look at the [Beaker test for a module](How-to-Write-a-Beaker-Test-for-a-Module.md) page.

data/docs/Openstack-Support.md

@@ -0,0 +1,32 @@
+This options allows for testing against Openstack instances.
+
+Considered **EXPERIMENTAL**, may break without notice.
+
+### Basic Openstack hosts file ###
+    HOSTS:
+      centos-6-master:
+        roles:
+          - master
+          - agent
+          - database
+          - dashboard
+        platform: el-6-x86_64
+        image: centos-6-x86_64-nocm
+        flavor: m1.large
+        hypervisor: openstack
+      centos-6-agent:
+        roles:
+          - agent
+        platform: el-6-x86_64
+        image: centos-6-x86_64-nocm
+        flavor: m1.large
+        hypervisor: openstack
+    CONFIG:
+      nfs_server: none
+      consoleport: 443
+      openstack_api_key: P1as$w0rd
+      openstack_username: user
+      openstack_auth_url: http://10.10.10.10:5000/v2.0/tokens
+      openstack_tenant: testing
+      openstack_network : testing
+      openstack_keyname : nopass

data/docs/Overview.md

@@ -0,0 +1,31 @@
+Beaker is an acceptance testing harness for Puppet PE and other Puppet Projects.  It can also be used as a virtual machine provisioner - setting up machines, running any configuration on those machines and then exiting.  
+
+Beaker goes through several phases when running tests
+
+* Provisioning
+  * skip with `--no-provision`
+  * Using supported hypervisors provision SUTs for testing on
+  * Do any initial configuration to ensure that the SUTs can communicate with beaker and each other
+* Validation
+  * skip with `--no-validate`
+  * Check the SUTs for necessary packages (curl, ntpdate)
+* Configuration
+  * skip with `--no-configure`
+  * Do any post-provisioning configuration to the test nodes
+* Testing
+  * Pre-Suite
+   * use `--pre-suite`
+   * Run any test files defined as part of the `--pre-suite` command line option
+  * Tests
+   * use `--tests`
+   * Run any test files defined as part of the `--tests` command line option
+  * Post-Suite
+   * use `--post-suite`
+   * Run any test files defined as part of the `--post-suite` command line option
+* Reverting
+  * Skip with `--preserve-hosts`
+  * Destroy and cleanup all SUTs
+* Cleanup
+  * Report test results
+
+Beaker runs tests written in Ruby with an additional DSL API.  This gives you access to all standard Ruby along with acceptance testing specific commands.

data/docs/README.md

@@ -0,0 +1,43 @@
+![Beaker Muppet Image](http://images4.wikia.nocookie.net/__cb20101015151248/muppet/images/0/05/Beaker.jpg)
+
+## Beaker Info
+
+* [Beaker Owners & Reviewers](Beaker-Owners-and-Reviewers.md)
+* [How to install](Beaker-Installation.md)
+* [How to Beaker](How-To-Beaker.md)
+  * [Overview](Overview.md)
+  * [Beaker Installation](Beaker-Installation.md)
+  * [Creating A Test Environment](Creating-A-Test-Environment.md)
+    * [Roles, What Are They?](Roles-What-Are-They.md)
+    * Supported Virtualization Techniques
+      * [VMWare Fusion](VMWare-Fusion-Support.md)
+      * [EC2](EC2-Support.md)
+      * [vSphere](vSphere-Support.md)
+      * [Vagrant](Vagrant-Support.md)
+        * [Example Vagrant Hosts Files](Example-Vagrant-Hosts-Files.md)
+      * [Google Compute Engine](Google-Compute-Engine-Support.md)
+      * [Docker Support](Docker-Support.md)
+      * [Openstack](Openstack-Support.md)
+      * [Solaris](Solaris-Support.md)
+  * [The Command Line](The-Command-Line.md)
+  * [Argument Processing and Precedence](Argument-Processing-and-Precedence.md)
+    * [How To Use User/Password Authentication with Beaker](How-To-Use-User-Password-Authentication-with-Beaker.md)
+  * [Running Masterless Beaker](Beaker-with-Masterless-Puppet.md)
+  * [Types, Puppet 4, & The All-In-One Agent](Types,-Puppet-4,-and-the-All-In-One-Agent.md)
+  * [The Beaker DSL](The-Beaker-DSL.md)
+    * [Shared Options for Executing Beaker Commands](Shared-Options-for-Executing-Beaker-Commands.md)
+    * [Beaker DSL on rdoc.info](http://rdoc.info/github/puppetlabs/beaker/master/Beaker/DSL)
+  * [Let's Write a Test!](Lets-Write-a-Test.md)
+  * [Access The Live Test Console with Pry](Access-the-Live-Test-Console-with-Pry.md)
+  * [Test Tagging](Beaker-Test-Tagging.md)
+* [Beaker vs. Beaker-rspec](https://github.com/puppetlabs/beaker/wiki/beaker-vs.-beaker-rspec)
+* [How to Write a Beaker Test for a Module Using beaker-rspec](How-to-Write-a-Beaker-Test-for-a-Module.md)
+
+## Other Resources
+
+* [Latest Gem Release Notes](https://github.com/puppetlabs/beaker/blob/master/HISTORY.md#LATEST)
+* [File a Beaker Bug](File-a-Beaker-Bug.md)
+* [Video: Beaker 101 talk at PDXPUG, May 2014](https://www.youtube.com/watch?v=cSyJXTYFXFg)
+* [Podcast: Beaker, May 2014](http://puppetlabs.com/podcasts/podcast-beaker-cloud-enabled-acceptance-testing-tool)
+* [Podcast: Automated Testing with Beaker for Windows, December 2014](http://puppetlabs.com/podcasts/podcast-automated-testing-beaker-windows)
+* [Real-world Examples: Puppetlabs Acceptance Testing for Puppet](https://github.com/puppetlabs/puppet/tree/master/acceptance/tests)

data/docs/Roles-What-Are-They.md

@@ -0,0 +1,44 @@
+Each host in a host configuration file is defined to have one or more roles.  Beaker supports the roles `master`, `agent`, `frictionless`, `dashboard` and `database`.  These roles indicate what Puppet responsibilities the host will assume.  If puppet is installed as part of the Beaker test execution then the roles will be honored (ie, the host defined as `master` will become the puppet master node).  Other than puppet installation, the roles provide short cuts to node access.  In tests you can refer to nodes by role:
+
+    on master, "echo hello"
+    on database, "echo hello"
+
+## Creating Your Own Roles
+Arbitrary role creating is supported in Beaker.  New roles are created as they are discovered in the host/config file provided at runtime.
+
+### Example User Role Creation
+```
+HOSTS:
+  pe-ubuntu-lucid:
+    roles:
+      - agent
+      - dashboard
+      - database
+      - master
+      - nodes
+      - ubuntu
+    vmname : pe-ubuntu-lucid
+    platform: ubuntu-10.04-i386
+    snapshot : clean-w-keys
+    hypervisor : fusion
+  pe-centos6:
+    roles:
+      - agent
+      - nodes
+      - centos
+    vmname : pe-centos6
+    platform: el-6-i386
+    hypervisor : fusion
+    snapshot: clean-w-keys
+CONFIG:
+  nfs_server: none
+  consoleport: 443
+```
+
+In this case I've created the new roles `nodes`, `centos` and `ubuntu`.  These roles can now be used to call any Beaker DSL methods that require a host.
+
+```
+on centos, 'echo I'm the centos box'
+on ubuntu, 'echo I'm the ubuntu box'
+on nodes, 'echo this command will be executed on both defined hosts'
+```

data/docs/Shared-Options-for-Executing-Beaker-Commands.md

@@ -0,0 +1,43 @@
+Beaker commands are executed through an ssh connection to each individual SUT.  Various options are supported during command execution that control how the commands themselves are executed, what output is generated and how results are interpreted.
+
+## :acceptable_exit_codes
+
+Provide either a single or an array of acceptable/passing exit codes for the provided command.  Defaults to the single exit code `0`.
+
+    on host, puppet( 'agent -t' ), :acceptable_exit_codes => [0,1,2]
+
+## :accept_all_exit_codes
+
+Consider any exit codes returned by the command to be acceptable/passing.  Defaults to `nil`/`false`.
+
+    on host, puppet( 'agent -t' ), :accept_all_exit_codes => true
+
+## :expect_connection_failure
+
+Assume that this command will cause a connection failure.  Used for `host.reboot` so that Beaker can handle the broken ssh connection.
+
+    on host, "reboot", {:expect_connection_failure => true}
+
+## :dry_run
+
+Do not actually execute this command on the SUT.  Defaults to `false`.
+
+    on host, "don't do this crazy thing", {:dry_run => true}
+
+## :pty
+
+Should this command be executed in a pseudoterminal?  Defaults to `false`.
+
+    on host, "sudo su -c \"service ssh restart\"", {:pty => true})
+
+## :silent
+
+Do not output any logging for this command.  Defaults to `false`.
+
+    on host, "echo hello", {:silent => true}
+
+## :stdin
+
+Specifies standard input to be provided to the command post execution.  Defaults to `nil`.
+
+    on host, "this command takes input", {:stdin => "hiya"}