axe-matchers 1.0.0

data/lib/axe/api.rb

@@ -0,0 +1,5 @@
+module Axe
+  module API
+    LIBRARY_IDENTIFIER = "axe"
+  end
+end

data/lib/axe/api/a11y_check.rb

@@ -0,0 +1,48 @@
+require 'forwardable'
+require 'json'
+
+require 'axe/api'
+require 'axe/api/audit'
+require 'axe/api/context'
+require 'axe/api/options'
+require 'axe/api/results'
+require 'axe/javascript_library'
+
+module Axe
+  module API
+    class A11yCheck
+      METHOD_NAME = "#{LIBRARY_IDENTIFIER}.a11yCheck"
+
+      extend Forwardable
+
+      def_delegators :@context, :include, :exclude
+      def_delegators :@options, :rules_by_tags, :run_rules, :skip_rules, :run_only_rules, :custom_options
+
+      def initialize
+        @context = Context.new
+        @options = Options.new
+      end
+
+      def call(page)
+        inject_axe_lib page
+        audit page do |results|
+          Audit.new to_js, Results.new(results)
+        end
+      end
+
+      private
+
+      def inject_axe_lib(page)
+        JavaScriptLibrary.new.inject_into page
+      end
+
+      def audit(page)
+        yield page.execute_async_script "#{METHOD_NAME}.apply(#{LIBRARY_IDENTIFIER}, arguments)", @context.to_json, @options.to_json
+      end
+
+      def to_js
+        "#{METHOD_NAME}(#{@context}, #{@options}, callback);"
+      end
+    end
+  end
+end

data/lib/axe/api/audit.rb

@@ -0,0 +1,25 @@
+module Axe
+  module API
+    class Audit
+
+      attr_reader :invocation, :results
+
+      def initialize(invocation, results)
+        @invocation = invocation
+        @results = results
+      end
+
+      def passed?
+        results.violations.count == 0
+      end
+
+      def failure_message
+        "#{results.failure_message}\nInvocation: #{invocation}"
+      end
+
+      def failure_message_when_negated
+        "Expected to find accessibility violations. None were detected.\nInvocation: #{invocation}"
+      end
+    end
+  end
+end

data/lib/axe/api/context.rb

@@ -0,0 +1,60 @@
+require 'forwardable'
+
+module Axe
+  module API
+    class Context
+      extend Forwardable
+
+      attr_reader :inclusion, :exclusion
+
+      def initialize
+        @inclusion = []
+        @exclusion = []
+      end
+
+      def include(selector)
+        @inclusion.concat ensure_nested_array(selector)
+        self
+      end
+
+      def exclude(selector)
+        @exclusion.concat ensure_nested_array(selector)
+        self
+      end
+
+      def to_hash
+        {}.tap do |context_param|
+          # include key must not be included if empty
+          # (when undefined, defaults to `document`)
+          context_param[:include] = @inclusion unless @inclusion.empty?
+
+          # exclude array allowed to be empty
+          # and must exist in case `include` is omitted
+          # because context_param cannot be empty object ({})
+          context_param[:exclude] = @exclusion
+        end
+      end
+
+      def to_json
+        if @inclusion.empty?
+          if @exclusion.empty?
+            "document"
+          else
+            %Q({"include":document,"exclude":#{@exclusion.to_json}})
+          end
+        else
+          to_hash.to_json
+        end
+      end
+
+      alias :to_s :to_json
+
+      private
+
+      def ensure_nested_array(selector)
+        Array(selector).map { |s| Array(s) }
+      end
+
+    end
+  end
+end

data/lib/axe/api/options.rb

@@ -0,0 +1,34 @@
+require 'forwardable'
+require 'axe/api/rules'
+
+module Axe
+  module API
+    class Options
+      extend Forwardable
+
+      def_delegator :@rules, :by_tags, :rules_by_tags
+      def_delegator :@rules, :run_only, :run_only_rules
+      def_delegator :@rules, :run, :run_rules
+      def_delegator :@rules, :skip, :skip_rules
+      def_delegator :@custom, :merge!, :custom_options
+
+      attr_reader :rules, :custom
+
+      def initialize
+        @rules = Rules.new
+        @custom = {}
+      end
+
+      def to_hash
+        @rules.to_hash.merge(@custom)
+      end
+
+      def to_json
+        to_hash.to_json
+      end
+
+      alias :to_s :to_json
+
+    end
+  end
+end

data/lib/axe/api/results.rb

@@ -0,0 +1,23 @@
+require 'axe/api/value_object'
+
+module Axe
+  module API
+    class Results < ValueObject
+      require 'axe/api/results/rule'
+
+      values do
+        attribute :url, ::String
+        attribute :timestamp
+        attribute :passes, ::Array[Rule]
+        attribute :violations, ::Array[Rule]
+      end
+
+      def failure_message
+        <<-MSG.gsub(/^\s*/,'')
+        Found #{violations.count} accessibility #{violations.count == 1 ? 'violation' : 'violations'}
+        #{ violations.each_with_index.map(&:failure_message).join("\n\n") }
+        MSG
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+require 'axe/api/value_object'
+require 'axe/api/results/node'
+
+module Axe
+  module API
+    class Results
+      class Check < ValueObject
+        values do
+          attribute :id, ::Symbol
+          attribute :impact, ::Symbol
+          attribute :message, ::String
+          attribute :data, ::String
+          attribute :relatedNodes, ::Array[Node]
+        end
+
+        def failure_message
+          <<-MSG
+          #{message}
+          MSG
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+require 'axe/api/results/node'
+require 'axe/api/results/check'
+
+module Axe
+  module API
+    class Results
+      class CheckedNode < Node
+        values do
+          attribute :impact, ::Symbol
+          attribute :any, ::Array[Check]
+          attribute :all, ::Array[Check]
+          attribute :none, ::Array[Check]
+        end
+
+        def failure_message
+          <<-MSG
+          #{super}
+          #{[].concat(any).concat(all).map(&:failure_message).join("\n")}
+          MSG
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,21 @@
+require 'axe/api/value_object'
+
+module Axe
+  module API
+    class Results
+      class Node < ValueObject
+        values do
+          attribute :html, ::String
+          attribute :target #String or Array[String]
+        end
+
+        def failure_message
+          <<-MSG
+          #{Array(target).join(', ')}
+          #{html}
+          MSG
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,27 @@
+require 'axe/api/value_object'
+require 'axe/api/results/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_message(index)
+          <<-MSG
+          #{index+1}) #{help}: #{helpUrl}
+          #{nodes.map(&:failure_message).join("\n")}
+          MSG
+        end
+      end
+    end
+  end
+end

data/lib/axe/api/rules.rb

@@ -0,0 +1,43 @@
+module Axe
+  module API
+    class Rules
+      attr_reader :tags, :included, :excluded, :exclusive
+
+      def initialize
+        @tags = []
+        @included = []
+        @excluded = []
+        @exclusive = []
+      end
+
+      def by_tags(tags)
+        @tags += tags
+        self
+      end
+
+      def run_only(rules)
+        @exclusive += rules
+        self
+      end
+
+      def run(rules)
+        @included += rules
+        self
+      end
+
+      def skip(rules)
+        @excluded += rules
+        self
+      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/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,42 @@
+require 'forwardable'
+require 'webdriver_script_adapter/execute_async_script_adapter'
+
+module Axe
+  class Configuration
+    extend Forwardable
+
+    attr_accessor :page
+    def_delegators ::WebDriverScriptAdapter,
+      :async_results_identifier, :async_results_identifier=,
+      :max_wait_time, :max_wait_time=,
+      :wait_interval, :wait_interval=
+
+    def page_from(world)
+      page_from_eval(world) ||
+        page ||
+        default_page_from(world) ||
+        from_ivar(:@page, world) ||
+        from_ivar(:@browser, world) ||
+        from_ivar(:@driver, world) ||
+        from_ivar(:@webdriver, world) ||
+        NullWebDriver.new
+    end
+
+    private
+
+    def page_from_eval(world)
+      world.instance_eval "#{page}" if page.is_a?(String) || page.is_a?(Symbol)
+    end
+
+    def default_page_from(world)
+      world.page if world.respond_to? :page
+    end
+
+    def from_ivar(ivar, world)
+      self.page = ivar
+      page_from_eval(world)
+    end
+  end
+
+  class NullWebDriver; end
+end

data/lib/axe/cucumber/step.rb

@@ -0,0 +1,89 @@
+require 'yaml'
+
+require 'axe'
+require 'axe/matchers/be_accessible'
+
+# The purpose of this class is to enable private helper methods for assertion
+# and cucumber argument parsing without leaking the helper methods into the
+# cucumber World object.
+# Further, using these helper methods for assert/refute removes the dependency
+# on rspec. So end users may choose to use any (or non) assertion/expectation
+# library, as this class uses the Axe Accessibility Matcher directly, without
+# using a matcher/expectation library DSL.
+module Axe
+  module Cucumber
+    class Step
+      REGEX = /^
+
+      # require initial phrasing, with 'not' to negate the matcher
+      (?-x:the page should(?<negate> not)? be accessible)
+
+      # optionally specify which subtree to check, via CSS selector
+      (?-x:;? within "(?<inclusion>.*?)")?
+
+      # optionally specify subtrees to be excluded, via CSS selector
+      (?-x:;?(?: but)? excluding "(?<exclusion>.*?)")?
+
+      # optionally specify ruleset via list of comma-separated tags
+      (?-x:;? according to: (?<tags>.*?))?
+
+      # optionally specify rules (as comma-separated list of rule ids) to check
+      # in addition to default ruleset or explicit ruleset specified above via tags
+      # if the 'only' keyword is supplied, then *only* the listed rules are checked, not *additionally*
+      (?-x:;?(?: and)? checking(?<run_only> only)?: (?<run_rules>.*?))?
+
+      # optionally specify rules (as comma-separated list of rule ids) to skip
+      (?-x:;?(?: but)? skipping: (?<skip_rules>.*?))?
+
+      # optionally specify custom options (as a yaml-parsed hash or json string) to pass directly to axe-core
+      (?-x:;? with options: (?<options>.*?))?
+
+      $/x
+
+      def self.create_for(world)
+        new Axe.page_from world
+      end
+
+      def initialize(page)
+        @page = page
+      end
+
+      def be_accessible(negate, inclusion, exclusion, tags, run_only, run_rules, skip_rules, options)
+        accessibility = Matchers::BeAccessible.new
+
+        accessibility.within(selector inclusion) if inclusion
+        accessibility.excluding(selector exclusion) if exclusion
+        accessibility.according_to(split tags) if tags
+        run_only ? accessibility.checking_only(split run_rules) : accessibility.checking(split run_rules) if run_rules
+        accessibility.skipping(split skip_rules) if skip_rules
+        accessibility.with_options(to_hash options) if options
+
+        if negate then refute accessibility else assert accessibility end
+      end
+
+      private
+
+      attr_reader :page
+
+      def selector(selector)
+        split(selector)
+      end
+
+      def split(string)
+        String(string).split(/,\s*/)
+      end
+
+      def to_hash(string)
+        YAML.load string
+      end
+
+      def assert(matcher)
+        raise matcher.failure_message unless matcher.matches? page
+      end
+
+      def refute(matcher)
+        raise matcher.failure_message_when_negated if matcher.matches? page
+      end
+    end
+  end
+end