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 axe spec Comando 

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 todas as páginas do projeto, por exemplo, fechar um banner de cookies ou 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 a serem analisadas. 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

As ações são strings no actions (ou globalActions) array de um arquivo spec. Eles realizam tarefas como clicar em botões, preencher formulários, dispensar diálogos, esperar por estados de 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 executam em sequência em uma página específica. A analyze ação deve ser chamada pelo menos uma vez por página.
  • Ações globais executam 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 sucessivos <iframe> elementos 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 anterior.

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: executar uma análise de acessibilidade
  2. change: mudar o valor de um <input>, <textarea>, ou <select> via JavaScript
  3. click: clicar em um elemento
  4. dismiss: dispensar um popup ou modal
  5. eval: avaliar JavaScript arbitrário
  6. press: pressionar uma tecla (com ou sem modificadores)
  7. select: selecionar uma opção em um <select>
  8. type: digitar em um <input>
  9. wait: esperar por um estado específico ou pausar

analyze

O analyze ação executa uma análise de acessibilidade. Ela 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 o with title variante para distinguir os resultados).

O ruleset parâmetro opcional 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 obter informações sobre como incluir ou excluir elementos, consulte a 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 no envio, excluindo elementos com a classe old-api, usando o 508 conjunto de regras, 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

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

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

click

O click ação 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

O dismiss ação fecha um popup ou modal clicando no botão de fechar. Forneça um seletor CSS para o contêiner modal e outro para o botão de fechar. A ação falha de forma graciosa se qualquer um dos elementos não estiver presente.

note

Esta ação não dispensa alert() ou confirm() ou

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

eval

O eval ação executa JavaScript arbitrário na página. Use-a para manipular o DOM ou realizar 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

O press ação envia uma tecla para um elemento (opcionalmente com teclas modificadoras). Para nomes de teclas suportados, consulte a 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

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

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

O type ação digita uma string em um <input> ou <textarea> elemento. 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

O wait ação espera que um elemento alcance um estado especificado ou aguarda por uma determinada duração.

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

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

Para a duração do sono, valores numéricos são interpretados como milissegundos. As cadeias de caracteres são convertidas usando o ms pacote, 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 executam em todas as páginas de um projeto em resposta a mudanças de estado, em vez de serem executadas proceduralmente como as ações de página. Apenas uma ação global é atualmente suportada: dismiss modal.

  • As ações globais funcionam tanto em modo spec quanto em 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.
  • O dismiss modal ação global aguarda um modal especificado aparecer e o fecha antes que as ações de página continuem.

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 screenshot objeto a um projeto no seu arquivo de especificação. Cada página gera um arquivo PNG nomeado <page-id>-screenshot.png (qualquer / ou \ na página id é substituído por _). Se uma página não tiver id, um é derivado do seu name removendo todos os espaços em branco.

Propriedade Tipo Padrão Descrição
enabled booleano — Obrigatório. Defina como true para habilitar a captura de capturas 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) para 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 busca recursivamente no diretório e em 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 analyze ação, 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 para o 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 para o Axe Developer Hub. Veja Enviar Resultados para o Axe Developer Hub.

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

Especifica o 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 axe.js arquivo alternativo. A maioria dos usuários não precisa desta opção. Ela é destinada a casos de uso avançados, como testes contra 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 o navegador alert(), confirm(), e prompt() diálogos antes da verificação.

--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 analyze ação na lista de ações de cada página. Por padrão, toda página em um arquivo especificado deve incluir pelo menos uma analyze ação; este flag desativa essa verificação, o que é útil quando se executa um fluxo de trabalho que realiza apenas ações sem realizar uma verificação de acessibilidade.

--no-exit

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

--no-git-data

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

--no-html

Impede que o CLI gere um relatório HTML. Use isso junto com --format para controlar quais formatos de relatório são escritos, ou quando você deseja apenas resultados JSON sem um resumo em 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 ações (veja Configurar); este flag ignora todas elas.

--page-name <name>

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

--page-source

Acrescenta o código fonte HTML verificado aos resultados. Requer --verbose.

--page-title

Acrescenta 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 arquivo de especificações pageList.

--scanned-url

Adiciona a URL base e a URL da verificação atual aos resultados detalhados. Apenas para Chrome. Requer --verbose.

--set-distinct-id <id>

Substitui o valor de ID distinto.

--set-legacy-mode

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

important

Esta é uma opção de último recurso. Foi relatado que permite que as verificações sejam concluídas 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 o texto decorativo da saída do CLI. Os resultados são exibidos somente quando --verbose também está ativo. Use isso em scripts ou pipelines de CI onde 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

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

--universal-ruleset <id>

Especifica o ID do conjunto de regras para registrar nos metadados da saída em formato universal. O padrão é wcag2.1. Requer --format universal. Veja a 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 inativa. Uma vez que novas conexões caiam para ou abaixo deste limite, o CLI prossegue com a verificação. Use isso junto com --wait-network-idle-timeout para ajustar quando o CLI é executado em páginas com atividade de rede de fundo 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?