axe-matchers 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 33ad37f031298e34a65bb01d494d4a26ab600a41
-  data.tar.gz: 4deb2f97a3ccac73730c1dd4d8572d1cd45bf2ed
+  metadata.gz: a4ce283bc01f3e57d9c2d68192f9c81063cd1244
+  data.tar.gz: 98200dc0c23e1e0d90bae077591b747ad4e087cd
 SHA512:
-  metadata.gz: e57a6e8793fc43ff030efaeb39664365aecbcd86ed55a66742e40d0c4749c177669619bf6a5479312b0fe28c89cef68baeb8a7436ce230971931b05efb125dc6
-  data.tar.gz: 4def6e8ca24af43a8cc89e85d6c7c3b3ec64d0724ad4e332acd92e04d4c2f718408be6367606122a88a83f9a9b8067b4424766bf6f07d58cba6065f4528ef6bd
+  metadata.gz: 1c04838dedcf4eb65c9461b4115d2b814ec7a463f66a92f47ef003164be6dcb447f8917d33114ff75cbcef2222afae3980cd838a65e0f28c20aad520f9da0d3c
+  data.tar.gz: 6d3cf4f14f44191c53e5e6af6a3526f7e28ca9e32ea94afaeedd36636fd8c27c248a39ef136753cb1e8c7234f3065d2fa1eff7247b240bedde81e8411af8889c

data/README.md

@@ -1,72 +1,140 @@
+# Installation
 
+`gem install axe-matchers`
 
-# Requirements
+or add `gem 'axe-matchers'` to your `Gemfile` and `bundle install`
 
-1. Ruby 2.0.0 or later.
-2. Bundler for gem dependencies
-3. Brewdler for system dependencies (phantomjs, chromedriver, etc)
-4. Rake as task runner
-5. RSpec for unit tests
-6. Cucumber for end to end tests
-7. Node/npm are necessary for pulling down the axe-core package
+# Cucumber Configuration
 
-## Ruby Version management
+1. Require step definitions
 
-[rbenv](https://github.com/sstephenson/rbenv) is recommended but you may also use [rvm](https://rvm.io/), [chruby](https://github.com/postmodern/chruby) or other ruby version manager of your choice. 2.0.0-p481 is the official minimum version, as it is the default Ruby bundled with OS X Mavericks, but the gem *ought* to support 1.9 and above.
+Require the axe-matcher step definitions in `features/support/env.rb` or similar.
 
-The `.ruby-version` is intentionally ignored from the repo for the same reason that `Gemfile.lock` should not be committed. See http://yehudakatz.com/2010/12/16/clarifying-the-roles-of-the-gemspec-and-gemfile/ for more clarification.
+``` ruby
+require 'axe/cucumber/step_definitions'
+```
+
+2. Configure Browser/WebDriver
+
+If there exists a `page` method on the Cucumber `World` (as is provided by the Capybara DSL), or if one of `@page`, `@browser`, `@driver` or `@webdriver` exist, then no configuration is necessary.  Otherwise, the browser object must be configurate manually.
+
+The browser/page object can be provided directly. Or in cases where it hasn't been instantiated yet, the variable name can be given as a String/Symbol.
+
+``` ruby
+@firefox = Selenium::WebDriver.for :firefox
+
+Axe::Cucumber.configure do |c|
+  # browser object
+  c.page = @firefox
+
+  # or variable name
+  c.page = :@firefox
+end
+```
+
+# Accessibility Steps
+
+To construct an axe accessibility Cucumber step, begin with the base step, and append any clauses necessary. All of the following clauses may be mixed and matched; however, they must appear in the specified order:
+
+`Then the page should be accessible [including] [excluding] [according-to] [checking-rules/checking-only-rules] [skipping-rules]`
+
+## Base Step
+
+``` gherkin
+Then the page should be accessible
+```
+
+The base step is the core component of the step. It is a complete step on its own and will verify the currently loaded page is accessible using the default configuration of [axe.a11yCheck](https://github.com/dequelabs/axe-core/blob/master/doc/API.md#api-name-axea11ycheck) (the entire document is checked using the default rules).
+
+## Inclusion clause
+
+``` gherkin
+Then the page should be accessible within "#selector"
+```
 
-## Bundler
+The inclusion clause (`within "#selector"`) specifies which elements of the page should be checked. A valid CSS selector must be provided, and is surrounded in double quotes. Compound selectors may be used to select multiple elements. e.g. `within "#header, .footer"`
 
-    `gem install bundler` to install bundler
-    `bundle install` to install necessary gems
+Additional [context parameter documentation](https://github.com/dequelabs/axe-core/blob/master/doc/API.md#a-context-parameter)
 
-All subsequent commands (when invoking rake, rspec, cucumber, etc) must be prefixed with `bundle exec` unless you are using bundler binstubs or rbenv-bundle-exec or similar. (Elsewhere in this readme, the `bundle exec` prefix will be omitted.)
+## Exclusion clause
 
-## Brewdler
+``` gherkin
+Then the page should be accessible excluding "#selector"
+```
 
-Most of the dependencies necessary for running the various test suite configurations are provided via gems and managed by bundler.
+The exclusion clause (`excluding "#selector"`) specifies which elements of the document should be ignored. A valid CSS selector must be provided, and is surrounded in double quotes. Compound selectors may be used to select multiple elements. e.g. `excluding "#widget, .ad"`
 
-However, to run the tests against phantomjs, you will need phantomjs installed. And to run the tests against chrome, you will need chromedriver. Both of these are system dependencies. These can be installed manually, or through homebrew. To ease installation of these non-gem dependencies, a `Brewfile` is provided.
+Additional [context parameter documentation](https://github.com/dequelabs/axe-core/blob/master/doc/API.md#a-context-parameter)
 
-    `brew tap homebrew/bundle` to install brewdler
-    `brew bundle` to install phantomjs and chromedriver
+If desired, a semicolon (`;`) or the word `but` may be used to separate the exclusion clause from the inclusion clause (if present).
 
-Additionally, to test against Safari, the SafariDriver extension is needed. Install it (using Safari) from http://selenium-release.storage.googleapis.com/2.45/SafariDriver.safariextz.
+``` gherkin
+Then the page should be accessible within "#header"; excluding "#footer"
+Then the page should be accessible within "#header" but excluding "#footer"
+```
 
-## Rake Tasks
+## Accessibility Standard (Tag) clause
 
-Rake is the standard task runner. For a list of configured tasks, run `rake -T`. Briefly:
+``` gherkin
+Then the page should be accessible according to: wcag2a
+```
 
-- `rake spec` to run unit tests
-- `rake cucumber` to run end to end tests
-- `rake build` to build and package the gem
-- `rake clean` and `rake clobber` to clean up build assets
+The tag clause specifies which accessibility standard (or standards) should be used to check the page. The accessibility standards are specified by name (tag). Multiple standards can be specified when comma-separated. e.g. `according to: wcag2a, section508`
 
-# RSpec Unit Tests
+The acceptable [tag names are documented](https://github.com/dequelabs/axe-core/blob/master/doc/API.md#b-options-parameter) as well as a [complete listing of rules](https://github.com/dequelabs/axe-core/blob/master/doc/rule-descriptions.md) that correspond to each tag/standard.
 
-These confirm the proper behavior of the matchers. These are located in the `spec` directory and may be run with `rake spec` or `rspec`.
+If desired, a semicolon (`;`) may be used to separate the tag clause from the preceding clause.
 
-# Cucumber Features
+``` gherkin
+Then the page should be accessible within "#header"; according to: best-practice
+```
 
-There is a single feature that does a minimal test of the matchers + cucumber steps + axe js library. It is intended as a smoke test to validate against multiple webdrivers. Unless a specific profile is specified, cucumber will run the default profile which drives webkit (headless) with capybara. Alternatiely, you may specify the driver and browser combination:
+## Checking Rules clause
 
+``` gherkin
+Then the page should be accessible checking: ruleId
 ```
-cucumber -p capybara -p poltergeist
-cucumber -p capybara -p webkit
-cucumber -p capybara -p firefox
-cucumber -p selenium -p phantomjs
-cucumber -p watir -p chrome
+
+The checking-rules clause specifies which *additional* rules to run (in addition to the specified tags, if any, or the default ruleset). The rules are specified by comma-separated rule IDs. (see [rules documentation](https://github.com/dequelabs/axe-core/blob/master/doc/rule-descriptions.md) for a list of valid rule IDs)
+
+If desired, a semicolon (`;`) or the word `and` may be used to separate the checking-rules clause from the preceding clause.
+
+``` gherkin
+Then the page should be accessible according to: wcag2aa; checking: color-contrast
+Then the page should be accessible according to: wcag2aa and checking: color-contrast
+```
+
+### Exclusive Rules clause
+
+``` gherkin
+Then the page should be accessible checking only: ruleId
 ```
 
-First specify the driver (one of: `capybara`, `selenium` or `watir`), and choose the browser (`firefox`, `chrome`, `safari`, `phantomjs`). All three drivers support all four browsers. Capybara alone also supports `webkit` and `poltergeist`.
+This clause is not really a separate clause. But rather, by adding the word `only` to the checking-rules clause, the meaning of the step can be changed. As described above, by default the checking-rules clause specifies *additional* rules to run. If the word `only` is used, then *only* the specified rules are checked.
 
-These profile configurations can also be run via rake: `rake cucumber:{driver}:{browser}`. For example:
+## Skipping Rules clause
 
+``` gherkin
+Then the page should be accessible skipping: ruleId
 ```
-rake cucumber:capybara:firefox
-rake cucumber:selenium:chrome
-rake cucumber:watir:phantomjs
+
+The skipping-rules clause specifies which rules to skip. This allows an accessibility standard to be provided (via the tag clause) while ignoring a particular rule. The rules are specified by comma-separated rule IDs. (see [rules documentation](https://github.com/dequelabs/axe-core/blob/master/doc/rule-descriptions.md) for a list of valid rule IDs)
+
+If desired, a semicolon (`;`) or the word `but` may be used to separate the skipping-rules clause from the preceding clause.
+
+``` gherkin
+Then the page should be accessible according to: wcag2a; skipping: accesskeys
+Then the page should be accessible according to: wcag2a but skipping: accesskeys
 ```
 
-You may omit the browser (`rake cucumber:capybara`) and it will run the features under every configured browser for the given driver. Alternatively, you may omit the driver (`rake cucumber:firefox`) and it will run the features with each driver for the given browser. Additionally, there are special options to run every driver/browser combination `rake cucumber:all`, or only the headless browsers `rake cucumber:headless`. (Headless combinations are capybara+poltergeist, capybara+webkit, capybara+phantomjs, selenium+phantomjs, watir+phantomjs)
+# Examples
+
+``` gherkin
+Then the page should be accessible within "main, header" but excluding "footer"
+
+Then the page should be accessible excluding "#sidebar" according to: wcag2a, wcag2aa but skipping: color-contrast
+
+Then the page should be accessible checking only: document-title, label
+
+Then the page should be accessible according to: best-practice and checking: aria-roles, definition-list
+```

data/lib/axe/api/a11y_check.rb

@@ -1,6 +1,8 @@
 require 'forwardable'
 require 'json'
 
+require 'chain_mail/chainable'
+
 require 'axe/api'
 require 'axe/api/audit'
 require 'axe/api/context'
@@ -14,9 +16,11 @@ module Axe
       METHOD_NAME = "#{LIBRARY_IDENTIFIER}.a11yCheck"
 
       extend Forwardable
+      def_delegators :@context, :within, :excluding
+      def_delegators :@options, :according_to, :checking, :checking_only, :skipping, :with_options
 
-      def_delegators :@context, :include, :exclude
-      def_delegators :@options, :rules_by_tags, :run_rules, :skip_rules, :run_only_rules, :custom_options
+      extend ChainMail::Chainable
+      chainable :within, :excluding, :according_to, :checking, :checking_only, :skipping, :with_options
 
       def initialize
         @context = Context.new

data/lib/axe/api/audit.rb

@@ -18,7 +18,7 @@ module Axe
       end
 
       def failure_message_when_negated
-        "Expected to find accessibility violations. None were detected.\nInvocation: #{invocation}"
+        "Expected to find accessibility violations. None were detected.\n\nInvocation: #{invocation}"
       end
     end
   end

data/lib/axe/api/context.rb

@@ -1,60 +1,36 @@
-require 'forwardable'
+require 'axe/api/selector'
 
 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
+      def within(*selectors)
+        @inclusion.concat selectors.map { |s| Array(Selector.new s) }
       end
 
-      def exclude(selector)
-        @exclusion.concat ensure_nested_array(selector)
-        self
+      def excluding(*selectors)
+        @exclusion.concat selectors.map { |s| Array(Selector.new s) }
       end
 
       def to_hash
         {}.tap do |context_param|
-          # include key must not be included if empty
-          # (when undefined, defaults to `document`)
+          # omit empty arrays
+          # (include must not be present if empty)
+          # (exclude is allowed to be empty; but meh)
           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
+          context_param[:exclude] = @exclusion unless @exclusion.empty?
         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
+        to_hash.to_json
       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

@@ -6,13 +6,8 @@ module Axe
     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_delegators :@rules, :according_to, :checking, :checking_only, :skipping
+      def_delegator :@custom, :merge!, :with_options
 
       def initialize
         @rules = Rules.new

data/lib/axe/api/rules.rb

@@ -1,8 +1,6 @@
 module Axe
   module API
     class Rules
-      attr_reader :tags, :included, :excluded, :exclusive
-
       def initialize
         @tags = []
         @included = []
@@ -10,24 +8,20 @@ module Axe
         @exclusive = []
       end
 
-      def by_tags(tags)
-        @tags += tags
-        self
+      def according_to(*tags)
+        @tags.concat tags.flatten
       end
 
-      def run_only(rules)
-        @exclusive += rules
-        self
+      def checking(*rules)
+        @included.concat rules.flatten
       end
 
-      def run(rules)
-        @included += rules
-        self
+      def checking_only(*rules)
+        @exclusive.concat rules.flatten
       end
 
-      def skip(rules)
-        @excluded += rules
-        self
+      def skipping(*rules)
+        @excluded.concat rules.flatten
       end
 
       def to_hash

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/cucumber.rb

@@ -0,0 +1,3 @@
+require 'axe/dsl'
+
+World Axe::DSL

data/lib/axe/cucumber/step.rb

@@ -1,11 +1,11 @@
 require 'yaml'
 
 require 'axe'
-require 'axe/matchers/be_accessible'
+require 'axe/matchers'
+require 'axe/expectation'
 
-# 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.
+# The purpose of this class is to support private helpers for 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
@@ -48,23 +48,22 @@ module Axe
         @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
+      def assert_accessibility(negate=false, inclusion="", exclusion="", tags="", run_only=false, run_rules="", skip_rules="", options=nil)
+        is_accessible = Axe::Matchers::BeAccessible.new.tap do |a|
+          a.within *selector(inclusion)
+          a.excluding *selector(exclusion)
+          a.according_to *split(tags)
+          a.checking *split(run_rules) unless run_only
+          a.checking_only *split(run_rules) if run_only
+          a.skipping *split(skip_rules)
+          a.with_options to_hash(options)
+        end
+
+        Axe::AccessibilityExpectation.create(negate).assert @page, is_accessible
       end
 
       private
 
-      attr_reader :page
-
       def selector(selector)
         split(selector)
       end
@@ -74,15 +73,7 @@ module Axe
       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
+        (string && !string.empty?) ? YAML.load(String(string)) : {}
       end
     end
   end