effective_test_bot 0.4.11 → 0.4.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a8b43bf111914f08abc4410da5eadf651d907a3d
-  data.tar.gz: efbbff64442365fcd0225126a31bb4a4e63aeb9e
+  metadata.gz: 5ede27ddd554e49edc914d193530a5d0d90b1334
+  data.tar.gz: 30ad17c211358cf211bd583d58044a44ec4a8946
 SHA512:
-  metadata.gz: 786cf32fb1a1f4f2560cf63c517aea402240022e4b30bba82171f2704b23659bb6ac9e1aee5895e60f1eb8da33f67a7381dfa6fe5e95665412116378337393ad
-  data.tar.gz: 2e1af8e474b89eba76a43a01b8bdf6274e1b2faf3e07e2a59cc92529983552cbc6159326093abec4a6f372231365ca6e855abf9f120aeff876bb7f83b6aae800
+  metadata.gz: 13471d53e1e4cf34d78dae3b4802567c862c2eb93517b0503926fc367e7b42e3b7e9c1785ef5e74abb989e95facaccaa6846e7778db43717ac3a2e354566f7d4
+  data.tar.gz: 1d9b51c137546d51ef794dd2ed9e984e7fcc5bbba5e45c57882be783cf006f3dee0519450ca10c6be5d1f984e1496d1ae31c856a32a68285ec51c4bc3fdbacbe

data/README.md

@@ -2,27 +2,23 @@
 
 Stop testing and start test botting.
 
-A minitest library of capybara-webkit based feature tests that should pass in every Ruby on Rails application.
+A [minitest](https://github.com/seattlerb/minitest) library of [capybara](https://github.com/jnicklas/capybara) based feature tests that should pass in every Ruby on Rails application.
 
-Adds many additional minitest assertions and capybara quality of life helper functions.
+Adds many additional assertions and quality of life helper functions.
 
-Provides a curated set of minitest/capybara/rails testing gems and a well configured `test_helper.rb` minitest file.
+Provides a curated set of minitest and capybara focused rails testing gems and a well configured `test_helper.rb` file.
 
-Includes a rake task to validate your testing environment.
+Run `rake test:bot:environment` to validate your testing environment.  Ensures that all fixtures and seeds are properly initialized.  Makes sure database transactions and web sessions correctly reset between tests.
 
-Ensures that all fixtures and seeds are properly initialized.  Makes sure database transactions and web sessions correctly reset between tests.
+Adds many class and instance level 1-liners to run entire test suites and check many assertions all at once.
 
-Provides a DSL of class and instance level 1-liners that run entire test suites, checking many assertions all at once.
+Autosaves an animated .gif for any failing test.
 
-Autosaves an animated gif for any failing test.
+Run `rake test:bot` to automatically check every route in your application against an appropriate test suite, without writing any code.  Clicks through every page, intelligently fills forms with appropriate pseudo-random input and checks for all kinds of errors and omissions.
 
-Run `rake test:bot` to automatically check every route in your application against an appropriate test suite, without writing any code.
+Turn on tour mode to programatically generate an animated .gif of every workflow in your website.
 
-Automatically fills forms with appropriate pseudo-random input, and checks for all kinds of errors and omissions along the way.
-
-Turn on tour mode to automatically generate animated gifs of every part of your website.
-
-Makes sure everything actually works.
+Make sure everything actually works.
 
 ## Getting Started
 
@@ -50,27 +46,27 @@ end
 
 Run the bundle command to install it:
 
-```console
+```
 bundle install
 ```
 
 Install the configuration file:
 
-```console
+```
 rails generate effective_test_bot:install
 ```
 
-The generator will run `minitest:install` if minitest is not already present and create an initializer file which describes all configuration options.
+The generator will run `minitest:install` if not already present and create an initializer file which describes all config options.
 
-Fixture or seed one user:
+Fixture or seed one user. At least one user -- ideally a fully priviledged admin type user -- must be created.
 
-effective_test_bot requires that at least one user -- ideally a fully priviledged admin type user -- be available in the testing environment.
+(there are future plans to make this better.  Right now `rake test:bot` just runs everything as one user.  There really isn't support for 'this user should not be able to' yet.)
 
-* There are future plans to make this better.  Right now `rake test:bot` just runs everything as one user.  There really isn't support for 'this user should not be able to'. yet.
+To create the initial user, please add it to either `test/fixtures/users.yml`, the `db/seeds.db` file or the effective_test_bot specific `test/fixtures/seeds.rb` file.
 
-As per the `test/test_helper.rb` default file, when minitest and/or effective_test_bot starts, following tasks are run:
+As per the included `test/test_helper.rb`, the following tasks run when minitest starts:
 
-```ruby
+```
 # Rails default task, load fixtures from test/fixtures/*.yml (including users.yml if it exists)
 rake db:fixtures:load
 
@@ -83,66 +79,66 @@ rake test:load_fixture_seeds
 
 Your initial user may be created by any of the above 3 tasks.
 
-Test that your testing environment is set up correctly:
-
-Run `rake test:bot:environment` and make sure all the tests pass.
+Finally, to test that your testing environment is set up correctly run `rake test:bot:environment` and have all tests pass.
 
 You now have effective_test_bot configured and you're ready to go.
 
 # How to use this gem
 
-Effective TestBot is a 3-layered cake of testing deliciousness.
+Effective TestBot provides 4 areas of support in writing [minitest](https://github.com/seattlerb/minitest) [capybara](https://github.com/jnicklas/capybara) tests. As a developer, use this gem to:
+
+1.) Enjoy a whole bunch of individual assertions and quality of life helper functions.
 
-The bottom layer consists of advanced individual minitest assertions and capybara quality of life helper functions.
+2.) Call one-liner methods to run test suites (10-50+ assertions) against a page, or use these methods to build larger tests.
 
-The middle layer is a meta testing DSL -- 1-liners for you to use in your regular minitest tests that run entire test suites (10-50+ assertions) against a page or controller.
+3.) Produce animated .gifs of test runs. Enable autosave_animated_gif_on_failure to help debug a tricky test, or run in tour mode and record walkthroughs of features.
 
-The final layer builds on the bottom two, run `rake test:bot` to scan every route in your application and choose an appropriate test suite to run.
+4.) Apply full stack automated testing. Just run `rake test:bot` to scan every route in your application and without writing any code check every controller action with an appropriate test suite.
 
 ## Minitest Assertions
 
-The following assertions are added for use in any minitest & capybara integration test:
+The following assertions are added for use in any integration test:
 
-- `assert_signed_in` visits the devise `new_user_session_path` and checks for the `devise.failure.already_authenticated` content
-- `assert_signed_out` visits the devise `new_user_session_path` and checks for absense of the `devise.failure.already_authenticated` content
-- `assert_page_title` makes sure there is an html <title></title> present
-- `assert_submit_input` makes sure there is an input[type='submit'] present
+- `assert_signed_in` visits the devise `new_user_session_path` and checks for the already signed in content.
+- `assert_signed_out` visits the devise `new_user_session_path` and checks for the sign in content.
+- `assert_page_title` makes sure there is an html `<title></title>` present.
+- `assert_submit_input` makes sure there is an `input[type='submit']` present.
 - `assert_page_status` checks for a given http status, default 200.
-- `assert_current_path(path)` asserts the current page path
-- `assert_redirect(from_path)` optionally with to_path, makes sure the current page path is not from_path
-- `assert_no_js_errors` - checks for any javascript errors on the page
+- `assert_current_path(path)` asserts the current page path.
+- `assert_redirect(from_path)` optionally with to_path, makes sure the current page path is not from_path.
+- `assert_no_js_errors` - checks for any javascript errors on the page.
 - `assert_no_unpermitted_params` makes sure the last submitted form did not include any unpermitted params and prints out any unpermitted params that do exist.
-- `assert_no_exceptions` checks for any exceptions in the last page request and gives a stacktrace if there was
-- `assert_no_html_form_validation_errors` checks for frontend html5 errors
-- `assert_jquery_ujs_disable_with` makes sure all input[type=submit] elements on the page have the data-disable-with property set
-- `assert_flash` optionally with the desired :success, :error key and/or message, makes sure the flash is set
-- `assert_assigns` asserts a given rails view_assigns object is present
-- `assert_no_assigns_errors` use after a form submit to make sure your assigned rails object has no errors.  Prints out any errors if they exist.
+- `assert_no_exceptions` checks for any exceptions in the last page request and gives a stacktrace if there was.
+- `assert_no_html_form_validation_errors` checks for frontend html5 errors.
+- `assert_jquery_ujs_disable_with` makes sure all `input[type=submit]` elements on the page have the `data-disable-with` property set.
+- `assert_flash`, optionally with the desired `:success`, `:error` key and/or message, makes sure the flash is set.
+- `assert_assigns` asserts a given rails view_assigns object is present.
+- `assert_no_assigns_errors` should be used after any form submit to make sure your assigned rails object has no errors.  Prints out any errors if they exist.
 - `assert_assigns_errors` use after an intentionally invalid form submit to make sure your assigned rails object has errors, or a specific error.
 
+As well,
+
+- `assert_page_normal` checks for general errors on the current page.  Checks include  `assert_no_exceptions`, `assert_page_status`, `assert_no_js_errors`, and `assert_page_title`.
+
 ## Capybara Extras
 
-The following quality of life helpers are added for use in any minitest & capybara integration test:
+The following quality of life helpers are added by this gem:
 
 ### fill_form
 
-Finds all the input, select and textarea form fields on the current page and fills them with pseudo-random appropriate values.
+Finds all input, select and textarea form fields and fills them with pseudo-random but appropriate values.
 
-Detects names, addresses, start and end dates, telephone numbers, postal and zip codes, file, price, email, numeric, password and password confirmation fields. Probably more.
+Intelligently fills names, addresses, start and end dates, telephone numbers, postal and zip codes, file, price, email, numeric, password and password confirmation fields. Probably more.
 
 Will only fill visible fields that are currently visible and not disabled.
 
 If a selection made in one field changes the visibility/disabled of fields later in the form, those fields will be properly filled.
 
-It works with the [cocoon](https://github.com/nathanvda/cocoon), [select2](https://select2.github.io/) and [effective_assets](https://github.com/code-and-effect/effective_assets) gems.
-
-It will click through bootstrap tabs and fill them left-to-right one tab at a time.
+It clicks through bootstrap tabs and fill them nicely left-to-right, one tab at a time, and knows how to work with [cocoon](https://github.com/nathanvda/cocoon), [select2](https://select2.github.io/) and [effective_assets](https://github.com/code-and-effect/effective_assets) form fields.
 
 You can pass a Hash of 'fills' to specify specific input values:
 
 ```ruby
-require 'test_helper'
-
 class PostTest < ActionDispatch::IntegrationTest
   test 'creating a new post' do
     visit new_post_path
@@ -166,156 +162,409 @@ The `min` and `max` html properties are considered when filling in any numeric f
 
 If there are 2 or more numeric inputs that end with the same jquery selector, the fields will be filled so that their sum will match the html `max` value.
 
-You can scope the fill_form to a particular area of the page by using the regular capybara `within` `do..end` block
+You can scope the fill_form to a particular area of the page by using the regular `within` `do..end` block
 
 ### submit_form
 
-As well as just click on the `input[type='submit']` button (or optional label), this helper also checks:
-- `assert_no_html5_form_validation_errors`
-- `assert_jquery_ujs_disable_with`
-- `assert_no_unpermitted_params`
+Clicks the first `input[type='submit']` field (or first submit field with the given label) and submits the form.
+
+Automatically checks for `assert_no_html5_form_validation_errors`, `assert_jquery_ujs_disable_with` and `assert_no_unpermitted_params`
+
+```ruby
+class PostTest < ActionDispatch::IntegrationTest
+  test 'creating a new post' do
+    visit(new_post_path) and fill_form
+    submit_form    # or submit_form('Save and Continue')
+  end
+end
+```
 
 ### other helpers
 
-- `submit_novalidate_form` will use javascript to disable all required fields, and submit a form without client side validation.
+- `submit_novalidate_form` submits the form without client side validation, ignoring any required field requirements.
 - `clear_form` clears all form fields, probably used before `submit_novalidate_form` to test invalid form submissions.
 - `sign_in(user)` optionally with user, signs in via `Warden::Test::Helpers` hacky login skipping method.
-- `sign_in_manually(user, password)` visits the devise `new_user_session_path` and signs in via the form
+- `sign_in_manually(user, password)` visits the devise `new_user_session_path` and signs in via the form.
 - `sign_up` visits the devise `new_user_registration_path` and signs up as a new user.
-- `as_user(user) do .. end` yields a block between `sign_in`, and `logout`
-- `synchronize!` should fix any timing issues waiting for capybara elements
+- `as_user(user) do .. end` yields a block between `sign_in`, and `logout`.
+- `synchronize!` should fix any timing issues waiting for page elements.
 - `was_redirect?` returns true/false if the last time we changed pages was a 304 redirect.
 - `was_download?` if clicking a link returned a file of any type rather than a page change.
 
 ## Capybara Super Extras
 
-So the problem with running integration tests with capybara-webkit is that it's a real full black-box integration test.
+Running integration tests with [capybara-webkit](https://github.com/thoughtbot/capybara-webkit) is truly a black-box integration testing experience.  This provides a lot of benefits, but also some severe limitations.
 
-Capybara runs in a totally separate process.  It knows nothing about your rails app.  You can't get access to any of the rails internal state. All you can test is html, javascript and urls. That really sucks.
+The test web server runs in a totally separate process.  It knows nothing about your application and it does not have access to any of the rails internal state. It only sees html, javascript, css and urls.
 
-effective_test_bot mixes in a rails controller include and does a bit of http header hackery to make available to capybara the internal rails state values that are just so handy.
+effective_test_bot fills in this knowledge gap by serializing any interesting values within the http header.  This gives our tests a way to peek inside the black box.
 
-The following are refreshed on each page change, and are available to check anywhere in your tests.
+The following representations of the rails internal state are made available:
 
-- `flash` a Hash representation of the current page's flash
-- `assigns` a Hash representation of the current page's rails `view_assigns`. Serializes any ActiveRecord objects, as well as any TrueClass, FalseClass, NilClass, String, Symbol, Numeric objects.  Does not serialize anything else, but sets a symbol `assigns[key] == :present_but_not_serialized`.
+- `assigns` a Hash representation of the current page's rails `view_assigns`. Serializes any `ActiveRecord` objects, as well as any `TrueClass`, `FalseClass`, `NilClass`, `String`, `Symbol`, and `Numeric` objects.  Does not serialize anything else, but sets a symbol `assigns[key] == :present_but_not_serialized`.
 - `exceptions` an Array with the exception message and a stacktrace.
-- `unpermitted_params` an Array of any unpermitted paramaters that were encountered by the last request
+- `flash` a Hash representation of the current page's flash.
+- `unpermitted_params` an Array of any unpermitted parameters that were encountered by the last request.
+
+## Effective Test Suites
+
+Each of the following test suites make 10-50+ assertions on a given page or controller action.  The idea is to check for every possible error or omission accross all layers of the stack.
+
+These may be used as standalone one-liners, in the style of [shoulda-matchers](https://github.com/thoughtbot/shoulda-matchers) and as helper methods to quickly build up more advanced tests.
+
+Each test suite has a class-level one-liner `x_test` and and one or more instance level `x_action_test` versions.
+
+### crud_test
+
+This test runs through the standard [CRUD](http://edgeguides.rubyonrails.org/getting_started.html) workflow of a given controller and checks that resource creation functions as expected -- that all the model, controller, views and database actually work -- and tries to enforce best practices.
+
+There are 9 different `crud_action_test` test suites that may be run individually. The one-liner `crud_test` runs all of them.
+
+The following instance level `crud_action_test` methods are available:
+
+- `crud_action_test(:index)` signs in as the given user, finds or creates a resource, visits `resources_path` and checks that a collection of resources has been assigned.
+- `crud_action_test(:new)` signs in as the given user, visits `new_resource_path`, and checks for a properly named form appropriate to the resource.
+- `crud_action_test(:create_invalid)` signs in as the given user, visits `new_resource_path` and submits an empty form. Checks that all errors are properly assigned and makes sure a new resource was not created.
+- `crud_action_test(:create_valid)` signs in as the given user, visits `new_resource_path`, and submits a valid form.  Checks for any errors and makes sure a new resource was created.
+- `crud_action_test(:show)` signs in as the given user, finds or creates a resource, visits `resource_path` and checks that the resource is shown.
+- `crud_action_test(:edit)` signs in as the given user, finds or creates a resource, visits `edit_resource_path` and checks that an appropriate form exists for this resource.
+- `crud_action_test(:update_invalid)` signs in as the given user, finds or creates a resource, visits `edit_resource_path` and submits an empty form.  Checks that the existing resource wasn't updated and that all errors are properly assigned and displayed.
+- `crud_action_test(:update_valid)` signs in as the given user, finds or creates a resource, visits `edit_resource_path` and submits a valid form. Checks for any errors and makes sure the existing resource was updated.
+- `crud_action_test(:destroy)` signs in as the given user, finds or creates a resource, visits `resources_path`.  It then finds or creates a link to destroy the resource and clicks the link.  Checks for any errors and makes sure the resource was deleted.  If the resource `respond_to?(:archived)` it will check for archive behavior instead of delete.
+
+Also,
+
+- `crud_action_test(:tour)` signs in as a given user and calls all the above `crud_action_test` methods from inside one test.  The animated .gif produced from this test suite records the entire process of creating, showing, editing and deleting a resource from start to finish.  It makes all the same assertions as running the test suites individually.
+
+
+A quick note on speed:  You can speed up these test suites by fixturing, seeding or first creating an instance of the resource being tested. Any tests that need to `find_or_create_resource` check for an existing resource first, otherwise visit `new_resource_path` and submit a form to create the resource.  Having a resource already created will speed things up.
+
+There are a few variations on the one-liner method:
+
+```ruby
+class PostsTest < ActionDispatch::IntegrationTest
+  # Runs all 9 crud_action tests against /posts
+  crud_test(Post, User.first)
+
+  # Runs all 9 crud_action tests against /posts and use this Post's attributes when calling fill_form.
+  crud_test(Post.new(title: 'my first post'), User.first)
+
+  # Runs all 9 crud_action tests against /admin/posts controller as a previously seeded or fixtured admin user
+  crud_test('admin/posts', User.where(admin: true).first)
+
+  # Run only some tests
+  crud_test(Post, User.first, only: [:new, :create_valid, :create_invalid, :show, :index])
+
+  # Run all except some tests
+  crud_test(Post, User.first, except: [:edit, :update_valid, :update_invalid])
 
-- `save_test_bot_screenshot` saves a screenshot of the current page to be added to the current test's animated gif (see screenshots and tour mode below).
+  # Skip individual assertions
+  crud_test(Post, User.first, skip: {create_valid: :path, update_invalid: [:path, :flash]})
+end
+```
+
+The individual test suites may also be used as part of a larger test:
+
+```ruby
+class PostsTest < ActionDispatch::IntegrationTest
+  test 'user may only update a post once' do
+    crud_action_test(:create_valid, Post, User.first)
+    assert_content 'successfully created post.  You may only update it once.'
+
+    crud_action_test(:update_valid, Post.last, User.first)
+    assert_content 'successfully updated post.'
+
+    crud_action_test(:update_valid, Post.last, User.first, skip: [:no_assigns_errors, :updated_at])
+    assert_assigns_errors(:post, 'you may no longer update this post.')
+    assert_content 'you may no longer update this post.'
+  end
+end
+```
+
+If your resource controller passes a `crud_test` you can be certain that your user is able to correctly create, edit, display and delete a resource without encountering any application errors.
+
+### devise_test
+
+This test runs through the the [devise](https://github.com/plataformatec/devise) sign up, sign in, and sign in invalid workflows.
+
+- `devise_action_test(:sign_up)` visits the devise `new_user_registration_path`, submits the sign up form and validates the `current_user`.
+- `devise_action_test(:sign_in)` creates a new user and makes sure the sign in process works.
+- `devise_action_test(:sign_in_invalid)` makes sure an invalid password is correctly denied.
+
+Use as a one-liner:
+
+```ruby
+class MyApplicationTest < ActionDispatch::IntegrationTest
+  devise_test  # Runs all tests (sign_up, sign_in_valid, and sign_in_invalid)
+end
+```
 
-## Test Bot DSL Methods
+Or each individually in part of a regular test:
 
-All of the following DSL methods use the assertions and capybara extras to build an entire test suite that runs against a given page or controller action.
+```ruby
+class MyApplicationTest < ActionDispatch::IntegrationTest
+  test 'user receives 10 tokens after signing up' do
+    devise_action_test(:sign_up)
+    assert_content 'Tokens: 10'
+    assert_equals 10, User.last.tokens
+    assert_equals 10, assigns(:current_user).tokens
+  end
+end
+```
+
+### member_test
+
+This test is intended for non-CRUD actions that operate on a specific instance of a resource.
+
+The action must be a `GET` with a required `id` value.  `member_test`-able actions appear as follows from `rake routes`:
+
+```
+unarchive_post  GET  /posts/:id/unarchive(.:format)  posts#unarchive
+```
 
-Right now the `crud_test` method is by far the most mature, with the other methods having had less development time.
+This test signs in as the given user, visits the given controller/action/page and checks `assert_page_normal` and `assert_assigns`.
 
-Each DSL method has a class level `x_test` and an instance level `x_action_test` version of each.
+Use it as a one-liner:
 
 ```ruby
-require 'test_helper'
+class PostsTest < ActionDispatch::IntegrationTest
+  # Uses find_or_create_resource! to load a seeded resource or create a new one
+  member_test('posts', 'unarchive', User.first)
+
+  # Run the member_test with a specific post
+  member_test('posts', 'unarchive', User.first, Post.find(1))
+end
+```
+
+Or as part of a regular test:
 
+```ruby
 class PostsTest < ActionDispatch::IntegrationTest
-  page_test(:posts_path, User.first)  # Runs the page_test test suite against posts_path (class level) as User.first
+  test 'posts can be unarchived' do
+    post = Post.create(title: 'first post', archived: true)
+
+    assert Post.where(archived: false).empty?
+    member_action_test('posts', 'unarchive', User.first, post)
+    assert Post.where(archived: false).present?
+  end
+end
+```
+
+### page_test
+
+This test signs in as the given user, visits the given page and simply checks `assert_page_normal`.
+
+Use it as a one-liner:
+
+```ruby
+class PostsTest < ActionDispatch::IntegrationTest
+  page_test(:posts_path, User.first)  # Runs the page_test test suite against posts_path as User.first
+end
+```
+
+Or as part of a regular test:
+
+```ruby
+class PostsTest < ActionDispatch::IntegrationTest
+  test 'posts are displayed on the index page' do
+    Post.create(title: 'first post')
 
-  # Does the same thing.
-  # Runs the page_test suite against posts_path (instance level) as User.first
-  test 'my posts test' do
     page_action_test(:posts_path, User.first)
+
+    assert page.current_path, '/posts'
+    assert_content 'first post'
+  end
+end
+```
+
+### redirect_test
+
+This test signs in as the given user, visits the given page then checks `assert_redirect(from_path, to_path)` and `assert_page_normal`.
+
+Use it as a one-liner:
+
+```ruby
+class PostsTest < ActionDispatch::IntegrationTest
+  # Visits /blog and tests that it redirects to a working /posts page
+  redirect_test('/blog', '/posts', User.first)
+end
+```
+
+Or as part of a regular test:
+
+```ruby
+class PostsTest < ActionDispatch::IntegrationTest
+  test 'visiting blog redirects to posts' do
+    Post.create(title: 'first post')
+    redirect_action_test('/blog', '/posts', User.first)
+    assert_content 'first post'
   end
 end
 ```
 
-### Skipping assertions and tests
+### wizard_test
+
+This test signs in as the given user, visits the given initial page and continually runs `fill_form`, `submit_form` and `assert_page_normal` up until the given final page, or until no more `input[type=submit]` are present.
 
-Each of these DSL test suite methods are designed to assert an expected standard rails behaviour.
+It tests any number of steps in a wizard, multi-step form, or inter-connected series of pages.
 
-But sometimes a developer has a good reason for deviating from what is considered standard; therefore, each individual assertion is skippable.
+As well, in the `wizard_action_test`, each page is yielded to the calling method.
 
-When an assertion fails, the minitest output will look something like:
+Use it as a one-liner:
 
-```console
+```ruby
+class PostsTest < ActionDispatch::IntegrationTest
+  wizard_test('/build_post/step1', '/build_post/step5', User.first)
+end
+```
+
+Or as part of a regular test:
+
+```ruby
+class PostsTest < ActionDispatch::IntegrationTest
+  test 'building a post in 5 steps' do
+    wizard_action_test('/build_post/step1', '/build_post/step5', User.first) do
+      if page.current_path.end_with?('step4')
+        assert_content 'your post is ready but must first be approved by an admin.'
+      end
+    end
+  end
+end
+```
+
+## Skipping individual assertions or test suites
+
+Each of the test suites checks a page or pages for some expected behaviour.  Sometimes a developer has a good reason for deviating from what is expected and it's frustrating when just one assertion in a test suite fails.
+
+So, almost every individual assertion made by these test suites is skippable.
+
+When an assertion fails, the output will look something like:
+
+```
 crud_test: (users#update_invalid)                               FAIL (3.74s)
 
-Minitest::Assertion: (path) Expected current_path to match resource #update path.
-  Expected: "/users/562391275"
-  Actual: "/members/562391275"
+Minitest::Assertion: (current_path) Expected current_path to match resource #update path.
+  Expected: "/users/1"
+  Actual: "/members/1"
   /Users/matt/Sites/effective_test_bot/test/test_botable/crud_test.rb:155:in `test_bot_update_invalid_test'
 ```
 
-The `(path)` is the name of the specific assertion that failed.
+Here, the `(current_path)` is the name of the specific test bot assertion that failed.
 
-The expectation is that when submitting an invalid form at `/users/562391275/edit` we should be returned to the update action url `/users/562391275`, but in this totally reasonable but not-standard case we are redirected to `/members/562391275` instead.
+The expectation is that when submitting an invalid form at `/users/1/edit` we should be returned to the update action url `/users/1`, but in this totally reasonable but not-standard case we are redirected to `/members/1` instead.
 
-You can skip this specific assertion by adding it to the `app/config/initializers/effective_test_bot.rb` file:
+You can skip this assertion by adding it to the `app/config/initializers/effective_test_bot.rb` file:
 
 ```ruby
 EffectiveTestBot.setup do |config|
   config.except = [
-    'users#create_invalid path',  # Skips the path assertion for just the users#create_invalid test
-    'path'                        # Skips the path assertion entirely in all tests
+    'users#create_invalid current_path',  # Skips the current_path assertion for just the users#create_invalid test
+    'current_path',                       # Skips the current_path assertion entirely in all tests
+    'users#create_invalid'                # Skips the entire users#create_invalid test
   ]
 end
 ```
 
-There is support for skipping individual assertions as well as entire tests.
+There is support for skipping individual assertions, entire tests, or a combination of both.
 
-Please see the installed effective_test_bot.rb initializer file for a full description of all options.
+Please see the installed `effective_test_bot.rb` initializer file for a full description of all options.
 
-### crud_test
+## Testing the test environment
 
-TODO
+Unfortunately, with the current day ruby on rails ecosystem, simply getting a testing environment setup correctly is a non-trivial endeavor filled with gotchas and many things that can go wrong.
 
-### devise_test
+User sessions need to properly reset and database transactions must be correctly rolled back between tests.  Seeds and fixtures that were once valid may become invalid as the application changes.  Database migrations must stay up to date.  Capybara needs to query your app with a single shared connection or weird things start happening.
 
-TODO
+Included with this gem is the `rails generate effective_test_bot:install` that does its best to provide a known-good set of configuration files that initialize all required testing gems.  However, every developer's machine is different, and there are just too many points of failure.  Everyone's `test/test_helper.rb` will be slightly different.
 
-### page_test
+Run `rake test:bot:environment` to check that capybara is doing the right thing, everything is reset properly between test runs, an initial user record exists, all seeded and fixtured data is valid, devise works and rails' jquery-ujs is present.
 
-TODO
+If all environment tests pass, you will have a great experience with automated testing.
 
-### member_test
+## Automated full stack testing
 
-TODO
+One of the main goals of `effective_test_bot` is to increase the speed at which tests can be written in any ruby on rails application.  Well, there's no faster way of writing tests than by not writing them at all.
 
-### redirect_test
-
-TODO
+Run `rake test:bot` to scan every route defined in `routes.rb` and run an appropriate test suite.
 
-### wizard_test
+You can configure test bot to skip individual tests or assertions, tweak screenshot behaviour and toggle tour mode via the `config/initializers/effective_test_bot.rb` file.  As well, there are a few command line options available.
 
-TODO
+These are some quick ways to customize test bot's behaviour:
 
-## Automated Testing / Rake tasks
-
-```ruby
-rake test:bot:environment
+```
+# Scan every route in the application as per config/initializers/effective_test_bot.rb
 rake test:bot
+
+# Test a specific controller (any routes matching posts)
 rake test:bot TEST=posts
+
+# Test a specific controller and action
 rake test:bot TEST=posts#index
 ```
 
-TODO
+## Animated gifs and screenshots
+
+Call `save_test_bot_screenshot` from within any test to take a screenshot of the current page.  If an animated .gif is produced at the end of the test -- either from autosave_animated_gif_on_failure or tour mode -- this screenshot will be used as one of the frames in the animation.
+
+This method is already called by `fill_form` and `submit_form`.
 
-## Screenshots and Animated Gifs
+To disable taking screenshots entirely set `config.screenshots = false` in the `config/initializers/effective_test_bot.rb` initializer file.
 
-TODO
+### Autosave on failure
+
+The `test/test_helper.rb` file that is installed by `effective_test_bot` enables [capybara-screenshot](https://github.com/mattheworiordan/capybara-screenshot)'s `autosave_on_failure` functionality.  So whenever a test fails, the current html will be written and a .png screenshot will be saved.  This is invaluable for troubleshooting why a test has failed.
+
+Building on this type of feature, `effective_test_bot` will also autosave an animated gif on failure.  This does slow down failing tests and can be disabled.
 
 ### Tour mode
 
-```ruby
+When running in tour mode, an animated .gif image file, a "tour", will be created for all successful tests.
+
+This feature is slow, increasing the runtime of each test by almost 30%, but it's also really cool.
+
+You can run test bot in tour mode by setting `config.tour_mode = true` in the `config/initializers/effective_test_bot.rb` file or by running any variation of the following rake tasks:
+
+```
+# Run test:bot in tour mode, saving an animated .gif for all successful tests
 rake test:bot:tour
+rake test:bot TOUR=true
+
+# Also prints the animated .gif file path to stdout
+rake test:bot:tourv
+rake test:bot TOUR=verbose
+
+# Makes a whole bunch of extra screenshots when filling out forms
+rake test:bot TOUR=extreme
+
+# Runs in tour mode and tests only a specific controller or action
 rake test:bot:tour TEST=posts
-rake test:bot:tourv # verbose mode
+rake test:bot:tour TEST=posts#index
 ```
 
-```ruby
-rake test:bot:tours # Prints out file location of all tour animated .gifs
-rake test:bot:purge # Deletes all tour and failure animated .gifs
+To print out the file location of all tour files, run the following:
+
+```
+# Prints out all animated .gif file locations
+rake test:bot:tours
+
+# Prints out any animated .gif files locations with a file name matching posts
+rake test:bot:tours TEST=posts
+```
+
+To delete all tour and autosave on failure animated .gifs, run the following:
+
+```
+# Deletes all tour and failure animated .gifs
+rake test:bot:purge
 ```
 
-TODO
+As well, to enable tour mode when running the standard `rake test`:
 
+```
+# Runs all regular minitest tests with tour mode enabled
+rake test:tour
+rake test:tourv
+```
 
 ## License
 

data/lib/effective_test_bot/version.rb

@@ -1,3 +1,3 @@
 module EffectiveTestBot
-  VERSION = '0.4.11'.freeze
+  VERSION = '0.4.12'.freeze
 end

data/lib/generators/templates/effective_test_bot.rb

@@ -5,13 +5,14 @@ if Rails.env.test?
 
     # Exclude the following tests or assertions from being run.
     # config.except = [
-    #   'widgets'
-    #   'posts#create_invalid'
-    #   'posts#index page_title'
+    #   'widgets',
+    #   'posts#create_invalid',
+    #   'posts#index page_title',
+    #   'posts#update_invalid' => ['page_title', 'current_path'],
     #   'no_unpermitted_params'
     # ]
 
-    # Run only the following tests.  Doesn't work with individual assertions>
+    # Run only the following tests.  Doesn't work with individual assertions
     # config.only = [
     #   'posts', 'events#index'
     # ]

data/test/support/effective_test_bot_assertions.rb

@@ -110,7 +110,7 @@ module EffectiveTestBotAssertions
 
   # assert_assigns
   # assert_assigns :current_user
-  # assert_assigns :current_user, true
+  # assert_assigns :current_user, 'there should a current user'
   def assert_assigns(key = nil, value = nil, message = nil)
     if key.present? && value.present?
       assert_equal value, assigns[key.to_s], message || "(assigns) Expected assigns[#{key}] to equal #{value}. Instead, it was: #{value}"

data/test/test_bot/integration/application_test.rb

@@ -1,5 +1,8 @@
 require 'test_helper'
 
+# This gets run when we type `rake test:bot`
+# Scan through every route and run a test suite against it
+
 module TestBot
   class ApplicationTest < ActionDispatch::IntegrationTest
     CRUD_ACTIONS = %w(index create new edit show update destroy) # Same order as resources :object creates them in

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: effective_test_bot
 version: !ruby/object:Gem::Version
-  version: 0.4.11
+  version: 0.4.12
 platform: ruby
 authors:
 - Code and Effect
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-12-17 00:00:00.000000000 Z
+date: 2016-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails