{"action":"created","comment":{"url":"https://api.github.com/repos/puppetlabs/beaker/pulls/comments/72298424","id":72298424,"diff_hunk":"@@ -0,0 +1,178 @@\n+# Beaker Style Guide\n+\n+## Scope of this guide\n+\n+The purpose of this guide is to provide definitions for preferred practices when\n+writing Beaker tests, both syntactically and stylistically. This guide will\n+define and provide examples for preferred test layout and conventions. Common\n+patterns that are recommend as well as patterns that should be avoided will be\n+described.\n+\n+No style manual can cover every possible circumstance. When a judgement call\n+becomes necessary, keep in mind the following general ideas:\n+\n+1. **Readability matters**. If you have to choose between two equally effective\n+alternatives, pick the more readable one. This is, of course, subjective, but if\n+you can read your own code three months from now, that’s a great start. Don’t be\n+clever over readable, unless you have a documented purpose. Use object oriented\n+programming when things get complex and DRY.\n+2. **Inherit upstream conventions**. Beaker is still ruby, so use the\n+[ruby community style guide](https://github.com/bbatsov/ruby-style-guide). When\n+not called out here, use the ruby style guide.\n+\n+## Test Naming\n+\n+Tests should test what they say they test. Test names, both the name of the test\n+file and the value given to the\n+[`test_name`](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/Structure#test_name-instance_method)\n+function should provide an accurate indication about the purpose of the test.\n+\n+The `test_name` function should be the first line in the Beaker test file.\n+\n+**Good:**\n+```ruby\n+# head -1 puppet/acceptance/tests/resource/file/should_default_mode.rb\n+test_name \"file resource: set default modes\"\n+```\n+\n+## Structure Methods Should Use Explicit Blocks\n+\n+These methods aid in self-documenting your tests, including indention in the\n+logs. If you don’t use explicit blocks, beaker does not know how to properly\n+indent your test’s output.\n+\n+The most common\n+[structure methods](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/Structure)\n+are\n+[`#test_name`](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/Structure#test_name-instance_method),\n+[`#step`](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/Structure#step-instance_method),\n+and\n+[`#teardown`](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/Structure#teardown-instance_method).\n+\n+**Good:**\n+```ruby\n+step 'do this thang' do\n+  on(host, \"echo 'do this thang'\")\n+end\n+```\n+**Bad:**\n+```ruby\n+step 'do this thang'\n+on(host, \"echo 'do this thang'\")\n+```\n+\n+## Teardowns\n+\n+- Return the state of the system to the way it was prior to test execution\n+- Put the teardown as early in the test as possible\n+\n+Teardowns must be used to return the system to the state it was in prior to the\n+execution or attempted execution of the test. Beaker will gather all teardowns\n+encountered throughout the execution path of the test. These teardowns will all\n+be executed when the test exits, even if the test exits early due to a failure\n+or error.\n+\n+### Place Teardowns Early\n+\n+Teardowns can be placed anywhere in the test file or its helpers. The preferred\n+style is to have a teardown step near the beginning of the test file to show the\n+reader that the system state will be restored.\n+\n+**Good:**\n+```ruby\n+test_name 'The source attribute' do\n+\n+  target_file_on_nix = '/tmp/source_attr_test'\n+  teardown do\n+    on(hosts[0], \"rm #{target_file_on_nix}\", :accept_all_exit_codes => true)\n+  end\n+  ...\n+end\n+```\n+\n+Teardowns are at the mercy of the scoping of the variables necessary to perform\n+the restoration of the system. This fact means that additional teardown steps\n+will need to be added within the scope necessary to do their job. Effort should\n+be taken to make the teardown steps prominent and readable so that it can be\n+confirmed, via the logs, that the system has been restored.\n+\n+Teardown steps registered outside of tests should use\n+[`#step`](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/Structure#step-instance_method)\n+to document and log what they are doing.\n+\n+## Acceptable Exit Codes\n+\n+When using the Beaker\n+[`on`](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/Helpers/HostHelpers#on-instance_method)\n+method, the default setting is that only an exit code of 0 (zero) will not\n+trigger an error. When other exit codes are acceptable, the\n+`:acceptable_exit_codes` key with an array of exit codes should be passed in the\n+options hash to `#on`. If 0 (zero) is the only acceptable exit code, then the\n+`:acceptable_exit_codes` symbol must not be used.\n+\n+Each example can be considered a bad example for the situation below it:\n+```ruby\n+# Single 0 exit code allowed\n+on(host, \"rm #{file_to_rm}\")\n+# Single non-0 exit code allowed\n+on(host, \"rm #{file_to_rm}\", :acceptable_exit_codes => 1)\n+# Multiple exit codes allowed\n+on(host, \"rm #{file_to_rm}\", :acceptable_exit_codes => [0,1])\n+# Any exit code allowed\n+on(host, \"rm #{file_to_rm}\", :accept_all_exit_codes => true)\n+```\n+\n+In the last case, when any exit code is allowed, one must follow-up with a valid\n+assertion test.\n+\n+If an exit_code outside of 0 is expected, one must use acceptable_exit_codes so\n+the test will fail on the proper assertion and not error at that command.  Allow\n+only the minimum expected set of exit codes unless coverage is provided by\n+subsequent assertions.\n+\n+## Outcomes\n+\n+When to use each, how to format the message:\n+\n+### `fail_test`, `pass_test`, & `skip_test` \n+\n+These can be used anywhere in a test to exit early. A \n+[`skip_test`](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/Outcomes#fail_test-instance_method)\n+between two assertions, for instance, will run the first assertion, raise an\n+exception for `skip_test`, run teardown, and then exit as we expect. The same is\n+true for\n+[fail_test](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/Outcomes#fail_test-instance_method).\n+\n+[pass_test](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/Outcomes#fail_test-instance_method)\n+should not be used unless fast-passing in a conditional branch.\n+\n+### Skipping Tests\n+\n+Skipping tests can be used, for instance, when they are temporarily failing or\n+not yet complete.\n+\n+**Good:**\n+```ruby\n+skip_test 'should never run on solaris' if agent['platform'] =~ /solaris/\n+```\n+**Bad:**\n+```ruby\n+confine :to, :platform => 'solaris:pending'\n+```\n+\n+If they are failing due to an “expected failure” you should wrap your failing\n+assertion in an\n+[`expect_failure`](http://www.rubydoc.info/github/puppetlabs/beaker/Beaker/DSL/Structure#expect_failure-instance_method)\n+block with an explanatory logging message:\n+\n+```ruby\n+expect_failure('expected to fail due to PE-1234') do\n+  assert_equal(400, response.code, 'bad response code from API call')\n+end\n+```","path":"docs/concepts/style_guide.md","position":172,"original_position":172,"commit_id":"4c4c726f1fb958ad094bf5216444ec62550a0b3d","original_commit_id":"4c4c726f1fb958ad094bf5216444ec62550a0b3d","user":{"login":"er0ck","id":7454093,"avatar_url":"https://avatars.githubusercontent.com/u/7454093?v=3","gravatar_id":"","url":"https://api.github.com/users/er0ck","html_url":"https://github.com/er0ck","followers_url":"https://api.github.com/users/er0ck/followers","following_url":"https://api.github.com/users/er0ck/following{/other_user}","gists_url":"https://api.github.com/users/er0ck/gists{/gist_id}","starred_url":"https://api.github.com/users/er0ck/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/er0ck/subscriptions","organizations_url":"https://api.github.com/users/er0ck/orgs","repos_url":"https://api.github.com/users/er0ck/repos","events_url":"https://api.github.com/users/er0ck/events{/privacy}","received_events_url":"https://api.github.com/users/er0ck/received_events","type":"User","site_admin":false},"body":"+1\r\nsomething like\r\n```\r\non(blah, 'blah', :allow_all_exit_codes => true) do |result|\r\n  expect_failure 'known issue: TIK-1234' do\r\n    assert_equal(4,result.exit_code,'did not receive expected exit code for blah')\r\n  end\r\nend\r\n```","created_at":"2016-07-26T17:33:54Z","updated_at":"2016-07-26T17:33:54Z","html_url":"https://github.com/puppetlabs/beaker/pull/1197#discussion_r72298424","pull_request_url":"https://api.github.com/repos/puppetlabs/beaker/pulls/1197","_links":{"self":{"href":"https://api.github.com/repos/puppetlabs/beaker/pulls/comments/72298424"},"html":{"href":"https://github.com/puppetlabs/beaker/pull/1197#discussion_r72298424"},"pull_request":{"href":"https://api.github.com/repos/puppetlabs/beaker/pulls/1197"}}},"pull_request":{"url":"https://api.github.com/repos/puppetlabs/beaker/pulls/1197","id":78759853,"html_url":"https://github.com/puppetlabs/beaker/pull/1197","diff_url":"https://github.com/puppetlabs/beaker/pull/1197.diff","patch_url":"https://github.com/puppetlabs/beaker/pull/1197.patch","issue_url":"https://api.github.com/repos/puppetlabs/beaker/issues/1197","number":1197,"state":"open","locked":false,"title":"(BKR-80) created style guide for beaker tests","user":{"login":"kevpl","id":8973629,"avatar_url":"https://avatars.githubusercontent.com/u/8973629?v=3","gravatar_id":"","url":"https://api.github.com/users/kevpl","html_url":"https://github.com/kevpl","followers_url":"https://api.github.com/users/kevpl/followers","following_url":"https://api.github.com/users/kevpl/following{/other_user}","gists_url":"https://api.github.com/users/kevpl/gists{/gist_id}","starred_url":"https://api.github.com/users/kevpl/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kevpl/subscriptions","organizations_url":"https://api.github.com/users/kevpl/orgs","repos_url":"https://api.github.com/users/kevpl/repos","events_url":"https://api.github.com/users/kevpl/events{/privacy}","received_events_url":"https://api.github.com/users/kevpl/received_events","type":"User","site_admin":false},"body":"[skip ci]","created_at":"2016-07-25T22:00:09Z","updated_at":"2016-07-26T17:33:54Z","closed_at":null,"merged_at":null,"merge_commit_sha":"1fe98a1a9764f93906c59e15c3fbb6944379c7f0","assignee":null,"assignees":[],"milestone":null,"commits_url":"https://api.github.com/repos/puppetlabs/beaker/pulls/1197/commits","review_comments_url":"https://api.github.com/repos/puppetlabs/beaker/pulls/1197/comments","review_comment_url":"https://api.github.com/repos/puppetlabs/beaker/pulls/comments{/number}","comments_url":"https://api.github.com/repos/puppetlabs/beaker/issues/1197/comments","statuses_url":"https://api.github.com/repos/puppetlabs/beaker/statuses/4c4c726f1fb958ad094bf5216444ec62550a0b3d","head":{"label":"kevpl:docs_style_guide","ref":"docs_style_guide","sha":"4c4c726f1fb958ad094bf5216444ec62550a0b3d","user":{"login":"kevpl","id":8973629,"avatar_url":"https://avatars.githubusercontent.com/u/8973629?v=3","gravatar_id":"","url":"https://api.github.com/users/kevpl","html_url":"https://github.com/kevpl","followers_url":"https://api.github.com/users/kevpl/followers","following_url":"https://api.github.com/users/kevpl/following{/other_user}","gists_url":"https://api.github.com/users/kevpl/gists{/gist_id}","starred_url":"https://api.github.com/users/kevpl/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kevpl/subscriptions","organizations_url":"https://api.github.com/users/kevpl/orgs","repos_url":"https://api.github.com/users/kevpl/repos","events_url":"https://api.github.com/users/kevpl/events{/privacy}","received_events_url":"https://api.github.com/users/kevpl/received_events","type":"User","site_admin":false},"repo":{"id":24955690,"name":"beaker","full_name":"kevpl/beaker","owner":{"login":"kevpl","id":8973629,"avatar_url":"https://avatars.githubusercontent.com/u/8973629?v=3","gravatar_id":"","url":"https://api.github.com/users/kevpl","html_url":"https://github.com/kevpl","followers_url":"https://api.github.com/users/kevpl/followers","following_url":"https://api.github.com/users/kevpl/following{/other_user}","gists_url":"https://api.github.com/users/kevpl/gists{/gist_id}","starred_url":"https://api.github.com/users/kevpl/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/kevpl/subscriptions","organizations_url":"https://api.github.com/users/kevpl/orgs","repos_url":"https://api.github.com/users/kevpl/repos","events_url":"https://api.github.com/users/kevpl/events{/privacy}","received_events_url":"https://api.github.com/users/kevpl/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/kevpl/beaker","description":"Puppet acceptance testing harness","fork":true,"url":"https://api.github.com/repos/kevpl/beaker","forks_url":"https://api.github.com/repos/kevpl/beaker/forks","keys_url":"https://api.github.com/repos/kevpl/beaker/keys{/key_id}","collaborators_url":"https://api.github.com/repos/kevpl/beaker/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/kevpl/beaker/teams","hooks_url":"https://api.github.com/repos/kevpl/beaker/hooks","issue_events_url":"https://api.github.com/repos/kevpl/beaker/issues/events{/number}","events_url":"https://api.github.com/repos/kevpl/beaker/events","assignees_url":"https://api.github.com/repos/kevpl/beaker/assignees{/user}","branches_url":"https://api.github.com/repos/kevpl/beaker/branches{/branch}","tags_url":"https://api.github.com/repos/kevpl/beaker/tags","blobs_url":"https://api.github.com/repos/kevpl/beaker/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/kevpl/beaker/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/kevpl/beaker/git/refs{/sha}","trees_url":"https://api.github.com/repos/kevpl/beaker/git/trees{/sha}","statuses_url":"https://api.github.com/repos/kevpl/beaker/statuses/{sha}","languages_url":"https://api.github.com/repos/kevpl/beaker/languages","stargazers_url":"https://api.github.com/repos/kevpl/beaker/stargazers","contributors_url":"https://api.github.com/repos/kevpl/beaker/contributors","subscribers_url":"https://api.github.com/repos/kevpl/beaker/subscribers","subscription_url":"https://api.github.com/repos/kevpl/beaker/subscription","commits_url":"https://api.github.com/repos/kevpl/beaker/commits{/sha}","git_commits_url":"https://api.github.com/repos/kevpl/beaker/git/commits{/sha}","comments_url":"https://api.github.com/repos/kevpl/beaker/comments{/number}","issue_comment_url":"https://api.github.com/repos/kevpl/beaker/issues/comments{/number}","contents_url":"https://api.github.com/repos/kevpl/beaker/contents/{+path}","compare_url":"https://api.github.com/repos/kevpl/beaker/compare/{base}...{head}","merges_url":"https://api.github.com/repos/kevpl/beaker/merges","archive_url":"https://api.github.com/repos/kevpl/beaker/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/kevpl/beaker/downloads","issues_url":"https://api.github.com/repos/kevpl/beaker/issues{/number}","pulls_url":"https://api.github.com/repos/kevpl/beaker/pulls{/number}","milestones_url":"https://api.github.com/repos/kevpl/beaker/milestones{/number}","notifications_url":"https://api.github.com/repos/kevpl/beaker/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/kevpl/beaker/labels{/name}","releases_url":"https://api.github.com/repos/kevpl/beaker/releases{/id}","deployments_url":"https://api.github.com/repos/kevpl/beaker/deployments","created_at":"2014-10-08T18:55:37Z","updated_at":"2016-03-10T17:41:11Z","pushed_at":"2016-07-26T17:06:11Z","git_url":"git://github.com/kevpl/beaker.git","ssh_url":"git@github.com:kevpl/beaker.git","clone_url":"https://github.com/kevpl/beaker.git","svn_url":"https://github.com/kevpl/beaker","homepage":null,"size":12212,"stargazers_count":0,"watchers_count":0,"language":"Ruby","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"puppetlabs:master","ref":"master","sha":"cdb3aa5b2d0cc0711403f8ffb248a2a2e0684445","user":{"login":"puppetlabs","id":234268,"avatar_url":"https://avatars.githubusercontent.com/u/234268?v=3","gravatar_id":"","url":"https://api.github.com/users/puppetlabs","html_url":"https://github.com/puppetlabs","followers_url":"https://api.github.com/users/puppetlabs/followers","following_url":"https://api.github.com/users/puppetlabs/following{/other_user}","gists_url":"https://api.github.com/users/puppetlabs/gists{/gist_id}","starred_url":"https://api.github.com/users/puppetlabs/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/puppetlabs/subscriptions","organizations_url":"https://api.github.com/users/puppetlabs/orgs","repos_url":"https://api.github.com/users/puppetlabs/repos","events_url":"https://api.github.com/users/puppetlabs/events{/privacy}","received_events_url":"https://api.github.com/users/puppetlabs/received_events","type":"Organization","site_admin":false},"repo":{"id":12164675,"name":"beaker","full_name":"puppetlabs/beaker","owner":{"login":"puppetlabs","id":234268,"avatar_url":"https://avatars.githubusercontent.com/u/234268?v=3","gravatar_id":"","url":"https://api.github.com/users/puppetlabs","html_url":"https://github.com/puppetlabs","followers_url":"https://api.github.com/users/puppetlabs/followers","following_url":"https://api.github.com/users/puppetlabs/following{/other_user}","gists_url":"https://api.github.com/users/puppetlabs/gists{/gist_id}","starred_url":"https://api.github.com/users/puppetlabs/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/puppetlabs/subscriptions","organizations_url":"https://api.github.com/users/puppetlabs/orgs","repos_url":"https://api.github.com/users/puppetlabs/repos","events_url":"https://api.github.com/users/puppetlabs/events{/privacy}","received_events_url":"https://api.github.com/users/puppetlabs/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/puppetlabs/beaker","description":"Puppet Acceptance Testing Harness","fork":false,"url":"https://api.github.com/repos/puppetlabs/beaker","forks_url":"https://api.github.com/repos/puppetlabs/beaker/forks","keys_url":"https://api.github.com/repos/puppetlabs/beaker/keys{/key_id}","collaborators_url":"https://api.github.com/repos/puppetlabs/beaker/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/puppetlabs/beaker/teams","hooks_url":"https://api.github.com/repos/puppetlabs/beaker/hooks","issue_events_url":"https://api.github.com/repos/puppetlabs/beaker/issues/events{/number}","events_url":"https://api.github.com/repos/puppetlabs/beaker/events","assignees_url":"https://api.github.com/repos/puppetlabs/beaker/assignees{/user}","branches_url":"https://api.github.com/repos/puppetlabs/beaker/branches{/branch}","tags_url":"https://api.github.com/repos/puppetlabs/beaker/tags","blobs_url":"https://api.github.com/repos/puppetlabs/beaker/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/puppetlabs/beaker/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/puppetlabs/beaker/git/refs{/sha}","trees_url":"https://api.github.com/repos/puppetlabs/beaker/git/trees{/sha}","statuses_url":"https://api.github.com/repos/puppetlabs/beaker/statuses/{sha}","languages_url":"https://api.github.com/repos/puppetlabs/beaker/languages","stargazers_url":"https://api.github.com/repos/puppetlabs/beaker/stargazers","contributors_url":"https://api.github.com/repos/puppetlabs/beaker/contributors","subscribers_url":"https://api.github.com/repos/puppetlabs/beaker/subscribers","subscription_url":"https://api.github.com/repos/puppetlabs/beaker/subscription","commits_url":"https://api.github.com/repos/puppetlabs/beaker/commits{/sha}","git_commits_url":"https://api.github.com/repos/puppetlabs/beaker/git/commits{/sha}","comments_url":"https://api.github.com/repos/puppetlabs/beaker/comments{/number}","issue_comment_url":"https://api.github.com/repos/puppetlabs/beaker/issues/comments{/number}","contents_url":"https://api.github.com/repos/puppetlabs/beaker/contents/{+path}","compare_url":"https://api.github.com/repos/puppetlabs/beaker/compare/{base}...{head}","merges_url":"https://api.github.com/repos/puppetlabs/beaker/merges","archive_url":"https://api.github.com/repos/puppetlabs/beaker/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/puppetlabs/beaker/downloads","issues_url":"https://api.github.com/repos/puppetlabs/beaker/issues{/number}","pulls_url":"https://api.github.com/repos/puppetlabs/beaker/pulls{/number}","milestones_url":"https://api.github.com/repos/puppetlabs/beaker/milestones{/number}","notifications_url":"https://api.github.com/repos/puppetlabs/beaker/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/puppetlabs/beaker/labels{/name}","releases_url":"https://api.github.com/repos/puppetlabs/beaker/releases{/id}","deployments_url":"https://api.github.com/repos/puppetlabs/beaker/deployments","created_at":"2013-08-16T17:57:03Z","updated_at":"2016-07-26T08:45:43Z","pushed_at":"2016-07-26T17:06:40Z","git_url":"git://github.com/puppetlabs/beaker.git","ssh_url":"git@github.com:puppetlabs/beaker.git","clone_url":"https://github.com/puppetlabs/beaker.git","svn_url":"https://github.com/puppetlabs/beaker","homepage":"https://groups.google.com/forum/#!forum/puppet-beaker","size":15708,"stargazers_count":250,"watchers_count":250,"language":"Ruby","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":228,"mirror_url":null,"open_issues_count":6,"forks":228,"open_issues":6,"watchers":250,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/puppetlabs/beaker/pulls/1197"},"html":{"href":"https://github.com/puppetlabs/beaker/pull/1197"},"issue":{"href":"https://api.github.com/repos/puppetlabs/beaker/issues/1197"},"comments":{"href":"https://api.github.com/repos/puppetlabs/beaker/issues/1197/comments"},"review_comments":{"href":"https://api.github.com/repos/puppetlabs/beaker/pulls/1197/comments"},"review_comment":{"href":"https://api.github.com/repos/puppetlabs/beaker/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/puppetlabs/beaker/pulls/1197/commits"},"statuses":{"href":"https://api.github.com/repos/puppetlabs/beaker/statuses/4c4c726f1fb958ad094bf5216444ec62550a0b3d"}}}}
{"actor":{"display_login":"er0ck"}}