Analisar Páginas Usando Arquivos Spec

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 os 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
• Estrutura do Arquivo Spec
• Ações
• Seletores
• Ações Globais
• Processamento em Lote com axe bulk-spec
• Opções

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 para analisar 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

Página

Formato JSON/YAML

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

Ações

As ações são cadeias de texto no actions (ou globalActions) array de um arquivo de especificação. Elas executam tarefas como clicar em botões, preencher formulários, fechar diálogos, esperar por estados da página e realizar 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 todas as páginas do projeto em resposta a alterações 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 recebem um argumento de seletor que identifica um elemento na página. Um seletor pode ser um seletor CSS ou XPath, especificado como uma única cadeia de texto ou uma lista de cadeias.

Para direcionar elementos dentro de iframes, é necessário usar uma lista. Todos os seletores da lista, exceto o último, identificam elementos sucessivos para se 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. <iframe> elementos, 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 subsequente seletor de iframe é relativo ao documento dentro do iframe precedente.

O uso de uma única cadeia de texto (não uma lista) não consegue navegar dentro de 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

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

1. analyze: executar uma análise de acessibilidade
2. change: alterar o valor de um <input>, <textarea>, ou <select> via JavaScript
3. click: clicar em um elemento
4. dismiss: fechar 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

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. Regras disponíveis:

Para informações sobre como incluir ou excluir elementos, consulte a documentação da API axe-core sobre o parâmetro Context.

# 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 combinando várias 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 a 508 regra, 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 change ação altera o valor de um <input>, <textarea>, ou <select> elemento via JavaScript. Use change quando eventos normais do DOM não estão disponíveis.

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

click

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

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

# Click the body element
click "body"

dismiss

A dismiss ação fecha um popup ou modal clicando no 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 qualquer um dos elementos não estiver presente.

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

eval

A 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

A press ação envia um pressionamento de tecla para um elemento (opcionalmente com teclas modificadoras). Para os 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

A 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

A type uma 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

A ação wait aguarda que um elemento atinja um estado especificado ou faz uma pausa por uma duração determinada.

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

Para a duração da pausa, 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

# 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 todas as páginas de um projeto em resposta a mudanças de estado, em vez de serem executadas de forma procedural como ações de página. Atualmente, apenas uma ação global é suportada: dismiss modal.

• As 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 de página, não em uma sequência fixa.
• A ação global dismiss modal aguarda que um modal especificado apareça e o dispensa antes que as ações da 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"

Processamento em Lote com axe bulk-spec

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

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 para stdout durante a execução.

Os resultados são escritos no diretório de saída: um arquivo JSON por analyze ação, além de um arquivo de log listando todos os arquivos de especificação que falharam e a razão para a falha.

Opções

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

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

Especifica a chave da API do Axe Developer Hub. Necessário (junto com --axe-devhub-project-id) para enviar resultados ao Axe Developer Hub. Veja Enviar Resultados ao 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 ao Axe Developer Hub.

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

Especifica a URL do servidor do Axe Developer Hub. Padrão é https://axe.deque.com. Equivalente à variável de ambiente ", "context": "paragraph AXE_DEVHUB_SERVER_URL . Veja ", "context": "paragraph Enviar Resultados para Axe Developer Hub", "context": "link text.", "context": "paragraph

-c, --custom <path>

Especifica um arquivo de conjunto de regras personalizado, substituindo o conjunto de regras padrão.", "context": "paragraph

--descendant-links

Coleta os links de cada página e os adiciona aos resultados. Requer ", "context": "paragraph --verbose.", "context": "paragraph

--dismiss-alerts

Descarta automaticamente ", "context": "paragraph alert(), ", "context": "paragraph confirm()e ", "context": "paragraph prompt() diálogos do navegador antes de escanear.", "context": "paragraph

--enable-tracking <state>

Permite o envio de dados para a biblioteca de métricas.", "context": "paragraph

--filter <type(s)>

Filtra tipos de resultados da saída: ", "context": "paragraph passes, ", "context": "paragraph violations, ", "context": "paragraph incomplete, ", "context": "paragraph inapplicable. Requer ", "context": "paragraph --format csv.", "context": "paragraph

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

Formato(s) do relatório: ", "context": "paragraph html, ", "context": "paragraph junit, ", "context": "paragraph csv, ou uma combinação separada por vírgulas. Padrão: ", "context": "paragraph html.", "context": "paragraph

--no-git-data

Exclui informações de branch e commit do Git ao enviar resultados para o Axe Developer Hub. Veja ", "context": "paragraph Enviar Resultados para Axe Developer Hub", "context": "link text.", "context": "paragraph

--page-name <name>

Executa apenas a página com o nome especificado do arquivo spec ", "context": "paragraph pageList.", "context": "paragraph

--page-source

Adiciona o código fonte HTML escaneado aos resultados. Requer ", "context": "paragraph --verbose.", "context": "paragraph

--page-title

Adiciona o título da página aos resultados. Requer ", "context": "paragraph --verbose.", "context": "paragraph

--remote-proxy <proxy-server>

Roteia o tráfego através do servidor proxy remoto especificado.", "context": "paragraph

--resume-from <name>

Pula todas as páginas antes da página nomeada no arquivo spec ", "context": "paragraph pageList.", "context": "paragraph

--scanned-url

Adiciona a URL base e a URL do escaneamento atual aos resultados detalhados. Somente Chrome. Requer ", "context": "paragraph --verbose.", "context": "paragraph

--set-distinct-id <id>

Substitui o valor do ID distinto.", "context": "paragraph

--set-legacy-mode

Habilita o modo de escaneamento legado ", "context": "paragraph , que será removido na versão 5.0.", "context": "paragraph. Esta é uma opção de última instância. Relatou-se que permite concluir escaneamentos em páginas que substituem ", "context": "paragraph

--set-tracking-url <url>

Filtra o conjunto de regras padrão por tag.", "context": "paragraph

-t, --tags

Define uma string de agente de usuário personalizada para o navegador.", "context": "paragraph

--user-agent

Valida seu arquivo spec sem executá-lo.", "context": "paragraph

--validate

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

-v, --verbose

Para opções adicionais de configuração, veja ", "context": "paragraph

Configurar", "context": "link text Configure.