mediawiki_selenium 0.4.3 → 1.0.0.pre.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1370bd256c005fa2d4d225fd94da2124219c7120
-  data.tar.gz: 802b87cd07fdc7c9661f072433a17ad378a7a09c
+  metadata.gz: 6cfb45e7cecfe3d24690b4bc3b0577b523a32f0c
+  data.tar.gz: da0ddd70c32a9e191f88eb28091295b115a36621
 SHA512:
-  metadata.gz: 7ca28e9b1124c314f402d4abec4e4f544c052abfaeeeff006539c960f988c0ea38c7c80d567d64662ecb767ef82f9f423a2c3f1c111fe8ac303171be90c23b03
-  data.tar.gz: 272eba01eb16179269395248009a517b5a79b8c08fe57a0124f71fa78ecacb60d960bdcb3d2104d01195b973d722299c75b518d324300cbea8b72382c61de4ca
+  metadata.gz: ba624b67027eeec05822cd82927f4849859f07d43302d416965ef8be9f3541b010d332ef19668ec07b87d9d57288cbfa6e4ea61309c04ea5c683abddc999d24e
+  data.tar.gz: 231504b0c5ae4b35f307b0544c67e56b6c07fb9e4cdc2050a3b089e54db445c80c047ed0f55ad850ce9584e54f3f4ed86720b25ed49d3c9175b44c8d1f533a17

data/.gitreview

@@ -2,5 +2,5 @@
 host=gerrit.wikimedia.org
 port=29418
 project=mediawiki/selenium.git
-defaultbranch=0.4
+defaultbranch=master
 defaultrebase=0

data/.rspec

@@ -0,0 +1 @@
+--color

data/.yardopts

@@ -1 +1,2 @@
 --title "MediaWiki Selenium"
+--markup markdown

data/Gemfile

@@ -1,4 +1,4 @@
-#ruby=ruby-2.1.1
+#ruby=ruby-2.1.3
 #ruby-gemset=mediawiki_selenium
 
 source "https://rubygems.org"

data/README.md

@@ -1,82 +1,123 @@
-# Mediawiki::Selenium
+# MediaWiki-Selenium
 
-Several MediaWiki extensions share code that makes it easy to run Selenium
-tests. This gem makes it easy to update the shared code.
+MediaWiki-Selenium is a Ruby framework for the implementation and execution of
+acceptance tests against [MediaWiki](https://www.mediawiki.org/wiki/MediaWiki)
+installations. It is comprised of a number of core dependencies and native
+APIs that help you describe the expected behavior of your MediaWiki-related
+features, and drive cross-browser simulations to ensure the correctness of
+your implementation.
+
+## Core Dependencies
+
+* [Cucumber](https://github.com/cucumber/cucumber) provides the natural
+  [Gherkin](https://github.com/cucumber/cucumber/wiki/Gherkin) language used
+  to describe application features, a basic API for binding that natural
+  language to step definitions written in Ruby, and a test runner for
+  executing the suite.
+
+* [PageObject](https://github.com/cheezy/page-object) helps you to implement
+  [PageObject patterns](https://code.google.com/p/selenium/wiki/PageObjects)
+  within your test suite that better encapsulate the expected structure and
+  mechanics of your application's UI.
+
+* [Watir](https://github.com/watir/watir/) and
+  [Selenium](http://docs.seleniumhq.org/) for driving browser sessions.
+
+* [RSpec](https://github.com/rspec/rspec-expectations) for asserting
+  expectations of scenario outcomes.
 
 ## Installation
 
-To run the Selenium tests you will have to install Ruby. Look at the `Gemfile`
-file for the exact required version. You also have to install the latest
-versions of RubyGems and Firefox (the default browser in which the tests run).
-The easiest way to install Ruby on Linux/Unix/Mac is [RVM](https://rvm.io/) and
-on Windows [RubyInstaller](http://rubyinstaller.org/).
+Ruby 1.9 or above is required, 2.1 is recommended. The easiest way to install
+it is with [RVM](https://rvm.io/) or [rbenv](http://rbenv.org/) on
+Linux/Unix/OS X, and with [RubyInstaller](http://rubyinstaller.org/) on
+Windows.
 
-    cd tests/browser
-    gem update --system
-    gem install bundler
-    bundle install
+Create a `Gemfile` in the root of your MediaWiki-related project that
+specifies the version of `mediawiki_selenium` you wish to use (typically the
+latest version).
 
-If you're not using RVM to manage your Ruby versions, you will need to run the
-commands as root (using `sudo`).
+    gem 'mediawiki_selenium', '~> 1.0.0'
 
-Environment variables `MEDIAWIKI_USER` and `MEDIAWIKI_PASSWORD` are required for
-tests tagged `@login`. For local testing, create a test user on your local wiki
-and export the user and password as the values for those variables.
-For example:
+Install the gem and its dependencies by running `bundle install`. (If
+[Bundler](http://bundler.io/) is not yet installed, install it with
+`gem install bundler`, or `sudo gem install bundler` if you're using a
+system wide Ruby.)
 
-    export MEDIAWIKI_USER=<username here> # Linux/Unix/Mac
-    set MEDIAWIKI_USER=<username here> # Windows Command Prompt
-    $env:MEDIAWIKI_USER="<username here>" # Windows PowerShell
+## Getting Started
 
-    export MEDIAWIKI_PASSWORD=<password here> # Linux/Unix/Mac
-    set MEDIAWIKI_PASSWORD=<password here> # Windows Command Prompt
-    $env:MEDIAWIKI_PASSWORD="<password here>" # Windows PowerShell
+Once the gem is installed, run `mediawiki-selenium-init` in your project's
+root directory to create a boilerplate configuration under `tests/browser`.
 
-## Usage
+    $ bundle exec mediawiki-selenium-init
+        create  tests/browser
+        create  tests/browser/environments.yml
+        create  tests/browser/features/support/env.rb
 
-Run the tests with `bundle exec cucumber`, this should start Firefox.
+Default configuration for various resources (wiki URLs, users, etc.) is
+typically loaded from an `environments.yml` YAML file in the current working
+directory. It should contain defaults for each environment in which the tests
+are expected to run, indexed by environment name. Double check that the
+generated file is suitable for how you expect your tests to be run, for
+example against [Mediawiki-Vagrant](http://www.mediawiki.org/wiki/MediaWiki-Vagrant)
+for local development, or against at least the [Beta Cluster](http://www.mediawiki.org/wiki/Beta_cluster)
+for continuous integration.
 
-By default the tests run at en.wikipedia.beta.wmflabs.org. If you want to run
-the tests on another web server, set the `MEDIAWIKI_URL` environment variable. For example:
+For details on how environment configuration is loaded and used by step
+definitions, see the documentation for `MediawikiSelenium::Environment`.
 
-    export MEDIAWIKI_URL=http://commons.wikimedia.beta.wmflabs.org/wiki/ # Linux/Unix/Mac
-    set MEDIAWIKI_URL=http://commons.wikimedia.beta.wmflabs.org/wiki/ # Windows Command Prompt
-    $env:MEDIAWIKI_URL="http://commons.wikimedia.beta.wmflabs.org/wiki/" # Windows PowerShell
+## Writing Tests
 
-Some tests use the [MediaWiki web API](https://www.mediawiki.org/wiki/API:Main_page)
-to interact with the web server in addition to driving a browser.
-If you want these tests to run on another web server,
-you must also set the `MEDIAWIKI_API_URL` environment variable. For example:
+The ability to write effective and cruft-free tests will come with practice
+and greater familiarity with the underlying libraries. On mediawiki.org,
+you'll find some helpful [high-level documentation](http://www.mediawiki.org/wiki/Quality_Assurance/Browser_testing/Writing_tests)
+to get you started.
 
-    export MEDIAWIKI_API_URL=http://commons.wikimedia.beta.wmflabs.org/w/api.php # Linux/Unix/Mac
-    set MEDIAWIKI_API_URL=http://commons.wikimedia.beta.wmflabs.org/w/api.php # Windows Command Prompt
-    $env:MEDIAWIKI_API_URL="http://commons.wikimedia.beta.wmflabs.org/w/api.php" # Windows PowerShell
+To see exactly which methods are available from within step definitions, see
+the documentation for `MediawikiSelenium::Environment`,
+`MediawikiSelenium::ApiHelper`, and `MediawikiSelenium::PageFactory`.
 
-To run a single test file:
+## Running Tests
 
-    bundle exec cucumber features/FEATURE_NAME.feature
+Execute your tests by running `bundle exec cucumber` from within the
+`tests/browser` directory.
 
-To run a single test scenario, put a colon and the line number (NN) on which
-the scenario begins after the file name:
+By default, the entire suite is run which may take some time. If you wish to
+execute scenarios for just a single feature, you can provide the feature file
+as an argument.
 
-    bundle exec cucumber features/FEATURE_NAME.feature:NN
+    bundle exec cucumber feature/some.feature
 
-You can use a different browser with the `BROWSER` env variable, the fastest is
-probably PhantomJS, a headless browser:
+To run a single scenario, give the line number as well.
+
+    bundle exec cucumber feature/some.feature:11
+
+The set of default configuration to use (see "Getting started") is specified
+by the `MEDIAWIKI_ENVIRONMENT` environment variable, which should be defined
+somewhere in your shell profile. For example, if you're using
+[Mediawiki-Vagrant](http://www.mediawiki.org/wiki/MediaWiki-Vagrant) for your
+development and executing tests on the host OS, the environment name would be
+`mw-vagrant-host`.
+
+    export MEDIAWIKI_ENVIRONMENT=mw-vagrant-host # Linux/Unix/Mac
+    set MEDIAWIKI_URL=mw-vagrant-host # Windows Command Prompt
+    $env:MEDIAWIKI_URL="mw-vagrant-host" # Windows PowerShell
+
+Firefox is the default browser, but you can specify a different one by setting
+`BROWSER`.
 
     export BROWSER=phantomjs # Linux/Unix/Mac
     set BROWSER=phantomjs # Windows Command Prompt
     $env:BROWSER="internet_explorer" # Windows PowerShell
 
 By default, the browser will close itself at the end of every scenario. If you
-want the browser to stay open, set the environment variable `KEEP_BROWSER_OPEN`
-to `true`:
+want the browser to stay open, set `KEEP_BROWSER_OPEN` to `true`.
 
     export KEEP_BROWSER_OPEN=true # Linux/Unix/Mac
     set KEEP_BROWSER_OPEN=true # Windows Command Prompt
     $env:KEEP_BROWSER_OPEN="true" # Windows PowerShell
 
-## Headless Mode
+### Headless Mode
 
 Headless operation can be useful when running tests in an environment where
 there's no GUI available, environments such as a continuous integration
@@ -109,7 +150,7 @@ behavior.
     # Keep xvfb running after execution (the default is to kill it)
     HEADLESS_DESTROY_AT_EXIT=false bundle exec cucumber ...
 
-## Screenshots
+### Screenshots
 
 You can get screenshots on failures by setting the environment
 variable `SCREENSHOT_FAILURES` to `true`. Screenshots will be written under the
@@ -138,7 +179,7 @@ commit back both files.
 
 ### Repositories
 
-If not stated differently, Selenium tests are in `/tests/browser` folder and Jenkins jobs are at [integration.wikimedia.org/ci/view/BrowserTests](https://integration.wikimedia.org/ci/view/BrowserTests/).
+If not stated differently, Selenium tests are in `tests/browser` folder and Jenkins jobs are at [integration.wikimedia.org/ci/view/BrowserTests](https://integration.wikimedia.org/ci/view/BrowserTests/).
 
 Repositories that use the gem:
 
@@ -177,11 +218,23 @@ See https://www.mediawiki.org/wiki/Gerrit
 
 ## Release notes
 
-### 0.4.3 2015-06-03
-* Fixed bug in SauceLabs reporting for when a scenario is skipped
-
-### 0.4.2 2015-02-04
-* Removed use of `onfocus` from `LoginPage#login_with`
+### 1.0.0 2015-01-16
+* Substantial refactoring and backwards incompatible changes
+* Implemented an "environment abstraction layer" with the aim to:
+  * Improve test determinism by sourcing environment-specific default
+    configurations and enforcing an immutable runtime configuration
+  * Simplify test patterns by providing DSL constructs around commonly tested
+    MediaWiki resources
+  * Manage multiple isolated browser sessions within a single test scenario
+  * Serve more advanced use cases by supporting ad hoc browser customization
+* Cleaned up the global object space by moving methods into the new
+  `Environment` and `BrowserFactory` classes
+* Further decoupled core framework from Cucumber, allowing for the possibility
+  of its use under other Ruby test frameworks like RSpec
+* Established test suite with coverage for all newly implemented EAL modules
+  and classes
+* Improved high level and inline documentation with examples and links to
+  upstream resources
 
 ### 0.4.1 2014-11-11
 * Additional headless environment variables: HEADLESS_DISPLAY, HEADLESS_REUSE, HEADLESS_DESTROY_AT_EXIT.

data/bin/mediawiki-selenium-init

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "mediawiki_selenium"
+
+MediawikiSelenium::Initializer.new.install

data/lib/mediawiki_selenium.rb

@@ -9,22 +9,13 @@ mediawiki_selenium top-level directory and at
 https://git.wikimedia.org/blob/mediawiki%2Fselenium/HEAD/CREDITS.
 =end
 
-require "mediawiki_selenium/version"
-
-require "mediawiki_selenium/support/env"
-require "mediawiki_selenium/support/hooks"
-require "mediawiki_selenium/support/sauce"
-
-require "mediawiki_selenium/step_definitions/login_steps"
-require "mediawiki_selenium/step_definitions/navigation_steps"
-require "mediawiki_selenium/step_definitions/preferences_steps"
-require "mediawiki_selenium/step_definitions/resource_loader_steps"
-require "mediawiki_selenium/step_definitions/upload_file_steps"
-
-require "mediawiki_selenium/support/modules/api_helper"
-require "mediawiki_selenium/support/modules/url_module"
-
-require "mediawiki_selenium/support/pages/api_page"
-require "mediawiki_selenium/support/pages/login_page"
-require "mediawiki_selenium/support/pages/random_page"
-require "mediawiki_selenium/support/pages/reset_preferences_page"
+module MediawikiSelenium
+  autoload :VERSION, "mediawiki_selenium/version"
+  autoload :ApiHelper, "mediawiki_selenium/support/modules/api_helper"
+  autoload :BrowserFactory, "mediawiki_selenium/browser_factory"
+  autoload :ConfigurationError, "mediawiki_selenium/configuration_error"
+  autoload :Environment, "mediawiki_selenium/environment"
+  autoload :Initializer, "mediawiki_selenium/initializer"
+  autoload :PageFactory, "mediawiki_selenium/page_factory"
+  autoload :RemoteBrowserFactory, "mediawiki_selenium/remote_browser_factory"
+end

data/lib/mediawiki_selenium/browser_factory.rb

@@ -0,0 +1,24 @@
+module MediawikiSelenium
+  module BrowserFactory
+    autoload :Base, "mediawiki_selenium/browser_factory/base"
+    autoload :Firefox, "mediawiki_selenium/browser_factory/firefox"
+    autoload :Chrome, "mediawiki_selenium/browser_factory/chrome"
+    autoload :Phantomjs, "mediawiki_selenium/browser_factory/phantomjs"
+
+    # Resolves and instantiates a new factory for the given browser name.
+    #
+    # @example Create a new firefox factory
+    #   factory = BrowserFactory.new(:firefox)
+    #   # => #<MediawikiSelenium::BrowserFactory::Firefox>
+    #   factory.browser_for(env) # => #<Watir::Browser>
+    #
+    # @param browser_name [Symbol] Browser name.
+    #
+    # @return [BrowserFactory::Base]
+    #
+    def self.new(browser_name)
+      factory_class = const_get(browser_name.to_s.split("_").map(&:capitalize).join(""))
+      factory_class.new(browser_name)
+    end
+  end
+end

data/lib/mediawiki_selenium/browser_factory/base.rb

@@ -0,0 +1,212 @@
+require "watir-webdriver"
+
+module MediawikiSelenium
+  module BrowserFactory
+    # Browser factories instantiate browsers of a certain type, configure
+    # them according to bound environmental variables, and cache them
+    # according to the uniqueness of that configuration.
+    #
+    class Base
+      class << self
+        # Binds environmental configuration to any browser created by
+        # factories of this type. Use of this method should generally be
+        # reserved for macro-style invocation in derived classes.
+        #
+        # @example Always configure Firefox's language according to `:browser_language`
+        #   module MediawikiSelenium::BrowserFactory
+        #     class Firefox < Base
+        #       bind(:browser_language) do |language, options|
+        #         options[:desired_capabilities][:firefox_profile]["intl.accept_languages"] = language
+        #       end
+        #     end
+        #   end
+        #
+        # @param names [Symbol] One or more option names.
+        #
+        # @yield [values, browser_options] A block that binds the configuration to
+        #                                  the browser options.
+        #
+        def bind(*names, &blk)
+          raise ArgumentError, "no block given" unless block_given?
+
+          key = names.length == 1 ? names.first : names
+          default_bindings[key] ||= []
+          default_bindings[key] << blk
+        end
+
+        # All bindings for this factory class combined with those of super
+        # classes.
+        #
+        # @return [Hash]
+        #
+        def bindings
+          if superclass <= Base
+            default_bindings.merge(superclass.bindings) { |key, old, new| old + new }
+          else
+            default_bindings
+          end
+        end
+
+        # Bindings for this factory class.
+        #
+        # @return [Hash]
+        #
+        def default_bindings
+          @default_bindings ||= {}
+        end
+      end
+
+      attr_reader :browser_name
+
+      bind(:browser_timeout) { |value, options| options[:http_client].timeout = value.to_i }
+
+      # Initializes new factory instances.
+      #
+      # @param browser_name [Symbol]
+      #
+      def initialize(browser_name)
+        @browser_name = browser_name
+        @bindings = {}
+        @browser_cache = {}
+      end
+
+      # Returns a unique set of all the binding keys.
+      #
+      # @return [Array]
+      #
+      def all_binding_keys
+        bindings.keys.flatten.uniq
+      end
+
+      # Binds environmental configuration to any browser created by this
+      # factory instance.
+      #
+      # @example Override the user agent according :browser_user_agent
+      #   factory = BrowserFactory.new(:firefox)
+      #   factory.bind(:browser_user_agent) do |agent, options|
+      #     options[:desired_capabilities][:firefox_profile]["general.useragent.override"] = agent
+      #   end
+      #
+      # @example Annotate the session with our build information
+      #   factory.bind(:job_name, :build_number) do |job, build, options|
+      #     options[:desired_capabilities][:name] = "#{job} (#{build})"
+      #   end
+      #
+      # @example Bindings aren't invoked unless all given options are configured
+      #   factory.bind(:foo, :bar) do |foo, bar, options|
+      #     # this never happens!
+      #     options[:desired_capabilities][:name] = "#{foo} #{bar}"
+      #   end
+      #   factory.browser_for(Environment.new(foo: "x"))
+      #
+      # @param names [Symbol] One or more option names.
+      #
+      # @yield [values, browser_options] A block that binds the configuration to
+      #                                  the browser options.
+      #
+      def bind(*names, &blk)
+        key = names.length == 1 ? names.first : names
+        @bindings[key] ||= []
+        @bindings[key] << (blk || proc {})
+      end
+
+      # Effective bindings for this factory, those defined at the class level
+      # and those defined for this instance.
+      #
+      # @return [Hash]
+      #
+      def bindings
+        self.class.bindings.merge(@bindings) { |key, old, new| old + new }
+      end
+
+      # Instantiate a browser using the given environmental configuration.
+      # Browsers are cached and reused as long as the configuration is the
+      # same.
+      #
+      # @param config [Hash] Browser configuration.
+      #
+      # @return [Watir::Browser]
+      #
+      # @see #new_browser_for
+      #
+      def browser_for(config)
+        @browser_cache[config] ||= new_browser_for(config)
+      end
+
+      # Browser options for the given configuration.
+      #
+      # @param config [Hash]
+      #
+      # @return [Hash]
+      #
+      def browser_options(config)
+        options = default_browser_options.tap do |default_options|
+          bindings.each do |(names, bindings_for_option)|
+            bindings_for_option.each do |binding|
+              values = config.values_at(*Array(names))
+
+              unless values.any? { |value| value.nil? || value.to_s.empty? }
+                binding.call(*values, default_options)
+              end
+            end
+          end
+        end
+
+        finalize_options!(options)
+
+        options
+      end
+
+      # Iterate over each browser created by this factory.
+      #
+      # @yield [browser]
+      #
+      def each(&blk)
+        @browser_cache.values.each(&blk)
+      end
+
+      # A new browser for the given environmental configuration.
+      #
+      # @param config [Hash] Browser configuration.
+      #
+      # @return [Watir::Browser]
+      #
+      # @see #browser_for
+      #
+      def new_browser_for(config)
+        new_browser(browser_options(config))
+      end
+
+      # Executes additional teardown tasks.
+      #
+      # @param env [Environment] Environment.
+      # @param status [Symbol] Status of the executed scenario.
+      #
+      def teardown(env, status)
+        # abstract
+      end
+
+      protected
+
+      def default_browser_options
+        { http_client: http_client, desired_capabilities: desired_capabilities }
+      end
+
+      def desired_capabilities
+        Selenium::WebDriver::Remote::Capabilities.send(browser_name)
+      end
+
+      def finalize_options!(options)
+        # abstract
+      end
+
+      def http_client
+        Selenium::WebDriver::Remote::Http::Default.new
+      end
+
+      def new_browser(options)
+        Watir::Browser.new(options[:desired_capabilities].browser_name, options)
+      end
+    end
+  end
+end