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
@@ -2,10 +2,7 @@
2
2
 
3
3
  ## How does it work?
4
4
 
5
- The confine method will limit the hosts the testcase is run against. You can pass in either :to or :except
6
- to control how the criteria is applied (**:to** will apply the criteria to the hosts in order to find a match,
7
- **:except** will apply the criteria to the hosts, and return those hosts that do not match). The default behaviour
8
- is that the **TestCase#hosts** array is modified to only contain the hosts that match (or don't match) the criteria.
5
+ The confine method will limit the hosts the testcase is run against. You can pass in either :to or :except to control how the criteria is applied (**:to** will apply the criteria to the hosts in order to find a match, **:except** will apply the criteria to the hosts, and return those hosts that do not match). The default behaviour is that the **TestCase#hosts** array is modified to only contain the hosts that match (or don't match) the criteria.
9
6
 
10
7
  Full method documentation here:
11
8
 
@@ -13,10 +10,7 @@ Full method documentation here:
13
10
 
14
11
  ## How does the optional Array<Host> parameter work?
15
12
 
16
- However, if you pass in the optional Array<Host> to the method, the criteria will be applied to this hosts array
17
- (not **TestCase#hosts**). Subsequently, any of the hosts contained in **TestCase#hosts** that were not included in the Array<Host>
18
- passed to the method, will remain in **TestCase#hosts**. But any hosts that were filtered out by the criteria match
19
- will be overwritten.
13
+ However, if you pass in the optional Array<Host> to the method, the criteria will be applied to this hosts array (not **TestCase#hosts**). Subsequently, any of the hosts contained in **TestCase#hosts** that were not included in the Array<Host> passed to the method, will remain in **TestCase#hosts**. But any hosts that were filtered out by the criteria match will be overwritten.
20
14
 
21
15
  Take the following example:
22
16
 
@@ -52,20 +46,15 @@ Using the following confine:
52
46
 
53
47
  We will end up with a **TestCase#hosts** array with two hosts, one agent and one master.
54
48
 
55
- Since we passed in the 'agents' host array to the method, the criteria (:platform => 'el-7-x86_64') will be applied
56
- to this set of hosts. Only one agent matches this criteria (centos7_agent). Since the master host (ubuntu_master) was not
57
- included in the 'agents' host array when the criteria match was performed, it will remain in **TestCase#hosts**. But only one agent
58
- remains after the criteria match.
49
+ Since we passed in the 'agents' host array to the method, the criteria (:platform => 'el-7-x86_64') will be applied to this set of hosts. Only one agent matches this criteria (centos7_agent). Since the master host (ubuntu_master) was not included in the 'agents' host array when the criteria match was performed, it will remain in **TestCase#hosts**. But only one agent remains after the criteria match.
59
50
 
60
51
  `confine :except, { :platform => 'el-7-x86_64' }, agents`
61
52
 
62
- Will also return two hosts, one agent and one master. But it will be the other agent (ubuntu_agent) as its platform does not match
63
- 'el-7-x86_64'.
53
+ Will also return two hosts, one agent and one master. But it will be the other agent (ubuntu_agent) as its platform does not match 'el-7-x86_64'.
64
54
 
65
55
  `confine :to, { :platform => 'el-7-x86_64' }`
66
56
 
67
- Will return one host (centos7_agent). Because no Array<Host> was passed to the confine method, the criteria match
68
- is being applied directly to **TestCase#hosts** (which contains all hosts).
57
+ Will return one host (centos7_agent). Because no Array<Host> was passed to the confine method, the criteria match is being applied directly to **TestCase#hosts** (which contains all hosts).
69
58
 
70
59
  `confine :except, { :platform => 'el-7-x86_64' }`
71
60
 
@@ -7,6 +7,7 @@ beaker includes [pry-byebug](https://github.com/deivid-rodriguez/pry-byebug), a
7
7
  [Pry](http://pryrepl.org/) is a powerful Ruby editing and debugging tool. Beaker uses Pry runtime invocation to create a developer console.
8
8
 
9
9
  ### What is byebug?
10
+
10
11
  [Byebug](https://github.com/deivid-rodriguez/byebug) is a powerful debugger for ruby. It allows for flexible control of breakpoints, stepping through lines or the call stack. It lacks some features of pry such as source code editing and replaying code execution from within the debugging session, but can be used in combination with pry.
11
12
 
12
13
  There are several ways to have your tests break and enter debugging:
@@ -17,11 +18,12 @@ There are several ways to have your tests break and enter debugging:
17
18
 
18
19
  ## Add a breakpoint to your test file
19
20
 
20
- Add Pry to individual tests by adding `require 'pry'` to the Ruby test file.
21
- Then add the statement `binding.pry` at the point in code where you want access to the full, current Beaker environment.
21
+ Add Pry to individual tests by adding `require 'pry'` to the Ruby test file. Then add the statement `binding.pry` at the point in code where you want access to the full, current Beaker environment.
22
22
 
23
23
  ### Example
24
+
24
25
  #### Example test trypry.rb
26
+
25
27
  Here's a test file that exercises different ways of running commands on Beaker hosts. At the end of the main `hosts.each` loop I've included `binding.pry` to invoke the console.
26
28
 
27
29
  ```
@@ -49,6 +51,7 @@ end
49
51
  ```
50
52
 
51
53
  #### Sample output to the first `binding.pry` call:
54
+
52
55
  ```
53
56
  $ bundle exec beaker --tests tests/trypry.rb --hosts configs/fusion/winfusion.cfg --no-provision
54
57
  {
@@ -128,7 +131,9 @@ From: /Users/anode/beaker/tests/trypry.rb @ line 19 self.run_test:
128
131
 
129
132
  [1] pry(#<Beaker::TestCase>)>
130
133
  ```
134
+
131
135
  #### Using the console
136
+
132
137
  At this point I have access to the console. I have full access to Beaker hosts, the Beaker DSL and Ruby.
133
138
 
134
139
  Here's some sample console calls:
@@ -216,8 +221,11 @@ w2k8r2 executed in 0.08 seconds
216
221
  [5] pry(#<Beaker::TestCase>)> result.stdout.chomp
217
222
  => "Application Data\nDesktop\nDocuments\nFavorites\nMicrosoft\nPackage Cache\nStart Menu\nTemplates\nVMware\nbeaker.gemspec\nntuser.pol"
218
223
  ```
224
+
219
225
  #### Continue regular test execution
226
+
220
227
  Simply `exit` the console.
228
+
221
229
  ```
222
230
  [6] pry(#<Beaker::TestCase>)> exit
223
231
  ```
@@ -239,11 +247,9 @@ Consider this example test case _test.rb_, which is going to fail:
239
247
  assert_equal(important_expected_value, actual_value, 'This product is faulty')
240
248
  end
241
249
 
242
- You can run this test using `beaker -t test.rb` or (to use the `run` subcommand and just run the test and bypass host provisioning etc) `beaker run -t test.rb`
243
- It fails.
250
+ You can run this test using `beaker -t test.rb` or (to use the `run` subcommand and just run the test and bypass host provisioning etc) `beaker run -t test.rb`. It fails.
244
251
 
245
- Now try `beaker run -t test.rb --debug-errors`
246
- This will enter a pry console when the failure occurs.
252
+ Now try `beaker run -t test.rb --debug-errors` This will enter a pry console when the failure occurs.
247
253
 
248
254
  * Assert expected matches actual
249
255
  Exception raised during step execution and debug-errors option is set, entering pry. Exception was: #<Minitest::Assertion: This product is faulty.
@@ -305,11 +311,13 @@ The arrow indicates pry is showing code at the top of the stack trace. At positi
305
311
  From here, you can examine variables in your test. If you have hosts provisioned, you can send them commands using the [on](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/Helpers/HostHelpers#on-instance_method) method, or in a separate terminal ssh into them to investigate their state at the point of failure.
306
312
 
307
313
  ## Defining external breakpoints with byebug
314
+
308
315
  This method is perhaps the least intuitive to use; but combines the advantages of letting you pick the line(s) of code to set breakpoints on; and being able to debug without needing to edit your test code directly. It is sometimes desirable to debug a test without changing the test's code at all; for example, if you want to compare a test at two or more different git commits, your test source needs to remain unmodified from its committed form.
309
316
 
310
317
  byebug allows you to externally define breakpoints to keep them separate from your source code.
311
318
 
312
319
  ### Example
320
+
313
321
  Consider the following test file test.rb:
314
322
 
315
323
  ```ruby
@@ -1,8 +1,5 @@
1
1
  # The Hosts Directory
2
2
 
3
- This directory contains docs explaining any peculiarities or details of a particular
4
- OS's host implementation.
3
+ This directory contains docs explaining any peculiarities or details of a particular OS's host implementation.
5
4
 
6
- If you don't see a file here for an OS, then it's either not yet documented
7
- (feel free to help us out here!), or it should conform to our normal host
8
- abstraction assumptions.
5
+ If you don't see a file here for an OS, then it's either not yet documented (feel free to help us out here!), or it should conform to our normal host abstraction assumptions.
@@ -1,14 +1,16 @@
1
1
  # Arch Linux
2
2
 
3
3
  > Arch Linux is an independently developed, i686/x86-64 general-purpose GNU/Linux distribution that strives to provide the latest stable versions of most software by following a rolling-release model. The default installation is a minimal base system, configured by the user to only add what is purposely required.
4
- **Source: https://wiki.archlinux.org/index.php/Arch_Linux**
4
+
5
+ Source: https://wiki.archlinux.org/index.php/Arch_Linux
5
6
 
6
7
  # Installation
7
8
 
8
9
  ## Specifying a version to install
9
10
 
10
11
  > Arch Linux strives to maintain the latest stable release versions of its software as long as systemic package breakage can be reasonably avoided.
11
- **Source: https://wiki.archlinux.org/index.php/Arch_Linux**
12
+
13
+ Source: https://wiki.archlinux.org/index.php/Arch_Linux
12
14
 
13
15
  Since Arch is a rolling release, the Puppet version installed by Pacman will always be the latest avaliable release from the upstream.
14
16
 
@@ -1,36 +1,23 @@
1
1
  # Wind River Linux
2
2
 
3
- Wind River Linux is an embedded systems OS from Wind, an Intel Company. You
4
- can get more details on this from their
5
- [product page](http://www.windriver.com/products/linux/).
3
+ Wind River Linux is an embedded systems OS from Wind, an Intel Company. You can get more details on this from their [product page](http://www.windriver.com/products/linux/).
6
4
 
7
- Beaker provides support for 2 of Cisco's Wind River Linux platforms.
8
- Those platform codenames are `cisco_nexus` for Cisco NX-OS based systems
9
- and `cisco_ios_xr` for Cisco IOS XR based systems.
5
+ Beaker provides support for 2 of Cisco's Wind River Linux platforms. Those platform codenames are `cisco_nexus` for Cisco NX-OS based systems and `cisco_ios_xr` for Cisco IOS XR based systems.
10
6
 
11
7
  Beaker currently can install puppet on Cisco Nexus and Cisco IOS XR.
12
8
 
13
9
  # Host Requirements
14
10
 
15
- WRLinux hosts validate their setup once created, and will fail if not
16
- setup correctly. There are two conditions that are validated specifically
17
- on WRLinux hosts. These conditions are listed below.
11
+ WRLinux hosts validate their setup once created, and will fail if not setup correctly. There are two conditions that are validated specifically on WRLinux hosts. These conditions are listed below.
18
12
 
19
- A. All Cisco Nexus hosts will need a `:vrf` value, which determines their
20
- virtual routing framework for networking purposes. For our purposes,
21
- we tend to use the value `management`, so there is always a hosts
22
- file line that looks like this in our configuration:
13
+ A. All Cisco Nexus hosts will need a `:vrf` value, which determines their virtual routing framework for networking purposes. For our purposes, we tend to use the value `management`, so there is always a hosts file line that looks like this in our configuration:
23
14
 
24
15
  HOSTS:
25
16
  <hostname>:
26
17
  ...
27
18
  vrf: management
28
19
 
29
- B. All Cisco hosts will also require a user to be set on the
30
- hosts. This is because they don't allow ssh'ing as the root user,
31
- which is one of the main assumptions that Beaker operates under in
32
- the usual case. In order to specify a user to ssh with, add this
33
- block to a host:
20
+ B. All Cisco hosts will also require a user to be set on the hosts. This is because they don't allow ssh'ing as the root user, which is one of the main assumptions that Beaker operates under in the usual case. In order to specify a user to ssh with, add this block to a host:
34
21
 
35
22
  HOSTS:
36
23
  <hostname>:
@@ -40,22 +27,14 @@ block to a host:
40
27
 
41
28
  # Hypervisors
42
29
 
43
- WRLinux has only been developed and tested as a
44
- [vmpooler](https://github.com/puppetlabs/vmpooler) host.
30
+ WRLinux has only been developed and tested as a [vmpooler](https://github.com/puppetlabs/vmpooler) host.
45
31
 
46
- This doesn't mean that it can't be used in another hypervisor, but that
47
- Beaker doesn't specifically deal with the details of that hypervisor in creating
48
- WRLinux hosts, if there is anything specific to WRLinux that will need to be done in
49
- provisioning steps.
32
+ This doesn't mean that it can't be used in another hypervisor, but that Beaker doesn't specifically deal with the details of that hypervisor in creating WRLinux hosts, if there is anything specific to WRLinux that will need to be done in provisioning steps.
50
33
 
51
34
  # Installation Methods
52
35
 
53
36
  ## Open Source
54
37
 
55
- In order to install a puppet-agent against a WRLinux host, you'll have to use the
56
- [`install_puppet_agent_on`](blob/master/lib/beaker/dsl/install_utils/foss_utils.rb#L327)
57
- method.
38
+ In order to install a puppet-agent against a WRLinux host, you'll have to use the [`install_puppet_agent_on`](blob/master/lib/beaker/dsl/install_utils/foss_utils.rb#L327) method.
58
39
 
59
- It reaches out to the WRLinux-specific host code for any information that it needs.
60
- You can check out [these methods](blob/master/lib/beaker/host/cisco.rb) if you
61
- need more information about this.
40
+ It reaches out to the WRLinux-specific host code for any information that it needs. You can check out [these methods](blob/master/lib/beaker/host/cisco.rb) if you need more information about this.
@@ -1,17 +1,12 @@
1
1
  # EOS - Arista
2
2
 
3
- EOS is the network device OS from Arista. You can get more details from their
4
- [product page](https://www.arista.com/en/products/eos).
3
+ EOS is the network device OS from Arista. You can get more details from their [product page](https://www.arista.com/en/products/eos).
5
4
 
6
5
  # Hypervisors
7
6
 
8
- EOS has only been developed and tested as a
9
- [vmpooler](https://github.com/puppetlabs/vmpooler) host.
7
+ EOS has only been developed and tested as a [vmpooler](https://github.com/puppetlabs/vmpooler) host.
10
8
 
11
- This doesn't mean that it can't be used in another hypervisor, but that
12
- Beaker doesn't specifically deal with the details of that hypervisor in creating
13
- EOS hosts, if there is anything specific to EOS that will need to be done in
14
- provisioning steps.
9
+ This doesn't mean that it can't be used in another hypervisor, but that Beaker doesn't specifically deal with the details of that hypervisor in creating EOS hosts, if there is anything specific to EOS that will need to be done in provisioning steps.
15
10
 
16
11
  # Installation Methods
17
12
 
@@ -21,10 +16,6 @@ provisioning steps.
21
16
 
22
17
  ## Open Source
23
18
 
24
- In order to install a puppet-agent against an EOS host, you'll have to use the
25
- [`install_puppet_agent_dev_repo_on`](blob/master/lib/beaker/dsl/install_utils/foss_utils.rb#L1085)
26
- method.
19
+ In order to install a puppet-agent against an EOS host, you'll have to use the [`install_puppet_agent_dev_repo_on`](blob/master/lib/beaker/dsl/install_utils/foss_utils.rb#L1085) method.
27
20
 
28
- It reaches out to the EOS-specific host code for any information that it needs.
29
- You can check out [these methods](blob/master/lib/beaker/host/eos.rb) if you
30
- need more information about this.
21
+ It reaches out to the EOS-specific host code for any information that it needs. You can check out [these methods](blob/master/lib/beaker/host/eos.rb) if you need more information about this.
@@ -1,47 +1,34 @@
1
1
  # The Hypervisors Directory
2
2
 
3
- This directory contains docs explaining any peculiarities or details of a particular
4
- hypervisor's implementation.
3
+ This directory contains docs explaining any peculiarities or details of a particular hypervisor's implementation.
5
4
 
6
- If you don't see a file here for a hypervisor, then it's either not yet documented
7
- (feel free to help us out here!), or it should conform to our normal hypervisor
8
- assumptions.
5
+ If you don't see a file here for a hypervisor, then it's either not yet documented (feel free to help us out here!), or it should conform to our normal hypervisor assumptions.
9
6
 
10
7
  # Credentials File
11
8
 
12
- Beaker uses credentials from a `.fog` file for authentication. This file came
13
- from using the [fog cloud services library](http://fog.io). Beaker now only uses
14
- fog functionality in the openstack hypervisor, but we still use the `.fog` file
15
- for a credentials store.
9
+ Beaker uses credentials from a `.fog` file for authentication. This file came from using the [fog cloud services library](http://fog.io). Beaker now only uses fog functionality in the openstack hypervisor, but we still use the `.fog` file for a credentials store.
16
10
 
17
- By default, the file is located under the user's home directory. This helps to
18
- keep the credentials confidential. The path of `.fog` file can be changed by
19
- setting the `dot_fog` global beaker option.
11
+ By default, the file is located under the user's home directory. This helps to keep the credentials confidential. The path of `.fog` file can be changed by setting the `dot_fog` global beaker option.
20
12
 
21
- The `.fog` file is written in YAML. The keys are particular to the service that
22
- they correspond to, and each hypervisor's documentation should include the keys
23
- that are needed for it. An example `.fog` file is below:
13
+ The `.fog` file is written in YAML. The keys are particular to the service that they correspond to, and each hypervisor's documentation should include the keys that are needed for it. An example `.fog` file is below:
24
14
 
25
15
  ```yaml
26
- :default:
27
- :vsphere_server: 'vsphere.example.com'
28
- :vsphere_username: 'joe'
29
- :vsphere_password: 'MyP@$$w0rd'
30
- :vmpooler_token: 'randomtokentext'
16
+ default:
17
+ vsphere_server: 'vsphere.example.com'
18
+ vsphere_username: 'joe'
19
+ vsphere_password: 'MyP@$$w0rd'
20
+ vmpooler_token: 'randomtokentext'
31
21
  ```
32
22
 
23
+ Note: keys can be specified as either Strings or as Ruby Symbols (e.g. `:vsphere_server`). For interoprability with other systems, however, it is prudent to use Strings.
24
+
25
+ The credentials file supports multiple sections. Hypervisors currently do not specify a section, and the normal behavior is to fall back to using the `default` section. You can override the section by specifying an environment variable, [as documented on the fog website](https://fog.io/about/getting_started.html). Set `ENV['FOG_CREDENTIAL']` to specify an alternative provider section and `Beaker::Shared::FogFileParser.parse_fog_file()` will attempt to load that section, no matter what other section the hypervisor specifies.
26
+
33
27
  # External Hypervisors
34
28
 
35
- Puppet and its community have made several gems that support different
36
- hypervisors with beaker, the reason for this is that we're looking to decrease Beaker's
37
- dependency footprint, and hypervisors are one of the places where we can often
38
- increase the load across all Beaker uses to benefit a small group that uses a
39
- particular hypervisor.
29
+ Puppet and its community have made several gems that support different hypervisors with beaker, the reason for this is that we're looking to decrease Beaker's dependency footprint, and hypervisors are one of the places where we can often increase the load across all Beaker uses to benefit a small group that uses a particular hypervisor.
40
30
 
41
- In order to offset this, we've made a listing of gems and community-supported forks
42
- that support other external hypervisors. Please check them out if you'd like to use
43
- those hypervisors, hopefully it'll save you from spending time trying to support a
44
- new hypervisor yourself.
31
+ In order to offset this, we've made a listing of gems and community-supported forks that support other external hypervisors. Please check them out if you'd like to use those hypervisors, hopefully it'll save you from spending time trying to support a new hypervisor yourself.
45
32
 
46
33
  ### Hypervisor gems made by puppet (pre-included in beaker 3.x):
47
34
 
@@ -59,14 +46,9 @@ new hypervisor yourself.
59
46
 
60
47
  ### beaker-abs
61
48
 
62
- There is another hypervisor made and used internally by puppet,
63
- [beaker-abs](https://github.com/puppetlabs/beaker-abs), but it isn't included
64
- in beaker 3.x. If you'd like to use beaker-abs, you'll have to include it yourself.
49
+ There is another hypervisor made and used internally by puppet, [beaker-abs](https://github.com/puppetlabs/beaker-abs), but it isn't included in beaker 3.x. If you'd like to use beaker-abs, you'll have to include it yourself.
65
50
 
66
- You do that by requiring beaker-abs in your Gemfile as a sibling to beaker itself
67
- and then using `abs` as your hypervisor value in your hosts file. Please check the
68
- [beaker-abs README](https://github.com/puppetlabs/beaker-abs/blob/master/README.md)
69
- for more information.
51
+ You do that by requiring beaker-abs in your Gemfile as a sibling to beaker itself and then using `abs` as your hypervisor value in your hosts file. Please check the [beaker-abs README](https://github.com/puppetlabs/beaker-abs/blob/master/README.md) for more information.
70
52
 
71
53
  ### Hypervisor gems and beaker forks made by community:
72
54
 
@@ -1,88 +1,55 @@
1
1
  # How To Install Puppet
2
2
 
3
- This doc will guide you through the process of installing Puppet Agent using
4
- beaker's DSL helpers.
3
+ This doc will guide you through the process of installing Puppet Agent using beaker's DSL helpers.
5
4
 
6
- Note that this is not a complete documentation of the process, but a general
7
- overview. There will be specific hiccups for particular platforms and special
8
- cases. These are not all included at this point. The idea is that as we come
9
- upon them, we will now have a place to document those details, so that we can
10
- over time bring this to 100% completeness.
5
+ Note that this is not a complete documentation of the process, but a general overview. There will be specific hiccups for particular platforms and special cases. These are not all included at this point. The idea is that as we come upon them, we will now have a place to document those details, so that we can over time bring this to 100% completeness.
6
+
7
+ As of Beaker 4.0, these DSL extensions have been moved to `beaker-puppet`, so you'll need to add that gem in your project and require it in your test cases.
11
8
 
12
9
  # First Things First: What Do You Want to Install?
13
10
 
14
- If you understand [beaker's roles](https://github.com/puppetlabs/beaker/blob/master/docs/concepts/roles_what_are_they.md)
15
- and just want the shortcuts to installing Open Source Puppet across your testing
16
- environment, then you should go to our "High Level Shortcuts" section below.
11
+ If you understand [beaker's roles](https://github.com/puppetlabs/beaker/blob/master/docs/concepts/roles_what_are_they.md) and just want the shortcuts to installing Open Source Puppet across your testing environment, then you should go to our "High Level Shortcuts" section below.
17
12
 
18
- If you'd like to only install Puppet Agents, please checkout our "Puppet Agent
19
- Installs" section for more information.
13
+ If you'd like to only install Puppet Agents, please checkout our "Puppet Agent Installs" section for more information.
20
14
 
21
15
  # High Level Shortcuts
22
16
 
23
- The
24
- [`install_puppet_on`](http://www.rubydoc.info/gems/beaker/Beaker/DSL/InstallUtils/FOSSUtils#install_puppet_on-instance_method)
25
- method is a wrapper on our installing Puppet behavior that allows you to pass in
26
- which hosts in particular you'd like to install Puppet on as well as specifying
27
- the options used yourself. Please checkout the Rubydocs linked above for more
28
- info on this method.
17
+ The [`install_puppet_on`](http://www.rubydoc.info/gems/beaker/Beaker/DSL/InstallUtils/FOSSUtils#install_puppet_on-instance_method) method is a wrapper on our installing Puppet behavior that allows you to pass in which hosts in particular you'd like to install Puppet on as well as specifying the options used yourself. Please checkout the Rubydocs linked above for more info on this method.
29
18
 
30
- The
31
- [`install_puppet`](http://www.rubydoc.info/gems/beaker/Beaker/DSL/InstallUtils/FOSSUtils#install_puppet-instance_method)
32
- is deprecated. It's a shortcut method that just calls `install_puppet_on`
33
- passing the entire hosts array and global options hash. You can get the same
34
- using this code in your pre-suite:
19
+ The [`install_puppet`](http://www.rubydoc.info/gems/beaker/Beaker/DSL/InstallUtils/FOSSUtils#install_puppet-instance_method) is deprecated. It's a shortcut method that just calls `install_puppet_on` passing the entire hosts array and global options hash. You can get the same using this code in your pre-suite:
35
20
 
36
21
  ```ruby
37
22
  install_puppet_on(hosts, options)
38
23
  ```
39
24
 
40
- Note that both of the high level methods will call the `install_puppet_agent_on`
41
- method to install released Puppet Agent versions for your agent Systems Under
42
- Test (SUTs). Please checkout our "Released Open Source Puppet Agents" section
43
- below for more information on this method.
25
+ Note that both of the high level methods will call the `install_puppet_agent_on` method to install released Puppet Agent versions for your agent Systems Under Test (SUTs). Please checkout our "Released Open Source Puppet Agents" section below for more information on this method.
44
26
 
45
27
  # Puppet Agent Installs
46
28
 
47
- There are a number of Puppet Agents that you could be installing. There aren't
48
- only an ever-growing number of versions, but you can get Puppet Agent from a
49
- number of locations.
29
+ There are a number of Puppet Agents that you could be installing. There aren't only an ever-growing number of versions, but you can get Puppet Agent from a number of locations.
50
30
 
51
- If you'd like to install the Puppet Agent that comes with your particular Puppet
52
- Enterprise (PE) install, then please skip to our "PE Promoted Agent Installs"
53
- section below.
31
+ If you'd like to install the Puppet Agent that comes with your particular Puppet Enterprise (PE) install, then please skip to our "PE Promoted Agent Installs" section below.
54
32
 
55
- For our different Open Source variants, check out the sections just below, which
56
- differentiate between released & development Puppet Agent versions.
33
+ For our different Open Source variants, check out the sections just below, which differentiate between released & development Puppet Agent versions.
57
34
 
58
35
  ### Released Open Source Puppet Agents
59
36
 
60
- To install a released version of Puppet Agent, beaker provides the
61
- [`install_puppet_agent_on`](http://www.rubydoc.info/gems/beaker/Beaker/DSL/InstallUtils/FOSSUtils#install_puppet_agent_on-instance_method)
62
- method. Please checkout the Rubydocs for more info on this method.
37
+ To install a released version of Puppet Agent, beaker provides the [`install_puppet_agent_on`](http://www.rubydoc.info/gems/beaker/Beaker/DSL/InstallUtils/FOSSUtils#install_puppet_agent_on-instance_method) method. Please checkout the Rubydocs for more info on this method.
63
38
 
64
39
  ### Development Open Source Puppet Agents
65
40
 
66
- To install a development build of Puppet Agent, beaker provides the
67
- [`install_puppet_agent_dev_repo_on`](http://www.rubydoc.info/gems/beaker/Beaker/DSL/InstallUtils/FOSSUtils#install_puppet_agent_dev_repo_on-instance_method)
68
- method. Please checkout the Rubydocs for more info on this method.
41
+ To install a development build of Puppet Agent, beaker provides the [`install_puppet_agent_dev_repo_on`](http://www.rubydoc.info/gems/beaker/Beaker/DSL/InstallUtils/FOSSUtils#install_puppet_agent_dev_repo_on-instance_method) method. Please checkout the Rubydocs for more info on this method.
69
42
 
70
43
  ### PE Promoted Agent Installs
71
44
 
72
- If you're using this method, then you're going to be downloading the installer
73
- from a URL configured like so:
45
+ If you're using this method, then you're going to be downloading the installer from a URL configured like so:
74
46
 
75
47
  ```ruby
76
48
  http://pm.puppetlabs.com/puppet-agent/#{ pe_version }/#{ puppet_agent_version }/repos
77
49
  ```
78
50
 
79
- `pe_version` is a variable that you can provide using either the host or global
80
- property `:pe_ver`. This is usually done in the hosts file, and will default to
81
- `4.0.0-rc1` if nothing is specified.
51
+ `pe_version` is a variable that you can provide using either the host or global property `:pe_ver`. This is usually done in the hosts file, and will default to `4.0.0-rc1` if nothing is specified.
82
52
 
83
- `puppet_agent_version` is a variable you can provide the value of through the
84
- same methods as `pe_version` above. It will default to `latest`.
53
+ `puppet_agent_version` is a variable you can provide the value of through the same methods as `pe_version` above. It will default to `latest`.
85
54
 
86
- Beaker's DSL method to install from this location is
87
- [`install_puppet_agent_pe_promoted_repo_on`](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/InstallUtils/FOSSUtils#install_puppet_agent_pe_promoted_repo_on-instance_method).
88
- Follow the link to get API-level docs on this method for more info.
55
+ Beaker's DSL method to install from this location is [`install_puppet_agent_pe_promoted_repo_on`](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/InstallUtils/FOSSUtils#install_puppet_agent_pe_promoted_repo_on-instance_method). Follow the link to get API-level docs on this method for more info.
@@ -2,25 +2,15 @@
2
2
 
3
3
  ## What Are These?
4
4
 
5
- Typically when adding support for new platforms, a number of tests have to
6
- be confined away from executing on that new platform. This can be for a
7
- number of reasons, from partial implementation/support to tests having
8
- incorrect assumptions that don't work on the new platform.
5
+ Typically when adding support for new platforms, a number of tests have to be confined away from executing on that new platform. This can be for a number of reasons, from partial implementation/support to tests having incorrect assumptions that don't work on the new platform.
9
6
 
10
- Platform-specific tag confines are structures created to make this workflow
11
- easier, & achievable in a much more low-impact and adaptable way.
7
+ Platform-specific tag confines are structures created to make this workflow easier, & achievable in a much more low-impact and adaptable way.
12
8
 
13
9
  ## Ok, So How Do We Use Them?
14
10
 
15
- In the local options file (provided to the command line interface (CLI)
16
- using the `--options-file` parameter), you can now provide an array of
17
- hashes, where each hash specifies a platform to confine, based on the
18
- tags included in the test. The local options file key is
19
- `:platform_tag_confines`.
11
+ In the local options file (provided to the command line interface (CLI) using the `--options-file` parameter), you can now provide an array of hashes, where each hash specifies a platform to confine, based on the tags included in the test. The local options file key is `:platform_tag_confines`.
20
12
 
21
- An example local options file is included
22
- below (remember that local options files have to be readable into
23
- beaker as a ruby hash):
13
+ An example local options file is included below (remember that local options files have to be readable into beaker as a ruby hash):
24
14
 
25
15
  ```ruby
26
16
  {
@@ -43,18 +33,13 @@ beaker as a ruby hash):
43
33
  }
44
34
  ```
45
35
 
46
- In this case, there are two platform confines objects specified, one for
47
- Ubuntu 14.04, and the other for CentOS 7. These objects consist of a hash,
48
- filled with two entries: the `:platform` regex, and the `:tag_reason_hash`.
36
+ In this case, there are two platform confines objects specified, one for Ubuntu 14.04, and the other for CentOS 7. These objects consist of a hash, filled with two entries: the `:platform` regex, and the `:tag_reason_hash`.
49
37
 
50
- The `:platform` regex is just that, a Ruby regex matching the host's
51
- platform string.
38
+ The `:platform` regex is just that, a Ruby regex matching the host's platform string.
52
39
 
53
- The `:tag_reason_hash` is another hash that maps tags to the reason that
54
- tests that have this particular tag are being confined away from testing.
40
+ The `:tag_reason_hash` is another hash that maps tags to the reason that tests that have this particular tag are being confined away from testing.
55
41
 
56
- Taking one of our confine examples from above, we can think of the Ubuntu
57
- UI confine example like this:
42
+ Taking one of our confine examples from above, we can think of the Ubuntu UI confine example like this:
58
43
 
59
44
  "ui" tests will be confined away from ubuntu-1404 hosts, because
60
45
  "TODO: We have not applied the UI tests to Ubuntu yet"
@@ -62,15 +47,10 @@ UI confine example like this:
62
47
 
63
48
  ## But Why Do We Need These?
64
49
 
65
- Usually when we add platforms, the confining tests step is very heavy
66
- handed & repetitive, usually consisting of adding boilerplate confine
67
- calls that don't provide any explanation for why these are happening.
68
- This can make it hard to later know the reason for the confine, making
69
- it hard to know when we should be able to remove confines down the road.
50
+ Usually when we add platforms, the confining tests step is very heavy handed & repetitive, usually consisting of adding boilerplate confine calls that don't provide any explanation for why these are happening. This can make it hard to later know the reason for the confine, making it hard to know when we should be able to remove confines down the road.
70
51
 
71
- This new workflow should provide a number of advantages over the previous
72
- one, including:
52
+ This new workflow should provide a number of advantages over the previous one, including:
73
53
 
74
54
  1. Always reporting a reason for confining a platform
75
55
  2. Allowing these to be dynamically determined from configuration, rather
76
- than needing to edit tens to hundreds of test files in-repo
56
+ than needing to edit tens to hundreds of test files in-repo
@@ -2,40 +2,23 @@
2
2
 
3
3
  ## Motivation
4
4
 
5
- Often when developing acceptance tests to be run with beaker, you'll want to be
6
- able to quickly iterate on those tests in an already setup System Under Test
7
- (SUT) configuration. Beaker provides the ability to do that using its preserved
8
- hosts functionality.
5
+ Often when developing acceptance tests to be run with beaker, you'll want to be able to quickly iterate on those tests in an already setup System Under Test (SUT) configuration. Beaker provides the ability to do that using its preserved hosts functionality.
9
6
 
10
7
  ## But Is This The Right Solution?
11
8
 
12
- Many people are of the opinion that if you have to login to a SUT, then you've
13
- already failed, and that the purpose of good automation is so that you don't
14
- ever have to do this. Beaker supports a diverse group of developers and testers,
15
- and we try to remain flexible and support multiple approaches to these problems.
9
+ Many people are of the opinion that if you have to login to a SUT, then you've already failed, and that the purpose of good automation is so that you don't ever have to do this. Beaker supports a diverse group of developers and testers, and we try to remain flexible and support multiple approaches to these problems.
16
10
 
17
- Another approach you might take to debugging failed tests, during development or
18
- test runs in your Continuous Integration (CI) systems, is to archive any
19
- artifacts or log files from the SUTs, so that you can read them all from the
20
- beaker coordinator. Beaker provides a Domain-Specific Language (DSL) method to
21
- accomodate this workflow, called `archive_file_from`. Check out the
22
- [how-to article](archive_sut_files.md) on this method for details on it.
11
+ Another approach you might take to debugging failed tests, during development or test runs in your Continuous Integration (CI) systems, is to archive any artifacts or log files from the SUTs, so that you can read them all from the beaker coordinator. Beaker provides a Domain-Specific Language (DSL) method to accomodate this workflow, called `archive_file_from`. Check out the [how-to article](archive_sut_files.md) on this method for details on it.
23
12
 
24
- That being said, the preserved hosts functionality is still useful, particularly
25
- for new development. In this case, you might not be able to necessarily tell
26
- what files you might need from your SUTs, and exploration might be necessary.
13
+ That being said, the preserved hosts functionality is still useful, particularly for new development. In this case, you might not be able to necessarily tell what files you might need from your SUTs, and exploration might be necessary.
27
14
 
28
15
  ## How Do I Use It?
29
16
 
30
- Note that where you decide to use this option will affect its precedence. You
31
- can learn more about this in our
32
- [argument processing & precedence doc](../concepts/argument_processing_and_precedence.md).
17
+ Note that where you decide to use this option will affect its precedence. You can learn more about this in our [argument processing & precedence doc](../concepts/argument_processing_and_precedence.md).
33
18
 
34
19
  ### Command-Line Option
35
20
 
36
- The primary way that this option is provided is through the command line, where
37
- it's represented by the `--preserved-hosts` option. It defaults to `never`, and
38
- if you run `beaker --help`, you'll see the range of values that can be taken:
21
+ The primary way that this option is provided is through the command line, where it's represented by the `--preserved-hosts` option. It defaults to `never`, and if you run `beaker --help`, you'll see the range of values that can be taken:
39
22
 
40
23
  $ beaker --help
41
24
  ...
@@ -50,49 +33,25 @@ if you run `beaker --help`, you'll see the range of values that can be taken:
50
33
 
51
34
  ### Local Options or Global Config
52
35
 
53
- You can also provide a value for this option wherever you can provide a value
54
- that gets merged into beaker's global options hash. The two ways to do this are
55
- to provide it in a local options file, or in the global `CONFIG` section of your
56
- hosts file. To learn more about how to set these options, check out the
57
- [Options File Values](../concepts/argument_processing_and_precedence.md#options-file-values)
58
- and the
59
- [`CONFIG` Section of a Hosts File](../concepts/argument_processing_and_precedence.md#config-section-of-hosts-file)
60
- sections of the
61
- [argument processing & precedence doc](../concepts/argument_processing_and_precedence.md).
36
+ You can also provide a value for this option wherever you can provide a value that gets merged into beaker's global options hash. The two ways to do this are to provide it in a local options file, or in the global `CONFIG` section of your hosts file. To learn more about how to set these options, check out the [Options File Values](../concepts/argument_processing_and_precedence.md#options-file-values) and the [`CONFIG` Section of a Hosts File](../concepts/argument_processing_and_precedence.md#config-section-of-hosts-file) sections of the [argument processing & precedence doc](../concepts/argument_processing_and_precedence.md).
62
37
 
63
- Either way, the underlying property name that you will have to set if you use
64
- these options is `:preserve_hosts`.
38
+ Either way, the underlying property name that you will have to set if you use these options is `:preserve_hosts`.
65
39
 
66
40
  ## What Does It Do (In Detail)?
67
41
 
68
- Using the preserved hosts functionality outputs a `hosts_preserved.yml` file into
69
- the directory that holds all of the log files for a particular beaker run. The
70
- short way to access that directory is to look into the `log/latest` path, which
71
- is a symlink to the actual log directory for the run.
42
+ Using the preserved hosts functionality outputs a `hosts_preserved.yml` file into the directory that holds all of the log files for a particular beaker run. The short way to access that directory is to look into the `log/latest` path, which is a symlink to the actual log directory for the run.
72
43
 
73
- The `hosts_preserved.yml` file generated by a run differs from the original
74
- hosts file passed into Beaker in a number of ways:
44
+ The `hosts_preserved.yml` file generated by a run differs from the original hosts file passed into Beaker in a number of ways:
75
45
 
76
- - all suites are emptied
77
- - the host names are updated to point to the IPs (or hostnames) of the VMs since
78
- they exist and no longer need provisioning
79
- - the `provision` option is set to `false` (check
80
- [Beaker Test Run's](../tutorials/test_run.md) provisioning section for details).
46
+ - all suites are emptied - the host names are updated to point to the IPs (or hostnames) of the VMs since they exist and no longer need provisioning - the `provision` option is set to `false` (check [Beaker Test Run's](../tutorials/test_run.md) provisioning section for details).
81
47
 
82
48
  Beaker will also output the lines included below at the end of the run:
83
49
 
84
50
  You can re-run commands against the already provisioned SUT(s) with:
85
51
  /.../beaker --hosts log/centos7-64mdac-ubuntu1504-64a/2016-07-18_13_42_44/hosts_preserved.yml --tests smoke_simple.rb --preserve-hosts onpass
86
52
 
87
- The important piece here is the hosts argument, in that it's informing you of
88
- where the preserved hosts file is located. Of course, until you kick off another
89
- beaker run, you can also reach this file with the `log/latest/hosts_preserved.yml`
90
- symlink, as mentioned at the beginning of this section.
53
+ The important piece here is the hosts argument, in that it's informing you of where the preserved hosts file is located. Of course, until you kick off another beaker run, you can also reach this file with the `log/latest/hosts_preserved.yml` symlink, as mentioned at the beginning of this section.
91
54
 
92
55
  ## What Do I Do With It?
93
56
 
94
- For subsequent runs, if you want to set something, you'll have to pay attention
95
- to the precedence of your arguments, to be sure that you are overriding what is
96
- set in the preserved hosts file. Checkout the
97
- [argument processing & precedence doc](../concepts/argument_processing_and_precedence.md)
98
- for more details on the precedence order of options parsing.
57
+ For subsequent runs, if you want to set something, you'll have to pay attention to the precedence of your arguments, to be sure that you are overriding what is set in the preserved hosts file. Checkout the [argument processing & precedence doc](../concepts/argument_processing_and_precedence.md) for more details on the precedence order of options parsing.