Add better documentation for system tests

[aried3r]

Hey! I was really happy to see RSpec 3.7 was released with support for ActionDispatch::SystemTest. Great work!

However I'm not sure what the recommended way of using them is. The README has no mention of them but in one of the commits there's a small note about usage.

One of the first questions I had were:
– Can I do something similar to having application_system_test_case.rb? The note in the commit only says it's not used and that you have to call it manually in a test case. What if I want a global config for type: :system specs?
– Are the other helpers like the screenshot helper included (it appears so? As in, is RSpec really just a thin wrapper around the system tests and besides not being able to use application_system_test_case.rb everything works as expected and I just need to follow the Rails docs?
– Speaking of thin wrappers, when Rails 5.2 is released, will using :chrome_headless just work as a driver or will there have to be a change and new release of rspec-rails as well?

Since a lot of work went into system tests, I just want to make sure I don't miss out on it when using RSpec as a wrapper around them. :)

[JonRowe]

– Can I do something similar to having application_system_test_case.rb? The note in the commit only says it's not used and that you have to call it manually in a test case. What if I want a global config for type: :system specs?

Yes, RSpec has it's own configuration which has existed since long before system tests, you should just be able to do the equivalent in before(:suite) hook.

Are the other helpers like the screenshot helper included (it appears so? As in, is RSpec really just a thin wrapper around the system tests and besides not being able to use application_system_test_case.rb everything works as expected and I just need to follow the Rails docs?

They should do, application_system_test_case.rb just doesn't make sense in RSpecs world.

Speaking of thin wrappers, when Rails 5.2 is released, will using :chrome_headless just work as a driver or will there have to be a change and new release of rspec-rails as well?

I'd assume so, given we have nothing to do with driver selection.

[grepsedawk]

@Xosmond Tests are ran in transactions now so you shouldn't need DB cleaner

[amandapouget]

We are getting a ton of intermittent failures with system tests, latest Rspec-Rails and latest Rails.

Documentation would be extremely helpful. Lots of SO answers saying "you shouldn't need DB cleaner" aren't helpful... We shouldn't need it if we've configured things correctly. What is correctness?

Hence, need for documentation.

[JonRowe]

The docs for system testing are here: http://guides.rubyonrails.org/testing.html#system-testing but if someone would like to include some better docs within rspec's own I'll happily review a PR. Remember rspec-rails does not provide or configure this functionality, just exposes it.

[Xosmond]

@JonRowe I think I can do that the next week, because this project is rspec-rails not rspec.

PD: My old problem was the multi tenant gem that doesn't fit good on system tests with rspec.

[ooffeerr]

Hi! Is this issue still up for grabs?

[JonRowe]

As far as I know!

[fables-tales]

#2052 If you're going to add further documentation, this PR is a good place to start!

[andrewshawcare]

With ApplicationSystemTestCase I can turn off screenshots by doing this: https://stackoverflow.com/a/44337280

If RSpec does not use ApplicationSystemTestCase, how do I turn off screenshots?

[JonRowe]

You can define the same method within a spec to achieve that, e.g.

module DisableScreenshots
  def take_screenshot
    false
  end
end
RSpec.configuration.include DisableScreenshots, type: :system