diff options
Diffstat (limited to 'actionsystemtest/lib')
3 files changed, 122 insertions, 62 deletions
diff --git a/actionsystemtest/lib/action_system_test.rb b/actionsystemtest/lib/action_system_test.rb index ded2b96584..d28e30d116 100644 --- a/actionsystemtest/lib/action_system_test.rb +++ b/actionsystemtest/lib/action_system_test.rb @@ -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 diff --git a/actionsystemtest/lib/action_system_test/browser.rb b/actionsystemtest/lib/action_system_test/browser.rb index 09b72721c5..220d8b6807 100644 --- a/actionsystemtest/lib/action_system_test/browser.rb +++ b/actionsystemtest/lib/action_system_test/browser.rb @@ -1,5 +1,5 @@ module ActionSystemTest - class Browser + class Browser # :nodoc: def initialize(name, screen_size) @name = name @screen_size = screen_size diff --git a/actionsystemtest/lib/action_system_test/test_helpers/screenshot_helper.rb b/actionsystemtest/lib/action_system_test/test_helpers/screenshot_helper.rb index d4d0d79e95..af83ca3ec8 100644 --- a/actionsystemtest/lib/action_system_test/test_helpers/screenshot_helper.rb +++ b/actionsystemtest/lib/action_system_test/test_helpers/screenshot_helper.rb @@ -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? |