axe-core-api 2.6.1.pre.0f0b25b

data/lib/axe/api/results/rule.rb

@@ -0,0 +1,58 @@
+require_relative "../value_object"
+require_relative "./checked_node"
+
+module Axe
+  module API
+    class Results
+      class Rule < ValueObject
+        values do
+          attribute :id, ::Symbol
+          attribute :description, ::String
+          attribute :help, ::String
+          attribute :helpUrl, ::String
+          attribute :impact, ::Symbol
+          attribute :tags, ::Array[::Symbol]
+          attribute :nodes, ::Array[CheckedNode]
+        end
+
+        def failure_messages(index)
+          [
+            title_message(index + 1),
+            *[
+              helpUrl,
+              node_count_message,
+              "",
+              nodes.reject { |n| n.nil? }.map(&:failure_messages).map { |n| n.push("") }.flatten.map(&indent),
+            ].flatten.map(&indent),
+          ]
+        end
+
+        def to_h
+          {
+            description: description,
+            help: help,
+            helpUrl: helpUrl,
+            id: id,
+            impact: impact,
+            nodes: nodes.map(&:to_h),
+            tags: tags,
+          }
+        end
+
+        private
+
+        def indent
+          ->(line) { line.prepend(" " * 4) unless line.nil? }
+        end
+
+        def title_message(count)
+          "#{count}) #{id}: #{help} (#{impact})"
+        end
+
+        def node_count_message
+          "The following #{nodes.length} #{nodes.length == 1 ? "node" : "nodes"} violate this rule:"
+        end
+      end
+    end
+  end
+end

data/lib/axe/api/results.rb

@@ -0,0 +1,48 @@
+require_relative "./value_object"
+
+module Axe
+  module API
+    class Results < ValueObject
+      require_relative "./results/rule"
+
+      values do
+        attribute :inapplicable, ::Array[Rule]
+        attribute :incomplete, ::Array[Rule]
+        attribute :passes, ::Array[Rule]
+        attribute :timestamp
+        attribute :url, ::String
+        attribute :violations, ::Array[Rule]
+      end
+
+      def failure_message
+        [
+          "",
+          violation_count_message,
+          "",
+          violations_failure_messages,
+        ].flatten.join("\n")
+      end
+
+      def to_h
+        {
+          inapplicable: inapplicable.map(&:to_h),
+          incomplete: incomplete.map(&:to_h),
+          passes: passes.map(&:to_h),
+          timestamp: timestamp,
+          url: url,
+          violations: violations.map(&:to_h),
+        }
+      end
+
+      private
+
+      def violation_count_message
+        "Found #{violations.count} accessibility #{violations.count == 1 ? "violation" : "violations"}:"
+      end
+
+      def violations_failure_messages
+        violations.each_with_index.map(&:failure_messages)
+      end
+    end
+  end
+end

data/lib/axe/api/rules.rb

@@ -0,0 +1,37 @@
+module Axe
+  module API
+    class Rules
+      def initialize
+        @tags = []
+        @included = []
+        @excluded = []
+        @exclusive = []
+      end
+
+      def according_to(*tags)
+        @tags.concat tags.flatten
+      end
+
+      def checking(*rules)
+        @included.concat rules.flatten
+      end
+
+      def checking_only(*rules)
+        @exclusive.concat rules.flatten
+      end
+
+      def skipping(*rules)
+        @excluded.concat rules.flatten
+      end
+
+      def to_hash
+        {}.tap do |options|
+          # TODO warn that tags + exclusive-rules are incompatible
+          options.merge! runOnly: { type: :tag, values: @tags } unless @tags.empty?
+          options.merge! runOnly: { type: :rule, values: @exclusive } unless @exclusive.empty?
+          options.merge! rules: Hash[@included.product([enabled: true]) + @excluded.product([enabled: false])] unless @included.empty? && @excluded.empty?
+        end
+      end
+    end
+  end
+end

data/lib/axe/api/run.rb

@@ -0,0 +1,53 @@
+require "forwardable"
+require "json"
+
+require_relative "../../chain_mail/chainable"
+require_relative "./audit"
+require_relative "./context"
+require_relative "./options"
+require_relative "./results"
+require_relative "../core"
+
+module Axe
+  module API
+    class Run
+      JS_NAME = "run"
+      METHOD_NAME = "#{Core::JS_NAME}.#{JS_NAME}"
+
+      extend Forwardable
+      def_delegators :@context, :within, :excluding
+      def_delegators :@options, :according_to, :checking, :checking_only, :skipping, :with_options
+
+      extend ChainMail::Chainable
+      chainable :within, :excluding, :according_to, :checking, :checking_only, :skipping, :with_options
+
+      def initialize
+        @context = Context.new
+        @options = Options.new
+      end
+
+      def call(page)
+        audit page do |results|
+          Audit.new to_js, Results.new(results)
+        end
+      end
+
+      private
+
+      def audit(page)
+        yield page.execute_async_script "#{METHOD_NAME}.apply(#{Core::JS_NAME}, arguments)", *js_args
+      end
+
+      def js_args
+        [@context, @options]
+          .reject(&:empty?)
+          .map(&:to_json)
+      end
+
+      def to_js
+        str_args = (js_args + ["callback"]).join(", ")
+        "#{METHOD_NAME}(#{str_args});"
+      end
+    end
+  end
+end

data/lib/axe/api/selector.rb

@@ -0,0 +1,18 @@
+module Axe
+  module API
+    class Selector
+      def initialize(s)
+        @selector = case s
+                    when Array then s
+                    when String, Symbol then [String(s)]
+                    when Hash then Selector.new(s[:selector]).to_a.unshift s[:iframe]
+                    else Selector.new(s.selector).to_a.unshift s.iframe
+                    end
+      end
+
+      def to_a
+        @selector
+      end
+    end
+  end
+end

data/lib/axe/api/value_object.rb

@@ -0,0 +1,9 @@
+require 'virtus'
+
+module Axe
+  module API
+    class ValueObject
+      include ::Virtus.value_object mass_assignment: false, nullify_blank: true
+    end
+  end
+end

data/lib/axe/configuration.rb

@@ -0,0 +1,44 @@
+require "singleton"
+require "forwardable"
+require "json"
+
+require_relative "../hooks"
+require_relative "../webdriver_script_adapter/execute_async_script_adapter"
+
+module Axe
+  class Configuration
+    include Singleton
+    include Common::Hooks
+    extend Forwardable
+
+    attr_writer :jslib
+    attr_accessor :page,
+                  :jslib_path,
+                  :skip_iframes
+    def_delegators ::WebDriverScriptAdapter,
+                   :async_results_identifier,
+                   :async_results_identifier=,
+                   :max_wait_time,
+                   :max_wait_time=,
+                   :wait_interval,
+                   :wait_interval=
+
+    # init
+    def initialize
+      @page = :page
+      @skip_iframes = :skip_iframes
+      @jslib_path = get_root + "/node_modules/axe-core/axe.min.js"
+    end
+
+    # jslib
+    def jslib
+      @jslib ||= Pathname.new(@jslib_path).read
+    end
+
+    private
+
+    def get_root
+      Gem::Specification.find_by_name('axe-core-api').gem_dir
+    end
+  end
+end

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