As frames devem ser testadas com axe-core

Por que isto é importante

As páginas web frequentemente incorporam conteúdo usando elementos iframe ou frame — para anúncios, widgets de terceiros, formulários incorporados, reprodutores de vídeo, ou mesmo componentes de aplicação interna. Cada frame é essencialmente o seu próprio documento com o seu próprio DOM. Se o axe-core não estiver a executar dentro dessas frames, quaisquer violações de acessibilidade dentro delas passam completamente despercebidas.

Isto é classificado como um problema de impacto crítico no utilizador — não porque a própria frame seja inacessível, mas porque violações não detetadas dentro de frames podem afetar todos os utilizadores com deficiências. Utilizadores cegos que dependem de leitores de ecrã, utilizadores com visão que usam apenas teclado, e utilizadores surdos-cegos poderiam todos encontrar barreiras escondidas dentro de conteúdo de frame não testado. Etiquetas de formulário em falta, gestão de foco quebrada, contraste de cor insuficiente, ou texto alternativo em falta dentro de frames permaneceriam invisíveis ao seu processo de teste.

Esta regra é uma melhor prática da Deque em vez de um critério de sucesso WCAG específico. No entanto, as violações que passam despercebidas dentro de frames não testadas podem relacionar-se com numerosos critérios WCAG, incluindo 1.1.1 (Conteúdo não textual), 1.3.1 (Informação e relações), 2.1.1 (Teclado), 2.4.3 (Ordem de foco), 4.1.2 (Nome, função, valor), e muitos outros. O teste abrangente de acessibilidade requer que todo o conteúdo numa página seja analisado, incluindo conteúdo dentro de frames.

Como a regra funciona

Quando a propriedade de configuração iframes está definida como true, o axe-core tenta executar dentro de cada elemento iframe e frame na página. A regra usa seletores tanto frame como iframe para verificar se o script axe-core está presente no documento de cada frame. Se o axe-core não for encontrado dentro de uma frame, a regra retorna um resultado de “necessita revisão” para esse elemento.

A regra opera ao nível da página — o que significa que os resultados de nós através de diferentes frames são combinados num único resultado quando toda a página é testada. Uma função after opcional processa resultados de todas as frames em conjunto.

Como corrigir

Existem várias abordagens para garantir que as frames são testadas adequadamente:

1. Use o suporte integrado do axe-core para iframe. Quando executar o axe-core programaticamente, defina a opção iframes como true (esta é a predefinição). O axe-core tentará automaticamente comunicar com frames para recolher resultados — mas o script axe-core deve estar presente em cada frame para que isto funcione.

2. Injete axe-core em todas as frames. Se você controla o conteúdo da frame, inclua o script axe-core nesses documentos. Se estiver a usar uma framework de teste como Selenium, Puppeteer, ou Playwright, injete o script axe-core em cada frame antes de executar a análise.

3. Use a extensão de browser axe DevTools. A extensão axe DevTools lida com a injeção de frame automaticamente na maioria dos casos, tornando-a a opção mais simples para teste manual.

4. Para frames de terceiros que você não controla, reconheça que a cobertura de teste é limitada e considere testar o conteúdo de terceiros separadamente, ou documente-o como uma área que requer revisão manual.

Exemplos

Frame que desencadeia o problema

Um iframe está presente na página, mas o axe-core não está carregado dentro dele. O conteúdo dentro da frame permanece não testado:

<main>
  <h1>A nossa aplicação</h1>
  <iframe src="https://example.com/embedded-form" title="Formulário de contacto"></iframe>
</main>

Se https://example.com/embedded-form não tiver o axe-core carregado, o axe sinalizará esta frame como necessitando revisão.

Configuração correta com axe-core injetado

Quando usar uma ferramenta de teste como Playwright, certifique-se de que o axe-core é injetado em todas as frames:

const { AxeBuilder } = require('@axe-core/playwright');

// AxeBuilder analisa automaticamente conteúdo de iframe
const results = await new AxeBuilder({ page })
  .analyze();

Conteúdo de frame que inclui axe-core

Se você controla a fonte da frame, inclua o script axe-core diretamente:

<!-- Conteúdo dentro do documento iframe -->

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Formulário incorporado</title>
  <script src="/vendor/axe-core/axe.min.js"></script>
</head>
<body>
  <form>
    <label for="email">Endereço de email</label>
    <input type="email" id="email" name="email">
    <button type="submit">Subscrever</button>
  </form>
</body>
</html>

Frame adequadamente estruturada na página principal

Certifique-se sempre de que as suas frames têm atributos title descritivos para que os utilizadores compreendam o seu propósito:

<iframe src="/embedded-form.html" title="Formulário de subscrição de newsletter"></iframe>

Isto não corrigirá o problema de injeção do axe-core por si só, mas garante que a frame é acessível enquanto você trabalha para obter cobertura de teste completa dentro dela.

Learn more:

Deque Reference

Deque University - How To Fix

→