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.
`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:

analyze: executar uma análise de acessibilidade
change: mudar o valor de um <input>, <textarea>, ou <select> via JavaScript
click: clicar em um elemento
dismiss: dispensar um popup ou modal
eval: avaliar JavaScript arbitrário
press: pressionar uma tecla (com ou sem modificadores)
select: selecionar uma opção em um <select>
type: digitar em um <input>
wait: esperar por um estado específico ou pausar

`analyze`

A 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`

A 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`

A 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`

A 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() diálogos nativos confirm() ou

# 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 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`

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 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 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 a duração do sono, valores numéricos são interpretados como milissegundos. As cadeias de caracteres são convertidas usando o ms package — 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 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 de página, não em uma sequência fixa.
A 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"

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 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 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 Axe Developer Hub.

`-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, ou uma combinação separada por vírgulas. Padrão: html.

`--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.

`--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.

`-t, --tags`

Filtra o conjunto de regras padrão por tag.

`--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.

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

Analisar Páginas Usando Arquivos Spec

O axe spec Comando

Estrutura do Arquivo Spec

Exemplo de YAML

Projeto

Página

Formato JSON/YAML

Ações

Exemplo Completo de Ação

Seletores

Exemplo de Seletor de Iframe

Ações de Página

analyze

change

click

dismiss

eval

press

select

type

wait

Ações Globais

Processamento em Lote com axe bulk-spec

Opções

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

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

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

-c, --custom <path>

--descendant-links

--dismiss-alerts

--enable-tracking <state>

--filter <type(s)>

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

--no-git-data

--page-name <name>

--page-source

--page-title

--remote-proxy <proxy-server>

--resume-from <name>

--scanned-url

--set-distinct-id <id>

--set-legacy-mode

--set-tracking-url <url>

-t, --tags

--user-agent

--validate

-v, --verbose

Is this page helpful?

Help us improve this page

Still need help?