selenium-connect 2.3.0 → 3.0.0

data/.coveralls.yml

@@ -0,0 +1 @@
+service_name: travis-ci

data/.gitignore

@@ -23,3 +23,4 @@ tmp
 .yardoc
 _yardoc
 doc/
+build

data/.rspec

@@ -0,0 +1,6 @@
+--color
+--format progress
+--format documentation
+--out build/spec/manual_run.log
+--format html
+--out build/spec/manual_run.html

data/.travis.yml

@@ -3,3 +3,4 @@ rvm:
   - 1.9.3
 notifications:
   hipchat: 2a07784c1aeed1b6efa332242d3fc3@Regulation Station
+  email: false

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+#3.0.0 (2013-07-14)
+- updated rake file to run all the tests on a release start
+- Bumped version to 3.0.0 to prepare for release.
+- updated coverage badge in the docs and did a little ditty to jive gem name with proper file naming
+- updated the build process to add the version number and date to the top of the readme on release so that people know how old the docs is #5
+- updated documentation to reflect the changes in #5
+- added a facility to download a job tagged failure image to the logs directory
+- now sending a passed or failed bool in the finish command will mark sauce labs jobs as such #5
+- major refactoring of public api per #5 and updating the tests to match
+- added guard configuration and updated the coverage reports to go to the build directory #5
+- added coveralls code coverage information #5
+- added catch to rakefile for log deletions #5
+- updated tests for new support files location, cleaned up build process adding good logging and seperation of unit, integration, and system tests #5
+- moved specs into standard format, updated names to standard class file name convention #5
+- fixed some minor code quality issues
+
 #2.3.0 (2013-07-12)
 - removed debug information from the sauce_spec
 - Bumped version to 2.3.0 to prepare for release.

data/Guardfile

@@ -0,0 +1,6 @@
+guard :rspec do
+  watch(%r{^spec/unit/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/unit/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+

data/README.md

@@ -1,34 +1,51 @@
-Master Branch: [![Build Status](https://travis-ci.org/arrgyle/selenium-connect.png?branch=master)](https://travis-ci.org/arrgyle/selenium-connect)
+#selenium-connect 3.0.0 (2013-07-14)
 
-Develop Branch: [![Build Status](https://travis-ci.org/arrgyle/selenium-connect.png?branch=develop)](https://travis-ci.org/arrgyle/selenium-connect)
+[![Gem Version](https://badge.fury.io/rb/selenium-connect.png)](http://badge.fury.io/rb/selenium-connect) [![Build Status](https://travis-ci.org/arrgyle/selenium-connect.png?branch=develop)](https://travis-ci.org/arrgyle/selenium-connect) [![Code Climate](https://codeclimate.com/github/arrgyle/selenium-connect.png)](https://codeclimate.com/github/arrgyle/selenium-connect) [![Coverage Status](https://coveralls.io/repos/arrgyle/selenium-connect/badge.png?branch=develop)](https://coveralls.io/r/arrgyle/selenium-connect?branch=develop)
 
-#selenium-connect [![Code Climate](https://codeclimate.com/github/arrgyle/selenium-connect.png)](https://codeclimate.com/github/arrgyle/selenium-connect)
+A stupid simple way to run your Selenium tests on your computer, against a Selenium Grid, or in the cloud (e.g. SauceLabs). For a rocking implementation of this library, checkout [ChemistryKit](https://github.com/arrgyle/chemistrykit)!
 
-A stupid simple way to run your Selenium tests on your computer, against a Selenium Grid, or in the cloud (e.g. SauceLabs).
+All the documentation for Selenium Connect can be found in this README, organized as follows:
+
+- [Getting Started](#getting-started)
+- [Helpful Bits](#helpful-bits)
+- [Configuration](#configuration)
+- [Contribution Guidelines](#contribution-guidelines)
+- [Deployment](#deployment)
 
 ## Getting Started
 ```ruby
 require 'selenium-connect'
 
-SeleniumConnect.configure do |c|
-  c.host         = "localhost" #or "grid_ip_address" or "saucelabs"
-  c.browser      = "firefox"
-end
+# generate a config object
+config = SeleniumConnect::Configuration.new browser: 'firefox'
+
+# get connected
+sc = SeleniumConnect.start config
+
+# create a job
+job = sc.create_job
 
+# start the job to get a driver
+@driver = job.start
+
+# get on the road!
 @driver = SeleniumConnect.start
 @driver.get "http://www.google.com"
-SeleniumConnect.finish
-```
 
-## Helpful bits
+# finish your job
+job.finish
+
+# go have some fun!
+sc.finish
+
+## Helpful Bits
 
 ### Start
 If host is set to "localhost" and no jar file is specified, it will run the version of [selenium-standalone-server.jar](https://code.google.com/p/selenium/downloads/list) that is bundled with the library (currently 2.33.0). Or, you can specify your own jar if you have one you prefer to use. This is done with c.jar = 'path-to-jar-file'.
 
-If no additional parameters are set, the Selenium Server will be run in the background with logging disabled. If a logging directory is provided (with c.log = 'path-to-log-dir') then 3 output files will be generated:
+If no additional parameters are set, the Selenium Server will be run in the background with logging disabled. If a logging directory is provided (with c.log = 'path-to-log-dir') then 2 output files will be generated:
 + Selenium Server JSON Wire Protocol output (server.log)
 + Browser output (browser.log) -- currently only available for Firefox
-+ Test output (SPEC-testname.xml)
 
 This localhost functionality is driven using the [Selenium Rake Server Task](http://selenium.googlecode.com/svn/trunk/docs/api/rb/Selenium/Rake/ServerTask.html).
 
@@ -42,7 +59,71 @@ The finish command issues a quit command to the driver and stops the local serve
 - [PhantomJS](https://github.com/arrgyle/selenium-connect/blob/develop/spec/acceptance/headless_spec.rb)
 - [SauceLabs](https://github.com/arrgyle/selenium-connect/blob/develop/spec/acceptance/sauce_spec.rb)
 
-## Contributing
+## Configuration
+Configuration of Selenium Connect is SUPER SIMPLE if you want it to be:
+
+    config = SeleniumConnect::Configuration.new
+
+By default it will run a local instance of selenium server on port 4444 and launch firefox. Get going without a whole bunch of shenanigans.
+
+If however you want to install custom settings you can use any of the following:
+
+```YAML
+# Setup & Debugging
+jar: # this is where my selenium server jar is
+log: # the logs go to this folder
+
+# Where to run your tests
+host: 'localhost' # local, a grid ip or "saucelabs"
+port:
+
+# Browser
+browser:      'firefox'
+browser_path:
+profile_path:
+profile_name:
+
+# Saucelabs
+os:
+sauce_username: 'test_user_name'
+sauce_api_key:
+browser_version:
+description: #sauce job/test description
+
+```
+
+You can pass parameters into the new config object like:
+
+    config = SeleniumConnect::Configuration.new host: 'sauce labs', log: 'build'
+
+Or you can load them up from a YAML file:
+
+    config = SeleniumConnect::Configuration.new.populate_with_yaml '/my/config.yaml'
+
+
+###Additional Configuration
+When you create your job you can pass in parameters, right now just `:name` that lets you configure a job at runtime. This is helpful for using Sauce Labs where you'd want to update the description to whatever test job you are running:
+
+
+```Ruby
+#…
+job.start name: 'website should load'
+#…
+```
+
+Similarly, when you finish your job you can pass in parameters. Right now this is limited to sauce labs jobs, as it lets you mark the tests as passed, failed, and turn on downloading the failure screenshot:
+
+```Ruby
+# sweet your test passed!
+report = job.finish passed: true
+
+# shucks your test failed :(
+report = job.finish failed: true, failshot: true
+```
+
+The `report` is simply a container for arbitrary data. Right now we are passing back the sauce details.
+
+## Contribution Guidelines
 
 This project conforms to the [neverstopbuilding/craftsmanship](https://github.com/neverstopbuilding/craftsmanship) guidelines. Specifically related to the branching model and versioning. Please see the guidelines for details.
 
@@ -50,6 +131,30 @@ This project conforms to the [neverstopbuilding/craftsmanship](https://github.co
 
     bundle install
 
-### Run the Tests
+### Run the Tests!
+
+```
+rake              # defaults to 'build' task, code quality, unit, and integration tests
+rake unit         # unit tests
+rake integration  # integration tests
+rake system       # system tests
+```
+
+### Or get your Guard On!
+
+Running:
+
+    guard
+
+Will start watching the code and run the unit tests on save. Cool.
+
+## Deployment
+The release process is rather automated, just use one rake task with the new version number:
+
+    rake release_start['2.1.0']
+
+And another to finish the release:
+
+    rake release_finish['A helpful tag message that will be included in the gemspec.']
 
-    bundle exec rake build
+This handles updating the change log, committing, and tagging the release.

data/Rakefile

@@ -1,27 +1,43 @@
 # Encoding: utf-8
 
-require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 
-task default: :build_ci
+task default: :build
 
-task build_ci: [:clean, :prepare, :rubocop, :spec_unit]
+task build: [:clean, :prepare, :rubocop, :unit, :integration]
 
 desc 'Runs standard build activities.'
-task build: [:clean, :prepare, :rubocop, :spec_unit, :spec_full]
+task build_full: [:clean, :prepare, :rubocop, :unit, :integration, :system]
 
 desc 'Removes the build directory.'
 task :clean do
-  FileUtils.rm_rf('build')
+  FileUtils.rm_rf 'build'
+  FileUtils.rm 'chromedriver.log' if File.exist? 'chromedriver.log'
+  FileUtils.rm 'libpeerconnection.log' if File.exist? 'libpeerconnection.log'
 end
 desc 'Adds the build tmp directory for test kit creation.'
 task :prepare do
   FileUtils.mkdir_p('build/tmp')
+  FileUtils.mkdir_p('build/spec')
 end
-RSpec::Core::RakeTask.new(:spec_full)
 
-RSpec::Core::RakeTask.new(:spec_unit) do |t|
-  t.rspec_opts = '--tag ~selenium'
+def get_rspec_flags(log_name, others = nil)
+  "--format documentation --out build/spec/#{log_name}.log --format html --out build/spec/#{log_name}.html --format progress #{others}"
+end
+
+RSpec::Core::RakeTask.new(:unit) do |t|
+  t.pattern = FileList['spec/unit/**/*_spec.rb']
+  t.rspec_opts = get_rspec_flags('unit')
+end
+
+RSpec::Core::RakeTask.new(:integration) do |t|
+  t.pattern = FileList['spec/integration/**/*_spec.rb']
+  t.rspec_opts = get_rspec_flags('integration', '--tag=~selenium')
+end
+
+RSpec::Core::RakeTask.new(:system) do |t|
+  t.pattern = FileList['spec/integration/**/*_spec.rb']
+  t.rspec_opts = get_rspec_flags('system', '--tag selenium')
 end
 
 desc 'Runs code quality check'
@@ -46,7 +62,7 @@ task :release_start, :version do |t, args|
   system 'git pull --no-edit origin develop'
 
   # next assure all the tests run
-  task(:build).invoke
+  task(:build_full).invoke
 
   # start the release process
   system "git flow release start #{version}"
@@ -73,6 +89,8 @@ task :release_finish, :update_message do |t, args|
   gemspec   = File.join(Dir.getwd, 'selenium-connect.gemspec')
   changelog = File.join(Dir.getwd, 'CHANGELOG.md')
   version   = File.read(gemspec).match(/s.version\s+=\s?["|'](.+)["|']/)[1]
+  readme = File.join(Dir.getwd, 'README.md')
+  date = Time.new.strftime('%Y-%m-%d')
 
   ### Changelog
   # get the latest tag
@@ -85,7 +103,6 @@ task :release_finish, :update_message do |t, args|
   log = `git log --format="- %s" --no-merges #{hash.chomp}..HEAD`
 
   changelog_contents = File.read(changelog)
-  date = Time.new.strftime('%Y-%m-%d')
   # create the new heading
   updated_changelog = "##{version} (#{date})\n" + log + "\n" + changelog_contents
   # update the contents
@@ -99,8 +116,15 @@ task :release_finish, :update_message do |t, args|
   )
   File.open(gemspec, 'w') { |f| f.write(updated_gemspec) }
 
-  # Commit the updated change log and gemspec
-  system "git commit -am 'Updated CHANGELOG.md and gemspec for #{version} release.'"
+  ### Update the readme heading
+  updated = File.read(readme).gsub(
+    /^#selenium-connect \d+\.\d+.\d+ \(.+\)/,
+    "#selenium-connect #{version} (#{date})"
+  )
+  File.open(readme, 'w') { |f| f.write(updated) }
+
+  # Commit the updated change log and gemspec and readme
+  system "git commit -am 'Updated CHANGELOG.md gemspec and readme heading for #{version} release.'"
 
   # build the gem
   system 'gem build selenium-connect.gemspec'

data/lib/selenium-connect.rb

@@ -1,84 +1,5 @@
 # Encoding: utf-8
 
-require 'selenium-webdriver'
-require 'selenium-connect/configuration'
-require 'selenium-connect/runner'
-require 'selenium-connect/server'
-require 'sauce/client'
-require 'rest_client'
-
-# Selenium Connect main module
-module SeleniumConnect
-
-  extend self
-  attr_reader :config, :config_file, :location, :server, :driver
-
-  def configure
-    yield configuration
-  end
-
-  def configuration
-    @config = Configuration.new
-  end
-
-  def localhost?
-    config.host == 'localhost'
-  end
-
-  def debug_config
-    config
-  end
-
-  def run
-    if localhost?
-      @server = Server.new(config)
-      server.start
-    end
-    @driver = Runner.new(config).driver
-  end
-
-  def finish
-    # TODO this should grow into a standardized artifact returned
-    # by the driver
-    return_data = {}
-    begin
-      driver.quit
-      return_data = fetch_logs if config.host == 'saucelabs'
-    # rubocop:disable HandleExceptions
-    rescue Selenium::WebDriver::Error::WebDriverError
-      # rubocop:enable HandleExceptions
-      # no-op
-    end
-    server.stop if localhost?
-
-    return_data
-  end
-
-  def fetch_logs
-    # this could be pulled out into the specific sauce runner
-    job_id = driver.session_id
-    sauce_client = Sauce::Client.new
-    sauce_job = Sauce::Job.find(job_id)
-    # poll while job is in progress
-    while sauce_job.status == 'in progress'
-      sleep 5
-      sauce_job.refresh!
-    end
-
-    url = "#{sauce_client.api_url}jobs/#{job_id}/assets/selenium-server.log"
-    response = RestClient::Request.new(
-      method: :get,
-      url: url
-    ).execute
-
-    log_file = File.join(Dir.getwd, config.log, "sauce_job_#{job_id}.log") if config.log
-
-    File.open(log_file, 'w') do |log|
-      log.write response
-    end
-    { sauce_job: sauce_job }
-  end
-
-  alias_method :start, :run
-  alias_method :stop, :finish
-end
+# simple wrapper to join the dash oriented gem name with the _
+# convention for file names.
+require 'selenium_connect'

data/lib/selenium_connect.rb

@@ -0,0 +1,49 @@
+# Encoding: utf-8
+
+require 'selenium_connect/job'
+require 'selenium_connect/server'
+require 'selenium_connect/configuration'
+require 'selenium_connect/report/report_factory'
+
+# Selenium Connect main module
+class SeleniumConnect
+
+  attr_reader :config
+
+  # initializes and returns a new SeleniumConnect object
+  def self.start(config)
+    report_factory = SeleniumConnect::Report::ReportFactory.new
+    new config, report_factory
+  end
+
+  def initialize(config, report_factory)
+    raise ArgumentError, 'Instance of SeleniumConnect::Configuration expected.' unless config.is_a? SeleniumConnect::Configuration
+    @config = config
+    @report_factory = report_factory
+    server_start
+  end
+
+  def create_job(opts = {})
+    SeleniumConnect::Job.new @config, @report_factory
+  end
+
+  def finish
+    @server.stop unless @server.nil?
+    # returning empty report for now
+    @report_factory.build :main, {}
+  end
+
+  private
+
+    def server_start
+      if @config.host == 'localhost'
+        # TODO this is just temp,
+        # in the next iteration we will inject this in by default in start
+        # to a required argument in initialize
+        @server = Server.new(config)
+        @server.start
+      else
+        @server = nil
+      end
+    end
+end