bbc-a11y 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 860a8a0ec77c6173b3135e22cfe79fd35425bea9
-  data.tar.gz: 3e0a6bc605c287bcd11f4704166938dbbea0661e
+  metadata.gz: d59c94f740e8990fafb8ae7201c7096cd91ccef9
+  data.tar.gz: 57e5a3f69ce2e509ce61d765edda3c2b1df5893f
 SHA512:
-  metadata.gz: 43163b05f80e4d566df4f1c36307da416752c4f8630b2209c7d3a4a85f6480fc68cc5ab1010933552833af8708da9da54da8f270415ad3472ce77f6530521403
-  data.tar.gz: 934b77fb2a31ea46624b45679f499276dc839f843d1b6d67bc91c7e9ca4e44a2dec6a0411536819950e37bb6b1db73ee04ac89f95383728e69c340ceb681fb92
+  metadata.gz: 135ffcf60d5e6a159d0ddb987e0c939e6dfbdd41215f75e3887aad71bcf6a91f17d6f637f6299799434a5464d21fd8e61c44f183df6ab90fe45fc7936d657d8c
+  data.tar.gz: cec1529c7021ee79faec561281dabcfd0cf77fd1f16ea9c92530922aaaf93cefb16b914cafb5a70f8870439bf3d3c21f653828941c9bb5ae9d398bf460487418

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+rvm:
+  2.2
+before_script:
+  - npm install
+  - export PATH=$PWD/node_modules/.bin:$PATH
+script:
+  - bundle exec rake
+  - npm test

data/CONTRIBUTING.md

@@ -1,15 +1,77 @@
-# BBC A11y Contributing guidelines
+# BBC A11y Contributing Guidelines
 
-The standards are all stored in the `standards` directory.
+## How can I contribute?
 
-You can run a manual test of your development copy of a11y at any time just by running:
+We welcome contributions of all shapes and sizes, but we prefer them in the form
+of Github [issues](https://github.com/cucumber-ltd/bbc-a11y/issues/new) or [pull requests](https://help.github.com/articles/using-pull-requests). Please have a quick look at our [existing
+issues](https://github.com/cucumber-ltd/bbc-a11y/issues) before posting, as you may find we are already thinking about or working
+on a fix.
 
-    bundle exec ./bin/a11y <url>
+## Improving standards checks
 
-You can also use cucumber to run one specific test:
+If you believe there is a bug or misinterpretation of the BBC Accessibility
+Guidelines, please submit an issue with as much relevant detail as possible.
+Ideally this should include an HTML snippet that demonstrates the problem. Even
+more ideally, you can create or amend a scenario in one of our [cucumber features](features/check_standards).
 
-    A11Y_URL=<url> bundle exec cucumber features/04_language.feature
+## Contributing code
 
-The step definitions behind these features are shallow wrappers that delegate to objects in `lib/bbc/a11y/`. Those objects are unit-tested to ensure they'll behave as expected when tests pass or fail.
+Contributions of code are very welcome. You'll need to do a little bit more
+setup before you can start hacking on the code:
 
-To add new behaviour, test-drive changes to the objects in `lib`.
+### Prerequisites
+
+You'll need to install a few things on your system before you can work on the
+code:
+
+  * Ruby (1.9.3 is required, 2.0+ is recommended)
+  * node.js (5.0+ is recommended)
+  * phantomjs
+
+Once those are installed, you can install the Ruby dependencies:
+
+  ```
+  bundle install
+  ```
+
+...and the node.js dependencies:
+
+  ```
+  npm install
+  ```
+
+...then finally run all the tests to verify:
+
+  ```
+  bundle exec rake
+  ```
+
+You should see red if anything fails. If all tests pass, you are ready to start
+hacking! If not, please get in touch and we'll help you figure it out.
+
+### Amending features
+
+It usually makes sense to start by briefly reviewing the [cucumber
+features](features) as there may be similar scenarios already implemented. Then
+change the features, or add scenarios to cover new edge cases, or create new
+feature files.
+
+When you are done changing feature files, we recommend that you submit a pull
+request, to get feedback from the a11y team before implementing your change.
+
+### Implementing code changes
+
+When it's time to implement your changes, you might need to write Ruby, or
+JavaScript, or both. The standards checks are implemented in JavaScript,
+whereas the command-line runner is implemented in Ruby.
+
+There are high-level cucumber features, and low-level specs for both Ruby and
+JavaScript. The cucumber features are generally broad in scope have more moving
+parts, so depending on the change, it can be difficult to understand why things
+fail, and to iterate on changes. In this case you should consider writing or
+amending the low-level [JavaScript specs for the standards](spec/bbc/a11y/js)
+or [Ruby specs for the runner](spec/bbc/a11y).
+
+When all tests pass, please submit a pull request and the team will review it.
+
+Happy hacking!

data/GETTINGSTARTED.md

@@ -0,0 +1,65 @@
+## BBC A11y User Guide
+
+## Installing bbc-a11y to validate your project
+
+bbc-a11y is packaged as a Ruby gem. You'll most likely want to create a
+stand-alone repo to run your accessibility tests, but you can also add it as
+part of an existing repo.
+
+### Prerequisites
+
+[Install Ruby](https://www.ruby-lang.org/en/documentation/installation/) and
+then:
+
+    gem install bundler
+
+### Adding a11y to your project's Gemfile
+
+Create or amend your your project's `Gemfile` to include this line:
+
+    gem 'bbc-a11y`
+
+Now install the gem:
+
+    bundle install
+
+## Configuring a11y for your project
+
+You'll need to configure a11y with a set of URLs to run the checks against.
+Create a file called `a11y.rb` in the root of your project that looks something
+like this:
+
+```
+page "http://bbc.co.uk"
+page "http://bbc.co.uk/news"
+```
+
+### Skipping standards checks
+
+Nobody's perfect. Use `skip_standard` in the configuration to opt-out of certain
+checks.
+
+```
+page "http://bbc.co.uk" do
+  skip_standard 'Focusable controls: Anchors must have hrefs'
+end
+
+page "http://bbc.co.uk/news"
+```
+
+A11y will skip any standards from whose name matches that string.
+
+## Running it
+
+Once you're configured, you can run the tests using the `a11y` command, from the
+directory where your `a11y.rb` configuration file is stored:
+
+    bundle exec a11y
+
+This will pick up your `a11y.rb` configuration file and run the a11y checks on
+each page specified in your configuration. Output is printed to the console.
+
+## Using a11y in build scripts
+
+The `a11y` executable will exit with a non-zero status code if there are any
+standards failures, for convenient integration with CI tools like Jenkins.

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2014 Cucumber Limited
+Copyright (c) 2016 British Broadcasting Corporation
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,62 +1,19 @@
-[![Circle CI](https://circleci.com/gh/cucumber-ltd/bbc-a11y.svg?style=svg&circle-token=00d656fd091643ad692c78ca60e30ad95df9563a)](https://circleci.com/gh/cucumber-ltd/bbc-a11y)
 
-# WARNING - PROTOTYPE SOFTWARE
+# BBC Accessibility Standards Checker
 
-This project is still at an experimental / proof-of-concept stage. Please set your expectations appropriately, but *do* [give us as much feedback](https://github.com/cucumber-ltd/bbc-a11y/issues) as you can.
+This tool runs a set of tests against a set of URLs to verify whether each one
+meets the [BBC accessibility
+standards](http://www.bbc.co.uk/guidelines/futuremedia/accessibility/).
 
-#BBC Accessibility Standards
+This project is a work in progress, but it is stable and you can use it in your
+project today.
 
-This tool runs a set of tests against a set of URLs to verify whether each one meets the [BBC accessibility standards](http://www.bbc.co.uk/guidelines/futuremedia/accessibility/).
+## Using BBC A11y
 
-## How to install
+The [getting started guide](GETTINGSTARTED.md) shows how to use a11y in your
+project.
 
-bbc-a11y is packaged as a Ruby gem. You'll most likely want to create a stand-alone repo to run your accessibilty tests,
-but you can also add it as part of an existing repo.
+## Contributing to BBC A11y
 
-### Prerequisites
-
-[Install Ruby](https://www.ruby-lang.org/en/documentation/installation/) and then:
-
-    gem install bundler
-
-### Adding a11y to your project's Gemfile
-
-Create or amend your your project's `Gemfile` to include this line:
-
-    gem 'bbc-a11y`
-
-Now install the gem:
-
-    bundle install
-
-## Configuration
-
-You'll need to configure a11y with a set of URLs to run the checks against. Create a file `a11y.rb` in the root of your project that looks something like this:
-
-```
-page "http://bbc.co.uk"
-page "http://bbc.co.uk/news"
-```
-
-### Skipping scenarios
-
-Nobody's perfect. Use `skip_standard` in the configuration to opt-out of certain checks.
-
-```
-page "http://bbc.co.uk" do
-  skip_standard /W3C/
-end
-
-page "http://bbc.co.uk/news"
-```
-
-A11y will skip any scenarios from the specifications whose name contains that string.
-
-## Running it
-
-Once you're configured, you can run the tests using the `a11y` command, from the directory where your `a11y.rb` configuration file is stored:
-
-    bundle exec a11y
-
-This will pick up your `a11y.rb` configuration file and run the a11y checks on each page specified in your configuration.
-Output is printed to the console.
+We welcome contributions of ideas and code! Please refer to the
+[contributing guide](CONTRIBUTING.md).

data/Rakefile

@@ -4,7 +4,7 @@ Bundler::GemHelper.install_tasks
 task default: [:unit, :acceptance]
 
 task :unit do
-  sh "bundle exec rspec"
+  sh "bundle exec rspec && karma start --single-run"
 end
 
 task :acceptance do

data/a11y.rb

@@ -1,5 +1,3 @@
 page "https://bbc.co.uk/news" do
-  skip_standard /W3C/
-  skip_standard /JavaScript/
-  skip_standard /title/
+  skip_standard /title/i
 end

data/bbc-a11y.gemspec

@@ -16,7 +16,6 @@ Gem::Specification.new do |s|
   s.add_dependency 'capybara'
   s.add_dependency 'phantomjs'
   s.add_dependency 'poltergeist'
-  s.add_dependency 'colorize'
 
   s.add_development_dependency 'rspec',  '~> 3.0'
   s.add_development_dependency 'aruba', '~> 0.9'

data/features/check_standards/01_core_purpose.feature

@@ -0,0 +1,39 @@
+Feature: Core Purpose
+
+  Rationale
+  =========
+
+  While our aim is for all users to have access to all features of BBC apps and
+  sites we recognise that technology both restricts and extends what is
+  possible.
+
+  Additionally GEL is aimed providing the best experience to the broadest range
+  of users, and while it should not discriminate against users with access needs
+  nor does it give special privilege.
+
+  The aim of this guideline is to provide the most accessible base line
+  experience for the core purpose across the broadest range of technology.
+
+  See the following standards for examples of when a defined core purpose is
+  applicable:
+
+    * Progressive enhancement
+
+    * Minimum text size
+
+  It is not a reason to ignore accessibility for non-core page elements.
+
+  Using the standards and guidelines
+  ==================================
+
+  You can use use and re-use the the BBC Accessibility Standards and Guidelines
+  under an Open Government Licence for Public Sector Information.
+
+  Details can be found on the Open Government Licence for Public Sector
+  Information website.
+
+  Feedback
+  ========
+
+  We would love to hear your feedback. If you have a question or comment about
+  the standards or guidelines email us at AccessibilityTeam@bbc.co.uk.

data/features/check_standards/02_validation.feature

@@ -0,0 +1 @@
+Feature: Validation

data/features/check_standards/03_progressive_enhancement.feature

@@ -0,0 +1,3 @@
+Feature: Progressive Enhancement
+
+  * The core purpose of every document must not require JavaScript or CSS to function.

data/features/check_standards/{language.feature → 04_indicating_language.feature}

@@ -23,7 +23,7 @@ Feature: Specify content language
         </body>
       </html>
       """
-    When I validate the "html must have lang attribute" standard
+    When I validate the "Indicating language: html must have lang attribute" standard
     Then it passes
 
   Scenario: Missing lang attribute on html element
@@ -39,7 +39,7 @@ Feature: Specify content language
         </body>
       </html>
       """
-    When I validate the "html must have lang attribute" standard
+    When I validate the "Indicating language: html must have lang attribute" standard
     Then it fails with the message:
       """
       html tag has no lang attribute: /html

data/features/check_standards/05_page_titles.feature

@@ -0,0 +1 @@
+Feature: Page Titles

data/features/check_standards/{main_landmark.feature → 06_main_landmark.feature}

@@ -8,31 +8,31 @@ Feature: Main landmark
   The WAI-ARIA `main` landmark role can be help keyboard users with assistive technologies such as screen readers (and in the future as native browser functionality) to skip directly to the main content of a page, bypassing navigation and other contents that might be before it.
 
   Scenario: Page has a single main element
-    Given a page with the HTML:
+    Given a page with the body:
       """
       <div role="main">Main element</div>
       """
-    When I validate the "exactly one main landmark" standard
+    When I validate the "Main landmark: exactly one main landmark" standard
     Then it passes
 
   Scenario: Page has two main elements
-    Given a page with the HTML:
+    Given a page with the body:
       """
       <div role="main">Main one</div>
       <div role="main">Main two</div>
       """
-    When I validate the "exactly one main landmark" standard
+    When I validate the "Main landmark: exactly one main landmark" standard
     Then it fails with the message:
       """
       Found 2 elements with role="main": /html/body/div[1] /html/body/div[2]
       """
 
   Scenario: Page has zero main elements
-    Given a page with the HTML:
+    Given a page with the body:
       """
       <div role="not-main">Main one</div>
       """
-    When I validate the "exactly one main landmark" standard
+    When I validate the "Main landmark: exactly one main landmark" standard
     Then it fails with the message:
       """
       Found 0 elements with role="main".

data/features/check_standards/07_headings.feature

@@ -0,0 +1,222 @@
+Feature: Headings
+
+  A document **must** have exactly one `<h1>` element.
+
+  Heading levels after the document `<h1>` element **must** be sequential and **must not** skip heading levels.
+
+  Heading elements **must** be followed by content.
+
+  Rationale
+  =========
+
+  A logical heading structure is invaluable for users of screen readers and similar assistive technologies to help navigate content.
+
+  Users should be able to use the document's `<h1>` identify its main content. Documents should have one main subject.
+
+  Heading levels should not be skipped as a predictable document outline is an important factor for understandability.
+
+  Headings should not be used for non-heading purposes, i.e. to identify blocks of content. A heading should always
+  be followed either by non-heading content or by a heading of one level deeper.
+
+  Scenario: No main heading
+    Given a page with the body:
+      """
+      <h2>Heading 2</h2>
+      """
+    When I validate the "Headings: exactly one main heading" standard
+    Then it fails with the message:
+      """
+      Found 0 h1 elements.
+      """
+
+  Scenario: More than one main heading
+    Given a page with the body:
+      """
+      <h1>Heading 1</h1>
+      <h2>Heading 2</h2>
+      <h1>Heading 1</h1>
+      """
+    When I validate the "Headings: exactly one main heading" standard
+    Then it fails with the message:
+      """
+      Found 2 h1 elements: /html/body/h1[1] /html/body/h1[2]
+      """
+
+  Scenario: More than one main heading, but only one visible
+    Given a page with the body:
+      """
+      <h1>A Heading</h1>
+      <h1 style="display:none">Another Heading</h1>
+      """
+    When I validate the "Headings: exactly one main heading" standard
+    Then it passes
+
+  Scenario: Headings in ascending order
+    Given a page with the body:
+      """
+      <h1>Heading 1</h1>
+      <h2>Heading 2</h2>
+      <h3>Heading 3</h3>
+      <h4>Heading 4</h4>
+      <h5>Heading 5</h5>
+      <h6>Heading 6</h6>
+      """
+    When I validate the "Headings: headings must be in ascending order" standard
+    Then it passes
+
+  Scenario: Headings in invalid order
+    Given a page with the body:
+      """
+      <h1>Heading 1</h1>
+      <h3>Heading 3</h3>
+      <h2>Heading 2</h2>
+      """
+    When I validate the "Headings: headings must be in ascending order" standard
+    Then it fails with the message:
+      """
+      Headings are not in order: /html/body/h1 /html/body/h3
+      """
+
+  Scenario: Headings jump back up more than one level
+    Given a page with the body:
+      """
+      <h1>Heading 1</h1>
+      <h2>Heading 2</h2>
+      <h3>Heading 3</h3>
+      <h4>Heading 4</h4>
+      <h2>Heading 2b</h2>
+      <h3>Heading 3b</h3>
+      """
+    When I validate the "Headings: headings must be in ascending order" standard
+    Then it passes
+
+  Scenario: Heading is hidden
+    Given a page with the body:
+      """
+      <h1>Heading 1</h1>
+      <h3 style="display:none">Heading 3</h3>
+      <h2>Heading 2</h2>
+      """
+    When I validate the "Headings: headings must be in ascending order" standard
+    Then it fails with the message:
+      """
+      Headings are not in order: /html/body/h1 /html/body/h3
+      """
+
+  Scenario: Heading in a script tag
+    Given a page with the body:
+      """
+      <h1>Heading 1</h1>
+      <script>
+        var stuff = "<h3>Heading 3</h3>";
+      </script>
+      <h2>Heading 2</h2>
+      """
+    When I validate the "Headings: headings must be in ascending order" standard
+    Then it passes
+
+  Scenario: Subheading before the first main heading
+    Given a page with the body:
+      """
+      <h3>Ignore me</h3>
+      <h1>Heading 1</h1>
+      <h2>Heading 2</h2>
+      """
+    When I validate the "Headings: headings must be in ascending order" standard
+    Then it passes
+
+  Scenario: Content between headings
+    Given a page with the body:
+      """
+      <div role="main">
+        <h1>Main heading</h1>
+        <p>non-heading content</p>
+        <h2>Another heading</h2>
+        <p>non-heading content</p>
+        <h3>Main content</h3>
+        non-heading content
+        <h2>Secondary content</h2>
+        <p>non-heading content</p>
+        <h2>Tertiary content</h2>
+        non-heading content
+      </div>
+      """
+    When I validate the "Headings: content must follow headings" standard
+    Then it passes
+
+  Scenario: Heading followed by subheading
+    Given a page with the body:
+      """
+      <h1>Main heading</h1>
+      <h2>Another heading</h2>
+      <p>...and some content</p>
+      """
+    When I validate the "Headings: content must follow headings" standard
+    Then it passes
+
+  Scenario: No content between headings
+    Given a page with the body:
+      """
+      <div role="main">
+        <h1>Main heading</h1>
+        <p>non-heading content</p>
+        <h2>Secondary content</h2>
+        <h2>Tertiary content</h2>
+        <p>non-heading content</p>
+      </div>
+      """
+    When I validate the "Headings: content must follow headings" standard
+    Then it fails with the message:
+      """
+      No content follows: /html/body/div/h2[1]
+      """
+
+  Scenario: Nested heading followed by non-nested content
+    Given a page with the body:
+      """
+      <div>
+        <h1>Main heading</h1>
+      </div>
+      Followed by some content
+      """
+    When I validate the "Headings: content must follow headings" standard
+    Then it passes
+  
+  Scenario: Nested heading followed by heading
+    Given a page with the body:
+      """
+      <div>
+        <h1>Main heading</h1>
+      </div>
+      <h1>Another heading</h1>
+      """
+    When I validate the "Headings: content must follow headings" standard
+    Then it fails with the message:
+      """
+      No content follows: /html/body/div/h1
+      No content follows: /html/body/h1
+      """
+
+  Scenario: Nested heading followed by nested content
+    Given a page with the body:
+      """
+      <div>
+        <h1>Main heading</h1>
+      </div>
+      <div>
+        Followed by some content
+      </div>
+      """
+    When I validate the "Headings: content must follow headings" standard
+    Then it passes
+
+  Scenario: Non-nested heading followed by nested content
+    Given a page with the body:
+      """
+      <h1>Main heading</h1>
+      <div>
+        Followed by some content
+      </div>
+      """
+    When I validate the "Headings: content must follow headings" standard
+    Then it passes