mediawiki_selenium 1.5.0 → 1.6.0

data/features/login_helper.feature

@@ -0,0 +1,15 @@
+Feature: Login Helper
+
+  Background:
+    Given I have configured my environment from `ENV` and with:
+      """
+      user_factory: true
+      """
+      And I have set "MEDIAWIKI_API_URL" in my shell
+      And I have set "MEDIAWIKI_URL" in my shell
+      And I am using the user factory
+      And I am using the login helper
+
+  Scenario: Login helper logs in in via the API
+    When I log in via the helper method
+    Then I should be logged in to the wiki

data/features/rspec.feature

@@ -0,0 +1,64 @@
+@integration
+Feature: RSpec integration
+
+  As a developer, I want the option to use a test framework with less
+  indirection so that my tests are more straightforward to implement and
+  easier to reason about.
+
+  Background:
+    Given I have set up my `environments.yml`
+      And the following RSpec support file:
+      """
+      require 'bundler/setup'
+      require 'mediawiki_selenium/rspec'
+      """
+
+  Scenario: RSpec examples have access to the `Environment` via `#mw`
+    Given the following RSpec examples:
+    """
+    describe 'my feature' do
+      describe 'my component' do
+        it 'can access `mw` to implement its tests' do
+          expect(mw).to be_a(MediawikiSelenium::Environment)
+        end
+      end
+    end
+    """
+    When I run `rspec` against my examples
+    Then I should see 1 passing example
+
+  Scenario: Calls to `mw` methods can be unqualified/indirect
+    Given the following RSpec examples:
+    """
+    describe 'my feature' do
+      describe 'my component' do
+        it 'can call `mw` methods indirectly via `self`' do
+          expect(mw).to respond_to(:on_wiki)
+          expect(self).to respond_to(:on_wiki)
+        end
+      end
+    end
+    """
+    When I run `rspec` against my examples
+    Then I should see 1 passing example
+
+  Scenario: An alternative feature/scenario syntax is supported
+    Given the following RSpec examples:
+    """
+    feature 'my feature' do
+      background do
+        # do common stuff
+        @stuff = 'stuff'
+      end
+
+      scenario 'my scenario' do
+        expect(@stuff).to eq('stuff')
+      end
+
+      scenario 'my other scenario' do
+        expect(@stuff).to eq('stuff')
+      end
+    end
+    """
+    When I run `rspec` against my examples
+    Then I should see 2 passing examples

data/features/saucelabs.feature

@@ -6,9 +6,14 @@ Feature: Remote browser sessions through SauceLabs
       browser: firefox
       platform: linux
       """
+      And I have set "SAUCE_ONDEMAND_USERNAME" in my shell
+      And I have set "SAUCE_ONDEMAND_ACCESS_KEY" in my shell
 
   Scenario: SauceLabs sessions start just like a normal browser
-    Given I have set "SAUCE_ONDEMAND_USERNAME" in my shell
-      And I have set "SAUCE_ONDEMAND_ACCESS_KEY" in my shell
     When I start interacting with the browser
     Then the browser is open
+
+  Scenario: Failed scenarios mark SauceLabs jobs as failed
+    Given I have started interacting with the browser
+    When the scenario fails
+    Then the SauceLabs job should be marked as failed

data/features/screenshots.feature

@@ -0,0 +1,21 @@
+@integration
+Feature: Screenshots of failed scenarios
+
+  As a developer writing and running tests, it would be helpful to have a
+  screenshot of the browser window at the point where each scenario has
+  failed.
+
+  Background:
+    Given I have configured my environment with:
+      """
+      screenshot_failures: true
+      screenshot_failures_path: tmp/screenshots
+      """
+      And the "tmp/screenshots" directory exists
+      And I am using the screenshot helper
+
+  Scenario: A screenshot is taken for failed scenarios
+    Given the current scenario name is "Some scenario"
+      And I have started a browser
+    When the scenario fails
+    Then the file "tmp/screenshots/Some scenario.png" should exist

data/features/step_definitions/browser_steps.rb

@@ -8,6 +8,10 @@ Given(/^I am using a local browser$/) do
   allow(@env).to receive(:remote?).and_return(false)
 end
 
+When(/^I have started interacting with the browser$/) do
+  @env.browser
+end
+
 When(/^I start interacting with the browser$/) do
   @env.browser
 end

data/features/step_definitions/environment_steps.rb

@@ -3,7 +3,7 @@ Before do
 end
 
 After do
-  @env.teardown unless @env.nil?
+  @env.teardown unless @env.nil? || @env_torndown
   @tmp_files.each { |path| FileUtils.rm_r(path) if File.exist?(path) }
 end
 
@@ -56,7 +56,7 @@ When(/^the scenario ends$/) do
     sleep 0.3
     @env.teardown(name: @scenario_name, status: @scenario_status)
   ensure
-    @env = nil
+    @env_torndown = true
   end
 end
 

data/features/step_definitions/login_helper_steps.rb

@@ -0,0 +1,11 @@
+Given(/^I am using the login helper$/) do
+  @env.extend(MediawikiSelenium::LoginHelper)
+end
+
+When(/^I log in via the helper method$/) do
+  @env.log_in
+end
+
+Then(/^I should be logged in to the wiki$/) do
+  expect(@env.browser.element(id: 'pt-logout')).to be_present
+end

data/features/step_definitions/rspec_steps.rb

@@ -0,0 +1,32 @@
+require 'yaml'
+require 'open3'
+
+Given(/^I have set up my `environments\.yml`$/) do
+  step 'the "tmp/rspec/spec" directory exists'
+  File.open('tmp/rspec/environments.yml', 'w') { |io| io.write(YAML.dump({ 'default' => {} })) }
+end
+
+Given(/^the following RSpec support file:$/) do |content|
+  File.open('tmp/rspec/spec/spec_helper.rb', 'w') { |io| io.write(content) }
+end
+
+Given(/^the following RSpec examples:$/) do |content|
+  content = "require 'spec_helper'\n#{content}"
+  File.open('tmp/rspec/spec/examples_spec.rb', 'w') { |io| io.write(content) }
+end
+
+Given(/^$the following "(.+)" file for use with RSpec$/) do |path, content|
+  File.open(File.join('tmp/rspec', path), 'w') { |io| io.write(content) }
+end
+
+When(/^I run `rspec` against my examples$/) do
+  env = { 'MEDIAWIKI_ENVIRONMENT' => 'default' }
+  cmd = "'#{Gem.bin_path('bundler', 'bundle')}' exec rspec"
+
+  @rspec_output, @rspec_status = Open3.capture2e(env, cmd, chdir: 'tmp/rspec')
+end
+
+Then(/^I should see (\d+) passing examples?$/) do |n|
+  expect(@rspec_status).to be_success, "Examples did not pass. Output:\n---\n#{@rspec_output}---\n"
+  expect(@rspec_output).to match(/^#{n} examples?, 0 failures/)
+end

data/features/step_definitions/saucelabs_steps.rb

@@ -0,0 +1,18 @@
+require 'net/https'
+
+Then(/^the SauceLabs job should be marked as failed$/) do
+  job_id = @env.browser.driver.session_id
+
+  username = @env[:sauce_ondemand_username]
+  access_key = @env[:sauce_ondemand_access_key]
+
+  job_uri = URI.parse("https://saucelabs.com/rest/v1/#{username}/jobs/#{job_id}")
+
+  job_uri.user = username
+  job_uri.password = access_key
+
+  job = JSON.parse(Net::HTTP.get(job_uri))
+
+  expect(job).to include('passed')
+  expect(job['passed']).to be(false)
+end

data/features/step_definitions/screenshot_steps.rb

@@ -0,0 +1,3 @@
+Given(/^I am using the screenshot helper$/) do
+  @env.extend(MediawikiSelenium::ScreenshotHelper)
+end

data/lib/mediawiki_selenium.rb

@@ -1,14 +1,17 @@
 module MediawikiSelenium
   autoload :VERSION, 'mediawiki_selenium/version'
-  autoload :ApiHelper, 'mediawiki_selenium/support/modules/api_helper'
+  autoload :ApiHelper, 'mediawiki_selenium/helpers/api_helper'
   autoload :BrowserFactory, 'mediawiki_selenium/browser_factory'
   autoload :ConfigurationError, 'mediawiki_selenium/configuration_error'
   autoload :Environment, 'mediawiki_selenium/environment'
-  autoload :HeadlessHelper, 'mediawiki_selenium/support/modules/headless_helper'
+  autoload :HeadlessHelper, 'mediawiki_selenium/helpers/headless_helper'
   autoload :Initializer, 'mediawiki_selenium/initializer'
+  autoload :LoginHelper, 'mediawiki_selenium/helpers/login_helper'
   autoload :PageFactory, 'mediawiki_selenium/page_factory'
   autoload :Raita, 'mediawiki_selenium/raita'
   autoload :RemoteBrowserFactory, 'mediawiki_selenium/remote_browser_factory'
+  autoload :ScreenshotHelper, 'mediawiki_selenium/helpers/screenshot_helper'
+  autoload :StrictPending, 'mediawiki_selenium/cucumber/strict_pending'
   autoload :UserFactory, 'mediawiki_selenium/user_factory'
-  autoload :UserFactoryHelper, 'mediawiki_selenium/support/modules/user_factory_helper'
+  autoload :UserFactoryHelper, 'mediawiki_selenium/helpers/user_factory_helper'
 end

data/lib/mediawiki_selenium/browser_factory/base.rb

@@ -200,8 +200,12 @@ module MediawikiSelenium
       # @param _env [Environment] Environment.
       # @param _status [Symbol] Status of the executed scenario.
       #
+      # @return [Hash{String => String}] Artifacts.
+      #
+      # @see Environment#teardown
+      #
       def teardown(_env, _status)
-        # abstract
+        {}
       end
 
       protected

data/lib/mediawiki_selenium/cucumber.rb

@@ -0,0 +1,4 @@
+require 'mediawiki_selenium/cucumber/env'
+require 'mediawiki_selenium/cucumber/hooks'
+require 'mediawiki_selenium/cucumber/sauce'
+require 'mediawiki_selenium/cucumber/strict_pending'

data/lib/mediawiki_selenium/{support → cucumber}/env.rb

@@ -1,14 +1,12 @@
-# before all
 require 'bundler/setup'
 require 'page-object/page_factory'
 require 'watir-webdriver'
 
-require 'mediawiki_selenium/support/modules/api_helper'
-require 'mediawiki_selenium/support/modules/strict_pending'
-
 World { MediawikiSelenium::Environment.load_default }
 
 World(MediawikiSelenium::ApiHelper)
+World(MediawikiSelenium::LoginHelper)
 World(MediawikiSelenium::PageFactory)
+World(MediawikiSelenium::ScreenshotHelper)
 World(MediawikiSelenium::StrictPending)
 World(MediawikiSelenium::UserFactoryHelper)

data/lib/mediawiki_selenium/cucumber/hooks.rb

@@ -0,0 +1,73 @@
+Before('@custom-browser') do |scenario|
+  @scenario = scenario
+end
+
+AfterConfiguration do |config|
+  # Install a formatter that can be used to show feature-related warnings
+  pretty_format, io = config.formats.find { |(format, _io)| format == 'pretty' }
+  config.formats << ['MediawikiSelenium::WarningsFormatter', io] if pretty_format
+
+  # Set up Raita logging if RAITA_DB_URL is set. Include any useful
+  # environment variables that Jenkins would have set.
+  env = MediawikiSelenium::Environment.load_default
+  raita_url = env.lookup(:raita_url, default: nil)
+
+  if raita_url
+    raita_build = MediawikiSelenium::Raita.build_from(env)
+    config.formats << ['MediawikiSelenium::Raita::Logger', { url: raita_url, build: raita_build }]
+  end
+end
+
+# Determine scenario name and setup the environment
+Before do |scenario|
+  @scenario_name =
+    if scenario.respond_to? :feature
+      "#{scenario.feature.title}: #{scenario.title}"
+    elsif scenario.respond_to? :scenario_outline
+      outline = scenario.scenario_outline
+      "#{outline.feature.title}: #{outline.title}: #{scenario.name}"
+    else
+      scenario.name
+    end
+
+  setup(name: @scenario_name)
+end
+
+# Enforce a dependency check for all scenarios tagged with @extension- tags
+Before do |scenario|
+  # Backgrounds themselves don't have tags, so get them from the feature
+  if scenario.is_a?(Cucumber::Ast::Background)
+    tag_source = scenario.feature
+  else
+    tag_source = scenario
+  end
+
+  tags = tag_source.source_tag_names
+  dependencies = tags.map { |tag| tag.match(/^@extension-(.+)$/) { |m| m[1].downcase } }.compact
+  missing = missing_extensions(dependencies)
+
+  if missing.any?
+    scenario.skip_invoke!
+
+    if scenario.feature.respond_to?(:mw_warn)
+      warning = "Skipped feature due to missing MediaWiki extensions: #{missing.join(", ")}"
+      scenario.feature.mw_warn(warning, 'missing MediaWiki extensions')
+    end
+  end
+end
+
+Before do
+  # Create a unique random string for this scenario
+  @random_string = Random.new.rand.to_s
+end
+
+After do |scenario|
+  artifacts =
+    if scenario.respond_to?(:status)
+      teardown(name: @scenario_name, status: scenario.status)
+    else
+      teardown(name: @scenario_name)
+    end
+
+  artifacts.each { |path, mime_type| embed(path, mime_type) }
+end

data/lib/mediawiki_selenium/cucumber/sauce.rb

@@ -0,0 +1,22 @@
+require 'cucumber/formatter/junit'
+require 'mediawiki_selenium/remote_browser_factory'
+
+module Cucumber::Formatter
+  class Sauce < Junit
+    private
+
+    def format_exception(exception)
+      sids = MediawikiSelenium::RemoteBrowserFactory.last_session_ids
+
+      if sids.nil? || sids.empty?
+        message = 'Uh-oh. Could not find link to Sauce Labs job URL.'
+      else
+        message = sids.map { |sid| "Sauce Labs job URL: http://saucelabs.com/jobs/#{sid}\n" }.join
+      end
+
+      msgs = [message] + ["#{exception.message} (#{exception.class})"] + exception.backtrace
+
+      msgs.join("\n")
+    end
+  end
+end

data/lib/mediawiki_selenium/environment.rb

@@ -298,7 +298,7 @@ module MediawikiSelenium
     # @option options [Symbol] :id Alternative ID.
     # @option options [Object] :default Default if no configuration is found.
     #
-    # @return [Array<String>]
+    # @return [Hash{Symbol => String}]
     #
     # @see #lookup
     #
@@ -346,12 +346,43 @@ module MediawikiSelenium
       RemoteBrowserFactory::REQUIRED_CONFIG.all? { |name| lookup(name, default: false) }
     end
 
+    # Executes setup tasks, annotating the Selenium session with any
+    # configured `job_name` and `build_number`.
+    #
+    # Additional helpers may perform their own tasks by implementing this
+    # method.
+    #
+    # @example Setup the environment before each scenario starts
+    #   Before do |scenario|
+    #     setup(name: scenario.name)
+    #   end
+    #
+    # @param info [Hash] Hash of test case information.
+    #
+    def setup(info = {})
+      browser_factory.configure do |options|
+        options[:desired_capabilities][:name] = info[:name] || 'scenario'
+      end
+
+      browser_factory.configure(:job_name) do |job, options|
+        options[:desired_capabilities][:name] += " #{job}"
+      end
+
+      browser_factory.configure(:build_number) do |build, options|
+        options[:desired_capabilities][:name] += "##{build}"
+      end
+    end
+
     # Executes teardown tasks including instructing all browser factories to
     # close any open browsers and perform their own teardown tasks.
     #
+    # Teardown tasks may produce artifacts, which will be returned in the form
+    # `{ path => mime_type }`.
+    #
     # @example Teardown environment resources after each scenario completes
     #   After do |scenario|
-    #     teardown(name: scenario.name, status: scenario.status)
+    #     artifacts = teardown(name: scenario.name, status: scenario.status)
+    #     artifacts.each { |path, mime_type| embed(path, mime_type) }
     #   end
     #
     # @param info [Hash] Hash of test case information.
@@ -359,32 +390,22 @@ module MediawikiSelenium
     # @yield [browser]
     # @yieldparam browser [Watir::Browser] Browser object, before it's closed.
     #
+    # @return [Hash{String => String}] Hash of path/mime-type artifacts.
+    #
     def teardown(info = {})
+      artifacts = {}
+
       @_factory_cache.each do |(_, browser_name), factory|
         factory.each do |browser|
           yield browser if block_given?
           browser.close unless keep_browser_open? && browser_name != :phantomjs
         end
 
-        factory.teardown(self, info[:status] || :passed)
+        factory_artifacts = factory.teardown(self, info[:status] || :passed)
+        artifacts.merge!(factory_artifacts) if factory_artifacts.is_a?(Hash)
       end
-    end
 
-    # Returns a name from the given scenario.
-    #
-    # @param scenario [Cucumber::Ast::Scenario]
-    #
-    # @return [String]
-    #
-    def test_name(scenario)
-      if scenario.respond_to? :feature
-        "#{scenario.feature.title}: #{scenario.title}"
-      elsif scenario.respond_to? :scenario_outline
-        outline = scenario.scenario_outline
-        "#{outline.feature.title}: #{outline.title}: #{scenario.name}"
-      else
-        scenario.name
-      end
+      artifacts
     end
 
     # Returns the current value for `:mediawiki_user` or the value for the
@@ -416,7 +437,7 @@ module MediawikiSelenium
     # @yield [url]
     # @yieldparam url [String] Wiki URL.
     #
-    def visit_wiki(id)
+    def visit_wiki(id = nil)
       on_wiki(id) do |url|
         browser.goto url
         yield url if block_given?