= Build Status {<img src="https://secure.travis-ci.org/bbc-frameworks/frameworks-capybara.png"/>}[https://secure.travis-ci.org/bbc-frameworks/frameworks-capybara]

= frameworks-capybara

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'

* Celerity: This can be used to drive 'headless' tests.  Celerity is a ruby wrapper for HTMLUnit and as such provides support for Javascript, though this is commonly quite fragile.

* 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'
  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}'
  CREATE_NEW_FF_PROFILE - create a new Firefox profile with name provided by FIREFOX_PROFILE 
  CELERITY_JS_ENABLED (string - 'true', 'false') - determines whether Celerity (HTMLUnit) attempts to execute javascript 
  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)"

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://mykey@ondemand.saucelabs.com: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.

== Release instructions

* 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
* Run 'bundle install --binstubs --path vendor/to' bundle 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

== Contributing to frameworks-capybara
 
* 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.

== Copyright

See LICENSE.txt for further details.