beaker 3.35.0 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. checksums.yaml +4 -4
  2. data/.gitignore +32 -9
  3. data/CHANGELOG.md +56 -1
  4. data/CONTRIBUTING.md +82 -32
  5. data/DOCUMENTING.md +68 -44
  6. data/README.md +14 -31
  7. data/acceptance/lib/helpers/test_helper.rb +0 -28
  8. data/acceptance/pre_suite/subcommands/08_install_beaker.rb +1 -1
  9. data/acceptance/tests/base/dsl/helpers/host_helpers/backup_the_file_test.rb +9 -9
  10. data/acceptance/tests/base/dsl/helpers/host_helpers/create_remote_file_test.rb +106 -103
  11. data/acceptance/tests/base/dsl/helpers/host_helpers/curl_on_test.rb +5 -5
  12. data/acceptance/tests/base/dsl/helpers/host_helpers/install_package_test.rb +1 -50
  13. data/acceptance/tests/base/dsl/helpers/host_helpers/retry_on_test.rb +3 -3
  14. data/acceptance/tests/base/dsl/helpers/host_helpers/rsync_to_test.rb +71 -27
  15. data/acceptance/tests/base/dsl/helpers/host_helpers/scp_from_test.rb +3 -3
  16. data/acceptance/tests/base/dsl/helpers/host_helpers/scp_to_test.rb +3 -3
  17. data/acceptance/tests/base/host/file_test.rb +81 -0
  18. data/beaker.gemspec +7 -15
  19. data/docs/README.md +5 -12
  20. data/docs/concepts/beaker_libraries.md +2 -2
  21. data/docs/concepts/glossary.md +11 -0
  22. data/docs/concepts/style_guide.md +24 -91
  23. data/docs/concepts/test_tagging.md +3 -10
  24. data/docs/concepts/testing_beaker_itself.md +3 -2
  25. data/docs/concepts/ticket_process.md +17 -45
  26. data/docs/how_to/archive_sut_files.md +7 -33
  27. data/docs/how_to/change_terminal_output_coloring.md +7 -4
  28. data/docs/how_to/confine.md +5 -16
  29. data/docs/how_to/debug_beaker_tests.md +14 -6
  30. data/docs/how_to/hosts/README.md +2 -5
  31. data/docs/how_to/hosts/archlinux.md +4 -2
  32. data/docs/how_to/hosts/cisco.md +9 -30
  33. data/docs/how_to/hosts/eos.md +5 -14
  34. data/docs/how_to/hypervisors/README.md +18 -36
  35. data/docs/how_to/install_puppet.md +18 -51
  36. data/docs/how_to/platform_specific_tag_confines.md +11 -31
  37. data/docs/how_to/preserve_hosts.md +13 -54
  38. data/docs/how_to/rake_tasks.md +1 -4
  39. data/docs/how_to/recipes.md +9 -2
  40. data/docs/how_to/run_in_parallel.md +10 -10
  41. data/docs/how_to/ssh_agent_forwarding.md +8 -13
  42. data/docs/how_to/ssh_connection_preference.md +10 -10
  43. data/docs/how_to/test_arbitrary_beaker_versions.md +5 -12
  44. data/docs/how_to/the_beaker_dsl.md +207 -184
  45. data/docs/how_to/upgrade_from_2_to_3.md +13 -53
  46. data/docs/how_to/upgrade_from_3_to_4.md +52 -0
  47. data/docs/how_to/use_hocon_helpers.md +10 -28
  48. data/docs/how_to/use_user_password_authentication.md +13 -10
  49. data/docs/how_to/write_a_beaker_test_for_a_module.md +6 -2
  50. data/docs/tutorials/README.md +14 -55
  51. data/docs/tutorials/creating_a_test_environment.md +47 -52
  52. data/docs/tutorials/installation.md +57 -21
  53. data/docs/tutorials/lets_write_a_test.md +8 -1
  54. data/docs/tutorials/quick_start_rake_tasks.md +63 -62
  55. data/docs/tutorials/subcommands.md +19 -32
  56. data/docs/tutorials/test_run.md +14 -16
  57. data/docs/tutorials/test_suites.md +14 -43
  58. data/docs/tutorials/the_command_line.md +14 -2
  59. data/lib/beaker/cli.rb +11 -24
  60. data/lib/beaker/dsl/helpers/host_helpers.rb +10 -34
  61. data/lib/beaker/dsl/helpers.rb +4 -6
  62. data/lib/beaker/dsl/install_utils.rb +0 -5
  63. data/lib/beaker/dsl/roles.rb +1 -1
  64. data/lib/beaker/dsl.rb +7 -0
  65. data/lib/beaker/host/aix/file.rb +2 -2
  66. data/lib/beaker/host/aix/group.rb +1 -0
  67. data/lib/beaker/host/aix/user.rb +1 -0
  68. data/lib/beaker/host/freebsd/pkg.rb +9 -0
  69. data/lib/beaker/host/mac/group.rb +1 -0
  70. data/lib/beaker/host/mac/user.rb +8 -13
  71. data/lib/beaker/host/pswindows/file.rb +2 -2
  72. data/lib/beaker/host/pswindows/group.rb +1 -0
  73. data/lib/beaker/host/pswindows/user.rb +1 -0
  74. data/lib/beaker/host/unix/exec.rb +5 -5
  75. data/lib/beaker/host/unix/file.rb +43 -2
  76. data/lib/beaker/host/unix/group.rb +1 -0
  77. data/lib/beaker/host/unix/pkg.rb +9 -2
  78. data/lib/beaker/host/unix/user.rb +1 -0
  79. data/lib/beaker/host/windows/file.rb +32 -2
  80. data/lib/beaker/host/windows/group.rb +1 -0
  81. data/lib/beaker/host/windows/user.rb +1 -0
  82. data/lib/beaker/host.rb +12 -11
  83. data/lib/beaker/host_prebuilt_steps.rb +1 -5
  84. data/lib/beaker/hypervisor.rb +1 -5
  85. data/lib/beaker/logger.rb +1 -1
  86. data/lib/beaker/result.rb +4 -0
  87. data/lib/beaker/shared/fog_credentials.rb +61 -0
  88. data/lib/beaker/shared/host_manager.rb +6 -3
  89. data/lib/beaker/shared.rb +2 -1
  90. data/lib/beaker/subcommand.rb +5 -3
  91. data/lib/beaker/version.rb +1 -1
  92. data/lib/beaker.rb +0 -10
  93. data/spec/beaker/cli_spec.rb +21 -0
  94. data/spec/beaker/dsl/helpers/host_helpers_spec.rb +14 -51
  95. data/spec/beaker/dsl/wrappers_spec.rb +0 -46
  96. data/spec/beaker/host/mac/user_spec.rb +5 -8
  97. data/spec/beaker/host/unix/exec_spec.rb +1 -1
  98. data/spec/beaker/host/unix/file_spec.rb +39 -0
  99. data/spec/beaker/host/unix/pkg_spec.rb +66 -17
  100. data/spec/beaker/host/unix_spec.rb +4 -4
  101. data/spec/beaker/host/windows/file_spec.rb +55 -0
  102. data/spec/beaker/host_prebuilt_steps_spec.rb +26 -73
  103. data/spec/beaker/host_spec.rb +10 -14
  104. data/spec/beaker/hypervisor/hypervisor_spec.rb +3 -3
  105. data/spec/beaker/logger_spec.rb +4 -0
  106. data/spec/beaker/shared/fog_credentials_spec.rb +100 -0
  107. data/spec/beaker/shared/host_manager_spec.rb +8 -0
  108. data/spec/beaker/subcommand_spec.rb +1 -0
  109. metadata +56 -165
  110. data/acceptance/lib/beaker/acceptance/install_utils.rb +0 -58
  111. data/acceptance/tests/base/dsl/helpers/host_helpers/create_tmpdir_on_test.rb +0 -68
  112. data/acceptance/tests/base/dsl/install_utils/clone_git_repo_on_test.rb +0 -49
  113. data/lib/beaker/dsl/helpers/facter_helpers.rb +0 -57
  114. data/lib/beaker/dsl/install_utils/pe_defaults.rb +0 -143
  115. data/lib/beaker/dsl/install_utils/windows_utils.rb +0 -223
  116. data/spec/beaker/dsl/ezbake_utils_spec.rb +0 -279
  117. data/spec/beaker/dsl/install_utils/pe_defaults_spec.rb +0 -61
  118. data/spec/beaker/dsl/install_utils/windows_utils_spec.rb +0 -263
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 7f5dbb3dbc5bdfbfb8b3faf9309c674fa6e07cf3
4
- data.tar.gz: 35dcba5f1881fcb33c682151f9f06dab083fbe21
3
+ metadata.gz: 7d46e3ea54f2a217a78497681c57a24921de8719
4
+ data.tar.gz: 175ef59e2be00d70d0238f49e8f3d49e95257e2f
5
5
  SHA512:
6
- metadata.gz: 9b64080cc40e949ca9359e27f9c3bbcd97a5d2af745f26dcb86f3807655231afd5a4e99ccebd4e33e8c4dcf308fecb25ba4ce1614859ffdff50ce1da9c8d055a
7
- data.tar.gz: ac37b874e60d5b8aea0c8b4b63eb98ec2c612d78d7fbd86a37f41f2f4863d58db08c90b436bbae2165832801f5d9ceb337826d1b4779f730c0e0d5975026ce37
6
+ metadata.gz: abc5a220b83dd595577f90140ce3b60b1daf282d77e27279f110732cc643e20d46652046be5bec9beb55aa51dec38b82928c15814a34ce78efa8460335654295
7
+ data.tar.gz: ce529642242f5408f0ea4a8bc515f00f496c977854737f21f4787a04769ef02d003d1694bd818b9ae2478af5382329e4f0019f433a09bb2983b2fb4f0acfdbe8
data/.gitignore CHANGED
@@ -1,20 +1,46 @@
1
- *.swp
2
- log/*
3
1
  !.gitignore
2
+
3
+ # Gem structure
4
4
  junit
5
5
  acceptance-tests
6
6
  pkg
7
7
  Gemfile.lock
8
- options.rb
8
+
9
+ # Beaker-generated & local testing
9
10
  test.cfg
11
+ options.rb
12
+ merged_options.rb
13
+ tmp/
14
+ log/
15
+ sut-files.tgz
16
+
17
+ # YARD
10
18
  .yardoc
11
19
  yard_docs
12
- coverage
20
+ doc
21
+
22
+ # Dependencies
23
+ # NOTE: For consistency, please use `vendor/bundle` for Bundler-installed dependencies
13
24
  .bundle
14
25
  .vendor
15
26
  _vendor
16
- tmp/
17
- doc
27
+ vendor
28
+
29
+ # Byebug
30
+ .byebugrc
31
+ .byebug_history
32
+
33
+ # SimpleCov
34
+ coverage
35
+
36
+
37
+ #
38
+ # Editor/IDE Clutter
39
+ #
40
+ # (TODO: consider removing these; use local personal .gitignore instead)
41
+
42
+ # Vim
43
+ *.swp
18
44
  # JetBrains IDEA
19
45
  *.iml
20
46
  .idea/
@@ -24,6 +50,3 @@ doc
24
50
  # Vagrant folder
25
51
  .vagrant/
26
52
  .vagrant_files/
27
- # Byebug
28
- .byebugrc
29
- .byebug_history
data/CHANGELOG.md CHANGED
@@ -11,7 +11,62 @@ Tracking in this Changelog began for this project in version 3.25.0.
11
11
  If you're looking for changes from before this, refer to the project's
12
12
  git logs & PR history.
13
13
 
14
- # [Unreleased](https://github.com/puppetlabs/beaker/compare/3.35.0...master)
14
+ # [Unreleased](https://github.com/puppetlabs/beaker/compare/4.0.0...master)
15
+
16
+ # [4.0.0](https://github.com/puppetlabs/beaker/compare/3.37.0...4.0.0) - 2018-08-06
17
+
18
+ ### Fixed
19
+
20
+ - `host.rsync_to` throws `Beaker::Host::CommandFailure` if rsync call fails (BKR-463)
21
+ - `host.rsync_to` throws `Beaker::Host::CommandFailure` if rsync does not exist on remote system (BKR-462)
22
+ - `host.rsync_to` now check through configured SSH keys to use the first valid one
23
+ - Updated some `Beaker::Host` methods to always return a `Result` object
24
+
25
+ ### Added
26
+
27
+ - Adds `Beaker::Host#chown`, `#chgrp`, and `#ls_ld` methods (BKR-1499)
28
+ - `#uninstall_package` host helper, to match `#install_package`
29
+ - `Host.uninstall_package` for FreeBSD
30
+ - Now easily check a command's exit status by calling `Result.success?()` for a simple, truthy result. No need to validate the exit code manually.
31
+
32
+ ### Changed
33
+
34
+ - `#set_env` no longer calls `#configure_type_defaults_on`
35
+ - `beaker-puppet` DSL Extension Library has been formally split into a standard DSL Extension Library and removed as a dependency from Beaker. Please see our [upgrade guidelines](docs/how_to/upgrade_from_3_to_4.md).
36
+ - Beaker's Hypervisor Libraries have been removed as dependencies. Please see our [upgrade guidelines](docs/how_to/upgrade_from_3_to_4.md).
37
+
38
+ ### Removed
39
+
40
+ - `PEDefaults` has been moved to `beaker-pe`
41
+
42
+ # [3.37.0](https://github.com/puppetlabs/beaker/compare/3.36.0...3.37.0) - 2018-07-11
43
+
44
+ ### Fixed
45
+
46
+ - Exit early on --help/--version/--parse-only arguments instead of partial dry-run
47
+
48
+ ### Added
49
+
50
+ - `Beaker::Shared::FogCredentials.get_fog_credentials()` to parse .fog credential files
51
+
52
+ ### Changed
53
+
54
+ - `beaker-pe` is no longer automagically included. See [the upgrade guide](/docs/how_to/upgrade_from_3_to_4.md}) for more info
55
+ - `beaker-puppet` is no longer required as a dependency
56
+
57
+ # [3.36.0](https://github.com/puppetlabs/beaker/compare/3.35.0...3.36.0) - 2018-06-18
58
+
59
+ ### Fixed
60
+
61
+ - Raise `ArgumentError` when passing `role = nil` to `only_host_with_role()` or `find_at_most_one_host_with_role()`
62
+ - Use `install_package_with_rpm` in `add_el_extras`
63
+
64
+ ### Added
65
+
66
+ - Installation instructions for contributors
67
+ - Markdown formatting guidelines for `docs/`
68
+ - Glossary for project jargon in [`docs/concepts/glossary.md`](docs/concepts/glossary.md)
69
+ - Use AIX 6.1 packages everywhere for puppet6
15
70
 
16
71
  # [3.35.0](https://github.com/puppetlabs/beaker/compare/3.34.0...3.35.0) - 2018-05-16
17
72
 
data/CONTRIBUTING.md CHANGED
@@ -1,41 +1,86 @@
1
1
  # How To Contribute To Beaker
2
2
 
3
+ 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.
4
+
3
5
  ## Getting Started
4
6
 
5
- * Create a [Jira account](http://tickets.puppetlabs.com)
6
- * Make sure you have a [GitHub account](https://github.com/signup/free)
7
- * Submit a ticket for your issue, assuming one does not already exist.
7
+ 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
8
+
9
+ * Create a [Jira account](http://tickets.puppetlabs.com).
10
+ * Make sure you have a [GitHub account](https://github.com/signup/free).
11
+ * Submit a ticket for your issue on Jira, assuming one does not already exist.
8
12
  * Clearly describe the issue including steps to reproduce when it is a bug.
9
- * File a ticket in the [BKR project](https://tickets.puppetlabs.com/issues/?jql=project%20%3D%20BKR)
10
- * Fork the [Beaker repository on GitHub](https://github.com/puppetlabs/beaker)
13
+ * File the ticket in the [BKR project](https://tickets.puppetlabs.com/issues/?jql=project%20%3D%20BKR).
14
+ * Fork the [Beaker repository on GitHub](https://github.com/puppetlabs/beaker).
15
+ * [Get Beaker set up for development](docs/tutorials/installation.md#for-development).
11
16
 
12
17
  ## Making Changes
13
18
 
14
- * Create a topic branch from your fork of [puppetlabs/beaker](https://github.com/puppetlabs/beaker).
15
- * Please title the branch after the beaker ticket you intend to address, ie `BKR-1234`.
16
- * Make commits of logical units.
17
- * Check for unnecessary whitespace with `git diff --check` before committing.
18
- * Make sure your commit messages are in the proper format.
19
+ Contributions are accepted in the form of pull requests against the master branch on GitHub.
19
20
 
20
- ````
21
+ * Create a topic branch on your fork of [puppetlabs/beaker](https://github.com/puppetlabs/beaker) based on `master`.
22
+ * Make commits of logical units. If your commits are a mess, you will be asked to [rebase or at least squash](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) your PR.
23
+ * Check for unnecessary whitespace with `git diff --check` before committing.
24
+ * Make sure your commit messages are in the proper format:
25
+ ```
21
26
  (BKR-1234) Make the example in CONTRIBUTING imperative and concrete
22
27
 
23
- Without this patch applied the example commit message in the CONTRIBUTING
24
- document is not a concrete example. This is a problem because the
25
- contributor is left to imagine what the commit message should look like
26
- based on a description rather than an example. This patch fixes the
27
- problem by making the example concrete and imperative.
28
-
29
- The first line is a real life imperative statement with a ticket number
30
- from our issue tracker. The body describes the behavior without the patch,
31
- why this is a problem, and how the patch fixes the problem when applied.
32
- ````
33
-
34
- * 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.
28
+ 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.
29
+
30
+ 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.
31
+ ```
32
+ * 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.
33
+ * When you're ready for review, create a new pull request.
34
+
35
+ #### PR Requirements
36
+
37
+ Pull Requests are subject to the following requirements:
38
+
39
+ * Commits must be logical units. Follow these [basic guidelines](https://github.com/trein/dev-best-practices/wiki/Git-Commit-Best-Practices#basic-rules), and don't be afraid to make too many commits: it's always easier to squash than to fixup.
40
+ * Must not contain changes unrelated to the ticket being worked on. Issues you encounter as directly related to the main work for a ticket are fiar game. Many beaker components only get infrequent updates so it is not uncommon to encounter dependency version changes that cause problems. These can be addressed with a `(MAINT)` commit within the feature PR you're working on. Larger or only peripherally related changes should go through their own ticket, which you can create; tickets with attached PRs are generally accepted.
41
+ * Must merge cleanly. Only fast-forward merges are accepted, so make sure the PR shows as a clean merge.
42
+ * On that note, merge commits are not accepted. In order to keep your feature branch up-to-date and ensure a clean merge, you should [rebase](http://git-scm.com/book/en/Git-Branching-Rebasing) on top of beaker's master. You can also use this opportunity to keep your fork up to date. That workflow looks like this:
43
+ ~~~console
44
+ you@local:beaker $ git checkout master
45
+ Switched to branch 'master'
46
+ Your branch is up to date with 'origin/master'.
47
+ you@local:beaker $ git fetch upstream
48
+ you@local:beaker $ git merge upstream/master
49
+ Updating a01b5732..a565e1ac
50
+ Fast-forward
51
+ lib/beaker/logger.rb | 2 +-
52
+ spec/beaker/logger_spec.rb | 4 ++++
53
+ 2 files changed, 5 insertions(+), 1 deletion(-)
54
+ you@local:beaker $ git push
55
+ Total 0 (delta 0), reused 0 (delta 0)
56
+ To https://github.com/Dakta/beaker.git
57
+ a01b5732..a565e1ac master -> master
58
+ you@local:beaker $ git checkout BKR-816
59
+ Switched to branch 'BKR-816'
60
+ you@local:beaker $ git rebase master
61
+ # if you have conflicts, they'll appear here. Manually fix the listed files then use `git rebase --continue`. Repeat as necessary for each conflicting commit.
62
+ First, rewinding head to replay your work on top of it...
63
+ Fast-forwarded BKR-816 to master.
64
+ you@local:beaker $ git push --set-upstream origin BKR-816
65
+ Counting objects: 9, done.
66
+ Delta compression using up to 8 threads.
67
+ Compressing objects: 100% (9/9), done.
68
+ Writing objects: 100% (9/9), 2.05 KiB | 2.05 MiB/s, done.
69
+ Total 9 (delta 6), reused 0 (delta 0)
70
+ remote: Resolving deltas: 100% (6/6), completed with 6 local objects.
71
+ To https://github.com/Dakta/beaker.git
72
+ + [new branch] BKR-816 -> BKR-816
73
+ Branch 'BKR-816' set up to track remote branch 'BKR-816' from 'origin'.
74
+ ~~~
75
+
76
+ #### Courtesy
77
+
78
+ 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).
35
79
 
36
80
  ### Testing
37
81
 
38
- * 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.
82
+ 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.
83
+
39
84
  * 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.
40
85
  * 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/).
41
86
  * Run the tests to assure nothing else was accidentally broken, using `rake test`
@@ -44,20 +89,23 @@
44
89
  ### Documentation
45
90
 
46
91
  * Add an entry in the [CHANGELOG.md](CHANGELOG.md). Refer to the CHANGELOG itself for message style/form details.
47
- * Make sure that you have added documentation using [Yard](http://yardoc.org/) as necessary for any new code introduced.
92
+ * Make sure that you have added documentation using [YARD](http://yardoc.org/) as necessary for any new code introduced. See [DOCUMENTING](DOCUMENTING.md).
48
93
  * More user friendly documentation will be required for PRs unless exempted. Documentation lives in the [docs/ folder](docs).
49
94
 
50
- ## Making Trivial Changes
95
+ ## Making Changes Without a Ticket
96
+
97
+ The following kinds of changes are made without a corresponding Jira ticket.
51
98
 
52
99
  ### Maintenance
53
100
 
54
- 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.
101
+ 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.
55
102
 
56
103
  ````
57
- (MAINT) Fix whitespace
104
+ (MAINT) Fix whitespace
58
105
 
59
106
  - remove additional spaces that appear at EOL
60
107
  ````
108
+
61
109
  ### Version Bump For Gem Release
62
110
 
63
111
  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 +113,7 @@ To prepare for a new gem release of Beaker the `version.rb` file is updated with
65
113
  ````
66
114
  (GEM) Update version for Beaker 1.16.1
67
115
  ````
116
+
68
117
  ### History File Update
69
118
 
70
119
  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 +121,18 @@ To prepare for a new gem release of Beaker (after the version has been bumped) t
72
121
  ````
73
122
  (HISTORY) Update history for release of Beaker 1.16.1
74
123
  ````
124
+
75
125
  ## Submitting Changes
76
126
 
77
127
  * Push your changes to a topic branch in your fork of the repository.
78
128
  * Submit a pull request to [Beaker](https://github.com/puppetlabs/beaker)
79
- * Update your ticket
80
- * 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).
81
- * Include a link to the pull request in the ticket.
82
- * PRs are reviewed as time permits.
129
+ * 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).
130
+
131
+ PRs are reviewed as time permits.
83
132
 
84
133
  # Additional Resources
85
134
 
135
+ * [Beaker Glossary](docs/concepts/glossary.md)
86
136
  * [Puppet community guidelines](https://docs.puppet.com/community/community_guidelines.html)
87
137
  * [Bug tracker (Jira)](http://tickets.puppetlabs.com)
88
138
  * [BKR Jira Project](https://tickets.puppetlabs.com/issues/?jql=project%20%3D%20BKR)
data/DOCUMENTING.md CHANGED
@@ -1,15 +1,49 @@
1
1
 
2
- ## Contributing Documentation to Puppetlabs Test Harness ##
2
+ # Contributing Documentation to Beaker
3
3
 
4
+ ## Documents
4
5
 
5
- All inline documentation uses YARD, below is an example usage, a quick
6
- summary of documentation expectations and finally a short reference
7
- for those new to YARD.
6
+ 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.
8
7
 
9
- They say a picture is worth a thousand words, hopefully this example will
10
- be worth more than the 154 it’s composed of:
11
- ```ruby
8
+ ## Style
9
+
10
+ User-friendly Documentation (tutorials, how-tos, etc.) uses [GitHub Flavored Markdown](https://guides.github.com/features/mastering-markdown/). We adopt the following conventions.
11
+
12
+ ### Text
13
+
14
+ - 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.
15
+
16
+ ### Lists
17
+
18
+ - Use `-` lists to avoid confusion with `*emphasis*`.
19
+ - Be sure to indent code blocks within list items.
20
+
21
+ ### Headers
22
+
23
+ - Use Markdown Headers.
24
+ - Always place a blank line before and after headers.
25
+
26
+ ### Code
27
+
28
+ - Use inline code for snippets (paths, file names, variables, partial commands, etc.)
29
+ - Use fenced blocks for code of one full line or greater
30
+ - Offset fenced blocks with whitespace before and after, except in list items.
31
+ - Mark the language of code blocks:
32
+ ~~~
33
+ ```console
34
+ $ beaker --help
35
+ ```
36
+ ~~~
37
+ 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.
38
+ - It's nice to provide a shebang (`$`) in console examples to distinguish input from output.
39
+
40
+ ## Inline
12
41
 
42
+ 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.
43
+
44
+ They say a picture is worth a thousand words, hopefully this example will be worth more than the 154 it’s composed of:
45
+
46
+ ```ruby
13
47
  #
14
48
  # @param [Array<Host>, Host, #execute] hosts The host(s) to act on
15
49
  # @param [String] action The action to perform
@@ -44,15 +78,11 @@ be worth more than the 154 it’s composed of:
44
78
  yield result if block_given?
45
79
  end
46
80
  end
47
-
48
81
  ```
49
82
 
83
+ ## Documentation Guide
50
84
 
51
- ## Documentation Guide: ##
52
-
53
-
54
- Most of our documentation is done with the @tag syntax. With a few
55
- execptions tags follow this format:
85
+ Most of our documentation is done with the @tag syntax. With a few execptions tags follow this format:
56
86
 
57
87
  @tag [TypeOfValueInBrackets] nameOfValue Multi-word description that
58
88
  can span multiple lines, as long as lines after the first have
@@ -60,71 +90,65 @@ execptions tags follow this format:
60
90
 
61
91
  Note: The `tag` name and the `nameOfValue` in question cannot contain spaces.
62
92
 
63
- All sections should be considered mandatory, but in practice a committer
64
- can walk a contributor through the process and help ensure a high quality
65
- of documentation. When contributing keep especially in mind that an
93
+ 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
66
94
  `@example` block will go a long way in helping understand the use case
67
- (which also encourages use by others) and the @api tag helps to understand
68
- the scope of a Pull Request.
95
+ (which also encourages use by others) and the @api tag helps to understand the scope of a Pull Request.
69
96
 
70
- Please be liberal with whitespace (not trailing whitespace) and vertical
71
- alignment as it helps readability while “in code”. Default indentation
72
- is two spaces unless there are readability/vertical alignment concerns.
97
+ 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.
73
98
 
74
- While the `@params`, `@returns`, etc... may seem redundant they encourage
75
- thinking through exactly what you are doing and because of their strict
76
- format they allow a level of tooling not available in regular ruby.
99
+ 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.
77
100
 
78
101
  You are encouraged to run the YARD documentation server locally by:
79
102
 
80
- rake docs
103
+ ```console
104
+ $ rake docs
105
+ ```
81
106
 
82
107
  or
83
108
 
84
- rake docs:bg
109
+ ```console
110
+ $ rake docs:bg
111
+ ```
85
112
 
86
113
  depending on whether you want the server to run in the foreground or not
87
114
 
88
- Wait for the documentation to compile and then point your browser to:
89
-
90
- http://localhost:8808
91
-
115
+ Wait for the documentation to compile and then point your browser to [http://localhost:8808](http://localhost:8808).
92
116
 
93
- ## A Simple YARD Reference: ##
94
117
 
118
+ ## A Simple YARD Reference
95
119
 
96
120
  A Hash that must be in `{:symbol => ‘string’}` format:
97
121
 
98
122
  @param [Hash<Symbol, String>] my_hash
99
123
 
100
- This is also valid, and maybe more obvious to those used to Ruby
124
+ This is also valid, and maybe more obvious to those used to Ruby:
101
125
 
102
126
  @param [Hash{Symbol=>String}]
103
127
 
104
- When specifying an options hash you use @option to specify key/values
128
+ When specifying an options hash you use `@option` to specify keys/values:
105
129
 
106
130
  @param [Hash{Symbol=>String}] my_opts An options hash
107
131
  @option my_opts [ClassOfValue] :key_in_question A Description
108
132
  @option my_opts [Fixnum] :log_level The log level to run in.
109
133
  @option my_opts [Boolean] :turbo (true) Who doesn’t want turbos?
110
134
 
111
- This parameter takes an unordered list of Strings, Fixnums, and Floats
135
+ This parameter takes an unordered list of Strings, Fixnums, and Floats:
112
136
 
113
137
  @param [Array<String, Fixnum, Float>]
114
138
 
115
- This is an ordered list of String, then Fixnum
139
+ This is an ordered list of String, then Fixnum:
116
140
 
117
141
  @param [Array<(String, Fixnum)>]
118
142
 
119
- This is a parameter that needs to implement certain methods
143
+ This is a parameter that needs to implement certain methods:
120
144
 
121
145
  @param [#[], #to_s]
122
146
 
123
- This documents that a method may return any of the types listed
147
+ This documents that a method may return any of the types listed:
124
148
 
125
149
  @return [String, self, nil]
126
150
 
127
- This is the return statement for a method only used for side effects
151
+ This is the return statement for a method only used for side effects:
128
152
 
129
153
  @return [void]
130
154
 
@@ -136,11 +160,11 @@ List possible classes that the method may raise:
136
160
 
137
161
  @raise [Beaker::PendingTest]
138
162
 
139
- List parameter names yielded by a method
163
+ List parameter names yielded by a method:
140
164
 
141
165
  @yield [result, self]
142
166
 
143
- And specify what kind of object is yielded with this
167
+ And specify what kind of object is yielded:
144
168
 
145
169
  @yieldparam [Result] result
146
170
 
@@ -149,19 +173,19 @@ An `example` block contains a tag, description and then indented code:
149
173
  @example Accessing Host defaults using hash syntax
150
174
  host[‘platform’] #=> ‘debian-6-amd64’
151
175
 
152
- The `api` tag can have anything behind it, please use the following
153
- when documenting harness methods:
176
+ The `api` tag can have anything behind it, please use the following when documenting harness methods:
154
177
 
155
178
  @api dsl Part of the testing dsl used within tests
156
179
  @api public Methods third party integrations can rely on
157
180
  @api private Methods private to the harness, not to be used externally
158
181
 
159
- When deprecating a method include information on newer alternatives
182
+ When deprecating a method include information on newer alternatives:
160
183
 
161
184
  @deprecated This method is horrible. Please use {#foo} or {#bar}.
162
185
 
163
- When you want to reference other information use
186
+ When you want to reference other information use:
164
187
 
165
188
  @see ClassOrModule
189
+ @see #other_method
166
190
  @see http://web.url.com/reference Title for the link
167
191
 
data/README.md CHANGED
@@ -1,14 +1,8 @@
1
1
  # Beaker
2
2
 
3
- Beaker is a test harness focused on acceptance testing via interactions
4
- between multiple (virtual) machines. It provides platform abstraction between
5
- different Systems Under Test (SUTs), and it can also be used as a virtual machine
6
- provisioner - setting up machines, running any commands on those machines,
7
- and then exiting.
3
+ 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.
8
4
 
9
- Beaker runs tests written in Ruby, and provides additional Domain-Specific
10
- Language (DSL) methods. This gives you access to all standard Ruby along with
11
- acceptance testing specific commands.
5
+ 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.
12
6
 
13
7
  # Installation
14
8
 
@@ -21,24 +15,14 @@ Documentation for Beaker can be found in this repository in
21
15
 
22
16
  ## Table of Contents
23
17
 
24
- - [Tutorials](docs/tutorials) take you by the hand through the steps to setup a
25
- beaker run. Start here if you’re new to Beaker or test development.
26
- - [Concepts](docs/concepts) discuss key topics and concepts at a fairly high
27
- level and provide useful background information and explanation.
28
- - [Rubydocs](http://rubydoc.info/github/puppetlabs/beaker/frames) contains the
29
- technical reference for APIs and other aspects of Beaker. They describe how it
30
- works and how to use it but assume that you have a basic understanding of key concepts.
31
- - [How-to guides](docs/how_to) are recipes. They guide you through the steps
32
- involved in addressing key problems and use-cases. They are more advanced than
33
- tutorials and assume some knowledge of how Beaker works.
18
+ - [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.
19
+ - [Concepts](docs/concepts) discuss key topics and concepts at a fairly high level and provide useful background information and explanation.
20
+ - [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.
21
+ - [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.
34
22
 
35
23
  # Beaker Libraries
36
24
 
37
- Beaker functionality has been extended through the use of libraries available as
38
- gems. See the [complete list](docs/concepts/beaker_libraries.md) for available
39
- gems. See the
40
- [beaker-template documentation](https://github.com/puppetlabs/beaker-template/blob/master/README.md)
41
- for documentation on creating beaker-libraries.
25
+ 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.
42
26
 
43
27
  # License
44
28
 
@@ -46,15 +30,14 @@ See [LICENSE](LICENSE) file.
46
30
 
47
31
  # Support & Issues
48
32
 
49
- Please log tickets and issues at our
50
- [Beaker Issue Tracker](https://tickets.puppetlabs.com/issues/?jql=project%20%3D%20BKR).
51
- In addition there is an active #puppet-dev channel on Freenode.
33
+ 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.
52
34
 
53
- For additional information on filing tickets, please check out our
54
- [CONTRIBUTOR doc](CONTRIBUTING.md), and for ticket lifecycle information,
55
- checkout our [ticket process doc](docs/concepts/ticket_process.md).
35
+ 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).
36
+
37
+ # Contributing
38
+
39
+ If you'd like to contribute improvements to Beaker, please see [CONTRIBUTING](CONTRIBUTING.md).
56
40
 
57
41
  # Maintainers
58
42
 
59
- For information on project maintainers, please check out our
60
- [MAINTAINERS doc](MAINTAINERS.md).
43
+ For information on project maintainers, please check out our [MAINTAINERS doc](MAINTAINERS.md).
@@ -8,34 +8,6 @@ def test_scp_error_on_close?
8
8
  !!ENV["BEAKER_TEST_SCP_ERROR_ON_CLOSE"]
9
9
  end
10
10
 
11
- # NOTE: currently there is an issue with the tmpdir_on helper on cygwin and OS X
12
- # platforms: the `chown` command always fails with an error about not
13
- # recognizing the Administrator:Administrator user/group. Also, the call to
14
- # check user presence via `getent` also fails. Until this is fixed, we add this
15
- # shim that delegates to a non-`chown`/non-`getent`-executing version for the
16
- # purposes of our test setup.
17
- #
18
- # TODO: fix via: https://tickets.puppetlabs.com/browse/BKR-496
19
- def tmpdir_on(hosts, path_prefix = '', user=nil)
20
- first_host = Array(hosts).first
21
-
22
- return create_tmpdir_on(hosts, path_prefix, user) unless \
23
- first_host.is_cygwin? or first_host.platform =~ /osx/
24
-
25
- block_on hosts do | host |
26
- # use default user logged into this host
27
- if not user
28
- user = host['user']
29
- end
30
-
31
- if defined? host.tmpdir
32
- host.tmpdir(path_prefix)
33
- else
34
- raise "Host platform not supported by `tmpdir_on`."
35
- end
36
- end
37
- end
38
-
39
11
  # Returns the absolute path where file fixtures are located.
40
12
  def fixture_path
41
13
  @fixture_path ||=
@@ -17,6 +17,6 @@ test_name 'Install beaker and checkout branch if necessary' do
17
17
  step 'Build the gem and install it on the local system' do
18
18
  build_output = on(default, 'cd /opt/beaker/;gem build beaker.gemspec').stdout
19
19
  version = build_output.match(/^ File: (.+)$/)[1]
20
- on(default, "cd /opt/beaker/;gem install #{version} --no-rdoc --no-ri")
20
+ on(default, "cd /opt/beaker/;gem install #{version} --no-rdoc --no-ri; gem install beaker-vmpooler")
21
21
  end
22
22
  end