Classe AxeWatcherOptions

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

Configure o Axe Watcher para testes de acessibilidade em testes Java com Selenium e Playwright com opções personalizáveis

Not for use with personal data

A classe AxeWatcherOptions fornece opções de configuração para as integrações Axe Watcher com Selenium e Playwright em Java. Esta classe permite que você personalize como o Axe Watcher realiza testes de acessibilidade durante os testes automatizados de navegador, incluindo detalhes de conexão com o servidor, comportamento de execução de testes e padrões de acessibilidade.

Construtor

AxeWatcherOptions()

Cria uma nova instância de AxeWatcherOptions com configurações padrão. Os valores padrão são:

  • serverUrl: https://axe.deque.com
  • autoAnalyze: true
  • git: true
AxeWatcherOptions options = new AxeWatcherOptions();

Métodos

setApiKey(String apiKey)

Define a chave da API para autenticar com o Axe Developer Hub. Isso é necessário para usar o Axe Watcher.

Parâmetros:

  • apiKey - Sua chave da API do Axe Developer Hub

Retorna:

  • AxeWatcherOptions - A instância atual para encadeamento de métodos

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
options.setApiKey("your-api-key-here");

setProjectId(String projectId)

Parâmetros:

  • projectId - O ID do projeto que receberá os resultados de acessibilidade

Retorna:

  • AxeWatcherOptions - A instância atual para encadeamento de métodos

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
options.setProjectId("your-project-ID-here"); // a uuid identifying the project

setServerUrl(String serverUrl)

Define a URL do servidor para enviar os resultados de acessibilidade. O padrão é https://axe.deque.com.

Parâmetros:

  • serverUrl - URL do servidor para onde enviar os resultados de acessibilidade

Retorna:

  • AxeWatcherOptions - A instância atual para encadeamento de métodos

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
options.setServerUrl("https://custom.axe-instance.com");

setBuildId(String buildId)

Define o ID da build para executores de teste em paralelo. Quando não é nulo, isso permite que executores de teste em paralelo gerem resultados que aparecem como uma única execução de teste no Axe Developer Hub.

Parâmetros:

  • buildId - ID da build para agregar resultados, tipicamente um ID de build de CI/CD

Retorna:

  • AxeWatcherOptions - A instância atual para encadeamento de métodos

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
// Using a CI build ID from an environment variable
options.setBuildId(System.getenv("GITHUB_RUN_ID"));

setAutoAnalyze(boolean autoAnalyze)

Define se a página em teste deve ser analisada automaticamente. O padrão é true.

Parâmetros:

  • autoAnalyze - Se deve analisar automaticamente a página em teste

Retorna:

  • AxeWatcherOptions - A instância atual para encadeamento de métodos

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
// Disable automatic analysis for manual control
options.setAutoAnalyze(false);

setRunContext(AxeRunContext runContext)

Define o contexto da página em teste para limitar o escopo do que é analisado ou excluir certos elementos da análise.

Parâmetros:

  • runContext - Contexto de execução para análise com axe-core

Retorna:

  • AxeWatcherOptions - A instância atual para encadeamento de métodos

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
// Only analyze main content and exclude navigation
AxeRunContext context = new AxeRunContext()
    .setInclude(Arrays.asList("#main-content"))
    .setExclude(Arrays.asList("#navigation"));
options.setRunContext(context);

setRunOptions(AxeRunOptions runOptions)

Define opções adicionais para a análise com axe-core, como quais regras executar ou desativar.

Parâmetros:

  • runOptions - Opções de execução para análise com axe-core

Retorna:

  • AxeWatcherOptions - A instância atual para encadeamento de métodos

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
// Disable the color contrast rule and focus on WCAG 2.1 AA
Map<String, AxeRuleOptions> rules = new HashMap<>();
rules.put("color-contrast", new AxeRuleOptions().setEnabled(false));

AxeRunOnly runOnly = new AxeRunOnly()
    .setType("tag")
    .setValues(Arrays.asList("wcag21aa"));

AxeRunOptions runOptions = new AxeRunOptions()
    .setRules(rules)
    .setRunOnly(runOnly);

options.setRunOptions(runOptions);

setExcludeUrlPatterns(String[] excludeUrlPatterns)

Define padrões de URL para excluir da análise. Usa a biblioteca Minimatch para corresponder URLs.

Parâmetros:

  • excludeUrlPatterns - Padrões de URL para excluir da análise

Retorna:

  • AxeWatcherOptions - A instância atual para encadeamento de métodos

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
// Exclude login pages and admin dashboard
options.setExcludeUrlPatterns(new String[] {
    "https://example.com/login*",
    "https://example.com/admin/*"
});

setAllowedOrigins(String[] allowedOrigins)

Define as origens cujo conteúdo <iframe> de outra origem é analisado. Requer o Watcher 4.6.0 ou posterior.

Por padrão, apenas quadros da mesma origem são analisados, e problemas de acessibilidade dentro de um quadro de outra origem são totalmente deixados fora de seus resultados. Chame este método para incluir as origens que você nomeia. Não inclua a origem da sua própria aplicação, que é sempre permitida.

Cada entrada deve ser uma origem e nada mais: um esquema (http ou https), um host e uma porta opcional. Uma barra final e uma porta padrão (:80 para http, :443 para https) são removidas, o host é convertido para minúsculas e duplicatas são descartadas. Curingas não são suportados, então cada origem deve ser nomeada explicitamente. Um domínio contendo caracteres fora do alfabeto inglês deve ser fornecido em sua forma punycode (a grafia equivalente que começa com xn-- e que os navegadores usam internamente).

Veja Analisar iframes de outra origem para entender as implicações de confiança, o efeito sobre o tempo de análise, e a interação com a análise automática.

Parâmetros:

  • allowedOrigins - Origens cujos iframes de outra origem devem ser analisados

Retorna:

  • AxeWatcherOptions - A instância atual para encadeamento de métodos

Lança:

  • IllegalArgumentException - Se uma entrada não for uma origem apenas http ou https, contém um curinga, contém um caminho, consulta, fragmento ou credenciais, ou usa um domínio com caracteres fora do alfabeto inglês. As entradas são rejeitadas em vez de ignoradas, porque um erro por pouco deixaria o quadro não analisado enquanto o teste ainda relataria sucesso.

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("ACCESSIBILITY_API_KEY"))
    .setProjectId(System.getenv("PROJECT_ID"))
    .setAllowedOrigins(new String[] {"https://pay.example.com"});

setGit(boolean git)

Define se o Watcher coleta informações do Git para a execução de teste atual. O padrão é true. Defina como false ao executar em ambientes sem Git ou quando a coleta de dados do Git não for necessária.

Parâmetros:

  • git - Se deve coletar informações do Git

Retorna:

  • AxeWatcherOptions - A instância atual para encadeamento de métodos

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
// Disable Git info collection
options.setGit(false);

setGitInfo(AxeWatcherGitInfo gitInfo)

Define metadados Git explícitos para a execução de teste atual, ignorando a detecção automática do Git. Use isso quando seus testes ocorrerem em um repositório separado do repositório em teste, ou em ambientes de CI onde a detecção automática do Git é pouco confiável (por exemplo, clones superficiais ou estado de HEAD destacado).

Quando um AxeWatcherGitInfo não nulo é definido, ele tem precedência sobre setGit(boolean) — os metadados fornecidos são enviados mesmo se setGit(false) foi chamado anteriormente. Passar null limpa quaisquer metadados definidos anteriormente e reverte para o comportamento controlado por setGit(boolean).

Veja Fornecendo Metadados Git e AxeWatcherGitInfo para mais informações.

Parâmetros:

  • gitInfo - Metadados Git explícitos para usar. Passe null para limpar os metadados definidos anteriormente e reverter para o comportamento de detecção automática.

Retorna:

  • AxeWatcherOptions - A instância atual para encadeamento de métodos

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey(System.getenv("AXE_DEVELOPER_HUB_API_KEY"))
    .setProjectId(System.getenv("AXE_DEVELOPER_HUB_PROJECT_ID"))
    .setGitInfo(new AxeWatcherGitInfo()
        .setCommitSha(System.getenv("GIT_COMMIT"))
        .setBranch(System.getenv("GIT_BRANCH"))
        .setDefaultBranch("main"));

setConfigurationOverrides(ConfigurationOverrides configurationOverrides)

Define substituições de configuração com base nas configurações globais de configuração da conta Axe da sua organização.

Parâmetros:

  • configurationOverrides - Substituições de configuração

Retorna:

  • AxeWatcherOptions - A instância atual para encadeamento de métodos

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
// Override to use WCAG 2.2 AA and enable best practices
ConfigurationOverrides overrides = new ConfigurationOverrides()
    .setAccessibilityStandard(ConfigurationOverrides.AccessibilityStandard.WCAG22AA)
    .setEnableBestPractices(true);
options.setConfigurationOverrides(overrides);

setTakeScreenshots(boolean takeScreenshots)

Define se deve capturar uma captura de tela da página quando violações forem encontradas.

Parâmetros:

  • takeScreenshots - Se deve capturar capturas de tela quando violações forem encontradas (padrão: false)

Retorna:

  • AxeWatcherOptions - A instância atual para encadeamento de métodos

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
options.setTakeScreenshots(true);

setScreenshotDir(String screenshotDir)

Define o diretório onde capturas de tela são salvas localmente, além de serem enviadas para o Axe Developer Hub. Não tem efeito a menos que setTakeScreenshots(true) também seja chamado.

Quando definido, as capturas de tela são escritas em {screenshotDir}/YYYYMMDDTHHmmssSSS-{screenshot_id}.png. Caminhos relativos são resolvidos em relação ao diretório de trabalho do JVM. Se a criação de diretórios ou a gravação de arquivos falhar, um aviso é registrado e o conjunto de testes continua.

Parâmetros:

  • screenshotDir - Diretório para salvar capturas de tela. Informe null ou uma string vazia para desativar o salvamento local.

Retorna:

  • AxeWatcherOptions - A instância atual para encadeamento de métodos

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions()
    .setTakeScreenshots(true)
    .setScreenshotDir("./axe-screenshots");

setElementInternals(boolean elementInternals)

Habilita o suporte ao ElementInternals para elementos personalizados. Quando ativado, o Axe Watcher coleta funções ARIA e propriedades definidas via API ElementInternals, reduzindo falsos positivos em páginas que usam elementos personalizados com attachInternals(). Requer versão 4.12.0 ou superior do axe-core.

Parâmetros:

  • elementInternals - Se deve habilitar o suporte ao ElementInternals (padrão: false)

Retorna:

  • AxeWatcherOptions - A instância atual para encadeamento de métodos

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions()
    .setElementInternals(true);

getApiKey()

Obtém a chave de API atual.

Retorna:

  • String - A chave API atual

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
options.setApiKey("my-api-key");
String apiKey = options.getApiKey(); // Returns "my-api-key"

getProjectId()

Obtém o ID do projeto atual. O ID do projeto identifica o projeto que recebe os resultados de acessibilidade do Axe Watcher.

Retorna:

  • String - O ID do projeto atual

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
options.setProjectId("my-project-ID"); // should be a uuid identifying the project
String projectId = options.getProjectId(); // Returns the project ID

getServerUrl()

Obtém a URL do servidor atual.

Retorna:

  • String - A URL do servidor atual

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
String serverUrl = options.getServerUrl(); // Returns default "https://axe.deque.com"

getBuildId()

Obtém o ID da compilação atual.

Retorna:

  • String - O ID da compilação atual

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
options.setBuildId("build-123");
String buildId = options.getBuildId(); // Returns "build-123"

getAutoAnalyze()

Obtém se a análise automática está habilitada.

Retorna:

  • boolean - Se a análise automática está habilitada

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
boolean autoAnalyze = options.getAutoAnalyze(); // Returns true (default)

getRunContext()

Obtém o contexto de execução atual.

Retorna:

  • AxeRunContext - O contexto de execução atual

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
AxeRunContext context = new AxeRunContext();
options.setRunContext(context);
AxeRunContext currentContext = options.getRunContext();

getRunOptions()

Obtém as opções de execução atuais.

Retorna:

  • AxeRunOptions - As opções de execução atuais

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
AxeRunOptions runOptions = new AxeRunOptions();
options.setRunOptions(runOptions);
AxeRunOptions currentOptions = options.getRunOptions();

getExcludeUrlPatterns()

Obtém os padrões de URL a serem excluídos atuais.

Retorna:

  • String[] - Os padrões de URL a serem excluídos atuais

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
options.setExcludeUrlPatterns(new String[] {"https://example.com/login*"});
String[] patterns = options.getExcludeUrlPatterns();

getAllowedOrigins()

Obtém as origens cujos iframes de outra origem são analisados. Retorna os valores normalizados, que podem diferir do que você passou para setAllowedOrigins(): uma barra final e uma porta padrão são removidas, o host é convertido para minúsculas e duplicatas são descartadas.

Retorna:

  • String[] - As origens permitidas atualmente, ou null se nenhuma estiver definida

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
options.setAllowedOrigins(new String[] {"https://Pay.example.com:443/"});
String[] origins = options.getAllowedOrigins(); // {"https://pay.example.com"}

getGit()

Obtém se a coleta de informações do Git está habilitada.

Retorna:

  • boolean - true se a coleta de informações do Git está habilitada (padrão), falso se desabilitada

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
boolean git = options.getGit(); // Returns true (default)

getGitInfo()

Obtém os metadados explícitos do Git configurados atualmente ou null se nenhum metadado explícito tiver sido definido.

Retorna:

  • AxeWatcherGitInfo - Os metadados explícitos do Git atuais, ou null se nenhum estiver definido

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions()
    .setGitInfo(new AxeWatcherGitInfo().setBranch("main"));
AxeWatcherGitInfo gitInfo = options.getGitInfo(); // Returns the configured AxeWatcherGitInfo

getConfigurationOverrides()

Obtém as substituições de configuração atuais.

Retorna:

  • ConfigurationOverrides - As substituições de configuração atuais

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
ConfigurationOverrides overrides = new ConfigurationOverrides();
options.setConfigurationOverrides(overrides);
ConfigurationOverrides current = options.getConfigurationOverrides();

getTakeScreenshots()

Obtém se a captura de tela está habilitada.

Retorna:

  • boolean - true se capturas de tela são feitas quando violações são encontradas, false caso contrário

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
options.setTakeScreenshots(true);
boolean takeScreenshots = options.getTakeScreenshots(); // Returns true

getScreenshotDir()

Obtém o diretório de capturas de tela atual, ou null se nenhuma pasta local de salvamento tiver sido definida.

Retorna:

  • String - O diretório de capturas de tela atual, ou null

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions()
    .setScreenshotDir("./screenshots");
String dir = options.getScreenshotDir(); // Returns "./screenshots"

getElementInternals()

Obtém se o suporte a ElementInternals está ativado.

Retorna:

  • boolean - true se o suporte a ElementInternals estiver ativado, false caso contrário

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions();
boolean enabled = options.getElementInternals(); // Returns false (default)

toJson()

Serializa a instância AxeWatcherOptions para uma string JSON.

Retorna:

  • String - Uma representação em string JSON das opções

Lança:

  • RuntimeException - Se configurationOverrides e runOptions.runOnly forem usados juntos (estes são mutuamente exclusivos)

Exemplo:

AxeWatcherOptions options = new AxeWatcherOptions()
    .setApiKey("my-api-key")
    .setProjectId("my-project-id")
    .setServerUrl("https://custom.axe-instance.com");
String json = options.toJson();

Limitações de Configuração

Ao configurar AxeWatcherOptions, esteja ciente das seguintes restrições:

  1. A chave de API é necessária:

    options.setApiKey("your-api-key"); // Required

  2. O ID do Projeto é necessário:

    options.setProjectId("your-project-ID"); // Required

  3. Opções mutuamente exclusivas:

    Você não pode usar runOptions.runOnly e configurationOverrides.accessibilityStandard juntos. Se você precisar definir um padrão específico de acessibilidade, use ConfigurationOverrides conforme mostrado abaixo:

    // Correct: Using ConfigurationOverrides
options.setConfigurationOverrides(
    new ConfigurationOverrides()
        .setAccessibilityStandard(ConfigurationOverrides.AccessibilityStandard.WCAG22AA)
);

// Correct: Using RunOptions.runOnly
options.setRunOptions(
    new AxeRunOptions()
        .setRunOnly(new AxeRunOnly().setType("tag").setValues(Arrays.asList("wcag22aa")))
);

// Incorrect: Using both together will throw an exception
options.setConfigurationOverrides(
    new ConfigurationOverrides()
        .setAccessibilityStandard(ConfigurationOverrides.AccessibilityStandard.WCAG22AA)
).setRunOptions(
    new AxeRunOptions()
        .setRunOnly(new AxeRunOnly().setType("tag").setValues(Arrays.asList("wcag21aa")))
);

  4. A análise automática não detecta mudanças feitas dentro de um iframe:

    Com setAutoAnalyze(true), o Watcher observa apenas a página de nível superior, de modo que uma alteração feita dentro de um iframe (mesma origem ou outra origem) deixa a página parecendo inalterada e a análise automática é ignorada. Um iframe é, portanto, analisado a partir da última alteração na página de nível superior. Após interagir dentro de um quadro, volte ao quadro de nível superior e chame analyze() explicitamente, pois uma análise que você solicita nunca é ignorada:

    // The automatic analysis after this interaction is skipped: the top-level page is unchanged
driver.switchTo().frame("pay");
driver.findElement(By.id("submit")).click();

// Return to the top-level frame, then analyze the resulting state
driver.switchTo().defaultContent();
((AxeWatcherDriver) driver).axeWatcher().analyze();

    Veja Analisar iframes de outra origem para mais informações.

Veja também

Is this page helpful?

Help us improve this page

Still need help?