  '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": "<html-code>", // 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": "http://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": "http://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

QualWeb Rule ID	ACT Rule ID	ACT Rule Name
QW-ACT-R1	2779a5	HTML Page has a title
QW-ACT-R2	b5c3f8	HTML has lang attribute
QW-ACT-R3	5b7ae0	HTML lang and xml:lang match
QW-ACT-R4	bc659a	Meta-refresh no delay
QW-ACT-R5	bf051a	Validity of HTML Lang attribute
QW-ACT-R6	59796f	Image button has accessible name
QW-ACT-R7	b33eff	Orientation of the page is not restricted using CSS transform property
QW-ACT-R9	b20e66	Links with identical accessible names have equivalent purpose
QW-ACT-R10	4b1c6c	`iframe` elements with identical accessible names have equivalent purpose
QW-ACT-R11	97a4e1	Button has accessible name
QW-ACT-R12	c487ae	Link has accessible name
QW-ACT-R13	6cfa84	Element with `aria-hidden` has no focusable content
QW-ACT-R14	b4f0c3	meta viewport does not prevent zoom
QW-ACT-R15	80f0bf	audio or video has no audio that plays automatically
QW-ACT-R16	e086e5	Form control has accessible name
QW-ACT-R17	23a2a8	Image has accessible name
QW-ACT-R18	3ea0c8	`id` attribute value is unique
QW-ACT-R19	cae760	iframe element has accessible name
QW-ACT-R20	674b10	role attribute has valid value
QW-ACT-R21	7d6734	svg element with explicit role has accessible name
QW-ACT-R22	de46e4	Element within body has valid lang attribute
QW-ACT-R23	c5a4ea	video element visual content has accessible alternative
QW-ACT-R24	73f2c2	autocomplete attribute has valid value
QW-ACT-R25	5c01ea	ARIA state or property is permitted
QW-ACT-R26	eac66b	video element auditory content has accessible alternative
QW-ACT-R27	5f99a7	This rule checks that each aria- attribute specified is defined in ARIA 1.1.
QW-ACT-R28	4e8ab6	Element with role attribute has required states and properties
QW-ACT-R29	e7aa44	Audio element content has text alternative
QW-ACT-R30	2ee8b8	Visible label is part of accessible name
QW-ACT-R31	c3232f	Video element visual-only content has accessible alternative
QW-ACT-R32	1ec09b	video element visual content has strict accessible alternative
QW-ACT-R33	ff89c9	ARIA required context role
QW-ACT-R34	6a7281	ARIA state or property has valid value
QW-ACT-R35	ffd0e9	Heading has accessible name
QW-ACT-R36	a25f45	Headers attribute specified on a cell refers to cells in the same table element
QW-ACT-R37	afw4f7	Text has minimum contrast
QW-ACT-R38	bc4a75	ARIA required owned elements
QW-ACT-R39	d0f69e	All table header cells have assigned data cells
QW-ACT-R40	59br37	Zoomed text node is not clipped with CSS overflow
QW-ACT-R41	36b590	Error message describes invalid form field value
QW-ACT-R42	8fc3b6	Object element has non-empty accessible name
QW-ACT-R43	0ssw9k	Scrollable element is keyboard accessible
QW-ACT-R44	fd3a94	Links with identical accessible names and context serve equivalent purpose
QW-ACT-R48	46ca7f	Element marked as decorative is not exposed
QW-ACT-R49	aaa1bf	Audio or video that plays automatically has no audio that lasts more than 3 seconds
QW-ACT-R50	4c31df	Audio or video that plays automatically has a control mechanism
QW-ACT-R51	fd26cf	video element visual-only content is media alternative for text
QW-ACT-R52	ac7dc6	video element visual-only content has description track
QW-ACT-R53	ee13b5	video element visual-only content has transcript
QW-ACT-R54	d7ba54	video element visual-only content has audio track alternative
QW-ACT-R55	1ea59c	video element visual content has audio description
QW-ACT-R56	ab4d13	video element content is media alternative for text
QW-ACT-R57	f196ce	video element visual content has description track
QW-ACT-R58	2eb176	audio element content has transcript
QW-ACT-R59	afb423	audio element content is media alternative for text
QW-ACT-R60	f51b46	video element auditory content has captions
QW-ACT-R61	1a02b0	video element visual content has transcript
QW-ACT-R62	oj04fd	Element in sequential focus order has visible focus
QW-ACT-R63	b40fd1	Document has a landmark with non-repeated content
QW-ACT-R64	047fe0	Document has heading for non-repeated content
QW-ACT-R65	307n5z	Element with presentational children has no focusable content
QW-ACT-R66	m6b1q3	Menuitem has non-empty accessible name
QW-ACT-R67	24afc2	Letter spacing in style attributes is not !important
QW-ACT-R68	78fd32	Line height in style attributes is not !important
QW-ACT-R69	9e45ec	Word spacing in style attributes is not !important
QW-ACT-R70	akn7bn	frame with negative tabindex has no interactive elements
QW-ACT-R71	bisz58	`meta` element has no refresh delay (no exception)
QW-ACT-R72	8a213c	First focusable element is link to non-repeated content
QW-ACT-R73	3e12e1	Block of repeated content is collapsible
QW-ACT-R74	ye5d6e	Document has an instrument to move focus to non-repeated content
QW-ACT-R75	cf77f2	Bypass Blocks of Repeated Content
QW-ACT-R76	09o5cg	Text has enhanced contrast
QW-ACT-R77	in6db8	ARIA required ID references exist

Implemented WCAG 2.1 Techniques

QualWeb Technique ID	WCAG Technique ID	WCAG Technique Name
QW-WCAG-T1	H24	Providing text alternatives for the area elements of image maps
QW-WCAG-T2	H39	Using caption elements to associate data table captions with data tables
QW-WCAG-T3	H71	Providing a description for groups of form controls using fieldset and legend elements
QW-WCAG-T4	H73	Using the summary attribute of the table element to give an overview of data tables
QW-WCAG-T5	H36	Using alt attributes on images used as submit buttons
QW-WCAG-T6	SCR20	Using both keyboard and other device-specific functions
QW-WCAG-T7	H28	Providing definitions for abbreviations by using the abbr element
QW-WCAG-T8	F30	Failure of Success Criterion 1.1.1 and 1.2.1 due to using text alternatives that are not alternatives
QW-WCAG-T9	G141	Organizing a page using headings
QW-WCAG-T10	H2	Combining adjacent image and text links for the same resource
QW-WCAG-T11	H35	Providing text alternatives on applet elements
QW-WCAG-T12	F46	Failure of Success Criterion 1.3.1 due to using th elements, caption elements, or non-empty summary attributes in layout tables
QW-WCAG-T13	F47	Failure of Success Criterion 2.2.2 due to using the blink element
QW-WCAG-T14	H43	Using id and headers attributes to associate data cells with header cells in data tables
QW-WCAG-T15	H59	Using the link element and navigation tools
QW-WCAG-T16	H88	Using HTML according to spec
QW-WCAG-T17	G162	Positioning labels to maximize predictability of relationships
QW-WCAG-T18	H51	Using table markup to present tabular information
QW-WCAG-T19	H32	Providing submit buttons
QW-WCAG-T20	H33	Supplementing link text with the title attribute
QW-WCAG-T21	F89	Failure of Success Criteria 2.4.4, 2.4.9 and 4.1.2 due to not providing an accessible name for an image which is the only content in a link
QW-WCAG-T22	F52	Failure of Success Criterion 3.2.1 and 3.2.5 due to opening a new window as soon as a new page is loaded
QW-WCAG-T23	G1	Adding a link at the top of each page that goes directly to the main content area
QW-WCAG-T24	F55	Failure of Success Criteria 2.1.1, 2.4.7, and 3.2.1 due to using script to remove focus when focus is received
QW-WCAG-T25	H63	Using the scope attribute to associate header cells and data cells in data tables
QW-WCAG-T26	F59	Failure of Success Criterion 4.1.2 due to using script to make div or span a user interface control in HTML without providing a role for the control
QW-WCAG-T27	F88	Failure of Success Criterion 1.4.8 due to using text that is justified (aligned to both the left and the right margins)
QW-WCAG-T28	C12 C13 C14	Using `percent, em, names` for font sizes
QW-WCAG-T29	C19	Specifying alignment either to the left or right in CSS
QW-WCAG-T30	F4	Failure of Success Criterion 2.2.2 due to using text-decoration:blink without a mechanism to stop it in less than five seconds
QW-WCAG-T31	F24	Failure of Success Criterion 1.4.3, 1.4.6 and 1.4.8 due to specifying foreground colors without specifying background colors or vice versa
QW-WCAG-T32	H48	Using ol, ul and dl for lists or groups of links

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)

Keywords

FAQs

What is @qualweb/core?

Is @qualweb/core popular?

Is @qualweb/core well maintained?

Package last updated on 03 Sep 2024

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install