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
@@ -1,7 +1,5 @@
1
1
  # Rake test tasks for running beaker
2
2
 
3
- ## How does it work?
4
-
5
3
  There are some rake tasks that you can use to run Beaker tests from your local project dir.
6
4
 
7
5
  To use them from within your own project, you will need to require the following file in your project's rakefile:
@@ -20,8 +18,7 @@ from your project dir, you should see (as well as any rake tasks you have define
20
18
  rake beaker:test:git[hosts] # Run Beaker Git tests
21
19
  rake beaker:test:pe[hosts] # Run Beaker PE tests
22
20
 
23
- The last two tasks assume that you have an options file in /acceptance named beaker-git.cfg and beaker-pe.cfg
24
- respectively.
21
+ The last two tasks assume that you have an options file in `/acceptance` named `beaker-git.cfg` and `beaker-pe.cfg` respectively.
25
22
 
26
23
  Your options file would look something like:
27
24
 
@@ -3,11 +3,18 @@
3
3
  Patterns for best-use solutions to (not so) common problems
4
4
 
5
5
  ## How do i set persistent environment variables on a SUT, such as PATH?
6
+
7
+ ```ruby
6
8
  host.add_env_var('PATH', '/opt/puppetlabs/bin:$PATH')
9
+ ```
7
10
 
8
11
  ## How do i run commands on a SUT as a non-root user?
9
- (warning) this should be abstracted into a beaker helper, or part of on(): BKR-168 - Beaker::DSL::Helpers needs "as" method READY FOR ENGINEERING
10
12
 
11
- ###create the user, then su with --command:
13
+ (warning) this should be abstracted into a beaker helper, or part of `on()`: BKR-168 - Beaker::DSL::Helpers needs "as" method READY FOR ENGINEERING
14
+
15
+ Create the user, then `su` with `--command`:
16
+
17
+ ```ruby
12
18
  on(host, puppet("resource user #{username} ensure=present managehome-true"))
13
19
  on(host, "su #{username} --command '#{command}'")
20
+ ```
@@ -1,21 +1,21 @@
1
1
  # run_in_parallel global and command options
2
2
 
3
3
  ## run_in_parallel global option
4
- The run_in_parallel global option is an array with the following possible values: ['configure', 'install']
5
- It defaults to an empty array []
6
- It can be set in an options file, or overriden by the BEAKER_RUN_IN_PARALLEL environment variable
7
- example:
8
4
 
9
- export BEAKER_RUN_IN_PARALLEL=configure,install
5
+ The run_in_parallel global option is an array with the following possible values: ['configure', 'install']. It defaults to an empty array `[]`. It can be set in an options file, or overriden by the `BEAKER_RUN_IN_PARALLEL` environment variable. Example:
6
+
7
+ ```console
8
+ $ export BEAKER_RUN_IN_PARALLEL=configure,install
9
+ ```
10
10
 
11
11
  Including 'configure' causes timesync to execute in parallel (if timesync=true for any host)
12
12
 
13
13
  Including 'install' causes as much of the puppet install to happen in parallel as possible.
14
14
 
15
15
  ## run_in_parallel command option
16
- The run_in_parallel command option is a boolean value, specifying whether to execute each iteration (usually of hosts)
17
- in parallel, or not. The block_on method is the primary method accepting the run_in_parallel command option,
18
- however many methods that call into block_on respect it as well:
16
+
17
+ The run_in_parallel command option is a boolean value, specifying whether to execute each iteration (usually of hosts) in parallel, or not. The block_on method is the primary method accepting the run_in_parallel command option, however many methods that call into block_on respect it as well:
18
+
19
19
  - on
20
20
  - run_block_on
21
21
  - block_on
@@ -25,9 +25,9 @@ however many methods that call into block_on respect it as well:
25
25
  - execute_powershell_script_on
26
26
 
27
27
  ## Using InParallel in your test scripts
28
- In addition to the options, you can use InParallel within your test scripts as well.
29
28
 
30
- Examples:
29
+ In addition to the options, you can use InParallel within your test scripts as well. Examples:
30
+
31
31
  ```ruby
32
32
  include InParallel
33
33
 
@@ -1,26 +1,21 @@
1
1
  # How to Forward ssh(1) Agent
2
2
 
3
- `ssh(1)` agent forwarding can is activated in the `CONFIG` section of the hosts
4
- file:
3
+ `ssh(1)` agent forwarding can is activated in the `CONFIG` section of the hosts file:
5
4
 
6
- ~~~yaml
5
+ ```yaml
7
6
  HOSTS:
8
7
  ...
9
8
  CONFIG:
10
9
  forward_ssh_agent: true
11
- ~~~
10
+ ```
12
11
 
13
- Beaker will then make the ssh agent running on the beaker coordinator available to the Systems Under Test (SUT). There is
14
- a gotcha though: the agent socket file in the SUT is only available
15
- to the user who signed in. If you want to access remote machine resources as
16
- another user, you *must* change the socket permission.
12
+ Beaker will then make the ssh agent running on the beaker coordinator available to the Systems Under Test (SUT). There is a gotcha though: the agent socket file in the SUT is only available to the user who signed in. If you want to access remote machine resources as another user, you *must* change the socket permission.
17
13
 
18
- A dirty hack is to `chmod -R 777 /tmp/ssh-*` before changing to another user
19
- and relying on `$SSH_AUTH_SOCK`.
14
+ A dirty hack is to `chmod -R 777 /tmp/ssh-*` before changing to another user and relying on `$SSH_AUTH_SOCK`.
20
15
 
21
16
  Example:
22
17
 
23
- ~~~puppet
18
+ ```puppet
24
19
  exec { '/bin/chmod -R 777 /tmp/ssh-*':
25
20
  } ->
26
21
  vcsrepo { '/var/www/app':
@@ -28,8 +23,8 @@ vcsrepo { '/var/www/app':
28
23
  source => 'https://example.com/git/app.git',
29
24
  user => 'deploy'
30
25
  }
31
- ~~~
26
+ ```
32
27
 
33
- ## Cross SUT access
28
+ ## Cross-SUT access
34
29
 
35
30
  If you need to be able to SSH between SUTs while running Beaker acceptance tests, please refer to the [enabling cross SUT access](enabling_cross_sut_access.md) document
@@ -2,35 +2,35 @@
2
2
 
3
3
  Setting up a SSH connection to hosts can be tricky. Beaker supports three methods to SSH to hosts:
4
4
 
5
- 1. `ip`
6
- 2. `vmhostname (dns name)`
7
- 3. `hostname`
5
+ 1. `:ip`
6
+ 2. `:vmhostname` - DNS name
7
+ 3. `:hostname`
8
8
 
9
- Beaker tries to SSH to hosts using these methods in a particular preference (order). Default preference is mentioned above. We allow hypervisor authors and end users to provide an array of these methods that reflects their preference.
9
+ Beaker tries to SSH to hosts using these methods in a particular preference (order). Default preference is mentioned above. We allow hypervisor authors and end users to provide an array of these methods that reflects their preference. Note that methods are identified by Ruby symbols, not strings.
10
10
 
11
- ### Why set a preference?
11
+ ## Why set a preference?
12
12
 
13
13
  Depending upon your hypervisor, your host could have specific method that it uses to SSH better and faster than other methods. For example, hosts generated by vmpooler connects better with `vmhostname` as some change their ip adderess on restart. Therefore vmpooler hypervisor sets its connection preference to use vmhostname first.
14
14
 
15
- ### Setting SSH connection preference at hypervisor level
15
+ ## Setting SSH connection preference at hypervisor level
16
16
 
17
17
  Hypervisor authors can set SSH connection preference. The only thing they have to do is override the `connection_preference` method set in [hypervisor.rb](https://github.com/puppetlabs/beaker/blob/master/lib/beaker/hypervisor.rb) file in their own hypervisor file.
18
18
 
19
19
  For example, `beaker-vmpooler` overriding this in [vmpooler.rb](https://github.com/puppetlabs/beaker-vmpooler/blob/master/lib/beaker/hypervisor/vmpooler.rb) file.
20
20
 
21
- ### Setting SSH connection methods in hosts file
21
+ ## Setting SSH connection methods in hosts file
22
22
 
23
23
  End users can override the connection preference that is default or set by their hypervisor. This can be done from your hosts file. All you need to do is provide a `ssh_preference` for each host. The value of this key should be an array of the methods specified above in an order you prefer. Beaker then will attempt to SSH to the hosts in that particular order.
24
24
 
25
25
  Example of a host file:
26
26
 
27
- ```
27
+ ```yaml
28
28
  HOSTS:
29
29
  ubuntu1604-64-1:
30
30
  hypervisor: vmpooler
31
31
  platform: ubuntu-16.04-amd64
32
32
  template: ubuntu-1604-x86_64
33
- ssh_preference: ['vmhostname', 'hostname', 'ip']
33
+ ssh_preference: [:vmhostname, :hostname, :ip]
34
34
  roles:
35
35
  - agent
36
36
  - default
@@ -38,7 +38,7 @@ HOSTS:
38
38
  hypervisor: vmpooler
39
39
  platform: ubuntu-16.04-amd64
40
40
  template: ubuntu-1604-x86_64
41
- ssh_preference: ['ip, 'vmhostname']
41
+ ssh_preference: [:ip, :vmhostname]
42
42
  roles:
43
43
  - agent
44
44
  CONFIG:
@@ -1,12 +1,8 @@
1
1
  # Test arbitrary beaker versions without modifying test code
2
2
 
3
- In order to adjust the beaker version used without commiting a change to a Gemfile,
4
- we at Puppet often use a method in our code that changes the dependency based on the
5
- existence of ENV variables in the shell that beaker is executing from. The code
6
- itself looks like this:
3
+ In order to adjust the beaker version used without commiting a change to a Gemfile, we at Puppet often use a method in our code that changes the dependency based on the existence of ENV variables in the shell that beaker is executing from. The code itself looks like this:
7
4
 
8
5
  ```ruby
9
-
10
6
  def location_for(place, fake_version = nil)
11
7
  if place =~ /^(git[:@][^#]*)#(.*)/
12
8
  [fake_version, { :git => $1, :branch => $2, :require => false }].compact
@@ -16,11 +12,9 @@ def location_for(place, fake_version = nil)
16
12
  [place, { :require => false }]
17
13
  end
18
14
  end
19
-
20
15
  ```
21
16
 
22
- Once this method definition is in place in the Gemfile, we can call it in a gem command, like
23
- this:
17
+ Once this method definition is in place in the Gemfile, we can call it in a gem command, like this:
24
18
 
25
19
  ```ruby
26
20
 
@@ -37,10 +31,9 @@ git://github.com/puppetlabs/beaker.git#master
37
31
  ```
38
32
 
39
33
  ### file locations
34
+
40
35
  ```
41
36
  file://../relative/path/to/beaker
42
37
  ```
43
- By adjusting the shell environment that beaker is running in, we can modify what version of
44
- beaker is installed by bundler on your test coordinator without modifying any of the test
45
- code. This strategy can be used for any gem dependency, and is often used when testing
46
- [beaker libraries](../concepts/beaker_libraries.md) at Puppet.
38
+
39
+ By adjusting the shell environment that beaker is running in, we can modify what version of beaker is installed by bundler on your test coordinator without modifying any of the test code. This strategy can be used for any gem dependency, and is often used when testing [beaker libraries](../concepts/beaker_libraries.md) at Puppet.