Gem to simplify the configuration of Capybara when using multiple drivers, also exposes other useful utility methods.
Although utilising Capybara’s API to run tests is extremely simple the configuration and setup of the tool can be a little confusing, particularly if you want to avoid ending up with a spaghetti like env.rb file
The principle behind this gem is to factor out all the common setup code for registering Capybara drivers and allow the user to pass all configuration options through Cucumber’s command line interface (typically using cucumber.yml to make this easier).
Below are the current drivers that can be registered:
-
Selenium-Webdriver (Selenium2) - LOCAL: This can be used to drive ‘in-browser’ tests runnong on your local machine in IE, Firefox and Chrome (and any other browsers as and when they are added into the Selenium-Webdriver project)
-
Selenium-Webdriver (Selenium2) - REMOTE: This can be used to drive ‘in-browser’ tests on a remote macine, this could be another macine on your local network which is running a Selenium-Webdriver server or indeed a cloud service such as ‘Sauce Labs’
-
Mechanize-Caybara: This can be used, by setting BROWSER=mechanize
How to use this gem in your project:
In your env.rb simply add:
require 'frameworks-capybara'
The following environment variables can be set to configure your tests:
ENVIRONMENT - this must be one of either 'sandbox', 'sandbox6', 'int', 'test', 'stage', 'live'
BROWSER - this must be one of either 'ie', 'firefox', 'chrome', 'headless', 'remote'
HTTP_PROXY - url of proxy if required e.g. 'http://proxyhost:80', when running a headless browser this sets the proxy for the browser itself, when running a remote browser this sets the proxy for the client which will connect to the remote selenium server
PLATFORM - used when specifying remote test on a grid that provides a choice of platforms, this must be one of either 'WINDOWS' or 'LINUX'
PLATFORM_VERSION - used to specify the OS version of the specified platform e.g. '7', '8.1'
REMOTE_BROWSER - used when specifying remote test, must be one of either 'ie', 'firefox', 'chrome', 'headless', 'remote':w
REMOTE_BROWSER_VERSION - used when specifying remote test on a grid the provides a choice of browser versions for a given browser
REMOTE_URL - URL of remote Selenium-Webdriver server e.g. http://yourremotehost:4444/wd/hub
FIREFOX_PROFILE - specify a firefox profile to use when running in-browser tests (local or remote)
FIREFOX_PREFS - specify a json string of additional preferences e.g. FIREFOX_PREFS='{"javascript.enabled": false}'
FIREFOX_CERT_PATH - specify optional directory containing Firefox profile certificate (.db) files
FIREFOX_CERT_PREFIX - specify optional prefix for locating Firefox profile certificate files (e.g. <prefix>-<file>.db)
CREATE_NEW_FF_PROFILE - create a new Firefox profile with name provided by FIREFOX_PROFILE
XVFB - (string - 'true', 'false') - determines whether XVFB is used to run browser (i.e. headless Firefox on *nix platform)
FW_CERT_LOCATION - path to client certificate (combined pem)
CHROME_SWITCHES - pass in any allowed switches for the Selenium chrome driver (http://peter.sh/experiments/chromium-command-line-switches/) e.g. CHROME_SWITCHES="--user-agent=Mozilla/5.0 (PLAYSTATION 3; 3.55)"
PROJECT_NAME - optional project name description which gets displayed in Cucumber html reports
TEAM_NAME - optional team name description which gets displayed in Cucumber html reports
BROWSER_CLI_ARGS - optional additional arguments to pass to local browser processes (individual arguments should be separated with spaces)
The following environment variables are specific to running tests against a BrowserStack remote grid:
BS_BUILD - allows the user to specify a name for a logical group of tests e.g. 'Component A Tests'
BS_DEBUG - set to 'false' to disable screenshot generation ('true' by default)
BS_DEVICE - specify a mobile/tablet device e.g. 'iPhone 5C'
BS_DEVICE_ORIENTATION - specify to force the device orientation ('portrait' or 'landscape')
BS_PROJECT - allows the user to specify a name for a logical group of builds e.g. 'Project X'
BS_RESOLUTION - set the browser resolution e.g. '1024x768'
Here is a sample cucumber.yml:
<%intenv='ENVIRONMENT=int'%> <%testenv='ENVIRONMENT=test'%> <%stageenv='ENVIRONMENT=stage'%> <%liveenv='ENVIRONMENT=live'%> <%sandboxenv='ENVIRONMENT=sandbox'%> <%browser_headless='BROWSER=headless'%> <%browser_ie='BROWSER=ie'%> <%browser_firefox='BROWSER=firefox'%> <%browser_chrome='BROWSER=chrome'%> <%browser_remote='BROWSER=remote'%> <%proxy_on='=http://proxyhost:proxyport'%> <%sauce_remote_url='REMOTE_URL=http://[email protected]:80/wd/hub'%> <%demo_feature='features/demo.feature'%> firefox-local: <%=browser_firefox%> <%=testenv%> FIREFOX_PROFILE=default <%=no_stage_tests%> <%=no_xhtml_tests%> <%=demo_feature%> chrome-local: <%=browser_chrome%> <%=testenv%> <%=no_stage_tests%> <%=no_xhtml_tests%> <%=demo_feature%> ie-local: <%=browser_ie%> <%=testenv%> <%=no_stage_tests%> <%=no_xhtml_tests%> <%=demo_feature%> headless-local-proxy: <%=browser_headless%> <%=testenv%> <%=proxy_on%> <%=no_stage_tests%> <%=no_xhtml_tests%> <%=demo_feature%> headless-local-noproxy: <%=browser_headless%> <%=testenv%> <%=no_stage_tests%> <%=no_xhtml_tests%> <%=demo_feature%> saucelabs-proxy: <%=browser_remote%> <%=testenv%> <%=proxy_on%> FIREFOX_PROFILE=default PLATFORM=WINDOWS <%=sauce_remote_url%> <%=no_stage_tests%> <%=no_xhtml_tests%> REMOTE_BROWSER=firefox <%=demo_feature%> saucelabs-noproxy: <%=browser_remote%> <%=testenv%> FIREFOX_PROFILE=default PLATFORM=WINDOWS <%=sauce_remote_url%> <%=no_stage_tests%> <%=no_xhtml_tests%> REMOTE_BROWSER=firefox <%=demo_feature%>
This gem also sets up a number of ‘base urls’ for you to use in your tests, these are set based on the ENVIRONMENT variable you set when running cucumber tests (either from the comand line or in cucumber.yml), the following URLs are set:
@base_url @base_static_url @base_open_url
Finally this gem contains some useful monkey-patches to core libraries e.g. Capybara-Mechanize, Selenium-Webdriver and Cucumber.
-
Run tests - ‘rake’
-
If you have not published with ‘gem’ before, run ‘gem push’ to enter your credentials (ignore failed publish error at the end)
-
Bump version - manually update file in lib/version.rb
-
Update the CHANGES log (see file for convention).
-
Run ‘bundle install –binstubs –path vendor’ to pick up new version in Gemfile
-
Commit ‘Gemfile.lock’ changes
-
Release - ‘rake release’
You should see something like:
frameworks-capybara 0.2.23 built to pkg/frameworks-capybara-0.2.23.gem Tagged v0.2.23 Pushed git commits and tags Pushed frameworks-capybara 0.2.23 to rubygems.org
-
Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet
-
Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it
-
Fork the project
-
Start a feature/bugfix branch
-
Commit and push until you are happy with your contribution
-
Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.
-
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
See LICENSE.txt for further details.