saucer 0.6.5 → 1.0.0.alpha

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8563d0a40f72b5d339a70304d948f103b9655e38
-  data.tar.gz: 80844b96e29ff34b83ab1e47a6a25fe8206a8e12
+  metadata.gz: 0a0d5ca72570b0c717d295613491312bec954800
+  data.tar.gz: b12996df6767e459a2746a3eb3dcc7776eb42468
 SHA512:
-  metadata.gz: 3001ebb0491bce0b8c1de318d4b757cf26f8ece4c3869a9ec42e11043cf297fbd79fd6b48a6bce5ffb07e76254e84b222a4533443755304ceeb9b4fb02074e96
-  data.tar.gz: e078e82ec75bee429a90be76deefde3b6992aae3c125845addb5d1cf50a535685c62e262ed2dabf56702fdba0aa7290e3daad668f427f6fd7d61fba7c225fb37
+  metadata.gz: 34570556581c60312af0867069b7b3b3080f7e28b5386f44b21bce4124f62c47a37a02c5a00eea0154d95c5b2cd8547a8b37c1cd1bc87bc6bd92c152a8c177f5
+  data.tar.gz: fad1c1d36deddf108d981c114ae6e50f83bd54e3b61d9b4219470e5b08c6904cba57fa0c6b07d704f609f4f0bd98b7d9058e854ecfc70babb97b030087a9dd71

data/CHANGELOG.md

@@ -0,0 +1,6 @@
+### 1.0.0.alpha (2019-05-16)
+* Complete Revamp of the Project
+* Implement Options class to set customized values
+* Implement Session class to directly interface with Sauce
+* Automatically update Test Name, Build Name, Pass/Fail
+* Automatically add custom data: Ruby version, OS, gems

data/Gemfile

@@ -1,4 +1,6 @@
-source "https://rubygems.org"
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
 
 # Specify your gem's dependencies in saucer.gemspec
 gemspec

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2017 Titus Fortner
+Copyright (c) 2017-2019 Titus Fortner
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,94 +1,105 @@
 # Saucer
 
-Convenience methods for running your Ruby tests on Sauce Labs
+Make running your tests on Sauce Labs easier with these helpful wrappers and convenience methods
 
 ## Disclaimer
 *This code is provided on an "AS-IS” basis without warranty of any kind, either express or implied, including without limitation any implied warranties of condition, uninterrupted use, merchantability, fitness for a particular purpose, or non-infringement. Your tests and testing environments may require you to modify this framework. Issues regarding this framework should be submitted through GitHub. For questions regarding Sauce Labs integration, please see the Sauce Labs documentation at https://wiki.saucelabs.com/. This framework is not maintained by Sauce Labs Support.*
 
 ## Installation
 
-Add this line to your application's Gemfile:
+In your Gemfile: 
+
+`gem 'saucer'
+
+In your project:
 
 ```ruby
-gem 'saucer'
+require 'saucer'
 ```
 
 ## Usage
 
-#### Configuration
-
-Can optionally pass in a `Config::Selenium` instance with any of the 
-[supported Test Configuration Options](https://wiki.saucelabs.com/display/DOCS/Test+Configuration+Options)
-Note that Ruby syntax is a `Symbol` with snake_case and not `String` with camelCase
+#### Starting the Driver
+Use Saucer to start your sessions
 ```ruby
-config_selenium = Config::Selenium.new(version: '53', browser_name: :firefox)
-@driver = Driver.new(config_selenium)
+@session = Saucer::Session.begin
+@driver = @session.driver
 ```
-
-#### Cucumber
-RSpec doesn't need to be concerned with this, but Cucumber needs an extra step in `env.rb`:
+Optionally you can create options with various parameters to pass into `Session.begin`
 ```ruby
-Before do |scenario|
-  Saucer::Config::Sauce.scenario = scenario
-  @driver = Saucer::Driver.new
-end
-
-After do |scenario|
-  Saucer::Config::Sauce.scenario = scenario
-  @driver.quit
-end
+options = Saucer::Options.new(browser_name: 'Safari', 
+                              browser_version: '12.0',
+                              platform_name: 'macOS 10.14')
+@session = Saucer::Session.begin(options)
+@driver = @session.driver
 ```
 
-#### Parallel
-The most basic usage for parallel execution is to define the following Rake task, which 
-will every spec in the spec directory in 4 processes on the default Sauce platform (Linux with Chrome v48)
-
+#### Finishing the session
+You can still quit the driver yourself if you'd like
 ```ruby
-Saucer::Parallel.new.run
+@driver.quit
 ```
-
-To Specify basic number of processes, a specific subdirectory (Cucumber or RSpec), and
-reporting output file:
-
+You get some automatic data population if you end the Session
 ```ruby
-Saucer::Parallel.new(number: 7,
-                     path: 'features/foo',
-                     output: 'foo').run
+@session.end
 ```
 
-
-To specify Sauce configurations, create a Rake Task that takes parameters like this:
-
+#### Automatic Data Population
+To automatically pass in the test name, populate pass/fail and provide exception information:
+RSpec doesn't need to do anything, but Cucumber will need to specify the scenario information
+in the `env.rb` or `hooks.rb` file.
 ```ruby
-task :parallel_sauce do
-  configs = [{os: :mac_10_10, browser: :chrome, browser_version: 38},
-             {os: :mac_10_11, browser: :firefox, browser_version: 46},
-             {os: :mac_10_8, browser: :chrome, browser_version: 42}]
-
-  platforms = configs.map { |c| Saucer::PlatformConfiguration.new(c) }
-
-  Saucer::Parallel.new(platforms: platforms).run
+Before do |scenario|
+  options = Saucer::Options.new(scenario: scenario)
+  session = Saucer::Session.begin(options)
+  @driver = session.driver
 end
 ```
 
-or you can use the default rake task and define your configurations in 
-`configs/platform_configs.yml` like this:
-```yaml
-  - :os: :mac_10_10
-    :browser: :chrome
-    :browser_version: 38
-  - :os: :mac_10_11
-    :browser: :firefox
-    :browser_version: 46
-  - :os: :mac_10_8
-    :browser: :chrome
-    :browser_version: 42
+#### Session Commands
+Saucer provides a number of custom methods as part of the session instance:
+```ruby
+# Add useful information to a test after initializing a session
+@session.comment = "Foo"
+@session.tags = %w[foo bar]
+@session.tags << 'foobar'
+@session.data = {foo: 'bar'}
+@session.data[:bar] = 'foo'
+
+# These things should be set automatically, but can be set manually
+@session.name = 'Test Name'
+@session.build = 'Build Name'
+@session.result = 'passed'
+@session.result = 'failed'
+
+# Special Features that might be useful
+@session.stop_network
+@session.start_network
+@session.breakpoint
+
+# This will cause an error, but is available as an option 
+session.stop
+
+# These things can be done after the session has ended
+@session.save_screenshots
+@session.save_log(log_type: :selenium) 
+@session.save_log(log_type: :sauce) 
+@session.save_log(log_type: :automator) 
+@session.save_logs
+@session.save_video
+@session.save_assets
+@session.delete_assets
 ```
 
+#### Additional API Interactions
+A more fully featured wrapping of the Sauce API is planned for upcoming releases.
+For now, make use of [SauceWhisk](https://github.com/saucelabs/sauce_whisk).
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/saucer.
+Bug reports and pull requests are welcome on GitHub at https://github.com/titusfortner/saucer.
 
-## License
+## License & Copyright
 
 The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+see LICENSE.txt for full details and copyright.

data/Rakefile

@@ -1,6 +1,8 @@
-require "bundler/gem_tasks"
-require "rspec/core/rake_task"
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/lib/saucer.rb

@@ -1,6 +1,19 @@
-require "require_all"
+# frozen_string_literal: true
+
 require 'selenium-webdriver'
-require "saucer/version"
-require "sauce_whisk"
-require_rel "saucer"
+require 'saucer/options'
+require 'saucer/data_collection'
+require 'saucer/asset_management'
+require 'saucer/custom_commands'
+require 'saucer/job_update'
+require 'saucer/runners'
+require 'saucer/session'
+require 'saucer/version'
+
+module Saucer
+  class AuthenticationError < StandardError
+  end
 
+  class APIError < StandardError
+  end
+end

data/lib/saucer/asset_management.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module Saucer
+  module AssetManagement
+    def screenshots
+      start_time = Time.now
+      begin
+        urls = SauceWhisk::Jobs.job_assets(job_id)['screenshot_urls']
+        raise APIError, 'No screenshots found' if urls.nil?
+      rescue APIError
+        retry if Time.now - start_time < 5
+      end
+      job.screenshots
+    end
+
+    def save_screenshots(path = nil)
+      screenshots&.each do |screenshot|
+        save_file(path: path, file_name: screenshot.name, data: screenshot.data.body, type: 'screenshots')
+      end
+    end
+
+    # TODO: refactor leveraging `details.end_time`
+    def log(log_type = nil)
+      log_type ||= :sauce
+      valid = {sauce: 'log.json',
+               selenium: 'selenium-server.log',
+               automator: 'automator.log'}
+      unless valid.key?(log_type)
+        raise ArgumentError,
+              "#{log_type} is not a valid log type; use one of #{valid.keys}"
+      end
+
+      start_time = Time.now
+      begin
+        response = asset(valid[log_type]).body
+        raise APIError, "Can not retrieve log: #{response['message']}" if JSON.parse(response).key?('message')
+      rescue NoMethodError
+        # Sauce Log is Special
+        JSON.parse(response).map do |hash|
+          hash.map do |key, value|
+            "#{key}: #{value}"
+          end.join("\n")
+        end.join("\n\n")
+      rescue JSON::ParserError, NoMethodError
+        response
+      rescue APIError
+        retry if Time.now - start_time < 5
+        raise
+      end
+    end
+
+    def save_log(path: nil, log_type: nil)
+      log_type ||= :sauce
+      save_file(path: path, file_name: "#{log_type}.log", data: log(log_type), type: 'logs')
+    end
+
+    def save_logs(path: nil)
+      %i[sauce selenium automator].each do |type|
+        save_log(path: path, log_type: type)
+      end
+    end
+
+    def video_stream
+      start_time = Time.now
+      begin
+        response = asset('video.mp4').body
+        raise APIError, "Can not retrieve video: #{response['message']}" if JSON.parse(response).key?('message')
+      rescue JSON::ParserError
+        response
+      rescue APIError
+        retry if Time.now - start_time < 5
+        raise
+      end
+    end
+
+    def save_video(path = nil)
+      save_file(path: path, file_name: 'video.mp4', data: video_stream, type: 'videos')
+    end
+
+    def save_assets
+      save_logs
+      save_video
+      save_screenshots
+    end
+
+    def delete_assets
+      start_time = Time.now
+      begin
+        response = JSON.parse(SauceWhisk::Assets.delete(job_id).data.body)
+        raise APIError, "Can not delete assets: #{response}" if response.is_a?(String)
+      rescue APIError
+        retry if Time.now - start_time < 5
+        raise
+      end
+    end
+
+    private
+
+    def save_file(path:, data:, file_name:, type:)
+      path ||= File.expand_path("../../../assets/#{job_id}/#{type}/#{file_name}", __FILE__)
+
+      file_name = path[%r{[^/]*$}]
+      base_path = path.gsub(file_name, '')
+
+      FileUtils.mkdir_p(base_path) unless File.exist?(base_path)
+      File.write(path, data)
+    end
+
+    def asset(asset)
+      SauceWhisk::Jobs.fetch_asset(@job_id, asset)
+    end
+  end
+end

data/lib/saucer/custom_commands.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Saucer
+  module CustomCommands
+    def comment=(comment)
+      @driver.execute_script("sauce: context=#{comment}")
+    end
+
+    def stop_network
+      @driver.execute_script('sauce: stop network')
+    end
+
+    def start_network
+      @driver.execute_script('sauce: start network')
+    end
+
+    def breakpoint
+      @driver.execute_script('sauce: break')
+    end
+  end
+end

data/lib/saucer/data_collection.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Saucer
+  class DataCollection
+    PAGE_OBJECTS = %w[site_prism page-object watirsome watir_drops].freeze
+
+    def gems
+      Bundler.definition.specs.map(&:name).each_with_object({}) do |gem_name, hash|
+        name = Bundler.environment.specs.to_hash[gem_name]
+        next if name.empty?
+
+        hash[gem_name] = name.first.version
+      end
+    end
+
+    def page_objects
+      page_objects_gems = PAGE_OBJECTS & gems.keys
+      if page_objects_gems.size > 1
+        'multiple'
+      elsif page_objects_gems.empty?
+        'unknown'
+      else
+        page_objects_gems.first
+      end
+    end
+
+    def selenium_version
+      gems['selenium-webdriver']
+    end
+
+    def test_library
+      if gems['watir'] && gems['capybara']
+        'multiple'
+      elsif gems['capybara']
+        'capybara'
+      elsif gems['watir']
+        'watir'
+      else
+        'unknown'
+      end
+    end
+
+    def test_runner(runner)
+      gems[runner.name.to_s] ? "#{runner.name} v#{gems[runner.name.to_s]}" : 'Unknown'
+    end
+  end
+end

data/lib/saucer/job_update.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Saucer
+  module JobUpdate
+    def name=(name)
+      job.name = name
+    end
+
+    def build=(name)
+      job.build = name
+    end
+
+    def visibility=(value)
+      valid = %i[public public_restricted share team private]
+      raise ArgumentError, "#{value} is not a valid visibility value; use one of #{valid}" unless valid.include?(value)
+
+      job.visibility = value.to_s
+    end
+
+    def save
+      job.tags = tags unless tags.empty?
+      job.custom_data = data unless data.empty?
+      SauceWhisk::Jobs.save(job)
+    end
+  end
+end