Primeros pasos con el Servicio de Uso y las APIs

Este artículo muestra cómo configurar un servidor simple para recopilar eventos del servicio de uso (un servidor de eco) y mostrarlos en la consola. También aprenderás cómo construir un proyecto API de ejemplo que enviará eventos al servidor de eco. Además, verás cómo modificar el evento enviado al servicio de uso utilizando variables de entorno.

Requisitos previos

Necesitas instalar Node.js para usar este ejemplo. Consulta Node.js para el instalador de Node.js.

Configuración de un Servidor Echo

Crea un archivo con el código mostrado a continuación:

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)

Llamaremos al archivo echo-server.js. Guárdalo en un nuevo directorio y cambia a ese directorio.

El servidor escucha las solicitudes en el puerto 3000 y escribe el cuerpo de la solicitud recibida en la consola. Así que cada vez que se ejecuta un cliente de API o una prueba de CLI (y el registro de uso está habilitado), el servidor echo escribe el evento de uso recibido.

Instala express y body-parser, dos dependencias necesarias para ejecutar el código anterior:

npm i express body-parser

Inicia el servidor echo:

node echo-server.js

Creación de una Prueba

Puedes usar el Catálogo de Ejemplos para obtener código de prueba de ejemplo. Cuando ejecutes el código de prueba, enviará datos métricos de uso al servidor de eco que creaste en la sección anterior.

Inicia una nueva ventana de terminal o consola para los siguientes pasos.

Clona el repositorio del Catálogo de Ejemplos Deque en GitHub y luego cambia a ese directorio:

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

Para este ejemplo, utilizamos el código de muestra de Node.js Playwright. Cambia a ese directorio e instala los paquetes necesarios de Node.js:

cd Node/playwright
npm i

También puede que necesites instalar las dependencias de Playwright:

npx playwright install

Ahora configura las variables de entorno necesarias para habilitar la generación de métricas y establece el servidor en el servidor de eco local que creaste anteriormente:

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

Puedes configurar las variables de entorno y ejecutar las pruebas (npm test) desde la línea de comandos en Linux y 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 ventana del terminal que contiene el servidor de eco en ejecución mostrará resultados como los siguientes:

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

Para obtener detalles sobre las propiedades de este objeto, consulta El Objeto Evento.

Cambiar el Evento usando Variables de Entorno

Puedes cambiar el evento que las APIs o la CLI envían al servicio de uso utilizando variables de entorno. Este ejemplo demuestra cómo cambiar el evento.

Primero, establece una variable de entorno para el valor que deseas cambiar, por ejemplo:

export AXE_DEPARTMENT="test department"

Esto cambiará la propiedad department en el objeto evento como muestra el ejemplo a continuación (en Linux o macOS):

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

Desde la ventana del terminal donde estás ejecutando el servidor de eco, deberías ver un evento que incluye información de department como muestra la línea resaltada a continuación:

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

Para más información sobre las variables de entorno que puedes usar para modificar eventos de uso, consulta Controlar el Servicio de Uso a través de Variables de Entorno.

Próximos Pasos

Para seguir una versión de este tutorial para la CLI, consulta Primeros pasos con el Servicio de Uso y la CLI.

Para obtener información general sobre el servicio de uso, consulta El Servicio de Uso.

Para una referencia del objeto evento, consulta Referencia de Eventos del Servicio de Uso.