[ci skip]

WIP: Capybara Integration with Rails (AKA System Tests)

Prevent multiple values being set to `run_via`

Pointed out by @matthewd that the HWIA subclass changes the
AS scoped class and top-level HWIA hierarchies out from under
existing classes.

This reverts commit 71da3909, reversing
changes made to 41c33bd4.

There were some grammar issues and incorrect information in the system
tests documentation.

This renames the system test helper file to be application system test
case to match what the rest of Rails does. In the future we should
consider changing the test_helper to match.

* Override integration test default host

Integration tests automatically set the default host to
'http://example.com'. This works fine for integration tests because they
are not real browser sessions, but doesn't work fine for system tests
because they are real browser sessions.

We can override this by setting the `host!` in `before_setup. The
`Capybara.always_include_port` will allow the test to look at
`127.0.0.1:port capybara picks` and properly redirect the test.

Any application can override this by setting the `host!` in
their system test helper. Generally though, applications are going to be
using localhost.

In this commit I also moved the setup and teardown into their own module
for tidiness.

* Move teardown settings into system test case

These configuration options can be put into the system test case file
instead of the generated system tests helper file. This is an
implementation detail and therefore shouldn't be generated with the
template.

We only want the file name to include the word `failures` if it failed,
not any time the user wants to take a screenshot during a test run.

This serves as self documentation so users know how to change the
driver.

* Move system tests back into Action Pack
* Rename `ActionSystemTest` to `ActionDispatch::SystemTestCase`
* Remove private base module and only make file for public
`SystemTestCase` class, name private module `SystemTesting`
* Rename `ActionSystemTestCase` to `ApplicationSystemTestCase`
* Update corresponding documentation and guides
* Delete old `ActionSystemTest` files

I've renamed the server to `rails_puma` so that it doesn't override
Capybara's default puma server. I've also removed the hard port setting.
Users can simply use `Capybara.server_port` writer to set the port if
they require that.

Update the documentation after rewriting a majority of the functionality
for system testing.

This is a major rewrite of what existed previously. After discussing
this feature with DHH I realized that I was looking at the setup all
wrong.

I had originally mentally broken it into "what Rails wants" and "what
Capybara already has".

What happened after looking at it from DHH's angle was that I saw there
was no reason to group settings by Driver but instead the following
groups:

- There will always be a `Driver`
  - This can selenium, poltergeist, or capybara webkit. Capybara already
    provides all of these and there's no reason to break them into a
    category of Rails' usese Selenium like this and Capybara uses it
    like that.
- Only Selenium drivers care about `Browser`
  - Because of this it was weird to set it only in the Rails end.
  - Therefore only `Browser`, and not `Driver` cares about
    `screen_size`.
- Puma is the default `Server` in Rails
  - Therefore there's no reason to explictly support Webkit

Once I looked at it from this angle I was able to abstract all the
settings away from grouping the drivers with their options.

Now all the driver, server, and browser settings are abstracted away and
not part of the public facing API.

This means there's no requirement to initialize new classes to change
the default settings and the public options API is much smaller.

All of Rails preferred defaults are still there (selenium with port
21800 using the chrome browser with a screen size of 1400x1400) but
changing these no longer requires initializing a new class or
understanding which driver you're using underneath (rails defaults or
capybaras defaults respectively). Rails opinions are now simple defaults
instead of doing a them versus us setup with Drivers and explicit
options.

Changing the defaults is simple. Call `driven_by` with different
settings to change the defaults which will on their own initialize new
classes and change the default settings.

Use poltergeist with port 3000 for Puma

```
driven_by :poltergeist, on: 3000
```

Use selenium with the Chrome browser and a screen size of 800x800
```
driven_by :selenium, using: :firefox, screen_size: [ 800, 800 ]
```

The entire setup of how browser and drivers interact with each other are
abstracted away and the only required argument is the driver name.

This adds the required guides for how to write and use system tests in
your application.

1. Clean up screenshot helper

Updates documentation to be clearer and separates the concerns of saving
the image, setting the image path, and displaying the image.

2. Remove Rails provided assertions for selectors

This was moved upstream to Capybara and is no longer necessary to be
included in Rails

3. Remove form helper

The form helper is pretty specific to Basecamp's needs and may not be
helpful outside of Rails.

Since I've moved the teardown code that contains the screenshot handling
to be generated when the application is generated this code was
interfering with the screenshot taking.

Because this runs before any app teardown code we would be resetting
sessions before taking the screenshot, resulting in a blank browser
window. The code to reset the sessions must come AFTER a screenshot has
been taken.

If this is not set Webrick will log **everything** to STDOUT and
distract from the running tests. This will instead log to the log file.
This example was extracted from the Capybara source code.

Call doesn't make as much sense here, we're really starting to run the
driver.

Many changes have been made since the beginning so documentation needed
a refresher.

Originally I had set up system testing to have one configuration option
to be set in the test environment. After thinking it over I think a
generated class on app creation would be best. The reason for this is
Capybara has a ton of configuration options that I'm sure some folks
want to use.

Thinking about how we handle screenshots, database transactions, and a
whole bunch of other settings it would be better for users to be able to
turn all of that on and off.

When an app or scaffold is generated a `test/system_test_helper.rb` test
helper will be generated as well. This will contain the class for tests
to inherit from `ActionSystemTestCase` which will inherit from
`ActionSystemTest::Base`. Here is where users can change the test
driver, remove the screenshot helper, and add their additional Capybara
configuration.

By moving to the TestUnit Railtie, and doing the file requirement
inside the onload call we can avoid loading ActionSystemTest in
production and load it in the test env.

This is important for performance reasons - loading up unnecessary files
and object is expensive, especially when they should never be used in
production.

Renames `Rails::SystemTestCase` to `ActionSystemTest` and moves it to a
gem under the Rails name.

We need to name the class `ActionSystemTestCase` because the gem expects
a module but tests themselves expect a class.

Adds MIT-LICENSE, CHANGELOG, and README for the future.

Rubocop / code climate don't like single quotes and prefer doubles.

Puma is the default webserver of Rails. Because of this it doesn't make
sense to run tests in Webkit if the default server is Puma.

Here I've refactored the webserver to be it's own standalone module so
it can be shared between Rails' selenium default driver and Capybara's
defaut drivers.

This change adds support, tests, and documentation for the screenshot
helper.

If taking screenshots is supported by the driver (for example Rack Test
doesn't support screenshots) then a screenshot will be taken if the test
fails.

This removes the useless Rack Test Driver that Rails was providing and
moves to a shim like approach for default adapters.

If someone wants to use one of the default Capybara Drivers then we will
initialize a new `CapybaraDriver` that simply sets the default driver.

Rails though is much more opinionated than Capybara and to make system
testing a "works out of the box" framework in Rails we have the
`RailsSeleniumDriver`. This driver sets defaults that Rails deems
important for selenium testing. The purpose of this is to simply add a
test and it just works.

* Document Rails::SystemTestCase
* Document setting drivers with the configration options
* Document using the getter/setter for driver adapters
* Document the CapybaraRackTestDriver and defaults
* Document the CapybaraSeleniumDriver and defaults
* Document custom assertions provided by System Testing
* Document custom form helpers provided by System Testing

* Adds test case test
* Adds driver adapter test
* Adds tests for capybara seleium driver (testing the settings not
actually opening the browser to test capybara w/ selenium because that
would so so so slow)
* Adds tests for rack test driver
* Adds tests for generators

This will clean up the railtie quite a bit, rather than passing a set of
hash keys call the new class directly like we do with ActiveJob.

Only call driver once when tests start rather than in every single test
setup. This is more performant, and the other way was creating
unnecessary calls.

There's no real benefit to the using the `Base` class here because
`SystemTestCase` is already a very small class.

Rails itself is not a Rails application so instead of including
`capybara/rails` we should use the code in there to set up the test. The
only reason capybara needs to include capybara/rails in the first place
is because Rails didn't yet support it.

This makes it easier to ask the system test what driver adapter it is
currently using, and makes it easier to change that setting when
necessary.

Integration tests already handle all the fancy url mapping we need to do
so inherting from that allows us to not need to reinvent the wheel in
terms of loading up the route handling required to use `visit
users_path` over `visit /users`.

Adds assertions that are not part of Capybara but may be useful to Rails
users writing system tests.

This allows any application to change the driver adapter based on the
config settings in the test env.

These FormHelpers are selectors that aren't a capybara default but are
considered useful for Rails applications.

This is not yet configurable but is the minimum required to make
Capybara work with the Selenium driver. A lot of this will change as the
tests get fleshed out and the initialization requirements will eventually
be configurable via the application.

Capybara defaults to Rack Test for it's driver and works out of the box
but this adds the headers and allows for future configurable adapters
for system testing.