QualWeb core

The core allows you to perform automatic accessibility evaluations on web pages. It contains 3 evaluation modules:

• @qualweb/act-rules
• @qualweb/wcag-techniques
• @qualweb/best-practices

You can also perform evaluations at https://qualweb.di.fc.ul.pt/evaluator/, or by installing the chrome extension.

How to install

  $ npm i @qualweb/core --save

How to run

  'use strict';

  const { QualWeb, generateEARLReport } = require('@qualweb/core');

  (async () => {
    const plugins = {
      // Check https://github.com/berstend/puppeteer-extra/tree/master/packages/puppeteer-extra-plugin-adblocker
      adBlock: true, // Default value = false
      // Check https://github.com/berstend/puppeteer-extra/tree/master/packages/puppeteer-extra-plugin-stealth
      stealth: true // Default value = false
    };
    const qualweb = new QualWeb(plugins);

    const clusterOptions = {
      maxConcurrency: 5, // Performs several urls evaluations at the same time - the higher the number given, more resources will be used. Default value = 1
      timeout: 60 * 1000, // Timeout for loading page. Default value = 30 seconds
      monitor: true // Displays urls information on the terminal. Default value = false
    };

    const launchOptions = {
      ... // check https://github.com/puppeteer/puppeteer/blob/v10.1.0/docs/api.md#puppeteerlaunchoptions
      // In most cases there's no need to give additional options. Just leave the field undefined
    };

    // Starts the QualWeb core engine
    await qualweb.start(clusterOptions, launchOptions);

    // QualWeb evaluation report
    const qualwebOptions = {
      url: 'https://act-rules.github.io/pages/about/',
      ...
    };

    // Evaluates the given options - will only return after all urls have finished evaluating or resulted in an error
    const reports = await qualweb.evaluate(qualwebOptions);

    console.log(reports);
    //  {
    //    "url": "report",
    //    "url2": "report2"
    //  }

    // Stops the QualWeb core engine
    await qualweb.stop();

    const earlOptions = {
      // Check the options in the section below
    };

    // if you want an EARL report
    const earlReports = generateEARLReport(reports, earlOptions);

    console.log(earlReports);
    //  {
    //    "url": "earlReport",
    //    "url2": "earlReport2"
    //  }
  })();

Options

The available options fot the evaluate() function are:

{
  "url": "https://act-rules.github.io/pages/about/", // url to evaluate
  "urls": ["https://act-rules.github.io/pages/about/", "https://act-rules.github.io/rules/"], // Array of urls
  "file": "/path/to/file/with/urls", // urls must be separated by a newline (\n)
  "crawl": "https://act-rules.github.io", // Domain to crawl and obtain the urls
  "html": "", // Full webpage html, or just small snippets
  "log": {
    "file": true, // Logs errors to a file. Default value = false
    "console": false // Logs errors to the console. Default value = false
  },
  "viewport": {
    "mobile": false, // default value = false
    "landscape": true, // default value = viewPort.width > viewPort.height
    "userAgent": "custom user agent", // default value for desktop = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:22.0) Gecko/20100101 Firefox/22.0', default value for mobile = 'Mozilla/5.0 (Linux; U; Android 2.2; en-us; DROID2 GLOBAL Build/S273) AppleWebKit/533.1 (KHTML, like Gecko) Version/4.0 Mobile Safari/533.1'
    "resolution": {
      "width": 1920, // default value for desktop = 1366, default value for mobile = 1080
      "height": 1080 // default value for desktop = 768, default value for mobile = 1920
    }
  },
  "waitUntil": ["load", "networkidle0"], // Events to wait before starting evaluation, default value = "load". For more check https://github.com/puppeteer/puppeteer/blob/v10.1.0/docs/api.md#pagegotourl-options
  "validator": "https://127.0.0.1/validate", // HTML validator service endpoint. The url will be attached after of the given endpoint
  "crawlOptions": {
    "maxDepth": 2, // max depth to search, 0 to search only the given domain. Default value = -1 (search everything)
    "maxUrls": 100, // max urls to find. Default value = -1 (search everything)
    "timeout": 60, // how many seconds the domain should be crawled before it ends. Default value = -1 (never stops)
    "maxParallelCrawls": 10, // max urls to crawl at the same time. Default value = 5
    "logging": true // logs domain, current depth, urls found and time passed to the terminal
  },
  "translate": "en", // OR { "translate": "en", "fallback": "en" } OR { own translation object } check https://github.com/qualweb/locale#readme. Default = "en"
  "execute": {
    // choose which modules to execute
    // if this option is not specified, the default values below will be applied, otherwise unspecified values will default to false
    "wappalyzer": false, // wappalyzer module (https://github.com/qualweb/wappalyzer)
    "act": true, // act-rules module (https://github.com/qualweb/act-rules)
    "wcag": true, // wcag-techniques module (https://github.com/qualweb/wcag-techniques)
    "bp": false, // best-practices module (https://github.com/qualweb/best-practices)
    "counter": false // counter module (https://github.com/qualweb/counter)
  },
  "act-rules": {
    // More information about this options at https://github.com/qualweb/act-rules
    "rules": ["QW-ACT-R1", "b5c3f8"], // Array of rules to execute, can be passed the QualWeb Rule ID or the ACT Rule ID
    "exclude": ["QW-ACT-R1", "b5c3f8"], // Array of rules to exclude, can be passed the QualWeb Rule ID or the ACT Rule ID
    "levels": ["A", "AA", "AAA"], // Conformance levels to execute,
    "principles": ["Perceivable", "Operable", "Understandable", "Robust"] // Principles to execute
  },
  "wcag-techniques": {
    // More information about this options at https://github.com/qualweb/wcag-techniques
    "techniques": ["QW-WCAG-T1", "H39"], // Array of techniques to execute, can be passed the QualWeb Technique ID or the WCAG 2.1 Technique Code
    "exclude": ["QW-WCAG-T1", "H39"], // Array of techniques to exclude, can be passed the QualWeb Technique ID or the WCAG 2.1 Technique Code
    "levels": ["A", "AA", "AAA"], // Conformance levels to execute,
    "principles": ["Perceivable", "Operable", "Understandable", "Robust"] // Principles to execute
  },
  "best-practices": {
    // More information about this options at https://github.com/qualweb/best-practices
    "bestPractices": ["QW-BP1", "QW-BP2"], // Array of best practices to execute
    "exclude": ["QW-BP1", "QW-BP2"] // Array of best practices to exclude
  }
}

The available options fot the generateEARLReport() function are:

{
  "aggregated": true, // default value = false
  "aggregatedName": "websites.json", // The name to save the aggregated earl reports. default value = first url of the list
  "modules": {
    // Choose which modules to convert the report to earl, by default all modules are converted if they were executed
    "act": true, // default value = true
    "wcag": false, // default value = true
    "best-practices": false // default value = true
  } // If the "modules" value is given, any missing module value missing it's automatically set to false
}

Report details

In this section it's explained the evaluation report in detail. For a detailed version of the EARL report check @qualweb/earl-reporter.

  {
    "type": "evaluation",
    "system": {
      "name": "QualWeb",
      "description": "QualWeb is an automatic accessibility evaluator for webpages.",
      "version": "QualWeb version",
      "homepage": "https://www.qualweb.di.fc.ul.pt/",
      "date": "date of the evaluation",
      "hash": "unique hash",
      "url": {
        "inputUrl": "inserted url",
        "protocol": "protocol of the url",
        "domainName": "domain name of the url",
        "domain": "domain of the url",
        "uri": "uri of the url",
        "completeUrl": "complete url after all redirects"
      },
      "page": {
        "viewport": {
          "mobile": "was evaluated on a mobile context or not",
          "landscape": "was evaluated on a landscape context or not",
          "userAgent": "user agent used",
          "resolution": {
            "width": "window's width used",
            "height": "window's height used",
          }
        },
        "dom": {
          "html": "html code as a string",
          "title": "Title of the webpage",
          "elementCount": "Element count of the webpage"
        }
      }
    },
    "metadata": {
      "passed": "number of passed rules/techniques/best practices",
      "warning": "number of warning rules/techniques/best practices",
      "failed": "number of failed rules/techniques/best practices",
      "inapplicable": "number of inapplicable rules/techniques/best practices",
    },
    "modules": {
      "act-rules": {
        "type": "act-rules",
        "metadata": {
          "passed": "number of passed rules",
          "warning": "number of warning rules",
          "failed": "number of failed rules",
          "inapplicable": "number of inapplicable rules",
        },
        "assertions": {
          "QW_ACT_R1": {
            "name": "Name of the rule",
            "code": "QualWeb rule id",
            "mapping": "ACT rule id mapping",
            "description": "Description of the rule",
            "metadata": {
              "target": "Any target, can be one element, multiple elements, attributes, a relation between elements",
              "success-criteria?": [
                {
                  "name": "Name of the success criteria",
                  "level": "Level of conformance of the success criteria",
                  "principle": "Principle of the success criteria",
                  "url": "Url of the success criteria"
                }
              ],
              "related?": [], // related WCAG 2.1 techniques
              "url?": "Url of the rule",
              "passed": "Number of passed results",
              "warning": "Number of warning results",
              "failed": "Number ff failed results",
              "type?": [], // usually "ACTRule" or "TestCase"
              "a11yReq?": [], // WCAG 2.1 relation - something like "WCAG21:language"
              "outcome": "Outcome of the rule",
              "description": "Description of the outcome";
            },
            "results": [
              {
                "verdict": "Outcome of the test",
                "description": "Description of the test",
                "resultCode": "Test identifier",
                "pointer?": "Element pointer in CSS notation",
                "htmlCode?": "Element html code",
                "attributes?": "Attributes of the element",
                "accessibleName?": "Accessible name of the test target"
              },
              { ... }
            ]
          },
          "...": { ... }
        }
      },
      "wcag-techniques": {
        "type": "wcag-techniques",
        "metadata": {
          "passed": "number of passed techniques",
          "warning": "number of warning techniques",
          "failed": "number of failed techniques",
          "inapplicable": "number of inapplicable techniques",
        },
        "assertions": {
          "QW_WCAG_T1": {
            "name": "Name of the technique",
            "code": "QualWeb technique id",
            "mapping": "WCAG techniques code mapping",
            "description": "Description of the technique",
            "metadata": {
              "target": "Any target, can be one element, multiple elements, attributes, a relation between elements",
              "success-criteria?": [
                {
                  "name": "Name of the success criteria",
                  "level": "Level of conformance of the success criteria",
                  "principle": "Principle of the success criteria",
                  "url": "Url of the success criteria"
                }
              ],
              "related?": [], // related WCAG 2.1 techniques
              "url?": "Url of the technique",
              "passed": "Number of passed results",
              "warning": "Number of warning results",
              "failed": "Number ff failed results",
              "type?": [], // usually "ACTRule" or "TestCase"
              "a11yReq?": [], // WCAG 2.1 relation - something like "WCAG21:language"
              "outcome": "Outcome of the technique",
              "description": "Description of the outcome";
            },
            "results": [
              {
                "verdict": "Outcome of the test",
                "description": "Description of the test",
                "resultCode": "Test identifier",
                "pointer?": "Element pointer in CSS notation",
                "htmlCode?": "Element html code",
                "attributes?": "Attributes of the element" // if available
              },
              { ... }
            ]
          },
          "...": { ... }
        }
      },
      "best-practices": {
        "type": "best-practices",
        "metadata": {
          "passed": "number of passed best practices",
          "warning": "number of warning best practices",
          "failed": "number of failed best practices",
          "inapplicable": "number of inapplicable best practices",
        },
        "assertions": {
          "QW_BP1": {
            "name": "Name of the technique",
            "code": "QualWeb best practices id",
            "description": "Description of the best practices",
            "metadata": {
              "target": "Any target, can be one element, multiple elements, attributes, a relation between elements",
              "success-criteria?": [
                {
                  "name": "Name of the success criteria",
                  "level": "Level of conformance of the success criteria",
                  "principle": "Principle of the success criteria",
                  "url": "Url of the success criteria"
                }
              ],
              "related?": [], // related WCAG 2.1 techniques
              "passed": "Number of passed results",
              "warning": "Number of warning results",
              "failed": "Number ff failed results",
              "type?": [], // usually "ACTRule" or "TestCase"
              "a11yReq?": [], // WCAG 2.1 relation - something like "WCAG21:language"
              "outcome": "Outcome of the best practices",
              "description": "Description of the outcome";
            },
            "results": [
              {
                "verdict": "Outcome of the test",
                "description": "Description of the test",
                "resultCode": "Test identifier",
                "pointer?": "Element pointer in CSS notation",
                "htmlCode?": "Element html code",
                "attributes?": "Attributes of the element" // if available
              },
              { ... }
            ]
          },
          "...": { ... }
        }
      },
      "counter": {
        "type": "counter",
        "data": {
          "roles": {
            "button": 2,
            "link": 4,
            ...
          },
          "tags": {
            "div": 10,
            "table": 3,
            ...
          }
        }
      }
    }
  }

Implemented ACT Rules

Implemented WCAG 2.1 Techniques

Evaluation problems

Sometimes, some webpages fail to evaluate, or the evaluation may take a really long time. Before creating an issue check the error.log file and verify that:

• The URL is correct, and it uses http or https, or www, or both;
• The webpage exists;
• If using https, that the certificate is valid;
  • If you really want to evaluate the page with an invalid certificate, add "--ignore-certificate-errors" to the args in qualweb puppeteer launch options.
• The webpage is not password protected;
• The webpage is an HTML Document.

License

ISC

Versions

• 0.7.32 - Updated ACT-Rules c487ae(R12), 6cfa84 (R13), 73f2c2 (R24), 46ca7f (R48) and 78fd32 (R68)
• 0.7.31 - Removed dependencies on Wappalyzer module (continued)
• 0.7.30 - Removed dependencies on Wappalyzer module
• 0.7.29 - Fixed ACT-Rules bf051a (R5) and bc4a75 (R38)