kotovalexarian-likes-github/rails--rails
1
0
Fork 0
mirror of https://github.com/rails/rails.git synced 2022-11-09 12:12:34 -05:00
Code Releases Activity

Update documentation and guides

Browse source 
Update the documentation after rewriting a majority of the functionality
for system testing.
This commit is contained in:
eileencodes 2017-02-10 09:13:48 -05:00
parent 3dfbe7e4e5
commit 893c3b6282
5 changed files with 193 additions and 201 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

76
actionsystemtest/README.md
View file

@ -1,8 +1,10 @@
# Action System Test
Action System Test adds Capybara integration to your Rails application for
acceptance testing. This allows you to test the entire user experience
of your application rather than just your controllers, or just your models.
Action System Test adds Capybara integration to your Rails application and makes
it possible to test your application and it's JavaScript interactions.
This allows you to test the entire user experience of your application rather
than your controllers, models, and views separately.
Action System Test provides all of the setup out of the box for you to use
Capybara with the Selenium Driver in your Rails application. Changing the
@ -26,14 +28,14 @@ class UsersTest < ActionSystemTestCase
visit users_path
end
test 'creating a new user' do
click_on 'New User'
test "creating a new user" do
click_on "New User"
fill_in 'Name', with: 'Arya'
fill_in "Name", with: "Arya"
click_on 'Create User'
click_on "Create User"
assert_text 'Arya'
assert_text "Arya"
end
end
```
@ -44,8 +46,6 @@ it will fill in the "Name" field with "Arya" and click on the "Create User"
button. Lastly, we assert that the text on the Users show page is what we
expected, which in this case is "Arya".
For more helpers and how to write Capybara tests visit Capybara's README.
### Configuration
When generating a new application Rails will include the Capybara gem, the
@ -56,53 +56,47 @@ configuration if Rails doesn't work out of the box for you.
The <tt>system_test_helper.rb</tt> file provides a home for all of your Capybara
and Action System Test configuration.
Rails preset configuration for Capybara with Selenium defaults to Puma for
the web server on port 28100, Chrome for the browser, and a screen size of
1400 x 1400.
The default configuration uses the Selenium driver, with the Chrome browser,
served by Puma on port 21800 with a screen size of 1400x1400.
Changing the configuration is as simple as changing the driver in your
<tt>system_test_helper.rb</tt>
If you want to change the default settings of the Rails provided Selenium
configuration options you can initialize a new <tt>RailsSeleniumDriver</tt>
object.
you can change `driven_by` in the helper file.
The driver name is a required argument for `driven_by`. The optional arguments
that can be passed to `driven_by` are `:using` for the browser (this will only
be used for non-headless drivers like Selenium), `:on` for the port Puma should
use, and `:screen_size` to change the size of the screen for screenshots.
Below are some examples for changing the default configuration settings for
system tests:
Changing the browser, port for Puma, and screen size:
```ruby
class ActionSystemTestCase < ActionSystemTest::Base
ActionSystemTest.driver = RailsSeleniumDriver.new(
browser: :firefox,
server: :webrick
)
driven_by :selenium, using: :firefox, on: 3000, screen_size: [ 800, 800 ]
end
```
Capybara itself provides 4 drivers: RackTest, Selenium, Webkit, and Poltergeist.
Action System Test provides a shim between Rails and Capybara for these 4 drivers.
Please note, that Rails is set up to use the Puma server by default for these
4 drivers. Puma is the default in Rails and therefore is set as the default in
the Rails Capybara integration.
To set your application tests to use any of Capybara's defaults with no configuration,
set the following in your <tt>system_test_helper.rb</tt> file and follow setup instructions
for environment requirements of these drivers.
The possible settings are +:rack_test+, +:selenium+, +:webkit+, or +:poltergeist+.
The browser setting is not used by headless drivers like Poltergeist. When
using a headless driver simply leave out the `:using` argument.
```ruby
class ActionSystemTestCase < ActionSystemTest::Base
ActionSystemTest.driver = :poltergeist
driven_by :poltergeist, on: 3000
end
```
If you want to change the default server (puma) or port (28100) for Capbyara drivers
you can initialize a new object.
### Running the tests
Because system tests are time consuming and can use a lot of resources
they are not automatically run with `rails test`.
To run all the tests in the system suite run the system test command:
```ruby
class ActionSystemTestCase < ActionSystemTest::Base
ActionSystemTest.driver = ActionSystemTest::DriverAdapters::CapybaraDriver.new(
name: :poltergeist,
server: :webkit,
port: 3000
)
end
```
$ rails test:system
```

169
actionsystemtest/lib/action_system_test.rb
View file

@ -1,54 +1,25 @@
# System tests are similar to Integration tests in that they incorporate multiple
# controllers and actions, but can be used to simulate a real user experience.
# System tests are also known as Acceptance tests.
#
# To create a System Test in your application, extend your test class from
# <tt>ActionSystemTestCase</tt>. System tests use Capybara as a base and
# allow you to configure the driver. The default driver is
# <tt>RailsSeleniumDriver</tt> which provides a Capybara and the Selenium
# Driver with no configuration. It's intended to work out of the box.
#
# A system test looks like the following:
#
# require 'system_test_helper'
#
# class Users::CreateTest < ActionSystemTestCase
# def adding_a_new_user
# visit users_path
# click_on 'New User'
#
# fill_in 'Name', with: 'Arya'
# click_on 'Create User'
#
# assert_text 'Arya'
# end
# end
#
# When generating an application or scaffold a +system_test_helper.rb+ will also
# be generated containing the base class for system testing. This is where you can
# change the driver, add Capybara settings, and other configuration for your system
# tests.
#
# class ActionSystemTestCase < ActionSystemTest::Base
# ActionSystemTest.driver = :rack_test
# end
#
# You can also specify a driver by initializing a new driver object. This allows
# you to change the default settings for the driver you're setting.
#
# class ActionSystemTestCase < ActionSystemTest::Base
# ActionSystemTest.driver = ActionSystemTest::DriverAdapters::RailsSeleniumDriver.new(
# browser: :firefox
# )
# end
#
# A list of supported adapters can be found in DriverAdapters.
#
# If you want to use one of the default drivers provided by Capybara you can
# set the driver in your config to one of those defaults: +:rack_test+,
# +:selenium+, +:webkit+, or +:poltergeist+. These 4 drivers use Capyara's
# driver defaults whereas the <tt>RailsSeleniumDriver</tt> has pre-set
# configuration for browser, server, port, etc.
#--
## Copyright (c) 2014-2017 David Heinemeier Hansson
##
## Permission is hereby granted, free of charge, to any person obtaining
## a copy of this software and associated documentation files (the
## "Software"), to deal in the Software without restriction, including
## without limitation the rights to use, copy, modify, merge, publish,
## distribute, sublicense, and/or sell copies of the Software, and to
## permit persons to whom the Software is furnished to do so, subject to
## the following conditions:
##
## The above copyright notice and this permission notice shall be
## included in all copies or substantial portions of the Software.
##
## THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
## EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
## MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
## NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
## LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
## OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
## WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
##++
require "capybara/dsl"
require "action_controller"
@ -57,7 +28,91 @@ require "action_system_test/browser"
require "action_system_test/server"
require "action_system_test/test_helpers/screenshot_helper"
module ActionSystemTest
module ActionSystemTest # :nodoc:
# = Action System Test
#
# System tests let you test real application in the browser. Because system tests
# use a real browser experience you can test all of your JavaScript easily
# from your test suite.
#
# To create an ActionSystemTest in your application, extend your test class
# from <tt>ActionSystemTestCase</tt>. System tests use Capybara as a base and
# allow you to configure the settings through your <tt>system_test_helper.rb</tt>
# file that is generated with a new application or scaffold.
#
# Here is an example system test:
#
# require 'system_test_helper'
#
# class Users::CreateTest < ActionSystemTestCase
# test "adding a new user" do
# visit users_path
# click_on 'New User'
#
# fill_in 'Name', with: 'Arya'
# click_on 'Create User'
#
# assert_text 'Arya'
# end
# end
#
# When generating an application or scaffold a +system_test_helper.rb+ will also
# be generated containing the base class for system testing. This is where you
# can change the driver, add Capybara settings, and other configuration for
# your system tests.
#
# require "test_helper"
#
# class ActionSystemTestCase < ActionSystemTest::Base
# teardown do
# take_failed_screenshot
# Capybara.reset_sessions!
# end
# end
#
# By default, <tt>ActionSystemTest</tt> is driven by the Selenium driver, with
# the Chrome browser, on port 21800, and a browser size of 1400x1400.
#
# Changing the driver configuration options are easy. Let's say you want to use
# port 3000, and the Firefox browser instead. In your +system_test_helper.rb+
# file add the following:
#
# require "test_helper"
#
# class ActionSystemTestCase < ActionSystemTest::Base
# driven_by :selenium, using: :firefox, on: 3000
#
# teardown do
# take_failed_screenshot
# Capybara.reset_sessions!
# end
# end
#
# +driven_by+ has a required argument for the driver name. The keyword
# arguments are +:using+ for the browser (not applicable for headless drivers),
# +:on+ for port (the server is always Puma), and +:screen_size+ to change
# the size of the screen when taking screenshots.
#
# To use a headless driver, like Poltergeist, update your Gemfile to use
# Poltergeist instead of Selenium and then declare the driver name in the
# +system_test_helper.rb+ file. In this case you would leave out the +:using+
# option because the driver is headless.
#
# require "test_helper"
# require "capybara/poltergeist"
#
# class ActionSystemTestCase < ActionSystemTest::Base
# driven_by :poltergeist
#
# teardown do
# take_failed_screenshot
# Capybara.reset_sessions!
# end
# end
#
# Because <tt>ActionSystemTest</tt> is a shim between Capybara and Rails, any
# driver that is supported by Capybara is supported by Action System Test as
# long as you include the required gems and files.
include Capybara::DSL
include ActionSystemTest::TestHelpers::ScreenshotHelper
@ -72,6 +127,16 @@ module ActionSystemTest
end
end
# Action System Test configuration options
#
# The defaults settings are Selenium, using Chrome, on port 21800, with a
# screen size of 1400x1400.
#
# Examples:
#
# driven_by :poltergeist
#
# driven_by :selenium, using: :firefox, on: 3000
def self.driven_by(driver, using: :chrome, on: 21800, screen_size: [1400, 1400])
Driver.new(driver).run
Server.new(on).run

2
actionsystemtest/lib/action_system_test/browser.rb
View file

@ -1,5 +1,5 @@
module ActionSystemTest
class Browser
class Browser # :nodoc:
def initialize(name, screen_size)
@name = name
@screen_size = screen_size

13
actionsystemtest/lib/action_system_test/test_helpers/screenshot_helper.rb
View file

@ -4,14 +4,9 @@ module ActionSystemTest
module ScreenshotHelper
# Takes a screenshot of the current page in the browser.
#
# +take_screenshot+ can be used within your tests at points
# you want to take a screenshot if the driver supports screenshots. The
# Rack Test driver does not support screenshots.
#
# You can check if the driver supports screenshots by running
#
# ActionSystemTest.driver.supports_screenshots?
# => true
# +take_screenshot+ can be used at any point in your system tests to take
# a screenshot of the current state. This can be useful for debugging or
# automating visual testing.
def take_screenshot
save_image
puts "[Screenshot]: #{image_path}"
@ -23,7 +18,7 @@ module ActionSystemTest
#
# +take_screenshot+ is included in <tt>system_test_helper.rb</tt> that is
# generated with the application. To take screenshots when a test fails
# add +take_failed_screenshot+ to the teardown block before clearing any
# add +take_failed_screenshot+ to the teardown block before clearing
# sessions.
def take_failed_screenshot
take_screenshot unless passed?

134
guides/source/testing.md
View file

@ -39,7 +39,9 @@ fixtures/ integration/ models/ system_test
The `helpers`, `mailers`, and `models` directories are meant to hold tests for view helpers, mailers, and models, respectively. The `controllers` directory is meant to hold tests for controllers, routes, and views. The `integration` directory is meant to hold tests for interactions between controllers.
The system test directory holds system tests, also known as acceptance tests.
The system test directory holds system tests, which are used for full browser
testing of your application. System tests allow you to test your application
the way your users experience it and help you test your JavaScript as well.
System tests inherit from Capybara and perform in browser tests for your
application.
@ -598,9 +600,11 @@ Model tests don't have their own superclass like `ActionMailer::TestCase` instea
System Testing
--------------
System tests are full-browser acceptance tests that inherit from Capybara.
System tests are full-browser tests that can be used to test your application's
JavaScript and user experience. System tests use Capybara as a base.
System tests allow for running tests in either a real browser or a headless
browser for testing full user interactions with your application.
driver for testing full user interactions with your application.
For creating Rails system tests, you use the `test/system` directory in your
application. Rails provides a generator to create a system test skeleton for us.
@ -614,7 +618,7 @@ $ bin/rails generate system_test users_create_test.rb
Here's what a freshly-generated system test looks like:
```ruby
require 'test_helper'
require "system_test_helper"
class UsersCreateTest < ActionSystemTestCase
# test "the truth" do
@ -623,78 +627,58 @@ class UsersCreateTest < ActionSystemTestCase
end
```
Here the test is inheriting from `ActionSystemTestCase`. This allows for no-setup
Capybara integration with Selenium Webdriver.
By default, system tests are run with the Selenium driver, using the Chrome
browser, on port 21800 with Puma, and a screen size of 1400x1400. The next
section explains how to change the default settings.
### Changing the default settings
Capybara requires that a driver be selected. Rails defaults to the Selenium
Driver and provides default settings to Capyara and Selenium so that system
tests work out of the box with no required configuration on your part.
Rails makes changing the default settings for system test very simple. All
the setup is abstracted away so you can focus on writing your tests.
Some may prefer to use a headless driver so Rails provides a shim to set other
drivers for Capybara with minimal configuration.
When you generate a new application or scaffold, a `system_test_helper.rb` file
is created in the test directory. This is where all the configuration for your
system tests should live.
In the `system_test_helper.rb` that is generated with the application or test
you can set the driver:
If you want to change the default settings you can simple change what the system
tests are "driven by". Say you want to change the driver from Selenium to
Poltergeist. First add the Poltergeist gem to your Gemfile. Then in your
`system_test_helper.rb` file do the following:
```ruby
require 'test_helper'
require "test_helper"
require "capybara/poltergeist"
class ActionSystemTestCase < ActionSystemTest::Base
ActionSystemTest.driver = :poltergeist
driven_by :poltergeist
end
```
The drivers that Rails and Capybara support are `:rack_test`, `:poltergeist`,
`:capybara_webkit`, and of course `:selenium`.
For selenium you can choose either the Rails configured driver `:rails_selenium`
or `:selenium`. The `:selenium` driver inherits from `CabybaraDriver` and is
the vanilla setup of selenium with Capybara if you don't want to use the
Rails defaults.
The default settings for `:rails_selenium` driver uses the Chrome browser,
sets the server to Puma on port 28100 and the screen size to 1400 x 1400.
You can change the default settings by initializing a new driver object.
If you want to keep the Selenium driver but change the browser or port you
can pass Firefox and the port to driven by. The driver is a required
argument, all other arguments are optional.
```ruby
require 'test_helper'
require "test_helper"
class ActionSystemTestCase < ActionSystemTest::Base
ActionSystemTest.driver = ActionSystemTest::DriverAdapters::RailsSeleniumDriver.new(
browser: :firefox,
server: :webkit
)
driven_by :selenium, using: :firefox, on: 3000
end
```
The shim for other Capybara drivers provide some defaults such as driver name
server, and port. To change any of those settings, you can initialize a new
`CapybaraDriver` object.
```ruby
require 'test_helper'
class ActionSystemTestCase < ActionSystemTest::Base
ActionSystemTest.driver = ActionSystemTest::DriverAdapters::CapybaraDriver.new(
driver: :poltergeist,
server: :webrick
)
end
```
The driver name is a required argument for `driven_by`. The optional arguments
that can be passed to `driven_by` are `:using` for the browser (this will only
be used for non-headless drivers like Selenium), `:on` for the port Puma should
use, and `:screen_size` to change the size of the screen for screenshots.
If your Capybara configuration requires more setup than provided by Rails, all
of that configuration can be put into the `system_test_helper.rb` file provided
by Rails.
Please see Capybara's documentation for additional settings.
Please see [Capybara's documentation](https://github.com/teamcapybara/capybara#setup)
for additional settings.
### Helpers Available for System Tests
`ActionSystemTest` provides a few helpers in addition to those provided previously
by Rails or by Capybara.
### Screenshot Helper
The `ScreenshotHelper` is a helper designed to capture screenshots of your test.
This can be helpful for viewing the browser at the point a test failed, or
@ -707,52 +691,6 @@ file and will take a screenshot only if the test fails.
The `take_screenshot` helper method can be included anywhere in your tests to
take a screenshot of the browser.
A method is provided by the drivers to determine whether the driver is capable
of taking screenshots. The `RackTest` driver for example does not support
screenshots. `supports_screenshots?` checks whether the driver supports
screenshots:
```ruby
ActionSystemTest.driver.supports_screenshots?
=> true
```
The `ActiveJobSetup` helper configures your system tests for handling Active Job.
Two helper methods are included in the setup and teardown blocks in the
`system_test_helper.rb` file. `set_queue_adapter_to_async` sets your Active Job
queue adapter to the async adapter and remembers the original adapter.
In teardown the `reset_queue_adapter_to_original` method resets the Active Job
queue adapter back to the adapter your application has set for other environments.
This is helpful for ensuring that jobs run async so that the test's that rely
on job code are correctly tested at the time they run.
If you don't want these helper methods you can remove them from the setup and
teardown code in your `system_test_helper.rb`.
The `AssertionsHelper` provides two helper methods for assertions. In Capybara
you can assert that a selector does or does not exist, but often you have cases
where you need to assert the same selector exsits multiple times with different
values. For example, if you have 6 avatars on the page and you want to assert
that each of them has the respective title for each person you can use
`assert_all_of_selectors` and pass the selector, items you are asserting exist,
and options.
```ruby
assert_all_of_selectors(:avatar, 'Eileen', 'Jeremy')
assert_all_of_selectors(:avatar, 'Eileen', 'Jeremy', visible: all)
```
You can also assert that none of the selectors match with
`assert_none_of_selectors`:
```ruby
assert_none_of_selectors(:avatar, 'Tom', 'Dan')
assert_none_of_selectors(:avatar, 'Tom', 'Dan')
```
### Implementing a system test
Now we're going to add a system test to our blog application. We'll demonstrate
@ -777,7 +715,7 @@ previous command we should see:
Now let's open that file and write our first assertion:
```ruby
require 'system_test_helper'
require "system_test_helper"
class UsersTest < ActionSystemTestCase
test "viewing the index" do