Aan de slag met de Usage Service en de API's

Dit artikel laat zien hoe je een eenvoudige server opzet om usage service-evenementen te verzamelen (een echo-server) en deze op de console weer te geven. Je leert ook hoe je een voorbeeld-API-project bouwt dat evenementen naar de echo-server stuurt. Daarnaast leer je hoe je het evenement dat naar de usage service wordt verzonden, kunt aanpassen met behulp van omgevingsvariabelen.

Vereisten

Je moet Node.js installeren om dit voorbeeld te gebruiken. Zie Node.js voor de Node.js installer.

Een Echo Server opzetten

Maak een bestand aan met de code die hieronder wordt getoond:

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 zullen het bestand **echo-server.js** noemen. Sla het op in een nieuwe map en ga naar die map.

De server luistert naar aanvragen op poort 3000 en schrijft de body van de ontvangen aanvraag naar de console. Dus elke keer dat een API-client of CLI-test wordt uitgevoerd (en gebruiksregistratie is ingeschakeld), schrijft de echo server de ontvangen gebruiksgebeurtenis.

Installeer **express** en **body-parser**, twee afhankelijkheden die nodig zijn om de bovenstaande code uit te voeren:

npm i express body-parser

Start de echo server:

node echo-server.js

Een test maken

Je kunt de Voorbeeldcatalogus gebruiken om voorbeeldtestcode te verkrijgen. Wanneer je de testcode uitvoert, zal deze gegevens over gebruiksstatistieken naar de echo-server sturen die je in de vorige sectie hebt gemaakt.

Start een nieuw terminal- of consolevenster voor de volgende stappen.

Kloon de Deque Examples Catalog repository op GitHub en ga daarna naar die directory:

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

Voor dit voorbeeld hebben we de Node.js Playwright-codevoorbeeld gebruikt. Ga naar die directory en installeer de benodigde Node.js-pakketten:

cd Node/playwright
npm i

Je moet mogelijk ook de afhankelijkheden van Playwright installeren:

npx playwright install

Stel nu de vereiste omgevingsvariabelen in om de rapportage van statistieken mogelijk te maken en stel de server in op de lokale echo-server die je eerder hebt gemaakt:

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

Je kunt de omgevingsvariabelen instellen en de tests uitvoeren (npm test) vanaf de opdrachtregel op Linux en 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

Het terminalvenster dat de draaiende echo-server bevat, zal resultaten tonen zoals de volgende:

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

Voor details over de eigenschappen van dit object, zie Het Event Object.

Het evenement wijzigen met behulp van omgevingsvariabelen

Je kunt het evenement dat de API's of CLI naar de usage service verzendt veranderen door gebruik te maken van omgevingsvariabelen. Dit voorbeeld demonstreert hoe je het evenement kunt wijzigen.

Stel eerst een omgevingsvariabele in voor de waarde die je wilt veranderen, bijvoorbeeld:

export AXE_DEPARTMENT="test department"

Dit zal de afdeling-eigenschap van het gebeurtenisobject wijzigen, zoals het onderstaande voorbeeld laat zien (op Linux of macOS):

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

Vanuit het terminalvenster waarin je de echo-server uitvoert, zou je een gebeurtenis moeten zien die afdeling-informatie bevat zoals de gemarkeerde regel hieronder laat zien:

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

Voor meer informatie over de omgevingsvariabelen die je kunt gebruiken om gebruiksevenementen aan te passen, zie De Usage Service beheren via omgevingsvariabelen.

Volgende stappen

Voor een versie van deze handleiding voor de CLI, zie Aan de slag met de Usage Service en de CLI.

Voor algemene informatie over de usage service, zie De Usage Service.

Voor een referentie voor het evenementobject, zie De Usage Service Event Referentie.