Prise en main du service d'utilisation et des API

Cet article montre comment configurer un serveur simple pour collecter les événements du service d'utilisation (un serveur écho) et les afficher sur la console. Vous apprendrez également à créer un projet d'API exemple qui enverra des événements au serveur écho. Vous verrez aussi comment modifier l'événement envoyé au service d'utilisation à l'aide des variables d'environnement.

Prérequis

Vous devez installer Node.js pour utiliser cet exemple. Consultez Node.js pour l'installateur Node.js.

Configuration d'un serveur Echo

Créez un fichier contenant le code ci-dessous :

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)

Nous appellerons le fichier echo-server.js. Enregistrez-le dans un nouveau répertoire et changez de répertoire.

Le serveur écoute les requêtes sur le port 3000 et écrit le corps de la requête reçue sur la console. Ainsi, chaque fois qu'un client API ou un test CLI est exécuté (et que la journalisation d'utilisation est activée), le serveur echo écrit l'événement d'utilisation reçu.

Installez express et body-parser, deux dépendances nécessaires pour exécuter le code ci-dessus :

npm i express body-parser

Démarrez le serveur echo :

node echo-server.js

Créer un test

Vous pouvez utiliser le Catalogue d'exemples pour obtenir du code de test exemple. Lorsque vous exécutez le code de test, il enverra des données de métriques d'utilisation au serveur écho que vous avez créé dans la section précédente.

Démarrez une nouvelle fenêtre de terminal ou de console pour les étapes suivantes.

Clonez le dépôt du Catalogue d'exemples Deque sur GitHub puis changez de répertoire :

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

Pour cet exemple, nous avons utilisé l'exemple de code Node.js Playwright. Passez dans ce répertoire et installez les packages Node.js nécessaires :

cd Node/playwright
npm i

Il se peut que vous ayez également besoin d'installer les dépendances de Playwright :

npx playwright install

Définissez maintenant les variables d'environnement requises pour activer le reporting des métriques et réglez le serveur sur le serveur écho local que vous avez créé précédemment :

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

Vous pouvez définir les variables d'environnement et exécuter les tests (npm test) depuis la ligne de commande sur Linux et 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

La fenêtre du terminal qui contient le serveur écho en cours d'exécution affichera des résultats comme ceux-ci :

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

Pour des détails sur les propriétés de cet objet, voir L'objet événement.

Modifier l'événement à l'aide des variables d'environnement

Vous pouvez modifier l'événement que les API ou CLI envoient au service d'utilisation en utilisant des variables d'environnement. Cet exemple démontre comment modifier l'événement.

Tout d'abord, définissez une variable d'environnement pour la valeur que vous souhaitez changer, par exemple :

export AXE_DEPARTMENT="test department"

Cela changera la propriété department sur l'objet événement comme le montre l'exemple ci-dessous (sur Linux ou macOS) :

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

Depuis la fenêtre de terminal où vous exécutez le serveur écho, vous devriez voir un événement incluant les informations department comme le montre la ligne mise en évidence ci-dessous :

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

Pour plus d'informations sur les variables d'environnement que vous pouvez utiliser pour modifier les événements d'utilisation, voir Contrôler le service d'utilisation via des variables d'environnement.

Prochaines étapes

Pour suivre une version de ce tutoriel pour la CLI, voir Prise en main du service d'utilisation et de la CLI.

Pour une vue d'ensemble du service d'utilisation, voir Le service d'utilisation.

Pour une référence de l'objet événement, voir Référence d'événement du service d'utilisation.