Permalink
Browse files

Add documentation for system tests

* 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
  • Loading branch information...
eileencodes committed Sep 11, 2016
1 parent 9730b1d commit b44320254167152383b1fa8792cb17847a51fb49
@@ -2,6 +2,51 @@
require 'system_testing/driver_adapter'
module Rails
# System tests are similar to Integration tests in that they incorporate multiple
# controllers and actions, but can be used to similate 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>Rails::SystemTestCase</tt>. System tests use Capybara as a base and
# allows you to configure the driver. The default driver is RackTest.
#
# require 'test_helper'
#
# class Users::CreateTest < Rails::SystemTestCase
# 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
#
# System tests in your application can be configured to use different drivers.
#
# To specify a driver, add the following to your Rails' configuration file for
# the test environment.
#
# config.system_testing.driver = :capybara_selenium_driver
#
# You can also specify a driver with a new driver object. Through this method
# you can also change the default settings for the driver you're setting.
#
# config.system_testing.driver = SystemTesting::DriverAdapters::CapybaraRackTestDriver.new(
# useragent: 'My Useragent'
# )
#
# A list of supported adapters can be found in DriverAdapters.
#
# If you want to use a driver that is not supported by Rails but is available
# in Capybara, you can override Rails settings and use Capybara directly by
# setting the +Capybara.default_driver+ and +Capybara.javascript_driver+ in
# your test_help file.
#
# You can also skip using Rails system tests completely by not inheriting from
# <tt>Rails::SystemTestCase</tt> and following Capybara's instructions.
class SystemTestCase < ActionDispatch::IntegrationTest
include SystemTesting::TestHelper
include SystemTesting::DriverAdapter
@@ -1,18 +1,27 @@
require 'system_testing/driver_adapters'
module SystemTesting
# The <tt>SystemTesting::DriverAdapter</tt> module is used to load the driver
# set in your Rails' test configuration file.
#
# The default driver adapters is the +:capybara_rack_test_driver+.
module DriverAdapter
extend ActiveSupport::Concern
module ClassMethods
def default_driver
def default_driver # :nodoc
:capybara_rack_test_driver
end
# Returns the current driver that is set. If no driver is set in the
# Rails' configuration file then +:capybara_rack_test_driver+ will be
# initialized.
def driver
@driver ||= DriverAdapters.lookup(default_driver).new
end
# Specify the adapter and settings for the system test driver set in the
# Rails' configuration file.
def driver=(adapter)
@driver = case adapter
when Symbol
@@ -1,11 +1,21 @@
module SystemTesting
# == System Testing Driver Adapters
#
# System testing supports the following drivers:
#
# * {RackTest}[https://github.com/brynary/rack-test]
# * {Selenium}[https://github.com/SeleniumHQ/selenium]
module DriverAdapters
extend ActiveSupport::Autoload
autoload :CapybaraRackTestDriver
autoload :CapybaraSeleniumDriver
class << self
# Returns driver for specified name.
#
# SystemTesting::DriverAdapters.lookup(:capybara_selenium_driver)
# # => SystemTesting::DriverAdapters::CapybaraSeleniumDriver
def lookup(name)
const_get(name.to_s.camelize)
end
@@ -1,13 +1,32 @@
module SystemTesting
module DriverAdapters
# == CapybaraRackTestDriver for System Testing
#
# This is the default driver for Capybara. This driver does not support
# JavaScript because it doesn't open a browser when running the test suite.
#
# Although it does not support JavaScript testing the
# <tt>CapybaraRackTestDriver</tt> is fast and efficient. This driver requires
# no setup and becasue it does not need a webserver, additional configuration
# is not required.
#
# The <tt>CapybaraRackTestDriver</tt> only takes one argument for initialization
# which is +:useragent+.
#
# To set the useragent add the following to your
# Rails' configuration file:
#
# config.system_testing.driver = SystemTesting::DriverAdapters::CapybaraRackTestDriver.new(
# useragent: 'My UserAgent'
# )
class CapybaraRackTestDriver
attr_reader :useragent
def initialize(useragent: 'Capybara')
def initialize(useragent: 'Capybara') # :nodoc:
@useragent = useragent
end
def call
def call # :nodoc:
registration
end
@@ -3,17 +3,63 @@
module SystemTesting
module DriverAdapters
# == CapybaraSeleniumDriver for System Testing
#
# The <tt>CapybaraSeleniumDriver</t> uses the Selenium 2.0 webdriver. The
# selenium-webdriver gem is required by this driver.
#
# The CapybaraSeleniumDriver is useful for real browser testing and
# support Chrome and Firefox.
#
# To set your system testing to use the Selenium web driver add the
# following to your Rails' configuration test environment:
#
# config.system_testing.driver = :capybara_selenium_driver
#
# Because this driver supports real browser testing it is required that a
# server is configured.
#
# If no server is specified when the driver is initialized, Puma will be used
# by default. The default settings for the <tt>CapybaraSeleniumDriver</tt>
# are:
#
# #<SystemTesting::DriverAdapters::CapybaraSeleniumDriver:0x007ff0e992c1d8
# @browser=:chrome,
# @server=:puma,
# @port=28100,
# @screen_size=[ 1400, 1400 ]
# >
#
# The settings for the <tt>CapybaraSeleniumDriver</tt> can be changed from
# Rails' configuration file.
#
# config.system_testing.driver = SystemTesting::DriverAdapters::CapybaraSeleniumDriver.new(
# server: :webkit,
# port: 28100,
# screen_size: [ 800, 800 ]
# )
#
# The default browser is set to chrome because the current version of
# Firefox does not work with selenium-webdriver. If you want to use Firefox,
# you will need to use Firefox 45.0esr or 47.0 and ensure
# that selenium-webdriver is version 2.53.4. To change the browser from
# +:chrome+ to +:firefox+, initialize the selenium driver in your Rails'
# test environment:
#
# config.system_testing.driver = SystemTesting::DriverAdapters::CapybaraSeleniumDriver.new(
# browser: :firefox
# )
class CapybaraSeleniumDriver
attr_reader :browser, :server, :port, :screen_size
def initialize(browser: :chrome, server: :puma, port: 28100, screen_size: [1400,1400])
def initialize(browser: :chrome, server: :puma, port: 28100, screen_size: [1400,1400]) # :nodoc:
@browser = browser
@server = server
@port = port
@screen_size = screen_size
end
def call
def call # :nodoc:
registration
setup
end
@@ -1,7 +1,8 @@
require 'system_test_case'
module SystemTesting
class Railtie < Rails::Railtie
# = System Testing Railtie
class Railtie < Rails::Railtie # :nodoc:
config.system_testing = ActiveSupport::OrderedOptions.new
initializer "system_testing.set_configs" do |app|
@@ -2,7 +2,7 @@
require 'system_testing/test_helpers'
module SystemTesting
module TestHelper
module TestHelper # :nodoc:
include TestHelpers::FormHelper
include TestHelpers::Assertions
include Capybara::DSL
@@ -1,6 +1,11 @@
module SystemTesting
module TestHelpers
# Assertions for system testing that aren't included by default in Capybara.
# These are assertions that are useful specifically for Rails applications.
module Assertions
# Asserts that all of the provided selectors are present on the given page.
#
# assert_all_of_selectors('p', 'td')
def assert_all_of_selectors(*items)
options = items.extract_options!
type = type_for_selector(items)
@@ -10,6 +15,9 @@ def assert_all_of_selectors(*items)
end
end
# Asserts that none of the provided selectors are present on the page.
#
# assert_none_of_selectors('ul', 'ol')
def assert_none_of_selectors(*items)
options = items.extract_options!
type = type_for_selector(items)
@@ -1,18 +1,46 @@
module SystemTesting
module TestHelpers
# Form helpers for system testing that aren't included by default in
# Capybara.
module FormHelper
# Finds all provided fields or text areas and fills in with supplied values.
#
# fill_in_all_fields('Name' => 'Eileen', 'Job Title' => 'Programmer')
def fill_in_all_fields(fields)
fields.each do |name, value|
fill_in name, with: value
end
end
# Locates a checkbox that is present inside a label and checks it. When
# using styled boxes Selenium may not be able to see the checkbox. This
# form helper looks inside the checkbox and clicks the label instead of
# setting the value of the checkbox.
#
# click_checkbox_label 'Admin'
#
# By default +click_checkbox_label+ looks for checkboxes that are not
# checked by default. To locate an already checked box and uncheck it
# set checked to true:
#
# click_checkbox_label 'Admin', checked: true
def click_checkbox_label(name, checked: false)
field = find_checkbox(name, checked)
label = find_label_wrapper(field)
label.click
end
# In lieu of locating a button and calling +click_on+, +press_enter+ will
# submit the form via enter. This method will only work for drivers that
# load a browser like Selenium.
#
# test 'Adding a User' do
# fill_in 'Name', with: 'Arya'
#
# press_enter
#
# assert_text 'Arya'
# end
def press_enter
page.driver.browser.action.send_keys(:enter).perform
end

0 comments on commit b443202

Please sign in to comment.