Referência de API para a versão JavaScript e TypeScript do Watcher

Este guia de referência descreve as APIs fornecidas pelo @axe-core/watcher pacote (também referido como Axe Watcher ou simplesmente Watcher) para JavaScript e TypeScript.

AxeConfiguration Interface

A propriedade axe (um parâmetro passado para as funções de configuração) é o meio usual de alterar seu AxeConfiguration para Axe Watcher configurar o teste de acessibilidade. As seguintes propriedades estão contidas em AxeConfiguration:

apiKey

(Obrigatório) O apiKey valor é uma das duas propriedades (apiKey e projectId) que devem ser definidas no seu AxeConfiguration. Você pode obter o valor a partir da Página de Gerenciamento de Chaves API .

autoAnalyze

(Opcional) Defina este valor para false para impedir que as páginas sejam analisadas automaticamente. Para mais informações sobre o modo manual, veja Controle Seus Escaneamentos.

buildID

(Opcional) A buildID propriedade, quando não é null, permite que executores de teste paralelos gerem resultados que aparecem como uma única execução de teste no Developer Hub do axe. No caso de execuções paralelas de teste, cada executor de teste deve compartilhar a mesma buildID string não nula, o que faz com que cada execução de teste concatene seus resultados com os resultados existentes para o mesmo buildID e o SHA do commit Git. No entanto, quando buildID é null, múltiplas execuções de teste **sobrescrevem** resultados existentes que possuem o mesmo SHA do commit Git.

Veja Executando Testes em Paralelo para mais informações sobre como usar buildID com vários provedores de integração contínua.

configurationOverrides

(Opcional) Substitui valores definidos na configuração global. Veja a Interface de Sobrescrita de Configuração para mais informações.

excludeUrlPatterns

(Opcional) Impede que qualquer URL que corresponda a qualquer um dos padrões minimatch no excludeUrlPatterns array seja analisado.

axe: {
  excludeUrlPatterns: [ 'https://*.example.com/**', 'https://example.org/**' ]
}

Em Excluir URLs da Análise você pode encontrar uma tabela de URLs e padrões de exemplo para verificar correspondências.

git

(Opcional) Controla como o Watcher coleta metadados do Git para a execução atual do teste. Aceita um dos três valores:

• true (padrão): Watcher coleta automaticamente informações do Git (ramo, SHA do commit, autor e outros campos) usando o binário local do Git.
• false: Desativa toda a coleta de metadados do Git. Use isso ao executar em ambientes sem Git ou quando a coleta de dados do Git não for necessária.
• Um GitConfig objeto: Fornece metadados explícitos do Git e ignora completamente a auto-detecção. Quaisquer campos que você omitir serão definidos como padrão para null. Use isso quando seus testes forem executados em um repositório separado do repositório sob teste, ou em ambientes CI onde a auto-detecção do Git é pouco confiável.

Veja Fornecendo Metadados do Git para mais informações.

O GitConfig objeto possui os seguintes campos opcionais:

Exemplo usando variáveis de ambiente de CI para fornecer metadados explícitos do Git:

axe: {
  apiKey: process.env.AXE_DEVELOPER_HUB_API_KEY,
  projectId: '<your-project-id>',
  git: {
    commitSha: process.env.GIT_COMMIT,
    branch: process.env.GIT_BRANCH,
    defaultBranch: 'main'
  }
}

projectId

(Obrigatório) Especifica o ID do projeto que receberá os resultados de acessibilidade do Watcher. O seu ID de projeto é mostrado junto com as instruções ao criar um novo projeto, e você também pode obtê-lo na página de Projetos do Axe Developer Hub .

runContext

(Opcional) Permite escolher quais elementos serão incluídos e excluídos da análise de acessibilidade da sua página.

O valor de runContext pode ser:

1. Um único seletor CSS para elementos a serem incluídos na análise:

   axe: {
     runContext: '.main'
   }

2. Um array de seletores CSS para elementos a serem incluídos na análise:

   axe: {
     runContext: [ '.main', '.text-block' ]
   }

3. Um objeto de contexto contendo include e exclude propriedades (como mostrado no exemplo acima). Você pode especificar include ou exclude ou ambos. Cada include ou exclude pode ser um único seletor CSS ou um array de seletores CSS:

   axe: {
     runContext: {
       include: '.main',
       exclude: '.ad-section'
     }
   }

Mais detalhes estão disponíveis na Documentação do Contexto do axe-core.

runOptions

(Opcional) O runOptions objeto permite o seguinte subconjunto de propriedades do tipo Options do axe-core:

• ancestry: O padrão é false. Se true, os seletores CSS retornados incluem os elementos ancestrais dos elementos retornados.

  important

  Se sua página usa IDs ou classes dinâmicas (IDs ou classes de elementos que mudam sempre que a página é recarregada), você deve especificar ancestry como true para que o Axe Developer Hub possa detectar e rastrear adequadamente se os problemas de acessibilidade são duplicados porque, por padrão, o Axe Developer Hub espera que os IDs e as classes dos elementos permaneçam os mesmos entre as execuções de teste.

  Quando ancestry está true, o Axe Developer Hub usa a posição do elemento dentro da árvore DOM para localizar o mesmo elemento entre as execuções de teste.

  O exemplo a seguir mostra um seletor quando ancestry está false para um elemento iframe com um ID de *main-iframe* (<iframe id="main-iframe" ...>):

  iframe#main-iframe

  Se ancestry está true, o seletor incluiria todo o caminho desde o elemento raiz, e não há IDs ou classes especificados:

  html > body > div:nth-child(20) > div:nth-child(1) > div > div > ul > li:nth-child(1) > div > span > iframe

• runOnly: Isso permite que você limite quais regras são executadas especificando nomes ou tags. Veja runOnly abaixo para mais informações.

• rules: Ative ou desative regras usando a propriedade enabled . Veja rules abaixo para mais informações.

O exemplo a seguir mostra um exemplo de runOptions:

axe: {
  runOptions: {
    ancestry: true,
    runOnly: {
      type: 'tag',
      values: [ 'wcag2a' ]
    },
    rules: {
      'ruleId1': { enabled: false },
      'ruleId2': { enabled: false }
    }
  }
}

runOnly

O valor runOnly (parte do objeto runOptions ) pode ser um dos seguintes:

1. Uma string representando o ID da regra que você gostaria de usar para análise de acessibilidade:

   axe: {
     runOptions: {
       runOnly: 'ruleId'
     }
   }

2. Um array de strings representando os IDs das regras que você gostaria de usar:

   axe: {
     runOptions: {
       runOnly: [ 'ruleId1', 'ruleId2' ]
     }
   }

3. Um objeto com type e values propriedades. O type valor é uma string que pode ser rule, rules, tag, ou tags. A values propriedade deve ser uma matriz de strings que representa a(s) regra(s) ou etiqueta(s) que você gostaria de usar para a análise de acessibilidade. O exemplo a seguir mostra o uso do runOnly objeto para limitar o teste de acessibilidade às regras marcadas como wcag2a:

   axe: {
     runOptions: {
       runOnly: {
         type: 'tag',
         values: [ 'wcag2a' ]
       }
     }  
   }

• Para mais exemplos de uso de runOnly (com axe-core), consulte Exemplos do Parâmetro de Opções
• Para mais informações sobre os valores de etiqueta disponíveis, consulte Etiquetas do axe-core.
• Para informações sobre as regras, IDs de regras, e etiquetas, consulte Descrições das Regras

rules

O rules valor (no runOptions objeto) permite que você ative (enabled: true) ou desative (enabled: false) regras específicas durante a análise, como mostrado abaixo:

axe: {
  runOptions: {
    rules: {
      'ruleId1': { enabled: false },
      'ruleId2': { enabled: false }
    }
  }
}

sessionId

(Opcional) A sessionId propriedade foi descontinuada e não deve ser usada. Consulte buildID acima.

testingTypes

(Opcional) A testingTypes propriedade é uma matriz de strings para uso com o Cypress para especificar o teste de componente ou e2e (end-to-end) (ou ambos).

axe: {
  testingTypes: ['e2e', 'component']
}

timeout

(Opcional) O timeout objeto (do tipo Timeouts) em AxeConfiguration define os valores de timeout em milissegundos para os métodos do controlador respectivos (ou comandos customizados para o Cypress). (Veja as Classes de Controladores para informações sobre as classes de controladores e os Comentários Customizados do Cypress para informações sobre comandos customizados do Cypress.) Quando um timeout expira, o teste falha com uma mensagem indicando que o tempo limite foi excedido. Você pode aumentar o tempo limite para evitar o erro.

Este exemplo define o timeout para analyze 8 segundos, flush para 15 segundos, start para 10 segundos, e stop para 10 segundos. (Os valores padrão são mostrados na tabela sob Timeouts Interface.)

axe: {
  timeout: {
    analyze: 8000
    flush: 15000,
    start: 10000,
    stop: 10000,
  }
}

Funções de Configuração

As funções de configuração fornecidas pelo Watcher permitem que você modifique sua configuração para o framework de teste especificado, bem como adapte a forma como você deseja executar o Watcher para atender às suas necessidades. Consulte a Interface de Configuração do Axe para mais informações.

cypressConfig

Cria uma configuração para o Cypress.

cypressConfig(config: Cypress.ConfigOptions & Configuration): Cypress.ConfigOptions

cypressConfig Parâmetros

• config: Cypress.ConfigOptions & Configuration

  Tipo de interseção de Cypress.ConfigOptions e Configuration.

**Retorna**: Cypress.ConfigOptions

playwrightConfig

Cria uma configuração para o Playwright.

playwrightConfig(opts: Configuration & LaunchOptions): LaunchOptions

playwrightConfig Parâmetros

• opts: Configuration & LaunchOptions

  Tipo de interseção de LaunchOptions e Configuration.

**Retorna**: LaunchOptions

playwrightTest

Cria uma configuração para o Playwright Test.

playwrightTest(options: Options): ReturnValue

playwrightTest Parâmetros

• options: Options

  Options é um tipo de interseção de Configuration e LaunchOptions.

**Retorna**: ReturnValue

puppeteerConfig

Cria uma configuração para o Puppeteer.

puppeteerConfig(opts: Configuration & LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions): Options

puppeteerConfig Parâmetros

• opts: Configuration & LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions

  Tipo de interseção de LaunchOptions, BrowserLaunchArgumentOptions, BrowserConnectOptions, e Configuration.

**Retorna**: Options

wdioConfig

Cria uma configuração do WebdriverIO.

wdioConfig({ axe, ...options}: Options): RemoteOptions

wdioConfig Parâmetros

• arg: Options

  Options é um tipo de interseção de RemoteOptions e Configuration.

**Retorna**: RemoteOptions

wdioTestRunner

Cria uma configuração do WebdriverIO Testrunner.

wdioTestRunner(...params: unknown[]): Options.Testrunner

wdioTestRunner Parâmetros

• params: unknown[]

  O params valor é um dos seguintes:

  1. Um array contendo um valor, que é um tipo de interseção de Options.Testrunner e Configuration.
  2. Um array onde o primeiro valor é um AxeConfiguration e o segundo valor é um Options.Testrunner.

Retorna: Options.Testrunner

webdriverConfig

Cria uma configuração Selenium WebDriver.

webdriverConfig(arg: WebDriverArgs): Options

webdriverConfig Parâmetros

• arg: WebDriverArgs

  Um Configuration estendido para incluir um membro Selenium WebDriver Options .

Retorna: Options

Configuration Interface

A Configuration interface é usada com as funções de configuração e contém uma propriedade:

Todas as funções de configuração usam essa axe propriedade para permitir que você configure o Watcher e configure seus testes de acessibilidade. Veja a próxima seção, Interface AxeConfiguration, para mais informações.

ConfigurationOverrides Interface

A ConfigurationOverrides interface permite que você sobrescreva as configurações globais da sua organização para execuções de testes individuais. Esta propriedade deve ser usada de acordo com as permissões definidas na configuração global do seu empreendimento.

accessibilityStandard

Define o padrão de acessibilidade a ser testado. Opções disponíveis:

• „All“ - Testa contra todos os padrões disponíveis
• „WCAG 2.2 AAA“
• „WCAG 2.2 AA“
• „WCAG 2.2 A“
• „WCAG 2.1 AAA“
• „WCAG 2.1 AA“
• „WCAG 2.1 A“
• „WCAG 2.0 AAA“
• „WCAG 2.0 AA“
• „WCAG 2.0 A“
• „Trusted Tester v5“
• „EN 301 549“
• „RGAAv4“ - RGAA versão 4 (padrão de acessibilidade francês; requer axe-core 4.11.0 ou posterior)

Sua organização deve permitir a substituição desta configuração na configuração global, e o padrão selecionado deve estar entre as opções permitidas.

axeCoreVersion

Especifica qual versão do axe-core usar para teste. As opções disponíveis incluem:

• „latest“ - Última versão suportada atualmente incluída com o Axe Watcher
• Versões específicas a partir da 4.4.0 e posteriores (por exemplo, „4.10.2“, „4.9.1“, etc.)

Sua organização deve permitir a substituição desta configuração na configuração global, e a versão selecionada deve estar entre as opções permitidas.

bestPractices

Habilita ou desabilita regras de melhores práticas para a execução do teste. As melhores práticas melhoram a acessibilidade, mas não fazem parte dos padrões formais. Sua organização deve permitir a substituição desta configuração para que ela entre em vigor.

experimentalRules

Habilita ou desabilita regras experimentais para a execução do teste. As regras experimentais ainda estão em desenvolvimento e podem produzir falsos positivos. Sua organização deve permitir a substituição desta configuração na configuração global para que ela entre em vigor.

Controller Classes

As seguintes classes estendem a Controller classe abstrata para permitir que você controle manualmente a análise de acessibilidade das páginas do seu site.

Controller

abstract class Controller

A Controller classe abstrata contém os métodos para controlar a análise da página. Cada uma das classes concretas estende esta classe, então os seguintes métodos estão disponíveis em todas as classes concretas.

analyze

analyze(): Promise<void>

Analisa a página atual em busca de erros de acessibilidade. Você chama este método depois de configurar uma página da web para análise (como inserir valores em um formulário) e desativar a análise automática usando o stop método ou definindo autoAnalyze para false.

analyze Retorna

Promise<void>

analyze Comando equivalente do Cypress

cy.axeWatcherAnalyze()

flush

flush(): Promise<void>

Envia todos os resultados da varredura de acessibilidade para o Axe Developer Hub. Deve ser chamado ao final da execução do teste para garantir que os resultados tenham sido enviados aos servidores do Axe Developer Hub da Deque.

flush Retorna

Promise<void>

flush Comando equivalente do Cypress

cy.axeWatcherFlush()

start

start(): Promise<void>

Retoma a análise automática de páginas da web. Você chama este método quando deseja retomar a análise automática de páginas da web em busca de erros de acessibilidade.

start Retorna

Promise<void>

start Comando equivalente do Cypress

cy.axeWatcherStart()

stop

stop(): Promise<void>

Interrompe a análise automática de páginas da web. Após chamar o stop método, você pode realizar qualquer configuração adicional que sua página da web possa exigir e então chamar o analyze método para verificar a página em busca de erros de acessibilidade.

stop Retorna

Promise<void>

stop Comando equivalente do Cypress

cy.axeWatcherStop()

PlaywrightController

A PlaywrightController classe permite controlar manualmente a análise de acessibilidade para execuções de teste com Playwright e Playwright Test. Você pode iniciar e parar a análise automática de acessibilidade e analisar páginas que requerem configuração adicional.

Para mais informações sobre o Playwright, consulte a Documentação do Playwright.

Construtor

new PlaywrightController(driver: Page): PlaywrightController

Parâmetros

• driver: Page

O driver valor é um Page objeto.

Retorna PlaywrightController

Veja Controller para os métodos implementados na classe base abstrata.

PuppeteerController

A PuppeteerController classe permite o controle manual das suas execuções de teste com Puppeteer. O controle manual permite fornecer configurações adicionais necessárias por páginas da web mais complexas.

Para mais informações sobre o Puppeteer, consulte Puppeteer.

Construtor

new PuppeteerController(driver: Page): PuppeteerController

Parâmetros

• driver: Page

O driver valor é um Page objeto.

Retorna PuppeteerController

Veja Controller para os métodos implementados na classe base abstrata.

WdioController

O WdioController permite que você controle manualmente execuções de teste com WebdriverIO e WebdriverIO Testrunner. Para páginas que exigem configuração ou configuração adicional, você pode parar o teste automático e analisar manualmente cada página que requer essa configuração.

Construtor

new WdioController(driver: Browser): WdioController

Parâmetros

• driver: Browser

Retornos WdioController

Veja Controller para os métodos implementados na classe base abstrata.

WebdriverController

Construtor

new WebdriverController(driver: WebDriver): WebdriverController

Parâmetros

• driver: WebDriver

O driver valor é um objeto Selenium WebDriver .

Retornos WebdriverController

Veja Controller para os métodos implementados na classe base abstrata.

Comandos Personalizados do Cypress

Na plataforma de automação de navegador Cypress, os métodos nas classes *Controller são implementados como comandos personalizados. Veja Comandos Personalizados no site de documentação do Cypress para mais informações sobre como implementar e usar comandos personalizados.

Os seguintes comandos personalizados são implementados. Cada comando personalizado retorna Chainable<void> para permitir encadeamento com outros comandos do Cypress.

Exemplo de Comando Cypress

O exemplo a seguir mostra como importar os comandos Cypress do Developer Hub's Axe a partir do pacote @axe-core/watcher e depois chamar o comando axeWatcherFlush no final de cada teste (colocando-o dentro de afterEach()):

// Import the axe-watcher commands.
require('@axe-core/watcher/cypress/support')

// Flush Axe-watcher results after each test.
afterEach(() => {
  cy.axeWatcherFlush()
})

Interface de Timeouts

O objeto timeout (do tipo Timeouts) na interface AxeConfiguration permite que os usuários alterem os valores de timeout (em milissegundos) para as respectivas funções do controlador ou os comandos personalizados do Cypress.

interface Timeouts {
  start?: number
  stop?: number
  flush?: number
  analyze?: number
}