Getting Started with the Usage Service and the APIs

This article shows how to set up a simple server to collect usage service events (an echo server) and display them on the console. You'll also learn how to build an example API project that will send events to the echo server. You'll also see how to modify the event sent to the usage service using environment variables.

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

Creating a Test

You can use the Examples Catalog to obtain sample test code. When you run the test code, it will send usage metrics data to the echo server you created in the previous section.

Start a new terminal or console window for the following steps.

Clone the Deque Examples Catalog repository on GitHub and then change to that directory:

git clone git@github.com:dequelabs/axe-devtools-html-api-examples.git
cd axe-devtools-html-api-examples

For this example, we used the Node.js Playwright code sample. Change to that directory and install the necessary Node.js packages:

cd Node/playwright
npm i

You might also need to install Playwright's dependencies:

npx playwright install

Now set the required environment variables to enable metrics reporting and set the server to the local echo server you created earlier:

• export AXE_TRACK_USAGE=true
• export AXE_METRICS_URL=http//localhost:3000

You can set the environment variables and run the tests (npm test) from the command line on Linux and macOS:

AXE_TRACK_USAGE=true AXE_METRICS_URL=http://localhost:3000 npm test

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

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

The terminal window that contains the running echo server will show results like the following:

{
  dateTime: '2023-01-20T17:26:54.371Z',
  productComponent: 'api-node-playwright',
  productName: 'axe-devtools-html',
  version: 'v2',
  event: 'analyze',
  distinctId: '1b8a5e67-eb1f-4637-9668-be3a332d2c41',
  applicationProperties: {
    target: 'https://broken-workshop.dequelabs.com/',
    target_medium: 'text/html',
    engineVersion: '4.5.2',
    failedRuleCount: 2,
    failedRuleNames: 'color-contrast,label',
    failedItemCount: 5,
    inapplicableRuleCount: 39,
    incompleteRuleCount: 2,
    passedRuleCount: 21,
    testResults: {}
  }
}

For details on the properties of this object, see The Event Object.

Changing the Event using Environment Variables

You can change the event the APIs or CLI send to the usage service using environment variables. This example demonstrates the how to change the event.

First, set an environment variable for the value you'd like to change, for instance:

export AXE_DEPARTMENT="test department"

This will change the department property on the event object as the example below shows (on Linux or macOS):

AXE_DEPARTMENT="test department" AXE_TRACK_USAGE=true AXE_METRICS_URL=http://localhost:3000  npm test

From the terminal window where you're running the echo server, you should see an event that includes department information as the highlighted line below shows:

{
  dateTime: '2023-01-20T17:31:48.422Z',
  productComponent: 'api-node-playwright',
  productName: 'axe-devtools-html',
  version: 'v2',
  event: 'analyze',
  distinctId: '18cd1262-b5b7-4681-9f7a-a7d4c97745c8',
  applicationProperties: {
    target: 'https://broken-workshop.dequelabs.com/',
    target_medium: 'text/html',
    engineVersion: '4.5.2',
    failedRuleCount: 2,
    failedRuleNames: 'color-contrast,label',
    failedItemCount: 5,
    inapplicableRuleCount: 39,
    incompleteRuleCount: 2,
    passedRuleCount: 21,
    testResults: {}
  },
  department: 'test department'}

For more information about the environment variables you can use to modify usage events, see Controlling the Usage Service via Environment Variables.

Next Steps

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

For overview information about the usage service, see The Usage Service.

For a reference for the event object, see The Usage Service Event Reference.