saucelabs-adapter 0.7.6

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Kelly Felkins & Sam Pierson
+
+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.

data/README.markdown

@@ -0,0 +1,150 @@
+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.

data/Rakefile

@@ -0,0 +1,108 @@
+require 'rubygems'
+require 'rake'
+
+require 'rake'
+require 'spec'
+require 'spec/rake/spectask'
+
+desc 'Default: run unit tests.'
+task :default => :spec
+
+desc 'Test the saucelabs-adapter plugin.'
+Spec::Rake::SpecTask.new(:spec) do |t|
+  t.libs << 'lib'
+  t.verbose = true
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "saucelabs-adapter"
+    gem.summary = %Q{Adapter for running Selenium tests using SauceLabs.com}
+    gem.description = %Q{This gem augments Test::Unit and Polonium/Webrat to run Selenium tests in the cloud. }
+    gem.email = "pair+kelly+sam@pivotallabs.com"
+    gem.homepage = "http://github.com/pivotal/saucelabs-adapter"
+    gem.authors = ["Kelly Felkins, Chad Woolley & Sam Pierson"]
+    gem.files = [
+     "LICENSE",
+     "README.rdoc",
+     "Rakefile",
+     "VERSION",
+     "lib/saucelabs_adapter.rb",
+     "lib/saucelabs-adapter.rb",
+     "lib/saucelabs_adapter/run_utils.rb",
+     "lib/saucelabs_adapter/sauce_tunnel.rb",
+     "lib/saucelabs_adapter/selenium_config.rb",
+     "lib/saucelabs_adapter/test_unit_adapter.rb",
+     "lib/saucelabs_adapter/jsunit_selenium_support.rb",
+     "lib/saucerest-ruby/saucerest.rb",
+     "lib/saucerest-ruby/gateway.rb",
+     "lib/saucerest-python/tunnel.py",
+     "lib/saucerest-python/daemon.py",
+     "lib/saucerest-python/saucerest.py",
+     "lib/saucerest-python/sshtunnel.py",
+     "lib/tasks/jsunit.rake",
+     "generators/saucelabs_adapter/saucelabs_adapter_generator.rb",
+     "generators/saucelabs_adapter/templates/selenium.yml",
+     "generators/saucelabs_adapter/templates/saucelabs_adapter.rake",
+     "generators/saucelabs_adapter/templates/jsunit.rake",
+     "generators/saucelabs_adapter/templates/jsunit_suite_example.rb"
+  ]
+    gem.add_dependency 'rest-client', '>= 1.2.0'
+    gem.add_dependency 'net-ssh', '>= 2.0.12'
+    gem.add_dependency 'net-ssh-gateway', '>= 1.0.1'
+    gem.add_dependency 'selenium-client', '>= 1.2.17'
+    gem.add_dependency 'lsof', '>= 0.3.0'
+    # gem.add_development_dependency "thoughtbot-shoulda", ">= 0"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/**/test_*.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+#task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "saucelabs-adapter #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+def run(command)
+  puts command
+  puts `#{command}`
+end
+
+desc "Push gem to gemcutter.org"
+task :deploy => :build do
+  gem = `ls pkg/*|tail -1`.strip
+  puts "Deploying #{gem}:"
+  run "gem push #{gem}"
+end

data/VERSION

@@ -0,0 +1 @@
+0.7.6

data/generators/saucelabs_adapter/saucelabs_adapter_generator.rb

@@ -0,0 +1,49 @@
+
+# This generator bootstraps a Rails project for use with RSpec
+class SaucelabsAdapterGenerator < Rails::Generator::Base
+  DEFAULT_SHEBANG = File.join(Config::CONFIG['bindir'],
+                              Config::CONFIG['ruby_install_name'])
+
+  def initialize(runtime_args, runtime_options = {})
+    puts <<-HELPFUL_INSTRUCTIONS
+
+    The saucelabs_adapter generator installs glue to connect your Selenium tests to saucelabs.com
+
+    After running this generator:
+
+    1) Go edit config/selenium.yml and add your SauceLabs API credentials
+    2) Add this to your selenium_helper.rb:
+
+      require 'saucelabs-adapter'
+
+    HELPFUL_INSTRUCTIONS
+    super
+  end
+
+  def manifest
+    record do |m|
+      m.directory 'lib/tasks'
+      m.file      'saucelabs_adapter.rake',        'lib/tasks/saucelabs_adapter.rake'
+      m.file      'selenium.yml',                  'config/selenium.yml'
+      if options[:jsunit]
+        m.file      'jsunit.rake',                   'lib/tasks/jsunit.rake'
+        m.directory 'test/jsunit'
+        m.file      'jsunit_suite_example.rb',       'test/jsunit/jsunit_suite_example.rb'
+      end
+    end
+  end
+
+protected
+
+  def banner
+    "Usage: #{$0} saucelabs_adapter [options]"
+  end
+
+  def add_options!(opt)
+    opt.separator ''
+    opt.separator 'Options:'
+    opt.on('--jsunit', 'Also install Saucelabs support for JsUnit') do |value|
+      options[:jsunit] = true
+    end
+  end
+end

data/generators/saucelabs_adapter/templates/jsunit.rake

@@ -0,0 +1,62 @@
+require 'run_utils'
+
+namespace :jsunit do
+  namespace :selenium_rc do
+    desc "Runs JsUnit tests locally using configuration 'local' in config/selenium.yml (selenium server must already be started)"
+    task :local => [:local_jsunit_env, :suite]
+
+    desc "Run JsUnit tests at saucelabs.com (using configuration 'saucelabs' in config/selenium.yml)"
+    task :sauce => [:sauce_jsunit_env, :suite]
+
+    desc "Run JsUnit tests at saucelabs.com for all supported browsers"
+    task :sauce_all => [:sauce_jsunit_all_env, :suite]
+
+    desc "Run Selenium tests using configuration SELENIUM_ENV (from config/selenium.yml)"
+    task :custom => [:check_selenium_env_is_set, :suite]
+
+    task :local_jsunit_env do
+      ENV['SELENIUM_ENV'] = 'local_jsunit'
+    end
+
+    task :sauce_jsunit_env do
+      ENV['SELENIUM_ENV'] = 'saucelabs_jsunit'
+    end
+
+    task :sauce_jsunit_all_env do
+      ENV['SELENIUM_ENV'] = "saucelabs_jsunit_firefox,saucelabs_jsunit_ie,saucelabs_jsunit_chrome,saucelabs_jsunit_safari"
+    end
+
+    task :check_selenium_env_is_set do
+      raise "SELENIUM_ENV must be set" unless ENV['SELENIUM_ENV']
+    end
+
+    task :suite do
+      unless (File.exists?("test/jsunit/jsunit_suite.rb"))
+        raise "test/jsunit/jsunit_suite.rb not found, bailing.\nPlease create a script that will run your jsunit tests."
+      end
+      ENV['RUNNING_POLONIUM'] = 'false'
+
+      # TODO: This multi-suite support is a hack and slow, but it's the easiest way to support it without major refactoring to saucelabs_adapter
+      env = ENV['SELENIUM_ENV']
+      if env =~ /,/
+        begin
+          envs = env.split(',')
+          envs.each do |single_env|
+            ENV['SELENIUM_ENV'] = single_env
+            run_suite
+          end
+        ensure
+          # make sure we reset it to avoid confusion
+          ENV['SELENIUM_ENV'] = env
+        end
+      else
+        run_suite
+      end
+    end
+
+    def run_suite
+      success = RunUtils.run "ruby test/jsunit/jsunit_suite.rb"
+      raise "Jsunit suite run for #{ENV['SELENIUM_ENV']} environment failed." unless success
+    end
+  end
+end

data/generators/saucelabs_adapter/templates/jsunit_suite_example.rb

@@ -0,0 +1,19 @@
+require File.dirname(__FILE__) + "/../test_helper"
+require "saucelabs_adapter"
+
+class JsunitTest < ActiveSupport::TestCase
+  include ::JsunitSeleniumSupport
+
+  def setup
+    setup_jsunit_selenium # :timeout_in_seconds => 60, :app_server_logfile_path => "#{RAILS_ROOT}/log/jsunit_jetty_app_server.log"
+  end
+
+  def teardown
+    teardown_jsunit_selenium
+  end
+
+  def test_javascript
+    test_page = "/jsunit/javascripts/test-pages/" + (ENV['TEST'] ? "#{ENV['TEST']}.html" : "suite.html")
+    assert run_jsunit_test({:testPage => test_page}, :jsunit_suite_timeout_seconds => 600, :verbose => true)
+  end
+end

data/generators/saucelabs_adapter/templates/saucelabs_adapter.rake

@@ -0,0 +1,53 @@
+require 'saucelabs_adapter/run_utils'
+
+class Rake::Task
+  def self.exists?(name)
+    tasks.any? { |t| t.name == name }
+  end
+end
+
+namespace :selenium do
+
+  # Rake tasks are cumulative, and some old plugins are still defining selenium:server, so clear it.
+  Rake::Task[:'selenium:server'].clear_actions if Rake::Task.exists?('selenium:server')
+  
+  desc "Run the selenium remote-control server"
+  task :server do
+    system('selenium-rc')
+  end
+
+  desc "Run the selenium remote-control server in the background"
+  task :server_bg do
+    system('nohup selenium-rc 2&>1 &')
+  end
+
+  desc "Runs Selenium tests locally (selenium server must already be started)"
+  task :local => [:local_env, :suite]
+
+  desc "Run Selenium tests at saucelabs.com (using configuration 'saucelabs' in config/selenium.yml)"
+  task :sauce => [:sauce_env, :suite]
+
+  desc "Run Selenium tests using configuration SELENIUM_ENV (from config/selenium.yml)"
+  task :custom => [:check_selenium_env_is_set, :suite]
+
+  task :local_env do
+    ENV['SELENIUM_ENV'] = 'local'
+  end
+
+  task :sauce_env do
+    ENV['SELENIUM_ENV'] = 'saucelabs'
+  end
+
+  task :check_selenium_env_is_set do
+    raise "SELENIUM_ENV must be set" unless ENV['SELENIUM_ENV']
+  end
+
+  task :suite do
+    if (File.exists?("test/selenium/selenium_suite.rb"))
+      RunUtils.run "ruby test/selenium/selenium_suite.rb"
+    else
+      puts "test/selenium/selenium_suite.rb not found, bailing.\nPlease create a script that will run your selenium tests."
+      exit 1
+    end
+  end
+end