bbc-a11y 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5bde1a661b1feea57cf80e9d0133ae553ca7297e
+  data.tar.gz: e4e4f896df1d9edff57dc0dbd1542b511f6c21e4
+SHA512:
+  metadata.gz: 4b8a9d07f2f9622b08fd5f546010f0b2ca8a17f886bacedfba5f79f92a6067ffef8c2ca245d8fb7bd1d6d11ddc9d5d14b9475b6fa534dac55d5b17c12d4c675b
+  data.tar.gz: e0a91c494c3b23b79f83a8f54339823a72f3756334b9b837b6e703e443d1614e6dde93c1ca7ad1e010fad7ff1be51390a2baecb2bad2287457e4c702c746e3ff

data/.rspec

@@ -0,0 +1 @@
+--color

data/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# BBC A11y Contributing guidelines
+
+The standards are all stored in the `features` directory.
+
+You can run a manual test of your development copy of a11y at any time just by running:
+
+    bundle exec ./bin/a11y <url>
+
+You can also pick out a specific feature to run:
+
+    bundle exec ./bin/a11y <url> -- features/04_language.feature
+
+Or you can short-cut a11y's command-line interface and just run Cucumber directly:
+
+    URL=<url> bundle exec cucumber features/04_language.feature
+
+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.
+
+To add new behaviour, test-drive changes to the objects in `lib`.

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,54 @@
+# BBC Accessiblity Standards
+
+This tool runs a set of tests against a given URL to verify whether it meets the BBC accessibility standards.
+
+## How to use
+
+Run the `a11y` command, passing a URL:
+
+e.g.
+
+    a11y http://bbc.co.uk
+
+You can also pass arguments to Cucumber (which is used internally) by separating the arguments with `--`. Everything
+after the `--` is passed directly to Cucumber. For example, to skip the tests that require manual interraction:
+
+    a11y http://bbc.co.uk -- -t ~@manual
+
+## How to install
+
+A11y is packaged as a Ruby gem, but is not yet available on the public Rubygems server. To install it, you'll need to either build it by hand, or add a reference to the github source in your Gemfile.
+
+### Prerequisites
+
+Install Ruby and `gem install bundler`.
+
+### Adding a11y to your project's Gemfile
+
+Open your project's `Gemfile` and this line:
+
+    gem 'bbc-a11y`, git: 'git@github.com:mattwynne/bbc-a11y.git'
+
+Now install the gem:
+
+    bundle install --binstubs
+
+*Note:* You'll need to make sure every user who wants to run `bundle install` (including your continuous integration environment) has at least read access to this Github project.
+
+### Build and install the gem manually
+
+This will install the `a11y` tool globally on your machine.
+
+1. Clone this repository
+2. Install dependencies
+
+    ~~~
+    cd bbc-a11y
+    bundle install
+    ~~~
+
+3. Install the gem
+
+    ~~~
+    bundle exec rake install
+    ~~~

data/Rakefile

@@ -0,0 +1,12 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+task default: [:unit, :acceptance]
+
+task :unit do
+  sh "rspec"
+end
+
+task :acceptance do
+  sh "cd example && rake"
+end

data/bbc-a11y.gemspec

@@ -0,0 +1,32 @@
+# -*- encoding: utf-8 -*-
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+
+Gem::Specification.new do |s|
+  s.name        = 'bbc-a11y'
+  s.version     = File.read(File.expand_path("../lib/bbc/a11y/version", __FILE__))
+  s.authors     = ["Matt Wynne", "Ian Pouncey"]
+  s.description = "A tool for testing the compliance of web URLs against the BBC's accessibilty guidelines"
+  s.summary     = "bbc-a11y-#{s.version}"
+  s.email       = "github@ipouncey.co.uk"
+  s.homepage    = "https://cucumber.pro"
+  s.platform    = Gem::Platform::RUBY
+  s.license     = "MIT"
+  s.required_ruby_version = ">= 1.9.3"
+
+  s.add_dependency 'cucumber', '~> 2.0.0.rc'
+  s.add_dependency 'rspec',  '~> 3.0'
+  s.add_dependency 'capybara'
+  s.add_dependency 'selenium-webdriver'
+  s.add_dependency 'w3c_validators'
+  s.add_dependency 'cld'
+  s.add_dependency 'colorize'
+  s.add_development_dependency 'aruba'
+  s.add_development_dependency 'pry'
+  s.add_development_dependency 'rake'
+
+  s.rubygems_version = ">= 1.6.1"
+  s.files            = `git ls-files`.split("\n").reject {|path| path =~ /\.gitignore$/ }
+  s.test_files       = `git ls-files -- {spec,features}/*`.split("\n")
+  s.rdoc_options     = ["--charset=UTF-8"]
+  s.require_path     = "lib"
+end

data/bin/a11y

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+$:.unshift(File.dirname(__FILE__) + '/../lib') unless $:.include?(File.dirname(__FILE__) + '/../lib')
+
+require 'bbc/a11y/cli'
+BBC::A11y::CLI.new($stdin, $stdout, $stderr, ARGV.dup).call

data/example/.a11y.rb

@@ -0,0 +1,64 @@
+class Server
+  attr_reader :port
+
+  def initialize
+    @pid = nil
+    @port = find_available_port
+  end
+
+  def start
+    @pid = fork { `rackup -p #{port} -q` }
+    @pid = @pid + 1 # because rackup starts a child process
+    sleep(0.1) until responsive?
+  end
+
+  def stop
+    return unless @pid
+    Process.kill("SIGKILL", @pid)
+    Process.wait(@pid)
+  rescue Errno::ECHILD
+  end
+
+  private
+
+  def find_available_port
+    server = TCPServer.new('127.0.0.1', 0)
+    server.addr[1]
+  ensure
+    server.close if server
+  end
+
+  def responsive?
+    Net::HTTP.start('localhost', port) { |http| http.get("/perfect.html") }.is_a?(Net::HTTPSuccess)
+  rescue SystemCallError
+    false
+  end
+end
+
+server = Server.new
+
+BBC::A11y.configure do
+
+  before_all do
+    server.start
+  end
+
+  after_all do
+    server.stop
+  end
+
+  page "http://localhost:#{server.port}/perfect.html" do
+    skip_scenario "W3C"
+  end
+
+  page "http://localhost:#{server.port}/missing_header.html" do
+    skip_scenario "W3C"
+    skip_scenario "Check headings"
+
+    customize_world do
+      def Xassert_title_describes_primary_content_of_document(title, doc)
+        puts "TODO"
+      end
+    end
+  end
+end

data/example/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+gem 'rack'
+gem 'bbc-a11y', path: '..'

data/example/Rakefile

@@ -0,0 +1,3 @@
+task :default do
+  sh "bundle exec ../bin/a11y"
+end

data/example/config.ru

@@ -0,0 +1 @@
+run Rack::Directory.new("public")

data/example/public/missing_header.html

@@ -0,0 +1,13 @@
+<html lang="en-gb">
+  <head>
+    <title>Missing header</title>
+  </head>
+
+  <body>
+    <p role="main">
+    Here is some text in British English. This is needed so that we can verify that
+    the lang attribute in the html element at the top, which specified en-gb, is
+    correct.
+    </p>
+  </body>
+</html>

data/example/public/perfect.html

@@ -0,0 +1,14 @@
+<html lang="en-gb">
+  <head>
+    <title>Perfect page - Main heading</title>
+  </head>
+
+  <body>
+    <h1>Main heading</h1>
+    <p role="main">
+    Here is some text in British English. This is needed so that we can verify that
+    the lang attribute in the html element at the top, which specified en-gb, is
+    correct.
+    </p>
+  </body>
+</html>

data/features/01_core-purpose.md

@@ -0,0 +1,24 @@
+# The core purpose of every document must be defined
+
+Before design and implementation of a document or feature its core purpose **must** be defined.
+
+## Definitions
+
+### Core purpose
+
+The functionality to inform, educate, and entertain without which there would be no purpose for site or document.
+
+## 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:
+
+- [Core experience must not rely on JavaScript or CSS]()
+- [Minimum text size]()
+
+It is **not** a reason to ignore accessibility for non-core page elements.

data/features/02_validation.feature

@@ -0,0 +1,31 @@
+Feature: HTML Validation
+
+  All documents **must** have a [W3C recommended Doctype](http://www.w3.org/QA/2002/04/valid-dtd-list.html) and 
+  all Markup **must** validate against that Doctype.
+  
+  Rationale
+  =========
+  
+  While assistive technologies such as screen readers generally do a good job of interpreting 
+  invalid HTML there will be less risk of problems arising if the document follows a recognised
+  standard Doctype.
+  
+  Techniques
+  ==========
+
+  Pass:
+
+      <!DOCTYPE html>
+      <html lang="en-GB">
+  
+  Fail:
+
+      <html lang="en-GB">
+
+
+  Scenario: Submit to W3C validation Service
+
+    See http://validator.w3.org
+
+    When I submit the page to the W3C Markup Validation Service
+    Then there should be no errors

data/features/03_javascript.feature

@@ -0,0 +1,40 @@
+Feature: JavaScript
+
+  Core experience must not rely on JavaScript
+
+  The core purpose of every document **must** be defined.
+
+  The core content of every document must not require JavaScript to be added to the DOM
+
+  Rationale
+  =========
+
+  We aim to provide a core experience to as broad an audience as possible, allowing
+  users to choose the software and devices that work best for them in a broad range of circumstances.
+
+  Equally a robust site or application in the more traditional sense minimises its dependencies.
+  The minimum dependency for a web site should be an internet connection and the ability to parse HTML.
+
+  For this reason all BBC documents must enable their core purpose without relying on CSS or JavaScript.
+
+  CSS and JavaScript can, and should, be used to enhance the user experience beyond this basic level.
+  For example, a ‘live’ page has a core purpose to provide the latest content about an event to the user.
+  The core experience is the latest content at the time of the request. The experience enhanced with
+  JavaScript automatically updates this content without the user having to take action.
+
+  Definitions
+  ===========
+
+  *Core content* - The content that is provided to users without JavaScript.
+
+  Notes
+  =====
+
+  This is going to have to be a product specific test. Can we provide a template for this test, 
+  perhaps looking for elements based on provided selectors and make sure they are in the document?
+
+  @manual
+  Scenario: View the page with JavaScript disabled
+    When I view the page with JavaScript disabled
+    Then all core content is available in the DOM
+

data/features/04_language.feature

@@ -0,0 +1,58 @@
+Feature: Specify content language
+  
+  The main language of the page _must_ be specified.
+  
+  Changes to language within the page **must** be indicated.
+  
+  Rationale
+  =========
+  
+  Assistive technologies such as screen readers have support for different languages,
+  allowing for appropriate pronunciation.
+  
+  Techniques
+  ==========
+
+  Pass:
+
+  ```
+  <!DOCTYPE html>
+  <html lang="en-GB">
+  <head>
+    <title>Language techniques</title>
+  </head>
+  <body>
+    <h1>Techniques for language in HTML</h1>
+    <p><span lang="es">Cinco de Mayo</span> is Spanish for "fifth of May"</p>
+  </body>
+  </html>
+  ```
+
+  Fail:
+
+  ```
+  <!DOCTYPE html>
+  <html>
+  <head>
+    <title>Language techniques</title>
+  </head>
+  <body>
+    <h1>Techniques for language in HTML</h1>
+    <p>Cinco de Mayo is Spanish for "fifth of May"</p>
+  </body>
+  </html>
+  ```
+
+  Scenario: Check main body element lang attribute
+    When I visit the page
+    Then the <html> element must have a `lang` attribute
+    And the main natural language of the page must match that attribute
+
+  Scenario: Check for other elements with lang attributes
+    When I visit the page
+    Then all elements with `lang` attribute must have content in that natural language
+
+  @manual
+  Scenario: Check for areas of the page expressed in other languages, but missing a `lang` attribute
+    When I visit the page
+    Then any parts expressed in a natural language different to the main language of the page must have a matching `lang` attribute

data/features/05_page_title.feature

@@ -0,0 +1,45 @@
+Feature: Page title
+
+  A document **must** have a unique page `<title>` that identifies its main content.
+
+  Rationale
+  =========
+
+  Document titles help users orientate themselves within web sites and apps. The document `<title>` element 
+  content is often the first thing a speech output user will hear and acts as a confirmation of what page they 
+  have arrived at. Document titles commonly have the same content as the main `<h1>` element.
+
+  Techniques
+  ==========
+
+  Pass:
+
+    <title>BBC Weather</title>
+
+  Fail:
+
+    <title>BBC</title>
+
+  @manual
+  Scenario: Check the title
+
+    We can't easily test for the uniqueness of the title, but we can test for the presence of the element 
+    and ensure it has content.
+
+    In terms of prompting for manual tests, could we compare the title element with the content of the first
+    `<h1>` element on the page, and if the former contains the latter then automatically pass the test. 
+    
+    For example:
+
+        <title>BBC Weather - Weather in London</title>
+
+        ~
+
+        <h1>Weather in London</h1>
+
+    ...would pass automatically, but a `<title>` element that does not contain the string 'Weather in London' 
+    would be flagged for manual review.
+
+    When I visit the page
+    Then the document should have a title
+    And the title should describe the primary content of the document

data/features/06_main_landmark.feature

@@ -0,0 +1,24 @@
+Feature: Main landmark
+
+  A page **must** have exactly one element with `role="main"`
+
+  Rationale
+  =========
+
+  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.
+
+  Techniques
+  ==========
+
+  Pass:
+
+    <div role="main" id="main-content"></div>
+
+  Fail:
+
+    <div id="main-content"></div>
+
+  Scenario: Check for a single main element
+    When I visit the page
+    Then there should be exactly one element with `role="main"`
+

data/features/07_headings.feature

@@ -0,0 +1,65 @@
+Feature: Correctly use 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.
+
+  Techniques
+  ==========
+
+  Pass:
+
+    <div role="main">
+      <h1>Main page content</h1>
+      <p>Lorem ipsum…</p>
+      <h2>Secondary content</h2>
+      <h3>Tertiary content one</h2>
+      <ul>
+        <li>Lorem</li>
+      </ul>
+      <h3>Tertiary content two</h3>
+      <ul>
+        <li>Ipsum</li>
+      </ul>
+    </div>
+
+  Fail:
+
+    <div role="main">
+      <h3>Main content</h3>
+      <h2>Secondary content</h2>
+      <h2>Tertiary content</h2>
+      <p>Lorem ipsum…</p>
+    </div>
+
+  Notes
+  =====
+
+  For the second test, can we check the next text node after each heading and test that it is 
+  either not part of a heading element, or is part of a heading level of one level higher?
+
+  Questions
+  =========
+
+  1. Clarify the note, above!
+  2. Presumably it's OK for the hierarchy to jump *up* by more than 1? e.g. h1, h2, h3, h4, h2 is ok?
+
+  Scenario: Check headings
+    When I visit the page
+    Then there must be exactly one h1 element
+    And each heading must be followed by content or a heading of one level deeper (h2-h6)
+

data/features/08_title_attribute.feature

@@ -0,0 +1,71 @@
+Feature: Correctly use `title` attributes
+
+  `title` attributes **must not** be used for critical information and **must not** repeat content that is already visible and associated with the same control or content.
+
+  Rationale
+  =========
+
+  `title` attributes are inaccessible to keyboard users without additional Assistive Technology. They are dependent on user settings in Screen Readers and similar Assistive Technology.
+
+  Additionally they suffer from discoverability problems: pointing device users are required to hover over page elements and pause before the title tooltip displays, usually with no indication that there is additional content to be displayed.
+
+  Repeating content in visible text and `title` attributes can lead to content clutter and repeated phrases.
+
+  Key recommendations are:
+
+  - Do not use the `title` attribute unless on a form input as title text is not well supported on links on mobile 
+  - Do not use `title` attributes and explicit labels together on form fields
+
+  Techniques
+  ==========
+
+  Pass:
+
+      <label for="name">Name</label>
+      <input type="text" id="name" name="name" />
+      <label for="email">Email</label>
+
+      <input type="text" id="email" name="email" />
+
+      <button type="button"><img src="/path/to/image/close.png" alt="Close" /></button>
+
+  Fail:
+
+      <input type="text" name="name" title="Name" />
+      <input type="text" name="email" title="Email" />
+
+      <label for="name">Name</label>
+      <input type="text" id="name" name="name" title="Name" />
+
+      <button type="button" title="Close"></button>
+
+      <a href="/news" title="News">News</a>
+
+  Tests
+  =====
+
+  | Procedure | Expected Result | Type | 
+  | --------- | --------------- | ---- |
+  | Search source for all uses of the `title` attribute | Ensure no instances contain content that would be required by all users or content that is repeated in associated content | Manual |
+  | Search source for all uses of the `title` attribute | Ensure no instances contain content that is repeated within the element | Automated |
+  | Search source for all '<label>' elements and their associated form fields | Ensure that the associated form field does not have a title attribute | Automated |
+
+  --
+
+  Notes
+  =====
+
+  The first test is non-automatable, and may well have to be removed as it is too ambiguous.
+
+  Scenario: Check the elements with title attributes
+
+    Examples of failure:
+
+        <label for="name">Name</label>
+        <input type="text" id="name" name="name" title="Name" />
+
+        <a href="/news" title="News">News</a>
+
+    When I visit the page
+    Then there must be no elements with a title attribute whose content is repeated within the element
+    And any form fields with associated labels do not have a title attribute