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

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

Interface AxeConfiguration

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

apiKey

(Obrigatório) O valor apiKey é uma das duas propriedades (apiKey e projectId) que devem ser definidas no seu AxeConfiguration. Você pode obter seu valor na página Gerenciar Chaves de API .

axe: {
  apiKey: process.env.AXE_DEVELOPER_HUB_API_KEY
}

autoAnalyze

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

axe: {
  autoAnalyze: false
}

buildID

(Opcional) A propriedade buildID, quando não é null, permite que executores de teste paralelos gerem resultados que aparecem como uma única execução de teste no Axe Developer Hub. No caso de execuções de teste paralelas, cada executor de teste deve compartilhar a mesma string buildID, 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 SHA do commit do Git. No entanto, quando buildID é null, múltiplas execuções de teste **sobrescrevem** os resultados existentes que têm o mesmo SHA do commit do Git.

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

axe: {
  buildID: process.env.CI_BUILD_ID
}

configurationOverrides

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

axe: {
  configurationOverrides: {
    accessibilityStandard: 'WCAG 2.2 AA',
    bestPractices: true
  }
}

elementInternals

(Opcional) Quando true, o Watcher coleta funções ARIA e propriedades definidas via a API ElementInternals de elementos personalizados que usam attachInternals(). Isso reduz falsos positivos em páginas que usam elementos personalizados para componentes interativos. Requer a versão 4.12.0 ou superior do axe-core.

axe: {
  elementInternals: true
}

excludeUrlPatterns

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

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

Em Excluir URLs da Análise você pode encontrar uma tabela de URLs e exemplos de padrões 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 as 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 objeto GitConfig: Fornece metadados explícitos do Git e pula completamente a detecção automática. Qualquer campo que você omita será padrão para null. Use isso quando seus testes forem executados em um repositório separado do repositório em teste, ou em ambientes de CI onde a detecção automática do Git seja pouco confiável.

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

O objeto GitConfig possui os seguintes campos:

branch, commitSha e url são os campos gitful: uma sessão submetida sem todos os três é registrada como sem git e salva, mas o Axe Developer Hub muda para a visualização de sessão sem git, onde o histórico de branch e de commit de sessões anteriores não estará visível. Enviar uma sessão subsequente com todos os três campos restaura a visualização gitful. Se apenas um ou dois dos três estiverem presentes, o Axe Watcher descarta todos os campos gitful, registra a sessão como sem git e inclui um aviso na resposta.

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: process.env.AXE_PROJECT_ID,
  git: {
    commitSha: process.env.GIT_COMMIT,
    branch: process.env.GIT_BRANCH,
    url: process.env.GIT_URL,
    commitAuthor: process.env.GIT_AUTHOR_NAME,
    commitEmail: process.env.GIT_AUTHOR_EMAIL,
    commitMessage: process.env.GIT_COMMIT_MESSAGE,
    defaultBranch: 'main'
  }
}

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 ao criar um novo projeto, e você também pode obtê-lo na página de Projetos doAxe Developer Hub .

axe: {
  projectId: process.env.AXE_PROJECT_ID
}

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 propriedades include e exclude (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 em Documentação do Contexto do axe-core.

runOptions

(Opcional) O objeto runOptions 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 de elementos ou classes 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 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 execuções de teste.

  Quando ancestry é true, o Axe Developer Hub em vez disso usa a posição do elemento dentro da árvore DOM para localizar o mesmo elemento entre execuções de 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 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 as propriedades type e values. O valor type é 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 objeto runOnly para limitar os testes de acessibilidade a regras marcadas como wcag2a:

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

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

rules

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

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

serverURL

(Opcional) A URL do servidor do Axe Developer Hub para o qual o Watcher envia os resultados de acessibilidade. O padrão é https://axe.deque.com.

Você não precisa definir este valor se o seu projeto foi criado em axe.deque.com. No entanto, se a sua organização usar uma instância regional, nuvem privada ou implementação local do Axe Developer Hub, defina serverURL para a URL base dessa instância:

axe: {
  apiKey: process.env.ACCESSIBILITY_API_KEY,
  projectId: process.env.PROJECT_ID,
  serverURL: process.env.SERVER_URL // e.g., 'https://axe-eu.deque.com'
}

sessionId

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

testingTypes

(Opcional) A propriedade testingTypes é um array de strings para uso com Cypress para especificar teste de componentes ou fim a fim (e2e) (ou ambos).

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

timeout

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

Este exemplo define o timeout 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 Interface Timeouts.)

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, assim como adapte como você deseja executar o Watcher para atender suas necessidades. Veja Interface AxeConfiguration para mais informações.

cypressConfig

Cria uma configuração para o Cypress.

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

Parâmetros cypressConfig

• config: Cypress.ConfigOptions & Configuration

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

Retornos: Cypress.ConfigOptions

Exemplo cypressConfig

import { defineConfig } from 'cypress'
import { cypressConfig } from '@axe-core/watcher/cypress/config'

export default defineConfig(
  cypressConfig({
    axe: {
      apiKey: process.env.API_KEY,
      projectId: process.env.PROJECT_ID
    }
  })
)

playwrightConfig

Cria uma configuração para o Playwright.

playwrightConfig(opts: Configuration & LaunchOptions): LaunchOptions

Parâmetros playwrightConfig

• opts: Configuration & LaunchOptions

  Tipo de interseção de LaunchOptions e Configuration.

Retornos: LaunchOptions

Exemplo playwrightConfig

import { chromium } from 'playwright'
import { playwrightConfig } from '@axe-core/watcher/playwright'

const browserContext = await chromium.launchPersistentContext(
  '',
  playwrightConfig({
    axe: {
      apiKey: process.env.API_KEY,
      projectId: process.env.PROJECT_ID
    }
  })
)

playwrightTest

Cria uma configuração para o Playwright Test.

playwrightTest(options: Options): ReturnValue

Parâmetros playwrightTest

• options: Options

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

Retornos: ReturnValue

Exemplo playwrightTest

// fixtures.ts
import { playwrightTest } from '@axe-core/watcher/playwright-test'

export default playwrightTest({
  axe: {
    apiKey: process.env.API_KEY,
    projectId: process.env.PROJECT_ID
  }
})

puppeteerConfig

Cria uma configuração para o Puppeteer.

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

Parâmetros puppeteerConfig

• opts: Configuration & LaunchOptions & BrowserLaunchArgumentOptions & BrowserConnectOptions

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

Retornos: Options

Exemplo puppeteerConfig

import puppeteer from 'puppeteer'
import { puppeteerConfig } from '@axe-core/watcher/puppeteer'

const browser = await puppeteer.launch(
  puppeteerConfig({
    axe: {
      apiKey: process.env.API_KEY,
      projectId: process.env.PROJECT_ID
    }
  })
)

wdioConfig

Cria uma configuração do WebdriverIO.

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

Parâmetros wdioConfig

• arg: Options

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

Retornos: RemoteOptions

Exemplo wdioConfig

import { remote } from 'webdriverio'
import { wdioConfig } from '@axe-core/watcher/wdio'

const browser = await remote(
  wdioConfig({
    axe: {
      apiKey: process.env.API_KEY,
      projectId: process.env.PROJECT_ID
    },
    capabilities: { browserName: 'chrome' }
  })
)

wdioTestRunner

Cria uma configuração do WebdriverIO Testrunner.

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

Parâmetros wdioTestRunner

• params: unknown[]

  O valor params é 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.

Retornos: Options.Testrunner

Exemplo wdioTestRunner

import { wdioTestRunner } from '@axe-core/watcher/wdio'

export const config = wdioTestRunner({
  axe: {
    apiKey: process.env.API_KEY,
    projectId: process.env.PROJECT_ID
  }
})

webdriverConfig

Cria uma configuração Selenium WebDriver.

webdriverConfig(arg: WebDriverArgs): Options

Parâmetros webdriverConfig

• arg: WebDriverArgs

  Um Configuration estendido para incluir um membro Options do Selenium WebDriver.

Retornos: Options

webdriverConfig Exemplo

import { Builder } from 'selenium-webdriver'
import { Options } from 'selenium-webdriver/chrome'
import { webdriverConfig } from '@axe-core/watcher/webdriver'

const options = new Options()
const browser = await new Builder()
  .forBrowser('chrome')
  .setChromeOptions(
    webdriverConfig({
      axe: {
        apiKey: process.env.API_KEY,
        projectId: process.env.PROJECT_ID
      },
      options
    })
  )
  .build()

Configuration Interface

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

Todos os funções de configuração usam esta propriedade axe para permitir configurar o Watcher e configurar seus testes de acessibilidade. Veja a seção Interface AxeConfiguration acima para mais informações.

ConfigurationOverrides Interface

A interface ConfigurationOverrides permite que você substitua as configurações globais da 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 da sua empresa.

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.

axe: {
  configurationOverrides: {
    accessibilityStandard: 'WCAG 2.2 AA'
  }
}

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.

axe: {
  configurationOverrides: {
    axeCoreVersion: 'latest'
  }
}

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 ela tenha efeito.

axe: {
  configurationOverrides: {
    bestPractices: true
  }
}

experimentalRules

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

axe: {
  configurationOverrides: {
    experimentalRules: true
  }
}

Controller Classes

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

Controller

abstract class Controller

A classe abstrata Controller contém os métodos para controlar a análise de páginas. Cada uma das classes concretas estende essa 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 esse método após 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 método stop ou configurando autoAnalyze para false.

analyze Retorna

Promise<void>

analyze Exemplo

await controller.analyze()

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 Exemplo

await controller.flush()

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 Exemplo

await controller.start()

start Comando equivalente do Cypress

cy.axeWatcherStart()

stop

stop(): Promise<void>

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

stop Retorna

Promise<void>

stop Exemplo

await controller.stop()

stop Comando equivalente do Cypress

cy.axeWatcherStop()

PlaywrightController

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

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

Construtor

new PlaywrightController(driver: Page): PlaywrightController

Parâmetros

• driver: Page

O valor driver é um objeto de Page do Playwright.

Retorna PlaywrightController

PlaywrightController Exemplo

import { PlaywrightController, wrapPlaywrightPage } from '@axe-core/watcher/playwright'

let page = await browserContext.newPage()
const controller = new PlaywrightController(page)
page = wrapPlaywrightPage(page, controller)

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

PuppeteerController

A classe PuppeteerController permite o controle manual de suas execuções de teste com Puppeteer. O controle manual permite que você forneça a configuração adicional exigida por páginas da web mais complexas.

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

Construtor

new PuppeteerController(driver: Page): PuppeteerController

Parâmetros

• driver: Page

O valor driver é um objeto de Page do Puppeteer.

Retorna PuppeteerController

PuppeteerController Exemplo

import { PuppeteerController, wrapPuppeteerPage } from '@axe-core/watcher/puppeteer'

let page = await browser.newPage()
const controller = new PuppeteerController(page)
page = wrapPuppeteerPage(page, controller)

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

WdioController

O WdioController permite que você controle manualmente as execuções de teste do WebdriverIO e do WebdriverIO Testrunner. Para páginas que requerem configuração ou ajustes adicionais, você pode interromper o teste automático e analisar manualmente cada página que exija tal configuração.

Construtor

new WdioController(driver: Browser): WdioController

Parâmetros

• driver: Browser

Retorna WdioController

WdioController Exemplo

import { WdioController, wrapWdio } from '@axe-core/watcher/wdio'

// browser is the WebdriverIO Browser instance from your wdioConfig() setup
const controller = new WdioController(browser)
wrapWdio(browser, controller)

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

WebdriverController

Construtor

new WebdriverController(driver: WebDriver): WebdriverController

Parâmetros

• driver: WebDriver

O valor driver é um objeto de WebDriver do Selenium.

Retorna WebdriverController

WebdriverController Exemplo

import { WebdriverController, wrapWebdriver } from '@axe-core/watcher/webdriver'

// browser is the Selenium WebDriver instance from your webdriverConfig() setup
const controller = new WebdriverController(browser)
browser = wrapWebdriver(browser, controller)

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 a implementação e o uso de comandos personalizados.

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

Exemplo de Comando Cypress

O exemplo a seguir mostra como importar os comandos Cypress do Axe Developer Hub a partir do pacote @axe-core/watcher e então 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 objeto timeout (do tipo Timeouts) no AxeConfiguration permite que os usuários alterem os valores de timeout (em milissegundos) para as funções do controlador respectivas ou para os comandos personalizados do Cypress.

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