axe-core-api 2.6.1.pre.78a535c

data/lib/axe/core.rb

@@ -0,0 +1,45 @@
+require_relative "../webdriver_script_adapter/execute_async_script_adapter"
+require_relative "../webdriver_script_adapter/frame_adapter"
+require_relative "../webdriver_script_adapter/query_selector_adapter"
+require_relative "../loader"
+require_relative "./configuration"
+
+module Axe
+  class Core
+    JS_NAME = "axe"
+
+    def initialize(page)
+      @page = wrap_driver page
+      load_axe_core Axe::Configuration.instance.jslib
+    end
+
+    def call(callable)
+      callable.call(@page)
+    end
+
+    private
+
+    def load_axe_core(source)
+      Common::Loader.new(@page, self).call(source) unless already_loaded?
+    end
+
+    def already_loaded?
+      @page.evaluate_script <<-JS
+        window.#{JS_NAME} &&
+        typeof #{JS_NAME}.run === 'function'
+      JS
+    end
+
+    def wrap_driver(driver)
+      ::WebDriverScriptAdapter::QuerySelectorAdapter.wrap(
+        ::WebDriverScriptAdapter::FrameAdapter.wrap(
+          ::WebDriverScriptAdapter::ExecuteAsyncScriptAdapter.wrap(
+            ::WebDriverScriptAdapter::ExecEvalScriptAdapter.wrap(
+              driver
+            )
+          )
+        )
+      )
+    end
+  end
+end

data/lib/axe/dsl.rb

@@ -0,0 +1,15 @@
+require_relative "./matchers/be_accessible"
+require_relative "./expectation"
+
+module Axe
+  module DSL
+    module_function
+
+    # get the be_accessible matcher method
+    extend Matchers
+
+    def expect(page)
+      AccessibilityExpectation.new page
+    end
+  end
+end

data/lib/axe/expectation.rb

@@ -0,0 +1,33 @@
+module Axe
+  class AccessibleExpectation
+    def assert(page, matcher)
+      raise matcher.failure_message unless matcher.matches? page
+    end
+  end
+
+  class InaccessibleExpectation
+    def assert(page, matcher)
+      raise matcher.failure_message_when_negated if matcher.matches? page
+    end
+  end
+
+  class AccessibilityExpectation
+    def self.create(negate)
+      negate ? InaccessibleExpectation.new : AccessibleExpectation.new
+    end
+
+    def initialize(page)
+      @page = page
+    end
+
+    def to(matcher)
+      AccessibleExpectation.new.assert @page, matcher
+    end
+
+    def to_not(matcher)
+      InaccessibleExpectation.new.assert @page, matcher
+    end
+
+    alias :not_to :to_not
+  end
+end

data/lib/axe/finds_page.rb

@@ -0,0 +1,55 @@
+require_relative "./configuration"
+
+module Axe
+  class FindsPage
+    WEBDRIVER_NAMES = [:page, :browser, :driver, :webdriver]
+
+    class << self
+      alias :in :new
+    end
+
+    def initialize(world)
+      @world = world
+    end
+
+    def page
+      from_configuration || implicit or raise "A page/browser/webdriver must be configured"
+    end
+
+    private
+
+    def configuration
+      Axe::Configuration.instance
+    end
+
+    def from_configuration
+      if configuration.page.is_a?(String) || configuration.page.is_a?(Symbol)
+        from_world(configuration.page)
+      else
+        configuration.page
+      end
+    end
+
+    def implicit
+      WEBDRIVER_NAMES.map(&method(:from_world)).drop_while(&:nil?).first
+    end
+
+    def from_world(name)
+      via_method(name) || via_ivar(name)
+    end
+
+    def via_method(name)
+      @world.__send__(name) if @world.respond_to?(name)
+    end
+
+    def via_ivar(name)
+      name = ensure_ivar_format(name)
+      @world.instance_variable_get(name) if @world.instance_variables.include?(name)
+    end
+
+    def ensure_ivar_format(name)
+      # ensure leading '@'
+      name.to_s.sub(/^([^@])/, '@\1').to_sym
+    end
+  end
+end

data/lib/axe/matchers/be_accessible.rb

@@ -0,0 +1,36 @@
+require "forwardable"
+
+require_relative "../../chain_mail/chainable"
+require_relative "../core"
+require_relative "../api/run"
+
+module Axe
+  module Matchers
+    class BeAccessible
+      extend Forwardable
+      def_delegators :@audit, :failure_message, :failure_message_when_negated
+      def_delegators :@run, :within, :excluding, :according_to, :checking, :checking_only, :skipping, :with_options
+
+      extend ChainMail::Chainable
+      chainable :within, :excluding, :according_to, :checking, :checking_only, :skipping, :with_options
+
+      def initialize
+        @run = API::Run.new
+      end
+
+      def audit(page)
+        @audit ||= Core.new(page).call @run
+      end
+
+      def matches?(page)
+        audit(page).passed?
+      end
+    end
+
+    module_function
+
+    def be_accessible
+      BeAccessible.new
+    end
+  end
+end

data/lib/chain_mail/chainable.rb

@@ -0,0 +1,19 @@
+# TODO
+# - able to be extended
+# - able to be used without extending (module_function)
+# - variant that returns nil instead of self
+module ChainMail
+  module Chainable
+    module_function
+
+    def chainable(*methods)
+      methods.each do |method|
+        original = instance_method(method)
+        define_method method do |*args|
+          original.bind(self).call(*args)
+          self
+        end
+      end
+    end
+  end
+end

data/lib/hooks.rb

@@ -0,0 +1,31 @@
+module Common
+  module Hooks
+    HOOKS = [:after_load]
+
+    HOOKS.each do |hook_name|
+      # define instance-level registration method per hook
+      define_method hook_name do |callable = nil, &block|
+        callable ||= block
+        Hooks.callbacks.fetch(hook_name) << callable if callable
+      end
+
+      # define singleton-level run_* method per hook
+      define_singleton_method "run_#{hook_name}" do |*args|
+        callbacks.fetch(hook_name).each do |callback|
+          callback.call(*args)
+        end
+      end
+    end
+
+    # beware, the callbacks hash is a single shared instance tied to this module
+    def self.callbacks
+      @callbacks ||= initialize_callbacks_array_per_hook
+    end
+
+    private
+
+    def self.initialize_callbacks_array_per_hook
+      Hash[HOOKS.map { |name| [name, []] }]
+    end
+  end
+end

data/lib/loader.rb

@@ -0,0 +1,25 @@
+require_relative "./axe/configuration"
+require_relative "./hooks"
+
+module Common
+  class Loader
+    def initialize(page, lib)
+      @page = page
+      @lib = lib
+    end
+
+    def call(source)
+      @page.execute_script source
+      Common::Hooks.run_after_load @lib
+      load_into_iframes(source) unless Axe::Configuration.instance.skip_iframes
+    end
+
+    private
+
+    def load_into_iframes(source)
+      @page.find_frames.each do |iframe|
+        @page.within_frame(iframe) { call source }
+      end
+    end
+  end
+end

data/lib/webdriver_script_adapter/exec_eval_script_adapter.rb

@@ -0,0 +1,27 @@
+require 'dumb_delegator'
+
+module WebDriverScriptAdapter
+  # Capybara distinguishes eval from exec
+  # (eval is a query, exec is a command)
+  # this decorator makes webdriver act like capybara
+  class ExecEvalScriptAdapter < ::DumbDelegator
+    def self.wrap(driver)
+      raise WebDriverError, "WebDriver must respond to #execute_script" unless driver.respond_to? :execute_script
+
+      driver.respond_to?(:evaluate_script) ? driver : new(driver)
+    end
+
+    # executes script without returning result
+    def execute_script(script)
+      super
+      nil
+    end
+
+    # returns result of executing script
+    def evaluate_script(script)
+      __getobj__.execute_script "return #{script}"
+    end
+  end
+
+  class WebDriverError < TypeError; end
+end

data/lib/webdriver_script_adapter/execute_async_script_adapter.rb

@@ -0,0 +1,94 @@
+require "dumb_delegator"
+require "securerandom"
+require "timeout"
+require_relative "./exec_eval_script_adapter"
+
+module WebDriverScriptAdapter
+  class << self
+    attr_accessor :async_results_identifier,
+                  :max_wait_time,
+                  :wait_interval
+
+    def configure
+      yield self
+    end
+  end
+
+  module Defaults
+    module_function
+
+    def async_results_identifier
+      -> { ::SecureRandom.uuid }
+    end
+
+    # set max_wait_time based on type of webdriver
+    def max_wait_time
+      if defined? ::Capybara
+        if ::Capybara.respond_to? :default_max_wait_time
+          ::Capybara.default_max_wait_time
+        else
+          ::Capybara.default_wait_time
+        end
+      elsif defined? ::Selenium::WebDriver::Wait::DEFAULT_TIMEOUT
+        ::Selenium::WebDriver::Wait::DEFAULT_TIMEOUT
+      else
+        3
+      end
+    end
+
+    # set wait interval based on webdriver
+    def wait_interval
+      if defined? ::Selenium::WebDriver::Wait::DEFAULT_INTERVAL
+        ::Selenium::WebDriver::Wait::DEFAULT_INTERVAL
+      else
+        0.1
+      end
+    end
+  end
+
+  module ScriptWriter
+    module_function
+
+    def async_results_identifier
+      id = WebDriverScriptAdapter.async_results_identifier
+      "window['#{id.respond_to?(:call) ? id.call : id}']"
+    end
+
+    def callback(resultsIdentifier)
+      "function(err, returnValue){ #{resultsIdentifier} = (err || returnValue); }"
+    end
+
+    def async_wrapper(script, *args)
+      "(function(){ #{script} })(#{args.join(", ")});"
+    end
+  end
+
+  module Patiently
+    module_function
+
+    def wait_until
+      ::Timeout.timeout(WebDriverScriptAdapter.max_wait_time) do
+        sleep(WebDriverScriptAdapter.wait_interval) while (value = yield).nil?
+        value
+      end
+    end
+  end
+
+  class ExecuteAsyncScriptAdapter < ::DumbDelegator
+    def self.wrap(driver)
+      new ExecEvalScriptAdapter.wrap driver
+    end
+
+    def execute_async_script(script, *args)
+      results = ScriptWriter.async_results_identifier
+      execute_script ScriptWriter.async_wrapper(script, *args, ScriptWriter.callback(results))
+      Patiently.wait_until { evaluate_script results }
+    end
+  end
+
+  configure do |c|
+    c.async_results_identifier = Defaults.async_results_identifier
+    c.max_wait_time = Defaults.max_wait_time
+    c.wait_interval = Defaults.wait_interval
+  end
+end

data/lib/webdriver_script_adapter/frame_adapter.rb

@@ -0,0 +1,84 @@
+require "dumb_delegator"
+
+module WebDriverScriptAdapter
+  class FrameAdapter < ::DumbDelegator
+    def self.wrap(driver)
+      if driver.respond_to?(:within_frame)
+        CapybaraAdapter.new driver
+      elsif !driver.respond_to?(:switch_to)
+        WatirAdapter.new driver
+      elsif driver.switch_to.respond_to?(:parent_frame)
+        SeleniumAdapter.new driver # add within_frame to selenium
+      else
+        ParentlessFrameAdapter.new driver # old selenium doesn't support parent_frame
+      end
+    end
+
+    private
+
+    class CapybaraAdapter < ::DumbDelegator
+      def find_frames
+        all(:css, "iframe")
+      end
+    end
+
+    class WatirAdapter < ::DumbDelegator
+      # delegate to Watir's Selenium #driver
+      def within_frame(frame, &block)
+        SeleniumAdapter.instance_method(:within_frame).bind(FrameAdapter.wrap driver).call(frame, &block)
+      end
+
+      def find_frames
+        driver.find_elements(:css, "iframe")
+      end
+    end
+
+    class SeleniumAdapter < ::DumbDelegator
+      def within_frame(frame)
+        switch_to.frame(frame)
+        yield
+      ensure
+        begin
+          switch_to.parent_frame
+        rescue => e
+          if /switchToParentFrame|frame\/parent/.match(e.message)
+            ::Kernel.warn "WARNING:
+            This browser only supports first-level iframes.
+            Second-level iframes and beyond will not be audited.
+            To skip auditing all iframes,
+            set Axe::Configuration#skip_iframes=true"
+          end
+          switch_to.default_content
+        end
+      end
+
+      def find_frames
+        find_elements(:css, "iframe")
+      end
+    end
+
+    # Selenium Webdriver < 2.43 doesnt support moving back to the parent
+    class ParentlessFrameAdapter < ::DumbDelegator
+      # storage of frame stack (for reverting to parent) taken from Capybara
+      # : https://github.com/jnicklas/capybara/blob/2.6.2/lib/capybara/selenium/driver.rb#L117-L147
+      #
+      # There doesnt appear to be any way in Selenium Webdriver < 2.43 to move back to a parent frame
+      # other than going back to the root and then reiterating down
+      def within_frame(frame)
+        @frame_stack[window_handle] ||= []
+        @frame_stack[window_handle] << frame
+
+        switch_to.frame(frame)
+        yield
+      ensure
+        @frame_stack[window_handle].pop
+        switch_to.default_content
+        @frame_stack[window_handle].each { |f| switch_to.frame(f) }
+      end
+    end
+
+    def find_frames
+      find_elements(:css, "iframe")
+    end
+  end
+end