Uso Avançado de API com Ruby
Uso avançado do Axe DevTools para Web Ruby, incluindo regras personalizadas, opções de relatório e o serviço de uso
Este documento discute regras personalizadas, opções de relatório e o serviço de uso com Ruby.
Elementos Personalizados e ElementInternals
A partir do Axe DevTools Ruby 4.13.0, as verificações leem as semânticas ARIA que os componentes web declaram em JavaScript através de ElementInternals, em vez de apenas os atributos role e aria-* presentes na marcação. Nenhuma configuração é necessária. As semânticas no DOM ainda têm precedência: um atributo role ou aria-* explícito no elemento substitui o valor de ElementInternals.
Seus componentes devem publicar seus internos para que qualquer coisa disso tenha efeito, e um componente que os armazena em um campo de classe privado não pode ser lido. Veja Testando Elementos Customizados Que Usam ElementInternals.
Regras Personalizadas
Você pode especificar regras customizadas do axe-core em um arquivo JSON.
Se você ainda não tem regras personalizadas e deseja começar com um conjunto de regras personalizadas vazio, crie um arquivo axe-ruleset.json no diretório local com um objeto JavaScript vazio, por exemplo: {}.
Configurar Regras Personalizadas por meio de uma Variável de Ambiente
A configuração padrão espera que a localização do arquivo de regras personalizadas seja config/axe-ruleset.json, relativa ao diretório de trabalho atual.
Você pode substituir essa localização com a variável de ambiente AXE_RULESET_PATH ou manualmente através da configuração do Axe DevTools.
Defina a variável de ambiente AXE_RULESET_PATH para alterar a localização do seu axe-ruleset.json:
AXE_RULESET_PATH=/path/to/your/axe-ruleset.jsonConfigurando Regras Personalizadas via Configuração do Axe DevTools
Um objeto de configuração está disponível para definir a localização de uma regra personalizada usando o método AxeDevTools.configure caso você não deseje trabalhar com a variável de ambiente AXE_RULESET_PATH.
Todas as configurações abaixo são opcionais. Você pode omitir toda a invocação de AxeDevTools.configure para usar os valores padrão originais.
AxeDevTools.configure do |config|
# path to json configuration providing custom rules and checks
# set defaults to "config/axe-ruleset.json"
config.axe_ruleset_path = "config/axe-ruleset.json"
# Configure user pre-defined standard rule sets. Custom
# rules override these rule sets. See https://github.com/dequelabs/axe-core/blob/develop/doc/rule-descriptions.md
config.rule_set_id = '508'
endOpções de Relatórios
Configurando Opções de Relatórios com a Configuração do Axe DevTools
Os gems axe-devtools-* permitem registrar os resultados dos testes. Use a invocação AxeDevTools.Configure para configurar uma configuração global para relatórios:
AxeDevTools.configure do |config|
config.output_directory: 'my-results',
config.test_machine: 'my-server',
config.test_suite_name: 'Accessibility Tests For Application',
config.user_agent: 'Headless Chrome'
end
expect(page).to be_audited_for_accessibility.logging_results({
ui_state: 'Landing Page Load',
})A configuração de relatório pode ter as seguintes propriedades:
| Atributo | Valor Padrão | Descrição |
|---|---|---|
| ui_state (Obrigatório) | Atributo a ser passado no objeto options. |
|
| output_directory (Opcional) | axe-reports |
Nome do diretório onde os relatórios devem ser gerados. |
| test_machine (Opcional) | Valor para indicar onde o teste é executado. Por exemplo, CircleCI, TesterMachine01 |
|
| test_suite_name (Opcional) | axe-a11yCheck |
Nome para o conjunto de testes. Por exemplo, My Module Test Suite |
| user_agent (Opcional) | null | Passar um user agent alvo. Por exemplo, chrome. |
| verbose (Opcional) | false | flag para habilitar/desabilitar registro detalhado de rastreamento de pilha e mensagens. |
Além disso, note que todas as opções acima para AxeDevTools.configure podem ser passadas ao configurar o WebDriver de escolha. Por exemplo:
require 'axe-devtools-capybara'
AxeCapybara.configure do |config|
config.axe_config_path = 'config/my-ruleset.json'
endVeja Também
- Carregando resultados de acessibilidade JSON para o Axe Reports descreve como carregar seus resultados no Axe Reports.
- Obtendo uma chave de API do Axe Reports explica como obter uma chave de API para começar a usar o Axe Reports.
- Criando e Filtrando Relatórios mostra como você pode criar relatórios de acessibilidade em CSV, XML ou HTML a partir dos seus resultados de acessibilidade em JSON. Você também pode filtrar sua saída por gravidade usando esta ferramenta.
- Como Resultados JSON são Armazenados no Disco descreve as convenções de nomenclatura de arquivos para resultados de acessibilidade em JSON.
- Usando o CLI para enviar resultados de acessibilidade para o Axe Developer Hub mostra como você pode enviar seus arquivos de resultados
.jsonpara Axe Developer Hub.
Serviço de Uso
Você pode obter insights sobre as tendências de uso do Axe DevTools dentro da sua organização com o serviço de uso.
Por padrão, o serviço de uso está ativado, e a URL de rastreamento é https://usage.deque.com.
Na API Ruby, use a propriedade de configuração enableTracking descrita abaixo para desativar o rastreamento de uso, em vez da variável de ambiente AXE_TRACK_USAGE. Se seus eventos de uso não chegarem à Deque, defina a URL de rastreamento explicitamente com setTrackingUrl.
Configurando Opções de Serviço de Uso com Configuração do Axe DevTools
Os gems axe-devtools-* permitem configurar o serviço de uso via uma configuração global:
AxeDevTools.configure do |config|
config.setTrackingUrl: 'https://usage.deque.com',
endAs propriedades específicas de configuração do serviço de uso são:
| Atributo | Valor Padrão | Descrição |
|---|---|---|
| enableTracking | true | Opção para habilitar o rastreamento de uso. |
| setTrackingUrl | https://usage.deque.com |
Opção para substituir a URL de rastreamento. |
| equipes | As equipes executando seus testes, como um array de { id: "...", name: "..." } hashes. Veja Equipes. |
Além disso, observe que todas as opções acima para AxeDevTools.configure também podem ser passadas ao configurar o WebDriver de sua escolha. Por exemplo, para o Capybara:
require 'axe-devtools-capybara'
AxeCapybara.configure do |config|
config.enableTracking = false
endEquipes
Você pode registrar o equipes executando seus testes em eventos de uso. Cada equipe é um hash com valores string de id e name. Entradas sem ambos são descartadas, e um array vazio não envia equipes.
Você pode definir equipes em três locais. Se mais de um for definido, o primeiro nesta lista será usado:
-
Para uma única verificação RSpec, a cláusula
for_teams. -
Para toda a execução, a propriedade de configuração
teams:AxeDevTools.configure do |config| config.teams = [{ id: "1", name: "Web" }] end -
A variável de ambiente
AXE_TEAMS, configurada para um array JSON de objetos{ "id": "...", "name": "..." }ou para o caminho de um arquivo JSON contendo um. Se o valor não puder ser lido, a API imprime um aviso e não envia equipes, e a varredura continua.
O gem Cucumber não possui uma opção por verificação, portanto, use a propriedade de configuração teams ou AXE_TEAMS com Cucumber.
Eventos de uso também registram se uma pessoa ou um pipeline automatizado executou os testes. A API registra automation quando uma variável de ambiente comum de CI, como CI, GITHUB_ACTIONS ou JENKINS_URL, é configurada, e human caso contrário. Defina AXE_ACTOR para human ou automation para substituir isso.
Configurando Opções de Serviço de Uso com Variáveis de Ambiente
Além disso, as opções de uso do serviço podem ser configuradas por meio de variáveis de ambiente.
| Nome | Tipo | Pode Sobrescrever | Descrição |
|---|---|---|---|
AXE_DISTINCT_ID |
String | — | Um identificador UUID que permanece o mesmo para o usuário logado (a menos que seja regenerado). Em Ruby, essa variável é chamada de DEQUE_DISTINCT_ID. |
AXE_INCLUDE_TEST_RESULTS |
Boolean | — | Defina como true para incluir os resultados completos do axe-core no objeto testResults de cada evento (o padrão é false). Suportado apenas pelo CLI e pelas APIs do Node.js. |
AXE_METRICS_URL |
String | — | A URL do endpoint de uso REST (o padrão é https://usage.deque.com) |
AXE_TRACK_USAGE |
Boolean | — | Defina como false para desativar o relatório do serviço de uso. O relatório está ativado por padrão. |
AXE_ACTOR |
String | — | Defina como human ou automation para substituir a definição de se os eventos registram uma pessoa ou um pipeline automatizado executando os testes. Por padrão, automation é detectado a partir das variáveis de ambiente comuns de CI. Suportado apenas pelo CLI, pelas APIs do Node.js e pela API Ruby. |
AXE_APPLICATION |
String | false | O aplicativo que foi utilizado para verificar erros de acessibilidade |
AXE_DEV_INSTANCE |
Boolean | true | Indica se este evento é resultante das ações de um desenvolvedor de software. Útil para marcar e posteriormente remover eventos registrados durante o desenvolvimento ou teste. |
AXE_DEPARTMENT |
String | true | O departamento do usuário dentro da organização |
AXE_KEYCLOAK_ID |
String | false | O ID Keycloak do usuário |
AXE_LOGGED_IN |
Boolean | false | Registra se o usuário está logado na aplicação em teste |
AXE_ORGANIZATION |
String | true | A organização do usuário. Para que seu uso apareça nos Relatórios Axe, defina isso para o ID da sua organização (entre em contato com a Deque para obtê-lo). |
AXE_SESSION_ID |
String | false | Um UUID identificando a sessão do usuário |
AXE_TEAMS |
String | false | As equipes executando os testes, como um array JSON de objetos { "id": "...", "name": "..." } ou o caminho para um arquivo JSON que contém um. Um valor passado para a opção --set-teams do CLI, o método setTeams das APIs do Node.js ou a cláusula for_teams ou a propriedade de configuração teams da API Ruby tem precedência. Suportado apenas pelo CLI, pelas APIs do Node.js e pela API Ruby. |
AXE_USER_ID |
String | false | A identidade de um usuário específico, como um endereço de e-mail, nome ou ID de login. Os Relatórios Axe contam usuários únicos a partir deste valor. |
AXE_USER_JOB_ROLE |
String | false | O cargo do usuário |
AXE_USER_STATUS |
String | false | Informações de status que você deseja associar ao usuário |
