Introdução ao Serviço de Uso e às APIs

Este artigo mostra como configurar um servidor simples para coletar eventos do serviço de uso (um servidor de eco) e exibi-los no console. Você também aprenderá a construir um projeto de API exemplo que enviará eventos para o servidor de eco. Além disso, verá como modificar o evento enviado para o serviço de uso usando variáveis de ambiente.

Pré-requisitos

Você precisa instalar o Node.js para usar este exemplo. Veja Node.js para o instalador do Node.js.

Configurando um Servidor Echo

Crie um arquivo contendo o código mostrado abaixo:

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)

Vamos chamar o arquivo de **echo-server.js**. Salve-o em um novo diretório e mude para esse diretório.

O servidor escuta solicitações na porta 3000 e escreve o corpo da solicitação recebida no console. Assim, toda vez que um cliente de API ou teste de CLI é executado (e o registro de uso está ativado), o servidor echo escreve o evento de uso recebido.

Instale **express** e **body-parser**, duas dependências necessárias para executar o código acima:

npm i express body-parser

Inicie o servidor echo:

node echo-server.js

Criando um Teste

Você pode usar o Catálogo de Exemplos para obter código de teste exemplo. Quando você executar o código de teste, ele enviará dados de métricas de uso para o servidor de eco que você criou na seção anterior.

Abra um novo terminal ou janela de console para os passos seguintes.

Clone o repositório do Catálogo de Exemplos Deque no GitHub e, em seguida, vá para esse diretório:

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

Neste exemplo, usamos o código de amostra do Node.js Playwright. Vá para esse diretório e instale os pacotes necessários do Node.js:

cd Node/playwright
npm i

Você também pode precisar instalar as dependências do Playwright:

npx playwright install

Agora defina as variáveis de ambiente necessárias para habilitar o relatório de métricas e configure o servidor para o servidor de eco local que você criou anteriormente:

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

Você pode definir as variáveis de ambiente e executar os testes (npm test) a partir da linha de comando no Linux e no 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

A janela do terminal que contém o servidor de eco em execução mostrará resultados como os seguintes:

{
  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 detalhes sobre as propriedades deste objeto, veja O Objeto Evento.

Alterando o Evento usando Variáveis de Ambiente

Você pode alterar o evento que as APIs ou CLI enviam para o serviço de uso usando variáveis de ambiente. Este exemplo demonstra como alterar o evento.

Primeiro, defina uma variável de ambiente para o valor que você gostaria de alterar, por exemplo:

export AXE_DEPARTMENT="test department"

Isso alterará a propriedade departamento no objeto de evento conforme o exemplo abaixo mostra (no Linux ou macOS):

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

Na janela do terminal onde você está executando o servidor de eco, você deve ver um evento que inclui a informação departamento conforme a linha destacada abaixo mostra:

{
  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 mais informações sobre as variáveis de ambiente que você pode usar para modificar eventos de uso, veja Controlando o Serviço de Uso via Variáveis de Ambiente.

Próximas Etapas

Para seguir uma versão deste tutorial para o CLI, veja Introdução ao Serviço de Uso e ao CLI.

Para informações gerais sobre o serviço de uso, veja O Serviço de Uso.

Para uma referência do objeto de evento, veja Referência de Evento do Serviço de Uso.