Skip to content
This repository has been archived by the owner on Sep 24, 2019. It is now read-only.

How to contribute

Jump to bottom
Kevin Miller edited this page Feb 14, 2014 · 10 revisions

Building Quail

The dev branch of quail does not include the /dist directory, we build quail in the release branch then merge it into master on a release, but keeping this around in the development or any feature branches is not recommended.

To maintain a build of quail for testing, you will need to have http://nodejs.org installed on your machine, then run the following:

npm install
grunt build

To ease development, you can run grunt watch to have the build step happen automatically whenever a file changes.

Defining your own accessibility tests

A "test" in Quail should find and report on one specific type of accessibility problem in the page. There might be many kinds of tests for one technique or guideline, so that tests are atomic and easy to write feedback messages about. For example, while a select box or text box missing label elements are basically the same kind of failure, they are split into different tests so that feedback messages could read "This select box is missing a label" instead of "This form element is missing a label."

To define a test, add it's definition to `src/resources/tests.yml. A typical test looks like:

imgHasAlt: 
  type: "selector"
  testability: 1
  title: 
    en: "Image elements must have an \"alt\" attribute"
  description: 
    en: "All <code>img</code> elements must have an alt attribute"
  guidelines: 
    508: 
      - "a"
    wcag: 
      1.1.1: 
        techniques: 
          - "F65"
          - "H37"
  tags: 
    - "image"
    - "content"
  options: 
    selector: "img:not(img[alt])"

Tests should have a readable name as the index, and contain the following attributes. Please keep your test definitions in the following order to aid in legibility:

  • type - The type of test
    • selector - The test just uses a simple jQuery-compatible selector. The selector should be defined in the options attribute of the test (for example, in imgHasAlt, the selector is img:not(img[alt]).
    • custom - Loads a method of quail that should be defined in a "callback" attribute.
    • Any other test type looks to see if there is a defined component with that name and passes that component the test name and the full test object.
  • testability - A scale from 0 - 1 of how "testable" this test is. A value of 1 means "this test is accurate in 100% of cases," 0 is for things like tests that flag a flash object on the page that we can't test, but can at least find because of the object element.
  • title - An array of error message titles, keyed by two-digit language code.
  • description - An array of error messages, keyed by two-digit language code.
  • guidelines - An array of guideline assignments. Each guideline can also contain a configuration option to send additional configurations to tests.
  • tags - An array of tags, useful for implementers to see if a test applies to a certain context. Some common ones are:
    • content - Only applies to page content instead of metadata like doctype.
    • form - Tests related to form elements, labels, etc.
    • script - Test for JavaScript events.
  • components - An array of components the test requires to work.
  • libraries - An array of external libraries, should be in the form of a URL, assuming that we already know the location of lib (for example, if the test needs htmlparser then it would look like node-htmlparser/lib/htmlparser.js).
  • strings - An array of strings the test requires.
  • options - An object of options to pass to the test. For example, "selector" test types require a "selector" option as in the example above.

Components

Components are common code that can be used by more than one test, and should be in the namespace quail.components. Below is a list of current components:

  • acronym - Finds instances of words that do not have either an abbr or * ronym` tag with a title.
  • colors - Helpers with background colors and determining color contrast and * inosity.
  • convertToPx - Converts units from em to px.
  • event - Helper to find elements that have one type of event callback and sees * it has a corresponding one.
  • hasEventListener - Finds out whether a passed element has an active event * tener attached.
  • header - Helper for many tests that look at header order (like if an h3 is * followed by an h6).
  • label - Looks for corresponding labels for form elements.
  • labelProximity - Looks for labels located 'next to' their associated form * ments.
  • placeholder - Matches placeholder text in an element (like "read more" for * ks).
  • statistics - Statistics for average, variance, or standard deviation.
  • textStatistics - Finds reading level or other text statistics (like word * nt).
  • video - Handles video tags and video providers (like YouTube).

Custom test callbacks

Some tests require their own callbacks to do their work. If your test needs a custom callback, the callback should be a method on the main quail object (we'd like to change this in the future), have the same name as the test, and be placed in the src/j/custom directory.

If you want to tell quail a test failed on an element, use the quail.testFails method.

Strings

Tests for things like emoticons, redundant text, or language codes need strings to operate. Strings are stored in src/js/strings and are placed in the quail.strings namespace. For example, colors.js includes all the hex codes for color names.

Unit testing

Each accessibility test should have several pass/fail examples under /test/testfiles/common the directory /test/testfiles/quail is for testing quail functionality without accessibility tests (like that the color contrast component is working). Read more about writing your own test files.

Your test files should be named as myTestName-pass/fail.html and you can have several pass or fail files to cover different use cases. For now, you will also have to add each file to the arrays in /test/quail.html, although we have plans to automate all the test file compilation soon.

You can run the unit tests using Grunt by running grunt test, which will also run all the methods in grun t build. Any commit to quail will also be tested on Travis CI and Saucelabs.

If you just want to run a single file under test/testfiles via grunt, you can run grunt qunit:single --file ="common/myfile.html.

Clone this wiki locally