Workflow spec

Link to Workflow spec copied to clipboard

The axe DevTools CLI spec command runs a JSON or YAML/YML workflow spec, which lets you automate testing a collection of web pages for accessibility issues.

Command Format

axe spec <spec-file> <output-dir> [options]

For example:

axe spec deque-workflow.json ./axe-reports --format csv

Spec file

A spec file is a JSON or YAML/YML file that contains an array of web pages to be tested and various configuration properties (as mentioned below).

Properties Used in a Spec File

Here are the properties used with a spec file:

Property	Data Type	Description
`projects`	array	Groups tests and workflows.
. `metadata`	object	Provides customizable data for your use case.
. `name`	string	Unique name of the project.
. `id`	string	Unique identifier of the project.
. `globalActions`	array	(optional) The axe DevTools CLI waits for certain elements to appear on a page and dismisses them. In the example below, cookie messaging and user survey popups need to be dealt with before testing each page.
. `pageList`	array	List of pages
.. `name`	string	Name of the page
.. `url`	string	URL of the page
.. `actions`	array	(optional) Executes actions one after another on the page that is being tested. You can, for instance, fill out a form, navigate through a single page app, and test the application in different states. In the example below, the workflow enters "axe" into the Deque search UI. The global action dismisses the cookie popup. For complete list of actions, see workflow actions.

Example JSON file

Here is an example JSON spec file:

{
  "projects": [
    {
      "metadata": {
        "products": ["CLI"],
        "environment": ["Prod"]
      },
      "name": "deque.com",
      "id": "deque.com",
      "globalActions": [
        "dismiss modal \"#CybotCookiebotDialog\" with close button \"#CybotCookiebotDialogBodyButtonAccept\""
      ],
      "pageList": [
        {
          "name": "Deque search",
          "url": "https://www.deque.com/",
          "actions": [
            "type \"axe\" into element \"#searchform input\"",
            "click element \"#searchform button\"",
            "wait for element \".m-search-page\" to be found",
            "analyze"
          ]
        },
        {
          "name": "Axe Dashboard",
          "url": "https://axe.deque.com/"
        }
      ]
    }
  ]
}

Example YAML/YML file

projects:
  - metadata:
      products:
        - CLI
      environment:
        - Prod
    name: deque.com
    id: deque.com
    globalActions:
      - >-
        dismiss modal "#CybotCookiebotDialog" with close button
        "#CybotCookiebotDialogBodyButtonAccept"
    pageList:
      - name: Deque search
        url: https://www.deque.com/
        actions:
          - type "axe" into element "#searchform input"
          - click element "#searchform button"
          - wait for element ".m-search-page" to be found
          - analyze
      - name: Axe Dashboard
        url: https://axe.deque.com/

Output directory

The output directory is where axe DevTools CLI saves its results (as a JSON file).

The following code snippet saves JSON results and CSV reports in the ./axe-results/ directory:

axe spec deque-workflow.json ./axe-results --format csv

Options

The following options are available for axe spec:

-c, --custom <path>

Specifies a custom ruleset to use and overrides the default ruleset.

--descendant-links

Gets the links on the web page and appends them to the results. Requires the --verbose option.

--enable-tracking <state>

Enables sending data to the metrics library.

--filter [type(s)]

Provides a list of result types to filter from results: passes, violations, incomplete, inapplicable. (The --format csv option is required.)

axe reporter ./axe-reports/json/ --format=csv --filter passes,inapplicable

-f, --format [value]

Specifies the report type or types [html|junit|csv|html+junit+csv]. The default is html.

--page-source

Appends the scanned HTML page to the scan results. You must use this option with the --verbose option.

--page-name <name>

Tests a specific page named name from the pageList array in the JSON spec file.

--page-title

Gets the page title when scanning and appends it to the scan results. You must use --verbose option.

--remote-proxy <proxy-server>

Uses a remote proxy server.

--resume-from <name>

Runs the tests only after a specific page called name.

--scanned-url

Adds additional metadata to the verbose results: the base URL where the scan was initiated and the URL of the current scan. Works with the Chrome browser only and requires the --verbose option.

--set-distinct-id <distinct-id>

Changes the value of the distinct id.

--set-tracking-url <url>

Changes the url where the metrics data is sent.

-t, --tags

Filters standard ruleset by tag.

--user-agent

Uses the specified browser's user agent.

--validate

Verifies your spec file without running it.

-v, --verbose

Increases the output to include additional information including axe results and metadata like test-tool name, version, and environment.

For other options, see configuration flags