Premiers pas avec le service d'usage et les API

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

Prérequis

Vous devez installer Node.js pour utiliser cet exemple. Voir Node.js pour le programme d'installation de Node.js.

Mise en place 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 à ce 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 de l'utilisation est activée), le serveur d'écho écrit l'événement d'utilisation reçu.

Installez express et body-parser, deux dépendances requises 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 des exemples de code de test. Lorsque vous exécutez le code de test, il enverra les données des métriques d’utilisation au serveur d’é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 référentiel Deque Examples Catalog sur GitHub, puis accédez à ce 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. Accédez à ce répertoire et installez les packages Node.js nécessaires :

cd Node/playwright
npm i

Vous devrez peut-être également installer les dépendances de Playwright :

npx playwright install

Définissez maintenant les variables d’environnement requises pour activer la création de rapports de métriques et définissez le serveur sur le serveur d’é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 sous 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 echo en cours d'exécution affichera des résultats comme les suivants :

{
  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 plus de détails sur les propriétés de cet objet, voir L'Objet Événement.

Modification de l'événement à l'aide de variables d'environnement

Vous pouvez modifier l’événement que les API ou la CLI envoient au service d’utilisation à l’aide de variables d’environnement. Cet exemple montre le comment modifier l'événement.

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

export AXE_DEPARTMENT="test department"

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

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

À partir de la fenêtre du terminal où vous exécutez le serveur echo, vous devriez voir un événement qui inclut des informations sur le ** département** , comme le montre la ligne en surbrillance 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, consultez Contrôle du service d'utilisation via des variables d'environnement.

Prochaines étapes

Pour suivre une version de ce tutoriel pour la CLI, consultez Premiers pas avec le service d'utilisation et la CLI.

Pour obtenir des informations générales sur le service d'utilisation, consultez Le service d'utilisation.

Pour une référence sur l'objet événement, voir La Référence des Événements du Service d'Utilisation.