Analisar Páginas Usando Arquivos Spec

This page is not available in the language you requested. You have been redirected to the English version of the page.
Link to this page copied to clipboard

Como usar os subcomandos spec e bulk-spec para analisar páginas usando arquivos spec

Not for use with personal data

Um arquivo spec é um arquivo JSON ou YAML que define uma lista de páginas da web e as ações do navegador a serem executadas em cada página antes de analisar problemas de acessibilidade. Use axe spec para executar um único arquivo spec, ou axe bulk-spec para processar um diretório de arquivos spec.

O Comando axe spec

axe spec <spec-file> <output-dir> [options]

O <output-dir> é onde os resultados JSON são salvos. Se omitido, os resultados são salvos no diretório de trabalho atual.

Exemplo de uso:

axe spec ./axe-workflow.yaml ./axe-results --format html

Estrutura do Arquivo Spec

Um arquivo spec define um ou mais projetos, cada um com uma lista de páginas a serem analisadas e ações opcionais a serem realizadas em cada página.

Exemplo de YAML

projects:
  - name: deque.com
    id: deque.com
    metadata:
      products:
        - CLI
      environment:
        - Prod
    globalActions:
      - dismiss modal "#CybotCookiebotDialog" with close button "#CybotCookiebotDialogBodyButtonAccept"
    pageList:
      - name: Deque search
        url: https://www.deque.com/
        actions:
          - type "axe" into element "#searchform input"
          - click element "#searchform button"
          - wait for element ".m-search-page" to be found
          - analyze
      - name: Axe Dashboard
        url: https://axe.deque.com/

Projeto

Propriedade Tipo Descrição
name string Nome de exibição único do projeto.
id string Identificador único do projeto.
metadata objeto Opcional. Metadados arbitrários para seu caso de uso (por exemplo, nome do produto, ambiente).
globalActions array Opcional. Ações que respondem a mudanças de estado em cada página do projeto, por exemplo, fechando um banner de cookies ou um pop-up de pesquisa. Veja Ações Globais.
screenshot objeto Opcional. Captura uma captura de tela de cada página após a análise. Veja Captura de Capturas de Tela.
pageList array Lista de páginas para analisar. Veja Página.

Página

Propriedade Tipo Descrição
name string Nome de exibição da página.
url string URL da página.
actions array Opcional. Ações a serem realizadas na página antes ou depois da análise. Veja Ações.

Formato JSON/YAML

Arquivos spec podem ser escritos em YAML ou JSON. A tabela a seguir mostra os mesmos valores em cada formato. Note que em JSON, strings de ação que contêm aspas duplas devem escapá-las com uma barra invertida.

YAML JSON
type "axe" into element "#searchform input" "type \"axe\" into element \"#searchform input\""
dismiss modal "#CybotCookiebotDialog" with close button "#CybotCookiebotDialogBodyButtonAccept" "dismiss modal \"#CybotCookiebotDialog\" with close button \"#CybotCookiebotDialogBodyButtonAccept\""

Ações

Ações são strings no array actions (ou globalActions) de um arquivo spec. Elas realizam tarefas como clicar em botões, preencher formulários, fechar diálogos, esperar por estados da página e executar análises de acessibilidade. As ações são executadas na ordem listada.

Existem dois tipos de ações:

  • Ações de página são executadas em sequência em uma página específica. A ação analyze deve ser chamada pelo menos uma vez por página.
  • Ações globais são executadas em cada página do projeto em resposta a mudanças de estado. Veja Ações Globais.

Exemplo Completo de Ação

O exemplo a seguir faz login na Deque University e analisa o painel:

projects:
  - name: Deque University login flow
    id: deque-university-login-flow
    pageList:
      - name: homepage
        url: https://dequeuniversity.com/
        actions:
          - click element ".loginLink"
          - wait for element ".loginUsername" to be found
          - type "user@example.com" into element ".loginUsername"
          - type "secretpassword" into element "#loginPassword"
          - click element "input[type=submit]"
          - wait for element ".logoutLink" to be found
          - analyze page

Seletores

Muitas ações requerem um argumento seletor que identifica um elemento na página. Um seletor pode ser um seletor CSS ou seletor XPath, especificado como uma única string ou uma lista de strings.

Para direcionar elementos dentro de iframes: você deve usar uma lista. Todos os seletores na lista, exceto o último, identificam elementos <iframe> sucessivos para navegar, e devem ser seletores CSS. O último seletor na lista identifica o elemento alvo e pode ser CSS ou XPath. Cada seletor na lista é avaliado em relação ao contexto do documento estabelecido pela entrada anterior: o primeiro seletor é relativo ao documento raiz, e cada seletor de iframe subsequente é relativo ao documento dentro do iframe precedente.

Usar uma única string (não uma lista) não pode navegar em iframes.

Exemplo de Seletor de Iframe

Considere esta estrutura HTML:

<body>
  <!-- root document -->
  <iframe class="payment-widget">
    <!-- document inside the payment-widget iframe -->
    <div class="form-wrapper">
      <iframe id="card-fields">
        <!-- document inside the card-fields iframe -->
        <form>
          <input type="text" name="card-number" class="card-input">
        </form>
      </iframe>
    </div>
  </iframe>
</body>

Para clicar na entrada do número do cartão, use uma lista de seletores. Cada seletor CSS é avaliado dentro do contexto do documento estabelecido pela entrada anterior:

# "iframe.payment-widget" is evaluated in the root document
# "#card-fields" is evaluated in the document inside iframe.payment-widget
# ".card-input" is evaluated in the document inside #card-fields
click element [ "iframe.payment-widget", "#card-fields", ".card-input" ]

Para usar XPath para o elemento alvo final (os seletores de iframe ainda devem ser CSS):

click element [ "iframe.payment-widget", "#card-fields", "//input[@name='card-number']" ]

Em JSON:

"click element [\"iframe.payment-widget\", \"#card-fields\", \".card-input\"]"

Ações de Página

O CLI suporta nove ações de página:

  1. analyze: execute uma análise de acessibilidade
  2. change: altere o valor de um <input>, <textarea> ou <select> via JavaScript
  3. click: clique em um elemento
  4. dismiss: feche um pop-up ou modal
  5. eval: avalie JavaScript arbitrário
  6. press: pressione uma tecla (com ou sem modificadores)
  7. select: selecione uma opção em um <select>
  8. type: digite em um <input>
  9. wait: espere para um estado específico ou durma

analyze

A ação analyze executa uma análise de acessibilidade. Deve ser chamada pelo menos uma vez por página. Você pode chamá-la várias vezes para analisar uma página em diferentes pontos de um fluxo de trabalho (use a variante with title para distinguir os resultados).

O parâmetro opcional ruleset especifica qual conjunto de regras usar. O padrão é WCAG 2.1 AA. Conjuntos de regras disponíveis:

ID do Conjunto de Regras Padrão
wcag2 WCAG 2.0 AA
wcag2.1 WCAG 2.1 AA (padrão)
wcag2.2 WCAG 2.2 AA
wcag2aaa WCAG 2.0 AAA
wcag2.1aaa WCAG 2.1 AAA
wcag2.2aaa WCAG 2.2 AAA
508 Seção 508
ttv5 Teste Confiável v5
en301549 EN 301 549
rgaav4 RGAA v4

Para informações sobre inclusão ou exclusão de elementos, veja documentação da API axe-core sobre o parâmetro Contexto.

# Analyze using the WCAG 2.1 AA ruleset (default) — all three forms are equivalent
analyze
analyze the page
analyze page

# Analyze using the Section 508 ruleset
analyze page with ruleset "508"

# Analyze with a custom title (useful when analyzing a page multiple times)
analyze the page with title "after login"

# Analyze only a specific element
analyze only element "#main-content"

# Analyze only specific elements
analyze only element "#idOfElement" and element ".classToAnalyze"

# Analyze everything except images that are immediate children of paragraphs
analyze the page excluding element "p > img"

# Analyze everything except elements inside a frame with a specific class
analyze the page excluding element [ ".classOfFrameToExclude", "#idOfElement" ]

# Save results to a specific directory
analyze the page and save in "./homepage-team/"

# Save a copy to an additional directory while also saving to the default location
analyze the page and save a copy in "./homepage-team/"

# Use the axe-core library's built-in default ruleset
analyze the page with the source default ruleset

Exemplo de combinação de múltiplas opções: Analise apenas imagens dentro de elementos com a classe third-party e formulários que não são validados na submissão, excluindo elementos com a classe old-api, usando o conjunto de regras 508, com um título personalizado e um local de salvamento personalizado.

analyze only element [ ".third-party", "img"] and element "form[novalidate]" excluding element ".old-api" with ruleset "508" with title "What is this testing" and save in "Results for Some test"

Em JSON:

"analyze only element [\".third-party\", \"img\"] and element \"form[novalidate]\" excluding element \".old-api\" with ruleset \"508\" with title \"What is this testing\" and save in \"Results for Some test\""

change

A ação change altera o valor de um elemento <input>, <textarea> ou <select> via JavaScript. Use change quando eventos DOM normais não estiverem disponíveis.

# Change the value of an input
change the value of "input[name=song]" to "too many puppies"

click

A ação click clica no primeiro elemento que corresponde ao seletor fornecido.

# Click a button by class selector
click element ".myButton"

# Click the body element
click "body"

dismiss

A ação dismiss fecha um pop-up ou modal clicando em seu botão de fechar. Forneça um seletor CSS para o contêiner do modal e outro para o botão de fechar. A ação falha graciosamente se algum dos elementos não estiver presente.

note

Essa ação não fecha diálogos nativos de alert() ou confirm().

# Dismiss a modal using separate selectors for the container and close button
dismiss modal ".myModal" with close button ".myModal .close"

eval

A ação eval executa JavaScript arbitrário na página. Use-a para manipular o DOM ou executar ações personalizadas.

# Change the page title
eval "document.title = 'hello world'"

# Scroll an element into view
eval "document.querySelector('.someElement').scrollIntoView()"

# Scroll to the bottom of the page
eval "window.scrollTo(0, document.body.scrollHeight)"

press

A ação press envia uma tecla para um elemento (opcionalmente com teclas modificadoras). Para nomes de teclas suportados, veja documentação de teclas do Selenium.

# Press H on the body element
press "H" on "body"

# Press Shift+Tab on the navigation element
press "shift+tab" on element ".navigation"

# Press Shift+Control+7 on an element
press "shift+control+7" on element ".foo"

select

A ação select seleciona uma <option> de um elemento <select> por seu texto visível (não por seu atributo value).

Dado este HTML:

<select class="mySelect">
  <option></option>
  <option value="1">dog</option>
  <option value="2">cat</option>
  <option value="3">fish</option>
</select>
# Select by visible option text
select the "dog" option in ".mySelect"
select the "cat" option in element ".mySelect"

type

A ação type digita uma string em um elemento <input> ou <textarea>. Use-a para preencher formulários e campos de busca.

# Type into an email input
type "user@example.com" into element "input[type=email]"

# Type into a textarea
type "hello world" into "textarea.Message"

# Type with a delay between keystrokes to simulate human typing
type "sloth" into "input[type=search]" with a 150ms key delay

wait

A ação wait espera que um elemento atinja um estado especificado ou dorme por uma duração especificada.

Estados de elementos suportados: visible, hidden, selected, enabled, disabled, found.

Para esperas de estado de elemento, a ação tenta novamente até 3 vezes vezes por padrão (4 tentativas no total) antes de falhar. Para esperar mais por um elemento de carregamento lento, adicione with <n> retries para aumentar o número de tentativas.

Para duração do sono, valores numéricos são interpretados como milissegundos. Strings são convertidas usando o pacote ms, por exemplo: 1m = 60.000 ms, 1s = 1.000 ms.

# Wait for an element to appear
wait for element ".myElement" to be found

# Wait for an element to become hidden
wait for element ".myElement" to be hidden

# Allow more retries for a slow-loading element
wait for element ".myElement" to be found with 9 retries

# Sleep for 1 minute
wait for 1m

# Sleep for 1 second
wait for 1s

# Sleep for 30 milliseconds
wait for 30

Ações Globais

Ações globais são executadas em cada página de um projeto em resposta a mudanças de estado, em vez de rodarem proceduralmente como ações de página. Apenas uma ação global é atualmente suportada: dismiss modal.

  • Ações globais funcionam tanto no modo spec quanto no modo URI sem cabeça.
  • As ações globais não são procedurais: elas são acionadas em resposta a eventos da página, não em uma sequência fixa.
  • A ação global dismiss modal espera por um modal especificado aparecer e fecha-o antes das ações de página continuarem.

Adicione ações globais a um projeto após name/id e antes de pageList:

projects:
  - id: demo
    name: CLI demo
    globalActions:
      - dismiss modal "#__next .survey" with close button ".survey button.close"
    pageList:
      - name: homepage
        url: https://dequelabs.github.io/aget-demo-site
      - name: popup
        url: https://dequelabs.github.io/aget-demo-site
        actions:
          - wait for element "#__next header nav" to be visible
          - click element "#__next header nav a[href*=popup]"
          - wait for element ".content button" to be found
          - analyze with title "before popup"
          - click element ".content button"
          - analyze with title "with popup"
          - dismiss modal ".ReactModal__Content" with close button ".ReactModal__Content .close"
          - analyze with title "after popup"
      - name: contact
        url: https://dequelabs.github.io/aget-demo-site/contact
        actions:
          - analyze with title "form disabled"
          - wait for element "#__next .toggle" to be found
          - click element ".toggle button"
          - wait for element "input[name=name]" to be enabled
          - analyze with title "form enabled"
          - type "stephen" into element "input[name=name]"
          - type "555-555-5555" into element "input[name=phone]"
          - type "stephen@deque.com" into element "input[name=email]"
          - type "hello world" into element "textarea[name=message]"
          - click element "button[type=submit]"
          - wait for element ".thanks" to be found
          - analyze with title "thanks message"

Captura de Capturas de Tela

Para capturar uma captura de tela de cada página após a análise, adicione um objeto screenshot a um projeto no seu arquivo spec. Cada página gera um arquivo PNG nomeado <page-id>-screenshot.png (qualquer / ou \ no id da página é substituído por _). Se uma página não tiver id, um é derivado de seu name removendo todos os espaços em branco.

Propriedade Tipo Padrão Descrição
enabled booleano — Obrigatório. Defina como true para ativar a captura de tela. Funciona com todos os navegadores suportados.
fullPage booleano false Captura a página completa rolável usando o Chrome DevTools Protocol. Requer Chrome ou Chromium; outros navegadores fazem uma captura de tela da janela de visualização com um aviso.
boundingBoxes booleano false Adiciona coordenadas da caixa delimitadora (x, y, width e height) a cada nó de violação nos resultados do Axe, registrando onde o elemento aparece na captura de tela.
dir string <output-dir>/<project-id>/ Diretório onde os arquivos PNG de captura de tela são gravados.

Quando você executa axe spec com --verbose, cada resultado também inclui um campo screenshotPath com o caminho completo para o arquivo de captura de tela dessa página.

projects:
  - name: My App
    id: my-app
    screenshot:
      enabled: true
      fullPage: true
      boundingBoxes: true
      dir: ./screenshots
    pageList:
      - name: Home
        url: https://example.com/

Processamento em Lote com axe bulk-spec

Para processar múltiplos arquivos spec em uma única execução, use axe bulk-spec com um diretório contendo arquivos spec. O CLI pesquisa recursivamente o diretório e seus subdiretórios por arquivos spec.

axe bulk-spec <spec-files-directory> <output-directory>

O <output-directory> é opcional — se omitido, os resultados são salvos no diretório de trabalho atual.

Atualizações de progresso são impressas em stdout durante a execução.

Os resultados são gravados no diretório de saída: um arquivo JSON por ação analyze, além de um arquivo de log listando quaisquer arquivos spec que falharam e o motivo da falha.

Opções

As seguintes opções estão disponíveis para axe spec:

--axe-devhub-api-key <api-key>

Especifica a chave de API do Axe Developer Hub. Necessário (junto com --axe-devhub-project-id) para enviar resultados ao Axe Developer Hub. Veja Enviar Resultados para o Axe Developer Hub.

--axe-devhub-project-id <project-id>

Especifica o ID do projeto do Axe Developer Hub. Necessário (junto com --axe-devhub-api-key) para enviar resultados ao Axe Developer Hub. Veja Enviar Resultados para o Axe Developer Hub.

--axe-devhub-server-url <url>

Especifica a URL do servidor do Axe Developer Hub. O padrão é https://axe.deque.com. Equivalente à variável de ambiente AXE_DEVHUB_SERVER_URL. Veja Enviar Resultados para o Axe Developer Hub.

-a, --axe-source <path>

Caminho para um arquivo axe.js alternativo. A maioria dos usuários não precisa dessa opção. É destinado a casos de uso avançados, como testes com uma versão específica ou corrigida do axe-core.

--chrome-options [options]

Passa uma lista de switches de linha de comando do Chrome separada por vírgulas para o ChromeDriver. Use isso para habilitar recursos do navegador ou contornar restrições em ambientes específicos, por exemplo, em ambientes de CI conteinerizados onde o sandbox deve ser desabilitado.

axe spec workflow.yml --chrome-options="no-sandbox,disable-gpu"

-c, --custom <path>

Especifica um arquivo de conjunto de regras personalizado, substituindo o conjunto de regras padrão.

--descendant-links

Coleta os links de cada página e os anexa aos resultados. Requer --verbose.

--dismiss-alerts

Descarta automaticamente diálogos de navegador alert(), confirm() e prompt() antes da varredura.

--enable-tracking <state>

Permite enviar dados para a biblioteca de métricas.

--filter <type(s)>

Filtra tipos de resultado da saída: passes, violations, incomplete, inapplicable. Requer --format csv.

-f, --format <type(s)>

Formato(s) do relatório: html, junit, csv, universal, ou uma combinação separada por vírgulas. Padrão: html. Veja --universal-ruleset e --universal-best-practices para opções que se aplicam ao usar universal.

--no-analyze

Remove a exigência de uma ação analyze na lista de ações de cada página. Por padrão, toda página em um arquivo de especificação deve incluir pelo menos uma ação analyze; este sinalizador desativa essa verificação, o que é útil ao executar um fluxo de trabalho que realiza apenas ações sem executar uma varredura de acessibilidade.

--no-exit

Força o CLI a sair com o código 0 mesmo quando violações são encontradas. Por padrão, axe spec sai com o código 1 se violações forem detectadas. Use isso quando quiser coletar resultados sem falhar a construção CI.

--no-git-data

Exclui informações de ramo e commit do Git ao enviar resultados ao Axe Developer Hub. Veja Enviar Resultados para o Axe Developer Hub.

--no-html

Impede o CLI de gerar um relatório HTML. Use isso junto com --format para controlar quais formatos de relatório são gravados, ou quando você deseja apenas resultados JSON sem um resumo HTML.

--no-reports

Impede que o CLI gere qualquer arquivo de relatório. Os resultados ainda são coletados e exibidos no terminal, mas nada é gravado no disco. Útil para verificações rápidas onde arquivos de saída não são necessários.

--no-wait

Desativa a pausa automática entre ações do fluxo de trabalho. Por padrão, as pausas configuradas com --post-get-pause, --post-script-pause e --post-analyze-pause se aplicam entre as ações (veja Configurar); este sinalizador as ignora.

--page-name <name>

Executa apenas a página com o nome especificado a partir do pageList do arquivo de especificação.

--page-source

Anexa o código-fonte HTML escaneado aos resultados. Requer --verbose.

--page-title

Anexa o título da página aos resultados. Requer --verbose.

--remote-proxy <proxy-server>

Redireciona o tráfego através do servidor proxy remoto especificado.

--resume-from <name>

Pula todas as páginas antes da página nomeada no pageList do arquivo de especificação.

--scanned-url

Adiciona a URL base e a URL de varredura atual aos resultados detalhados. Somente para Chrome. Requer --verbose.

--set-distinct-id <id>

Substitui o valor de ID distinto.

--set-legacy-mode

Habilita o modo de verificação legado obsoleto, que será removido na versão 5.0.

important

Esta é uma opção de último recurso. Foi relatado que permite completar escaneamentos em páginas que substituem window.open(), uma prática desencorajada.

--set-tracking-url <url>

Substitui o URL para onde os dados de métricas são enviados.

--silent-mode

Suprime todo texto decorativo da saída do CLI. Resultados são exibidos apenas quando --verbose também está ativo. Use isso em scripts ou pipelines CI onde você deseja uma saída limpa sem banners de progresso ou mensagens de status.

-t, --tags

Filtra o conjunto de regras padrão por tag.

--universal-best-practices

Registra bestPracticesEnabled=true nos metadados da saída em formato universal. Requer --format universal.

--universal-ruleset <id>

Especifica o ID do conjunto de regras a ser registrado nos metadados da saída em formato universal. O padrão é wcag2.1. Requer --format universal. Veja o tabela de regras para valores válidos.

--user-agent

Define uma string de agente usuário personalizada para o navegador.

--validate

Valida seu arquivo de especificações sem executá-lo.

-v, --verbose

Inclui saída adicional: resultados Axe e metadados como nome da ferramenta, versão e ambiente.

--wait-network-idle-new-connections [number]

O número de novas conexões de rede que podem ser estabelecidas antes que a rede seja considerada ociosa. Uma vez que novas conexões caiam abaixo ou atinjam esse limite, o CLI prossegue com a varredura. Use junto com --wait-network-idle-timeout para ajustar quando o CLI é executado em páginas com atividade de rede em segundo plano em andamento.

--wait-network-idle-open-connections [number]

O número de conexões de rede abertas que podem permanecer antes que a rede seja considerada inativa. Quando conexões abertas caem para ou abaixo deste limite, o CLI prossegue com a verificação.

--wait-network-idle-polling-every [ms]

O intervalo em milissegundos em que o CLI verifica se a rede se tornou inativa. Reduza este valor para uma detecção mais rápida ao custo de um maior uso de CPU.

--wait-network-idle-timeout [ms]

O tempo máximo em milissegundos para esperar que a atividade de rede se estabilize antes de iniciar a verificação. Após o carregamento da página, o CLI monitora conexões de rede ativas e espera até que a contagem de conexões alcance o limite configurado. Se o tempo limite expirar antes que a rede fique inativa, o CLI prossegue com a verificação de qualquer forma.

Para opções de configuração adicionais, veja Configurar.

Is this page helpful?

Help us improve this page

Still need help?