Erste Schritte mit dem Verwendungsdienst und den APIs

In diesem Artikel wird gezeigt, wie Sie einen einfachen Server einrichten, um Verwendungsdienstereignisse (einen Echoserver) zu sammeln und auf der Konsole anzuzeigen. Außerdem erfahren Sie, wie Sie ein Beispiel-API-Projekt erstellen, das Ereignisse an den Echo-Server sendet. Sie erfahren außerdem, wie Sie das an den Nutzungsdienst gesendete Ereignis mithilfe von Umgebungsvariablen ändern können.

Voraussetzungen

Sie müssen Node.js installieren, um dieses Beispiel zu verwenden. Das Node.js-Installationsprogramm finden Sie unter Node.js .

Einrichten eines Echo-Servers

Erstellen Sie eine Datei mit dem unten gezeigten Code:

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)

Wir nennen die Datei echo-server.js. Speichern Sie es in einem neuen Verzeichnis und wechseln Sie in dieses Verzeichnis.

Der Server hört auf Anfragen auf Port 3000 und schreibt den Body der empfangenen Anfrage in die Konsole. Jedes Mal, wenn ein API-Client oder CLI-Test ausgeführt wird (und die Nutzungsprotokollierung aktiviert ist), schreibt der Echoserver das empfangene Nutzungsereignis.

Installieren Sie express und body-parser, zwei Abhängigkeiten, die zum Ausführen des obigen Codes erforderlich sind:

npm i express body-parser

Starten Sie den Echoserver:

node echo-server.js

Erstellen eines Tests

Sie können den Beispielkatalog verwenden, um Beispieltestcode zu erhalten. Wenn Sie den Testcode ausführen, sendet er Nutzungsmetrikdaten an den Echoserver, den Sie im vorherigen Abschnitt erstellt haben.

Starten Sie für die folgenden Schritte ein neues Terminal- oder Konsolenfenster.

Klonen Sie das Deque Examples Catalog Repository auf GitHub und wechseln Sie dann in dieses Verzeichnis:

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

Für dieses Beispiel haben wir das Node.js Playwright-Codebeispiel verwendet. Wechseln Sie in dieses Verzeichnis und installieren Sie die erforderlichen Node.js-Pakete:

cd Node/playwright
npm i

Möglicherweise müssen Sie auch die Abhängigkeiten von Playwright installieren:

npx playwright install

Legen Sie nun die erforderlichen Umgebungsvariablen fest, um die Metrikberichterstattung zu aktivieren, und stellen Sie den Server auf den zuvor erstellten lokalen Echoserver ein:

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

Sie können die Umgebungsvariablen festlegen und die Tests (npm test) über die Befehlszeile unter Linux und macOS ausführen:

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

Das Terminalfenster, das den laufenden Echo-Server enthält, zeigt Ergebnisse wie die folgenden an:

{
  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: {}
  }
}

Einzelheiten zu den Eigenschaften dieses Objekts finden Sie unter Das Ereignisobjekt.

Ändern des Ereignisses mithilfe von Umgebungsvariablen

Sie können das Ereignis, das die APIs oder die CLI an den Nutzungsdienst senden, mithilfe von Umgebungsvariablen ändern. Dieses Beispiel zeigt, wie das Ereignis geändert wird.

Legen Sie zunächst eine Umgebungsvariable für den Wert fest, den Sie ändern möchten, zum Beispiel:

export AXE_DEPARTMENT="test department"

Dadurch wird die Eigenschaft department des Ereignisobjekts geändert, wie das folgende Beispiel zeigt (unter Linux oder macOS):

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

Im Terminalfenster, in dem Sie den Echo-Server ausführen, sollten Sie ein Ereignis sehen, das department enthält, wie die unten hervorgehobene Zeile zeigt:

{
  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'}

Weitere Informationen zu den Umgebungsvariablen, die Sie zum Ändern von Nutzungsereignissen verwenden können, finden Sie unter Steuern des Nutzungsdiensts über Umgebungsvariablen.

Nächster Schritt

Eine Version dieses Tutorials für die CLI finden Sie unter Erste Schritte mit dem Nutzungsdienst und der CLI.

Übersichtsinformationen zum Nutzungsdienst finden Sie unter Der Nutzungsdienst.

Eine Referenz für das Ereignisobjekt finden Sie unter The Usage Service Event Reference.