beaker 3.35.0 → 3.36.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7f5dbb3dbc5bdfbfb8b3faf9309c674fa6e07cf3
-  data.tar.gz: 35dcba5f1881fcb33c682151f9f06dab083fbe21
+  metadata.gz: d09c76b61894b47c8131999162c587bc7430888d
+  data.tar.gz: 87c6c59e580f70e2aeabdee1b8705d4ed67830d6
 SHA512:
-  metadata.gz: 9b64080cc40e949ca9359e27f9c3bbcd97a5d2af745f26dcb86f3807655231afd5a4e99ccebd4e33e8c4dcf308fecb25ba4ce1614859ffdff50ce1da9c8d055a
-  data.tar.gz: ac37b874e60d5b8aea0c8b4b63eb98ec2c612d78d7fbd86a37f41f2f4863d58db08c90b436bbae2165832801f5d9ceb337826d1b4779f730c0e0d5975026ce37
+  metadata.gz: 56f5aded90aa96fe6783706b8b2fc7c264d65d4e8e718283135320760797be9a9c274f4016ce2b7d8d0a8e84c60cf64db410b1810140fddf707ec963b7f12b9e
+  data.tar.gz: 7aaca5742753ddb30f74cf6c602a0e162b4bbe1e655e5f6b33b433be9649cf0ee93634069e022505377b97a0f175391f84f30ef6bb0ef63839ec2a6dd592464c

data/.gitignore

@@ -1,20 +1,46 @@
-*.swp
-log/*
 !.gitignore
+
+# Gem structure
 junit
 acceptance-tests
 pkg
 Gemfile.lock
-options.rb
+
+# Beaker-generated & local testing
 test.cfg
+options.rb
+merged_options.rb
+tmp/
+log/
+sut-files.tgz
+
+# YARD
 .yardoc
 yard_docs
-coverage
+doc
+
+# Dependencies
+# NOTE: For consistency, please use `vendor/bundle` for Bundler-installed dependencies
 .bundle
 .vendor
 _vendor
-tmp/
-doc
+vendor
+
+# Byebug
+.byebugrc
+.byebug_history
+
+# SimpleCov
+coverage
+
+
+#
+# Editor/IDE Clutter
+#
+# (TODO: consider removing these; use local personal .gitignore instead)
+
+# Vim
+*.swp
 # JetBrains IDEA
 *.iml
 .idea/
@@ -24,6 +50,3 @@ doc
 # Vagrant folder
 .vagrant/
 .vagrant_files/
-# Byebug
-.byebugrc
-.byebug_history

data/CHANGELOG.md

@@ -11,7 +11,21 @@ Tracking in this Changelog began for this project in version 3.25.0.
 If you're looking for changes from before this, refer to the project's
 git logs & PR history.
 
-# [Unreleased](https://github.com/puppetlabs/beaker/compare/3.35.0...master)
+# [Unreleased](https://github.com/puppetlabs/beaker/compare/3.36.0...master)
+
+# [3.36.0](https://github.com/puppetlabs/beaker/compare/3.35.0...3.36.0) - 2018-06-18
+
+### Fixed
+
+- Raise `ArgumentError` when passing `role = nil` to `only_host_with_role()` or `find_at_most_one_host_with_role()`
+- Use `install_package_with_rpm` in `add_el_extras`
+
+### Added
+
+- Installation instructions for contributors
+- Markdown formatting guidelines for `docs/`
+- Glossary for project jargon in [`docs/concepts/glossary.md`](docs/concepts/glossary.md)
+- Use AIX 6.1 packages everywhere for puppet6
 
 # [3.35.0](https://github.com/puppetlabs/beaker/compare/3.34.0...3.35.0) - 2018-05-16
 

data/CONTRIBUTING.md

@@ -1,41 +1,42 @@
 # How To Contribute To Beaker
 
+Contributions are welcomed. Simple bug fixes and minor enhancements will usually be accepted. Larger features should be discussed with a team member before you invest in developing them with the expectation that they will be merged.
+
 ## Getting Started
 
-* Create a [Jira account](http://tickets.puppetlabs.com)
-* Make sure you have a [GitHub account](https://github.com/signup/free)
-* Submit a ticket for your issue, assuming one does not already exist.
+Beaker does not use GitHub Issues, but an internal ticketing system running Jira that interfaces with other services. To be accepted by the maintainers, changes must follow this workflow and tagging scheme. See [ticket process doc](docs/concepts/ticket_process.md) for a
+
+* Create a [Jira account](http://tickets.puppetlabs.com).
+* Make sure you have a [GitHub account](https://github.com/signup/free).
+* Submit a ticket for your issue on Jira, assuming one does not already exist.
   * Clearly describe the issue including steps to reproduce when it is a bug.
-  * File a ticket in the [BKR project](https://tickets.puppetlabs.com/issues/?jql=project%20%3D%20BKR)
-* Fork the [Beaker repository on GitHub](https://github.com/puppetlabs/beaker)
+  * File the ticket in the [BKR project](https://tickets.puppetlabs.com/issues/?jql=project%20%3D%20BKR).
+* Fork the [Beaker repository on GitHub](https://github.com/puppetlabs/beaker).
+* [Get Beaker set up for development](docs/tutorials/installation.md#for-development).
 
 ## Making Changes
 
-* Create a topic branch from your fork of [puppetlabs/beaker](https://github.com/puppetlabs/beaker). 
-  * Please title the branch after the beaker ticket you intend to address, ie `BKR-1234`.
-* Make commits of logical units.
-* Check for unnecessary whitespace with `git diff --check` before committing.
-* Make sure your commit messages are in the proper format.
-
-````
+* Create a topic branch on your fork of [puppetlabs/beaker](https://github.com/puppetlabs/beaker).
+* Make commits of logical units. If your commits are a mess, you may be asked to [rebase or at least squash](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) your PR.
+  * Check for unnecessary whitespace with `git diff --check` before committing.
+* Make sure your commit messages are in the proper format:
+  ```
     (BKR-1234) Make the example in CONTRIBUTING imperative and concrete
 
-    Without this patch applied the example commit message in the CONTRIBUTING
-    document is not a concrete example.  This is a problem because the
-    contributor is left to imagine what the commit message should look like
-    based on a description rather than an example.  This patch fixes the
-    problem by making the example concrete and imperative.
+    Without this patch applied the example commit message in the CONTRIBUTING document is not a concrete example.  This is a problem because the contributor is left to imagine what the commit message should look like based on a description rather than an example.  This patch fixes the problem by making the example concrete and imperative.
 
-    The first line is a real life imperative statement with a ticket number
-    from our issue tracker.  The body describes the behavior without the patch,
-    why this is a problem, and how the patch fixes the problem when applied.
-````
+    The first line is a real life imperative statement with a ticket number from our issue tracker.  The body describes the behavior without the patch, why this is a problem, and how the patch fixes the problem when applied.
+  ```
+* During the time that you are working on your patch the master Beaker branch may have changed - be sure to [rebase](http://git-scm.com/book/en/Git-Branching-Rebasing) on top of [Beaker's](https://github.com/puppetlabs/beaker) master branch before you submit your PR.  A successful rebase ensures that your PR will merge cleanly.
+
+#### Courtesy
 
-* During the time that you are working on your patch the master Beaker branch may have changed - you'll want to [rebase](http://git-scm.com/book/en/Git-Branching-Rebasing) on top of [Beaker's](https://github.com/puppetlabs/beaker) master branch before you submit your PR.  A successful rebase ensures that your PR will cleanly merge into Beaker.
+Please do not introduce personal ignores into the `.gitignore`, such as IDE configurations, editor version files, or personal testing artefacts. You may find it valuable to add the first two to [a global ignore](https://help.github.com/articles/ignoring-files/#create-a-global-gitignore), and the third to [a repository-level ignore](https://help.github.com/articles/ignoring-files/#explicit-repository-excludes).
 
 ### Testing
 
-* Submitted PR's will be tested in a series of spec and acceptance level tests - the results of these tests will be evaluated by a Beaker team member, as test results are currently not accessible by the public. Testing failures that require code changes will be communicated in the PR discussion.
+Submitted PR's will be tested in a series of spec and acceptance level tests - the results of these tests will be evaluated by a Beaker team member, as acceptance test results are not accessible by the public. Testing failures that require code changes will be communicated in the PR discussion.
+
 * Make sure you have added [RSpec](http://rspec.info/) tests that exercise your new code.  These test should be located in the appropriate `beaker/spec/` subdirectory.  The addition of new methods/classes or the addition of code paths to existing methods/classes requires additional RSpec coverage.
   * Beaker uses RSpec 3.1.0+, and you should **NOT USE** deprecated `should`/`stub` methods - **USE** `expect`/`allow`. See a nice blog post from 2013 on [RSpec's new message expectation syntax](http://teaisaweso.me/blog/2013/05/27/rspecs-new-message-expectation-syntax/).
   * Run the tests to assure nothing else was accidentally broken, using `rake test`
@@ -44,20 +45,23 @@
 ### Documentation
 
 * Add an entry in the [CHANGELOG.md](CHANGELOG.md). Refer to the CHANGELOG itself for message style/form details.
-* Make sure that you have added documentation using [Yard](http://yardoc.org/) as necessary for any new code introduced.
+* Make sure that you have added documentation using [YARD](http://yardoc.org/) as necessary for any new code introduced. See [DOCUMENTING](DOCUMENTING.md).
 * More user friendly documentation will be required for PRs unless exempted. Documentation lives in the [docs/ folder](docs).
 
-## Making Trivial Changes
+## Making Changes Without a Ticket
+
+The following kinds of changes are made without a corresponding Jira ticket.
 
 ### Maintenance
 
-For changes of a trivial nature, it is not always necessary to create a new ticket in Jira. In this case, it is appropriate to start the first line of a commit with `(MAINT)` instead of a ticket/issue number. 
+For changes of a trivial nature, it is not always necessary to create a new ticket in Jira. In this case, it is appropriate to start the first line of a commit with `(MAINT)` instead of a ticket/issue number.
 
 ````
-    (MAINT) Fix whitespace 
+    (MAINT) Fix whitespace
 
     - remove additional spaces that appear at EOL
 ````
+
 ### Version Bump For Gem Release
 
 To prepare for a new gem release of Beaker the `version.rb` file is updated with the upcoming gem version number.  This is submitted with `(GEM)` instead of a ticket/issue number.
@@ -65,6 +69,7 @@ To prepare for a new gem release of Beaker the `version.rb` file is updated with
 ````
      (GEM) Update version for Beaker 1.16.1
 ````
+
 ### History File Update
 
 To prepare for a new gem release of Beaker (after the version has been bumped) the `HISTORY.md` file is updated with the latest GitHub log.  This is submitted with `(HISTORY)` instead of a ticket/issue number.
@@ -72,17 +77,18 @@ To prepare for a new gem release of Beaker (after the version has been bumped) t
 ````
     (HISTORY) Update history for release of Beaker 1.16.1
 ````
+
 ## Submitting Changes
 
 * Push your changes to a topic branch in your fork of the repository.
 * Submit a pull request to [Beaker](https://github.com/puppetlabs/beaker)
-* Update your ticket
-  * Update your [Jira](https://tickets.puppetlabs.com/issues/?jql=project%20%3D%20BKR) ticket to mark that you have submitted code and are ready for it to be considered for merge (Status: Ready for Merge).
-    * Include a link to the pull request in the ticket.
-* PRs are reviewed as time permits.  
+* Update your [Jira](https://tickets.puppetlabs.com/issues/?jql=project%20%3D%20BKR) ticket to mark that you have submitted code and are ready for it to be considered for merge (Status: Ready for Merge).
+
+PRs are reviewed as time permits.
 
 # Additional Resources
 
+* [Beaker Glossary](docs/concepts/glossary.md)
 * [Puppet community guidelines](https://docs.puppet.com/community/community_guidelines.html)
 * [Bug tracker (Jira)](http://tickets.puppetlabs.com)
 * [BKR Jira Project](https://tickets.puppetlabs.com/issues/?jql=project%20%3D%20BKR)

data/DOCUMENTING.md

@@ -1,15 +1,49 @@
 
-## Contributing Documentation to Puppetlabs Test Harness ##
+# Contributing Documentation to Beaker
 
+## Documents
 
-All inline documentation uses YARD, below is an example usage, a quick
-summary of documentation expectations and finally a short reference
-for those new to YARD.
+Beyond the usual README, Beaker has an ever-growing amount of written documentation including tutorials, recipes, and other helpful information (see [docs/](docs)). Changes larger than bug fixes will usually be required to include such user-friendly documentation.
 
-They say a picture is worth a thousand words, hopefully this example will
-be worth more than the 154 it’s composed of:
-```ruby
+## Style
+
+User-friendly Documentation (tutorials, how-tos, etc.) uses [GitHub Flavored Markdown](https://guides.github.com/features/mastering-markdown/). We adopt the following conventions.
+
+### Text
+
+- Don't hard-wrap text blocks (including lists). There is disagreement about the ideal editor width, so don't hard-wrap text. Code blocks may be wrapped as appropriate.
+
+### Lists
+
+- Use `-` lists to avoid confusion with `*emphasis*`.
+- Be sure to indent code blocks within list items.
+
+### Headers
+
+- Use Markdown Headers.
+- Always place a blank line before and after headers.
+
+### Code
+
+- Use inline code for snippets (paths, file names, variables, partial commands, etc.)
+- Use fenced blocks for code of one full line or greater
+- Offset fenced blocks with whitespace before and after, except in list items.
+- Mark the language of code blocks:
+  ~~~
+  ```console
+    $ beaker --help
+  ```
+  ~~~
+  Supported languages are documented [here](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml). You will probably be using `console`, `ruby`, `puppet`, or `yaml` most of the time.
+- It's nice to provide a shebang (`$`) in console examples to distinguish input from output.
+
+## Inline
 
+All inline/generated documentation uses [YARD](http://yardoc.org/). Below is an example usage, a quick summary of documentation expectations, and finally a short reference for those new to YARD.
+
+They say a picture is worth a thousand words, hopefully this example will be worth more than the 154 it’s composed of:
+
+```ruby
     #
     # @param  [Array<Host>, Host, #execute] hosts    The host(s) to act on
     # @param  [String]                      action   The action to perform
@@ -44,15 +78,11 @@ be worth more than the 154 it’s composed of:
         yield result if block_given?
       end
     end
-
 ```
 
+## Documentation Guide
 
-## Documentation Guide: ##
-
-
-Most of our documentation is done with the @tag syntax. With a few
-execptions tags follow this format:
+Most of our documentation is done with the @tag syntax. With a few execptions tags follow this format:
 
     @tag [TypeOfValueInBrackets] nameOfValue Multi-word description that
       can span multiple lines, as long as lines after the first have
@@ -60,71 +90,65 @@ execptions tags follow this format:
 
 Note: The `tag` name and the `nameOfValue` in question cannot contain spaces.
 
-All sections should be considered mandatory, but in practice a committer
-can walk a contributor through the process and help ensure a high quality
-of documentation.  When contributing keep especially in mind that an
+All sections should be considered mandatory, but in practice a committer can walk a contributor through the process and help ensure a high quality of documentation.  When contributing keep especially in mind that an
 `@example` block will go a long way in helping understand the use case
-(which also encourages use by others) and the @api tag helps to understand
-the scope of a Pull Request.
+(which also encourages use by others) and the @api tag helps to understand the scope of a Pull Request.
 
-Please be liberal with whitespace (not trailing whitespace) and vertical
-alignment as it helps readability while “in code”. Default indentation
-is two spaces unless there are readability/vertical alignment concerns.
+Please be liberal with whitespace (not trailing whitespace) and vertical alignment as it helps readability while “in code”. Default indentation is two spaces unless there are readability/vertical alignment concerns.
 
-While the `@params`, `@returns`, etc... may seem redundant they encourage
-thinking through exactly what you are doing and because of their strict
-format they allow a level of tooling not available in regular ruby.
+While the `@params`, `@returns`, etc... may seem redundant, they encourage thinking through exactly what you are doing and because of their strict format they allow a level of tooling not available in regular Ruby.
 
 You are encouraged to run the YARD documentation server locally by:
 
-    rake docs
+```console
+    $ rake docs
+```
 
 or
 
-    rake docs:bg
+```console
+    $ rake docs:bg
+```
 
 depending on whether you want the server to run in the foreground or not
 
-Wait for the documentation to compile and then point your browser to:
-
-    http://localhost:8808
-
+Wait for the documentation to compile and then point your browser to [http://localhost:8808](http://localhost:8808).
 
-## A Simple YARD Reference: ##
 
+## A Simple YARD Reference
 
 A Hash that must be in `{:symbol => ‘string’}` format:
 
     @param [Hash<Symbol, String>] my_hash
 
-This is also valid, and maybe more obvious to those used to Ruby
+This is also valid, and maybe more obvious to those used to Ruby:
 
     @param [Hash{Symbol=>String}]
 
-When specifying an options hash you use @option to specify key/values
+When specifying an options hash you use `@option` to specify keys/values:
 
     @param [Hash{Symbol=>String}] my_opts An options hash
     @option my_opts [ClassOfValue] :key_in_question A Description
     @option my_opts [Fixnum]       :log_level       The log level to run in.
     @option my_opts [Boolean]      :turbo (true)    Who doesn’t want turbos?
 
-This parameter takes an unordered list of Strings, Fixnums, and Floats
+This parameter takes an unordered list of Strings, Fixnums, and Floats:
 
     @param [Array<String, Fixnum, Float>]
 
-This is an ordered list of String, then Fixnum
+This is an ordered list of String, then Fixnum:
 
     @param [Array<(String, Fixnum)>]
 
-This is a parameter that needs to implement certain methods
+This is a parameter that needs to implement certain methods:
 
     @param [#[], #to_s]
 
-This documents that a method may return any of the types listed
+This documents that a method may return any of the types listed:
 
     @return [String, self, nil]
 
-This is the return statement for a method only used for side effects
+This is the return statement for a method only used for side effects:
 
     @return [void]
 
@@ -136,11 +160,11 @@ List possible classes that the method may raise:
 
     @raise [Beaker::PendingTest]
 
-List parameter names yielded by a method
+List parameter names yielded by a method:
 
     @yield [result, self]
 
-And specify what kind of object is yielded with this
+And specify what kind of object is yielded:
 
     @yieldparam [Result] result
 
@@ -149,19 +173,19 @@ An `example` block contains a tag, description and then indented code:
     @example Accessing Host defaults using hash syntax
         host[‘platform’]  #=> ‘debian-6-amd64’
 
-The `api` tag can have anything behind it, please use the following
-when documenting harness methods:
+The `api` tag can have anything behind it, please use the following when documenting harness methods:
 
     @api dsl        Part of the testing dsl used within tests
     @api public     Methods third party integrations can rely on
     @api private    Methods private to the harness, not to be used externally
 
-When deprecating a method include information on newer alternatives
+When deprecating a method include information on newer alternatives:
 
     @deprecated This method is horrible. Please use {#foo} or {#bar}.
 
-When you want to reference other information use
+When you want to reference other information use:
 
     @see ClassOrModule
+    @see #other_method
     @see http://web.url.com/reference Title for the link
 

data/README.md

@@ -1,14 +1,8 @@
 # Beaker
 
-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 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.
+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.
 
 # Installation
 
@@ -21,24 +15,14 @@ Documentation for Beaker can be found in this repository in
 
 ## Table of Contents
 
-- [Tutorials](docs/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](docs/concepts) discuss key topics and concepts at a fairly high
-level and provide useful background information and explanation.
-- [Rubydocs](http://rubydoc.info/github/puppetlabs/beaker/frames) 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](docs/how_to) 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.
+- [Tutorials](docs/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](docs/concepts) discuss key topics and concepts at a fairly high level and provide useful background information and explanation.
+- [Rubydocs](http://rubydoc.info/github/puppetlabs/beaker/frames) 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](docs/how_to) 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](docs/concepts/beaker_libraries.md) for available
-gems. See the
-[beaker-template documentation](https://github.com/puppetlabs/beaker-template/blob/master/README.md)
-for documentation on creating beaker-libraries.
+Beaker functionality has been extended through the use of libraries available as gems. See the [complete list](docs/concepts/beaker_libraries.md) for available gems. See the [beaker-template documentation](https://github.com/puppetlabs/beaker-template/blob/master/README.md) for documentation on creating beaker-libraries.
 
 # License
 
@@ -46,15 +30,14 @@ See [LICENSE](LICENSE) file.
 
 # Support & Issues
 
-Please log tickets and issues at our
-[Beaker Issue Tracker](https://tickets.puppetlabs.com/issues/?jql=project%20%3D%20BKR).
-In addition there is an active #puppet-dev channel on Freenode.
+Please log tickets and issues at our [Beaker Issue Tracker](https://tickets.puppetlabs.com/issues/?jql=project%20%3D%20BKR). In addition there is an active #puppet-dev channel on Freenode.
 
-For additional information on filing tickets, please check out our
-[CONTRIBUTOR doc](CONTRIBUTING.md), and for ticket lifecycle information,
-checkout our [ticket process doc](docs/concepts/ticket_process.md).
+For additional information on filing tickets, please check out our [CONTRIBUTOR doc](CONTRIBUTING.md), and for ticket lifecycle information, check out our [ticket process doc](docs/concepts/ticket_process.md).
+
+# Contributing
+
+If you'd like to contribute improvements to Beaker, please see [CONTRIBUTING](CONTRIBUTING.md).
 
 # Maintainers
 
-For information on project maintainers, please check out our
-[MAINTAINERS doc](MAINTAINERS.md).
+For information on project maintainers, please check out our [MAINTAINERS doc](MAINTAINERS.md).