Getting Started with the Usage Service and the CLI

This article shows how to use the usage service with the CLI. You'll be guided through setting up a local server to echo usage service events, shown how to send usage metrics to the server using the CLI, and how to modify usage service events using environment variables.

The usage service allows you to track usage metrics for your organization's use of the CLI. Enabling the usage service can be an important tool for your organization to perform license compliance monitoring, testing audits, and ensuring all axe DevTools HTML instances are configured to your organization's standards.

For overview information about usage service see The axe DevTools Usage Service.

Prerequisites

You need to install Node.js to use this example. See Node.js for the Node.js installer.

Setting up an Echo Server

Create a file containing the code shown below:

const express = require('express')
const bodyParser = require('body-parser')

const app = express()

// Parse JSON bodies.
app.use(bodyParser.json())
// Accept events.
app.post('/:version/event', (req, res) => {
  const event = req.body
  console.log(event)

  // Respond so the client is happy.
  res.status(200)
  res.send('Event accepted!')
})

// Listen for requests.
app.listen(3000)

We'll call the file echo-server.js. Save it to a new directory and change to that directory.

The server listens to requests on port 3000 and writes the body of the request received to the console. So every time an API client or CLI test is run (and usage logging is enabled), the echo server writes the usage event received.

Install express and body-parser, two dependencies required to run the above code:

npm i express body-parser

Start the echo server:

node echo-server.js

Testing a Site with the CLI

You'll now need to set two environment variables: first, to enable the usage service and, second, to provide the URL for the server (the local server created in the previous section):

1. export AXE_TRACK_USAGE=true
2. export AXE_METRICS_URL=http://localhost:3000

In Linux or macOS, you can set the environment variables and invoke a CLI scan of a website on a single line as shown here:

AXE_TRACK_USAGE=true AXE_METRICS_URL=http://localhost:3000 axe https://broken-workshop.dequelabs.com/

set AXE_TRACK_USAGE=true
set AXE_METRICS_URL=http://localhost:3000

setx AXE_TRACK_USAGE true
setx AXE_METRICS_URL http://localhost:3000

This command runs an analysis using the CLI on the site https://broken-workshop.dequelabs.com.

Return to the console window where you are running the echo server, and you will see the received events from the echo server, an example of an event is shown below:

{
  dateTime: '2023-01-20T20:48:16.864Z',
  productComponent: 'api-cli',
  productName: 'axe-devtools-html',
  version: 'v2',
  event: 'uri: analyze',
  distinctId: 'f542d302-18a0-42a6-ab7f-ec1e42399bfe',
  applicationProperties: {
    target: 'https://broken-workshop.dequelabs.com/',
    target_medium: 'text/html',
    engineVersion: '4.5.2',
    failedRuleCount: 2,
    failedRuleNames: 'color-contrast,image-alt',
    failedItemCount: 12,
    inapplicableRuleCount: 33,
    incompleteRuleCount: 0,
    passedRuleCount: 27,
    testResults: {}
  }
}

For more information about the event object, see The Event Object.

Changing the Event Using Environment Variables

You can use environment variables to change the properties of the reported event. For example, you can change or add the userJobRole property by setting the AXE_USER_JOB_ROLE environment variable:

AXE_TRACK_USAGE=true AXE_METRICS_URL=http://localhost:3000 AXE_USER_JOB_ROLE="testing" axe https://broken-workshop.dequelabs.com/

An example of the events received by the echo server is shown below:

{
  dateTime: '2023-01-20T20:52:23.878Z',
  productComponent: 'api-cli',
  productName: 'axe-devtools-html',
  version: 'v2',
  event: 'uri: analyze',
  distinctId: '9c55a1f8-5177-44ee-a0e3-5dafa5ef9fc9',
  applicationProperties: {
    target: 'https://broken-workshop.dequelabs.com/',
    target_medium: 'text/html',
    engineVersion: '4.5.2',
    failedRuleCount: 2,
    failedRuleNames: 'color-contrast,image-alt',
    failedItemCount: 12,
    inapplicableRuleCount: 33,
    incompleteRuleCount: 0,
    passedRuleCount: 27,
    testResults: {}
  },
  userJobRole: 'testing'}

The userJobRole property was added by setting the AXE_USER_JOB_ROLE environment variable as shown by the highlighted line.

To set other properties in the event, see Controlling the Usage Service via Environment Variables.

Next Steps

To follow a version of this tutorial for the axe DevTools APIs, see Getting Started with the Usage Service and the APIs.

For overview information about the usage service, see The Usage Service. For reference information about the event object, see The Usage Service Event Reference.