The Usage Service Event Reference

This article contains reference information about:

• The event data that is sent to the usage service (version 2 of the event object, EventV2)
• Its contained applicationProperties object
• The testResults object (contained within the applicationProperties object) when AXE_INCLUDE_TEST_RESULTS is set to true

Version 2 Event

The following TypeScript interface defines a version 2 event:

interface EventV2 {
  version: 'v2'
  productName: string
  productComponent: string
  productComponentVersion: string
  event: string
  dateTime: Date
  keycloakId?: string
  distinctId: string
  userId?: string
  organization?: string
  department?: string
  application?: string
  devInstance?: boolean
  sessionId?: string
  userStatus?: string
  loggedIn?: boolean
  applicationProperties?: Record<string, any>
  userJobRole?: string
  actor?: 'human' | 'automation'
  teams?: { id: string; name: string }[]
}

distinctId

The distinctId value is a uuid that is set per user whenever the metrics are recorded. It should be stable across time because it is set upon first run of the CLI or code that uses the APIs. It is stored in the .deque/distinct_id file in each user's home directory.

actor

The CLI and the Node.js APIs set actor to automation when one of these environment variables is set to a value other than false or 0: CI, BUILD_NUMBER, BUILDKITE, CIRCLECI, CODEBUILD_BUILD_ID, GITHUB_ACTIONS, GITLAB_CI, JENKINS_URL, TEAMCITY_VERSION, TF_BUILD, or BITBUCKET_BUILD_NUMBER. Otherwise, actor is human. Set the AXE_ACTOR environment variable to human or automation to override the detection. The @axe-devtools/browser package can't read environment variables when it runs in a browser, so it reports human there.

teams

The teams array records the teams whose members ran the test. The CLI and the Node.js APIs always send it, as an empty array ([]) when no teams are set. You supply the teams yourself, with the AXE_TEAMS environment variable, the CLI's --set-teams option, or your Node.js API's setTeams method. Each team is an object with string id and name properties:

[{ "id": "1", "name": "Web" }]

Entries without a string id and name are dropped. A value that can't be read or isn't a JSON array is ignored, and the event is still sent.

applicationProperties

The applicationProperties object contains count information about the test run, as an example below shows:

  applicationProperties: {
    advancedRules: { enabled: false, value: 'disabled', source: 'unavailable' },
    target: 'https://broken-workshop.dequelabs.com/',
    targetMedium: 'text/html',
    urlCount: 1,
    engineVersion: '4.14.0',
    failedRuleCount: 2,
    failedRuleNames: 'color-contrast,label',
    failedItemCount: 5,
    criticalIssueCount: 3,
    seriousIssueCount: 2,
    moderateIssueCount: 0,
    minorIssueCount: 0,
    needsReviewItemCount: 4,
    inapplicableRuleCount: 39,
    incompleteRuleCount: 2,
    passedRuleCount: 21,
    testResults: {}
  },

testResults

The testResults object is defined as an axeResults object (defined by axe-core). It is only set when you have set the AXE_INCLUDE_TEST_RESULTS environment variable to true, which is supported by the CLI and the Node.js APIs only.

interface AxeResults extends EnvironmentData {
  toolOptions: RunOptions;
  passes: Result[];
  violations: Result[];
  incomplete: Result[];
  inapplicable: Result[];
}

The following shows an example of a testResults object:

{
  testEngine: {
    name: "axe-core",
    version: "4.4.1"
  },
  testRunner: {
    name: "axe"
  },
  testEnvironment: {
    userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML,like Gecko) Version/16.0 Safari/605.1.15",
    windowWidth: 1280,
    windowHeight: 720
  },
  timestamp: "2023-02-02T20:09:04.785Z",
  url: "https://broken-workshop.dequelabs.com/",
  toolOptions: {
    reporter: "v1"
  },
  inapplicable: [],
  passes: [],
  incomplete: [],
  violations: []
}

For brevity, the inapplicable, passes, incomplete, and violations arrays, which normally contain Result objects, were not included.

You can see the TypeScript definitions for these objects in the axe-core GitHub repo.

See Also

For tutorials demonstrating how to use the usage service, see Getting Started with the Usage Service and the APIs and Getting Started with the Usage Service and the CLI.

For general information on the usage service, see The Axe DevTools for Web Usage Service.