Saucelabs-Adapter
=================

Saucelabs-adapter provides the glue to connect Rails Selenium tests to saucelabs.com.

Currently it supports tests written using Webrat, Polonium and JSUnit.

Getting Started - Webrat or Polonium test suites
------------------------------------------------

1. Prerequisites:

    You must be able to run selenium tests locally using test/selenium/selenium_suite.rb

2. Install the gem:

        gem install saucelabs-adapter --source gems.pivotallabs.com

3. Run the saucelabs_adapter generator in your project:

        cd your_project

        script/generate saucelabs_adapter

4. Configure it.  In config/selenium.yml, replace YOUR-SAUCELABS-USERNAME and
   YOUR-SAUCELABS-ACCESS-KEY with your saucelabs.com account information.

5. Run Tests

    To run Selenium Test::Unit tests locally:

        rake selenium:local

    To run Selenium Test::Unit tests using saucelabs.com:

        rake selenium:sauce

Getting Started - JsUnit test suite
-----------------------------------

1. Prerequisites:

    Install the latest JsUnit from http://github.com/pivotal/jsunit

    JsUnit must be installed in RAILS_ROOT/public/jsunit as follows:

        public/jsunit/jsunit_jar/jsunit.jar      -- the compiled jar
        public/jsunit/jsunit/build.xml etc...    -- jsunit sources

2. Install the saucelabs-adapter gem:

        gem install saucelabs-adapter --source gems.pivotallabs.com

3. Run the saucelabs_adapter generator in your project:

        cd your_project

        script/generate saucelabs_adapter --jsunit

4. Configure it.

    In config/selenium.yml, replace YOUR-SAUCELABS-USERNAME and
    YOUR-SAUCELABS-ACCESS-KEY with your saucelabs.com account information.

    Rename RAILS_ROOT/test/jsunit/jsunit_suite_example.rb to RAILS_ROOT/test/jsunit/jsunit_suite.rb
    and modify it if necessary:
    test_page needs to be set to the path under /public where your JsUnit test page (suite.html or similar) lives,
    with '/jsunit' prepended. e.g. if your JsUnit suite runs from RAILS_ROOT/public/javascripts/test-pages/suite.html
    then test_page needs to be set to '/jsunit/javascripts/test-pages/suite.html'.

5. Run Tests

    To run JsUnit tests locally:

        rake jsunit:selenium_rc:local

    To run JsUnit tests using saucelabs.com:

        rake jsunit:selenium_rc:sauce

What You Should See
-------------------

When running tests, intermixed with your test output you should see the following lines:

        [saucelabs-adapter] Setting up tunnel from Saucelabs (yourhostname-12345.com:80) to localhost:4000
        [saucelabs-adapter] Tunnel ID 717909c571b8319dc5ae708b689fd7f5 for yourhostname-12345.com is up.
        Started
        ....................
        [saucelabs-adapter] Shutting down tunnel to Saucelabs...
        [saucelabs-adapter] done.

In Case of Problems
-------------------
Try setting environment variable SAUCELABS_ADAPTER_DEBUG to "true".  This enables more verbose output.


Continuous Integration
----------------------
Sauce Labs now lets you set the name of a test job.
By default the SaucelabsAdapter will set this to the name of the machine it is currently running on,
however you may override this by setting the environment variable SAUCELABS_JOB_NAME.

This can be useful if you run many tests from the same CI machine and would like to differentiate between
them without actually viewing the video.

What it Does
------------

The saucelabs-adapter performs two functions when it detects you are running a test that will use saucelabs.com:

1. It sets up a SauceTunnel before the test run starts and tears it down after the test ends.  This happens once for the entire test run.

2. It configures the selenium client to connect to the correct address at saucelabs.com.  This happens at the start of each test.

CHANGES
=======
0.7.6
-----
- Added saucelabs_max_duration configuration option.

0.7.0
-----
- The gem has been reorganized to better conform with Gem best-practices.

- The rakefile generator has changed.  If you are upgrading, you will need to rerun the generator and overwrite lib/tasks/saucelabs_adapter.rake,
or just change line 1 of that file to read:

        require 'saucelabs_adapter/run_utils'

- The selenium.yml syntax has changed to break out all the saucelabs info into separate lines, and the tunnel method is now explicitly stated:

    - Old:
            selenium_browser_key: '{"username": "YOUR-SAUCELABS-USERNAME", "access-key": "YOUR-SAUCELABS-ACCESS-KEY", "os": "Linux", "browser": "firefox", "browser-version": "3."}'
            #
            localhost_app_server_port: "4000"
            tunnel_startup_timeout: 240

    - New:
            saucelabs_username: "YOUR-SAUCELABS-USERNAME"
            saucelabs_access_key: "YOUR-SAUCELABS-ACCESS-KEY"
            saucelabs_browser_os: "Linux"
            saucelabs_browser: "firefox"
            saucelabs_browser_version: "3."
            #
            tunnel_method: :saucetunnel
            tunnel_to_localhost_port: 4000
            tunnel_startup_timeout: 240
            
- The dependency on Python has been removed.