Referência da 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 apenas Watcher) para JavaScript e TypeScript.

AxeConfiguration Interface

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

apiKey

(Obrigatório) O ", "context": "paragraph apiKey valor é uma das duas propriedades (", "context": "paragraphapiKey e ", "context": "paragraph projectId) que devem ser definidas no seu ", "context": "paragraph AxeConfiguration. Você pode obter seu valor na ", "context": "paragraph Página de Gerenciamento de Chaves de API", "context": "paragraph .", "context": "paragraph

autoAnalyze

(Opcional) Defina este valor como ", "context": "paragraph false para impedir que as páginas sejam analisadas automaticamente. Para mais informações sobre o modo manual, veja ", "context": "paragraph Controlando a Análise de Páginas", "context": "link text.", "context": "paragraph

buildID

(Opcional) A propriedade ", "context": "paragraph buildID , quando não ", "context": "paragraph null, permite que corredores de teste em paralelo gerem resultados que aparecem como uma única execução de teste no axe Developer Hub. No caso de execuções de teste em paralelo, cada corredor de teste deve compartilhar a mesma string não nula ", "context": "paragraph buildID , o que faz com que cada execução de teste concatene seus resultados com resultados existentes para o mesmo ", "context": "paragraph buildID e SHA do commit do Git. Contudo, quando ", "context": "paragraph buildID está ", "context": "paragraph null, múltiplas execuções de teste ", "context": "paragraph sobrescrevem", "context": "strong text resultados existentes que têm o mesmo SHA do commit do Git.", "context": "paragraph

Você geralmente pode obter um valor utilizável ", "context": "paragraph buildID do seu provedor de integração contínua. Por exemplo, você pode usar estes valores:", "context": "paragraph

• github.run_id

  Disponível dentro dos workflows do GitHub. Veja ", "context": "paragraph contexto do github", "context": "link text na documentação do GitHub para mais informações.", "context": "paragraph

• CIRCLE_PIPELINE_ID

  Com o CircleCI, o valor acima está disponível a partir do ambiente do seu processo. Veja ", "context": "paragraph Variáveis de ambiente embutidas", "context": "link text na documentação do CircleCI para mais informações.", "context": "paragraph

  Outras variáveis de ambiente de integração contínua que você pode usar para ", "context": "paragraph buildID:", "context": "paragraph

  Provedor", "context": "table cell	Variável de ambiente", "context": "table cell
  Bitbucket", "context": "link text	BITBUCKET_BUILD_NUMBER
  GitLab", "context": "link text	CI_PIPELINE_ID
  Jenkins", "context": "link text	BUILD_NUMBER

configurationOverrides

(Opcional) Substitui valores definidos na ", "context": "paragraph configuração global", "context": "link text. Veja a ", "context": "paragraph Interface de Substituições de Configuração", "context": "link text para mais informações.", "context": "paragraph

excludeUrlPatterns

(Opcional) Impede que qualquer URL que corresponda a qualquer um dos ", "context": "paragraph minimatch padrões no excludeUrlPatterns array de serem analisados.

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

Exemplos

git

(Opcional) Configure para false para impedir que o Watcher colete informações do Git para a execução do teste atual. O padrão é true. Isso é útil para projetos que não estão em um repositório Git ou onde a coleta de dados do Git causa erros.

projectId

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

runContext

(Opcional) Permite que você escolha quais elementos sã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 os elementos a serem incluídos na análise:

   axe: {
     runContext: '.main'
   }

2. Um array de seletores CSS para os 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 axe-core.

runOptions

(Opcional) O runOptions objeto permite o seguinte subconjunto de propriedades do tipo Options 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 corretamente se os problemas de acessibilidade são duplicados , porque, por padrão, o axe Developer Hub espera que os IDs e classes dos elementos permaneçam os mesmos entre os testes.

  Quando ancestry é true, o axe Developer Hub usa a posição do elemento dentro da árvore DOM para localizar o mesmo elemento entre os testes.

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

  iframe#main-iframe

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

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

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

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

O seguinte 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 a 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 propriedade values deve ser um array de strings representando a(s) regra(s) ou etiqueta(s) que você gostaria de usar para análise de acessibilidade. O exemplo a seguir mostra o uso do runOnly objeto para limitar o teste de acessibilidade a regras etiquetadas como wcag2a:

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

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

rules

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

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

sessionId

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

testingTypes

(Opcional) O testingTypes é um array de strings para uso com o Cypress, a fim de 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 tempo limite em milissegundos para os métodos do controlador respectivos (ou comandos personalizados para o Cypress). (Veja as Classes de Controlador para informações sobre as classes de controlador e os Comentários Personalizados do Cypress para informações sobre comandos personalizados do Cypress.) Quando um tempo limite 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 tempo limite de analyze para 8 segundos, flush para 15 segundos, start para 10 segundos, e stop para 10 segundos. (Os valores padrão são mostrados na tabela em 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 a estrutura de teste especificada, bem como adapte como você deseja executar o Watcher de acordo com suas necessidades. Veja a Interface de Configuração do Axe para mais informações.

cypressConfig

Cria uma configuração para 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 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 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 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 para 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 de Testrunner do WebdriverIO.

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 do array é um AxeConfiguration e o segundo valor é um Options.Testrunner.

Retorna: Options.Testrunner

webdriverConfig

Cria uma configuração de Selenium WebDriver.

webdriverConfig(arg: WebDriverArgs): Options

webdriverConfig Parâmetros

• arg: WebDriverArgs

  Um Configuration estendido para incluir um membro de 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 esta 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 de sua organização para execuções de teste individuais. Esta propriedade deve ser usada de acordo com as permissões definidas na configuração global de sua empresa.

accessibilityStandard

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

• ‘Tudo’ – 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 testes. As opções disponíveis incluem:

• ‘última’ – Versão mais recente suportada atualmente incluída com 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

Ativa ou desativa 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 tenha efeito.

experimentalRules

Ativa ou desativa regras experimentais para a execução do teste. As regras experimentais ainda estão em desenvolvimento e podem gerar falsos positivos. Sua organização deve permitir a substituição desta configuração na configuração global para que tenha efeito.

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, de modo que 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 após configurar uma página da web para análise (como inserir valores em um formulário) e ter desativado a análise automática usando o stop método ou configurando autoAnalyze para false.

analyze Retorna", "context": "heading level 5

Promise<void>

analyze Comando Cypress equivalente", "context": "heading level 5

cy.axeWatcherAnalyze()

flush

flush(): Promise<void>

Envia todos os resultados da varredura de acessibilidade para o axe Developer Hub. Deve ser chamado no final da execução do teste para garantir que os resultados foram enviados para os servidores do axe Developer Hub da Deque.", "context": "paragraph

flush Retorna", "context": "heading level 5

Promise<void>

flush Comando Cypress equivalente", "context": "heading level 5

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 para erros de acessibilidade.", "context": "paragraph

start Retorna", "context": "heading level 5

Promise<void>

start Comando Cypress equivalente", "context": "heading level 5

cy.axeWatcherStart()

stop

stop(): Promise<void>

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

stop Retorna", "context": "heading level 5

Promise<void>

stop Comando Cypress equivalente", "context": "heading level 5

cy.axeWatcherStop()

PlaywrightController

A ", "context": "paragraph 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.", "context": "paragraph

Para mais informações sobre o Playwright, consulte a ", "context": "paragraph Documentação do Playwright", "context": "link text.", "context": "paragraph

Construtor", "context": "heading level 4

new PlaywrightController(driver: Page): PlaywrightController

Parâmetros", "context": "heading level 5

• driver: ", "context": "paragraph Page

O ", "context": "paragraph driver valor é um ", "context": "paragraph Page objeto do Playwright.", "context": "paragraph

Retorna ", "context": "heading level 5 PlaywrightController

Veja ", "context": "paragraph Controller para os métodos implementados na classe base abstrata.", "context": "paragraph

PuppeteerController

A ", "context": "paragraph PuppeteerController classe permite o controle manual de suas execuções de teste com Puppeteer. O controle manual permite fornecer configuração adicional necessária para páginas da web mais complexas.", "context": "paragraph

Para mais informações sobre o Puppeteer, consulte ", "context": "paragraph Puppeteer", "context": "link text.", "context": "paragraph

Construtor", "context": "heading level 4

new PuppeteerController(driver: Page): PuppeteerController

Parâmetros", "context": "heading level 5

• driver: ", "context": "paragraph Page

O ", "context": "paragraph driver valor é um ", "context": "paragraph Page objeto do Puppeteer.", "context": "paragraph

Retorna ", "context": "heading level 5 PuppeteerController

Veja ", "context": "paragraph Controller para os métodos implementados na classe base abstrata.", "context": "paragraph

WdioController

O ", "context": "paragraph WdioController permite controlar manualmente as execuções de teste do WebdriverIO e do WebdriverIO Testrunner. Para páginas que requerem configuração ou configuração adicional, você pode parar os testes automáticos e analisar manualmente cada página que exija tal configuração.", "context": "paragraph

Construtor", "context": "heading level 4

new WdioController(driver: Browser): WdioController

Parâmetros", "context": "heading level 5

• driver: ", "context": "paragraph Browser

Retorna ", "context": "heading level 5 WdioController

Veja ", "context": "paragraph Controller para os métodos implementados na classe base abstrata.", "context": "paragraph

WebdriverController", "context": "heading level 3

Construtor

new WebdriverController(driver: WebDriver): WebdriverController

Parâmetros

• driver: WebDriver

O driver valor é um objeto Selenium WebDriver .

Retorna WebdriverController

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

Comandos Customizados do Cypress

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

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

Exemplo de Comando Cypress

O exemplo a seguir mostra como importar os comandos Cypress do Hub de Desenvolvedores axe a partir do pacote @axe-core/watcher e então chamar o comando axeWatcherFlush ao 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 Timeouts

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

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