@essentialaccessibility/aslint

    0.0.53 • Public • Published

    aslint

    ASLint is an accessibility testing tool for HTML-based content. It's cross-browser and cross-environment. There are more than 100 ASLint rules that covers WCAG 2.0, 2.1 standard and Best Practices.

    Best Practices refers to a collection of rules that doesn't conform to WCAG success criterion, but they improve the user experience.

    Getting started

    First download the package:

    npm install aslint --save-dev
    

    Now include the script:

    <script src="node_modules/aslint/dist/aslint.bundle.js"></script>
    

    Creating ASLint package

    Run npm run build:all in order to create ASLint package available in folder dist/aslint.bundle.js. The file app/index.html will be copied as well. It is used while playing with ASLint locally. See section Local Playground

    Run ASLint

    ASLint can be run using Promises as well as passing callback.

    Using Promises

    aslint
      // Optional config options; more about options below;
      .config(options)
      .run()
      .then((results): void => {
        if (results.summary.byIssueType.error.length > 0) {
          console.error(`There were ${results.summary.byIssueType.error.length} errors while scanning.`, results);
    
          return;
        }
    
        console.log('[ASLint] All tests passed.', results);
      })
      .catch((e) => {
        // Handle error here
      })
    

    or passing a callback

    aslint
      .run(function(results) {
        if (results.summary.byIssueType.error.length > 0) {
          console.error(`There were ${results.summary.byIssueType.error.length} errors while scanning.`, results);
    
          return;
        }
    
        console.log('[ASLint] All tests passed.', results);
      });
    

    Global properties

    version - to check what's the version of ASLint simply get value from aslint.version (type: string).

    Config Options

    context - (type: string, params: CSS Selector or XPath). Limit scanning within the document that matches the specified selector. Default: document.documentElement

    reportFormat - select results format type. Supported formats: json. Default: json

    asyncRunner – set to true if you want to prevent from code execution blocking User Interface thread. Since JavaScript is executed by the same thread that handles updating the User Interface, developers can easily lock up the UI and make it unresponsive to end-users, specifically on page with large amount of content (useful for monitoring injection where it’s being executed on every page). Default: false

    locale - (type: string, params: language code). Language tag in the format defined in Tags for Identifying Languages (BCP47). Set this to get all texts translated in a required language. Default: en-us

    includeHidden - (type: boolean). true if you want to include all visually hidden elements for the evaluation. Hidden means that the element isn’t visible within the viewport. Default: false

    includeElementReference - (type: boolean). true if you want to include element reference in every report. Default: false

    namespace - (type: string). Global namespace for application, e.g. window.aslint in browsers environment. Default: aslint

    Events

    addListener - an Event is an object that allows you to be notified when something interesting happens. ASLint contains common events that are dispatched in a certain situations. The argument to addListener() is always a function that you define to handle the event, but the parameters to the function depend on which event you're handling.

    Available events

    onBeforeRuleReport(handler) - an event that is dispatched just before the rule report is being saved. handler is a function that receives an object as its sole arguments.

    handler(ruleId: string, reportObject: object)
    

    onValidatorComplete(handler) - an event that is dispatched when validation is completed.

    handler(error: any, reportObject: object)
    

    Value null for error means that there were no errors. Otherwise error object is passed with all details.

    onValidatorReport(handler) - an event that is dispatched when single report is being saved.

    handler(reportObject: object)
    

    onValidatorReset() - an event that is dispatched when all results are being removed. No data are passed to the handler.

    onValidatorStarted - an event that is dispatched just before tests are being executed. No data are passed to the handler.

    Filters

    Filters gives an opportunity to modify data of other functions.

    addFilter - a method that provides a way for functions to modify data of other functions.

    Available filters

    onBeforeRuleReport(handler) - an event being called just before rule report is being saved. That way you can modify the report before saving it to the final report.

    Usage:

    .addFilter('onBeforeRuleReport', handler)
    

    handler take 1 argument: ruleReport (object, representing current report for the rule).

    Running unit tests

    Without debug

    npm run test

    With debug option

    with debug option that allows debugging, e.g. in the browser

    npm run test:debug

    Test Coverage report

    To generate unit tests coverage report run npm run test:coverage. The report should be generated under .jest/coverage path.

    Local Playground

    ASLint itself

    To use ASLint locally using browser the file app/index.html is being used. In order to build and test ASLint locally follow steps:

    1. Create local domain localhost.aslint.org and set to 127.0.0.1.
    2. Point root path to [location of ASLint]/dist
    3. Run npm run build:all to create ASLint package, translations and copy app/index.html.
    4. Open browser and go to localhost.aslint.org.

    End-to-end test

    To see ASLint in action you can run the example located at examples/puppeteer/test.js. That example uses framework Puppeteer.

    To run example follow:

    1. Run node examples/puppeteer/test.js

    Technology stack

    ASLint is written in TypeScript.

    To keep code quality and consistency there are also validators like ESLint, lint for markdown and circular dependecies checker.

    Supported browsers

    ASLint uses feature detection to support as wide as possible range of browsers. However, ASLint is being tested on:

    • Safari (Mac OS)
    • Chrome / Chromium
    • Firefox
    • Edge (Windows OS)

    Creating bookmarklet for the local usage

    When you want to use ASLint locally then you can create a bookmarklet that points to ASLint local code. You need to have configured local domain e.g. local.aslint.org that points to the ASLint dist folder.

    1. Use code from file app/bookmarklet/bookmarklet.js. You can modify that code in any way.
    2. Use tool https://mrcoles.com/bookmarklet/ to convert the code to the bookmarklet code.
    3. Create a bookmark in your browser, give a name and for url paste the code generate in step #2.

    Adding new translations

    Translations can be added in following steps:

    1. Create a new translations based on English version app/translations/en-us.json. File name should contains language and region code Example: app/translations/pl-pl.json
    2. Modify file app/services/translate.config.ts to include language file content created in step #1.
    3. Modify Jest tests setup: .jest/jest-setup.js.

    Understanding results

    Rules

    The rule report is represented through following interface:

    export interface IAslintRuleReport {
      categories: string[];
      issueType: string;
      recommendations: string[];
      resources: { content: string; url: string }[];
      results: IAslintRuleReportResult[];
      severity: string;
      status?: IAslintRuleReportStatus;
      totalElementsEvaluated: number;
    }
    

    categories - the rule might belong to multiple categories. Following categories are used in built-in rules by default:

    export enum IssueCategory {
      adaptable = 'adaptable',
      aria = 'aria',
      audio = 'audio',
      captcha = 'captcha',
      distinguishable = 'distinguishable',
      embedded_objects = 'embedded_objects',
      forms = 'forms',
      headings = 'headings',
      images = 'images',
      links = 'links',
      operable = 'operable',
      perceivable = 'perceivable',
      robust = 'robust',
      tables = 'tables',
      uncategorized = 'uncategorized',
      understandable = 'understandable',
      videos = 'videos'
    }
    

    Note: when you don't set categories on your custom rule then the categories will contain an empty array.

    issueType - there are 3 issue types: error, warning, passed. The issue type is determined based on the severity level. Let's see how it looks using "programming" language approach:

      case critical:
        return error;
    
      case high:
        return error;
    
      case low:
        return error;
    
      case info:
        return warning;
    
      default:
        return passed;
    

    Frequently Asked Questions

    Please refer to https://www.aslint.org/faq

    Code guidelines

    Please refer to https://www.aslint.org/coding-guidelines

    Contributing

    Contributions are welcome, and greatly appreciated! Contributing doesn't just mean submitting pull requests. There are many different ways for you to get involved, including answering questions on the issues, reporting or triaging bugs, and participating in the ASLint evolution process.

    Technical

    After pulling ASLint run npx husky install to create git pre-commit hook with validation.

    Acknowledgements

    Thanks to Cezary Tomczyk for inventing ASLint and making a substantial contribution to the design and development.

    Install

    npm i @essentialaccessibility/aslint

    DownloadsWeekly Downloads

    262

    Version

    0.0.53

    License

    MPL-2.0

    Unpacked Size

    1.53 MB

    Total Files

    325

    Last publish

    Collaborators

    • avatar
    • avatar