Analisar iframes de origem cruzada

O Axe Watcher analisa o conteúdo de elementos de mesma origem <iframe> juntamente com o restante da página. Os frames servidos de uma origem diferentes são ignorados por padrão, e problemas de acessibilidade dentro deles são completamente excluídos de seus resultados.

A opção allowedOrigins permite a análise desses frames. Você nomeia as origens que deseja cobrir, e o Watcher analisa frames servidos a partir delas como parte de cada análise da página que os incorpora.

Essa opção requer Watcher 4.6.0 ou posterior, e está disponível com as integrações JavaScript/TypeScript e as integrações Java.

Quando Você Precisa Desta Opção

Defina allowedOrigins quando partes significativas da sua experiência do usuário são servidas de outra origem, como um formulário de pagamento hospedado, um widget de reserva ou agendamento incorporado, um reprodutor de mídia com seus próprios controles, ou um widget de ajuda ou chat.

Você não precisa disso para frames servidos da sua própria origem, que são sempre analisados.

Configurar Origens Permitidas

Liste apenas as origens incorporadas que você deseja cobrir. A origem da sua própria aplicação é sempre permitida, então não a inclua.

JavaScript e TypeScript

axe: {
  apiKey: process.env.AXE_DEVELOPER_HUB_API_KEY,
  projectId: process.env.AXE_PROJECT_ID,
  allowedOrigins: [ 'https://pay.example.com' ]
}

Java

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

Decidir Quais Origens Confiar

A lista de permissões é aplicada em cada frame, não apenas no superior, e funciona em ambas as direções: um frame aceita uma mensagem apenas de uma origem na sua própria lista, e responde apenas a essas origens. Na prática, cada frame permite sua própria origem, todas as origens que você listar, e, somente quando a própria origem daquele frame está entre as que você listou, a origem do frame que o incorpora diretamente, desde que esse incorporação seja ou a página de nível superior ou outra origem que você listou.

Portanto, listar uma origem não a autoriza a responder a qualquer página que a enquadre. O que autoriza é a troca de marcação entre aquele frame e seu incorporador dentro da página em teste, razão pela qual a lista deve permanecer restrita a incorporações nas quais você confia.

É também por isso que curingas não são suportados e porque não há uma opção que signifique "analisar todos os frames." Uma lista de permissões que você não pode enumerar não é uma lista de permissões. Nomeie cada origem explicitamente, e mantenha a lista apenas com as incorporações que você realmente precisa cobrir.

Considere se a página em teste exibe algo sensível enquanto seus testes estão em execução. Se suas fixações de teste usam dados pessoais ou de pagamento realistas, pese isso contra as origens de terceiros que você está prestes a permitir.

Escrever as Origens Corretamente

Cada entrada deve ser uma origem e nada mais: um esquema (http ou https), um host e uma porta opcional. O Watcher normaliza o que você fornece removendo uma barra final e uma porta padrão (:80 para http, :443 para https), convertendo o host para minúsculas e descartando duplicatas.

O Watcher rejeita uma entrada que não pode usar ao relatar um erro quando sua configuração é lida, em vez de deixar o teste continuar e não analisar nada. No Java, setAllowedOrigins() lança IllegalArgumentException.

Domínios Que Contêm Caracteres Não Ingleses

Um domínio que contém caracteres fora do alfabeto inglês, como café.example.com ou пример.рф, tem uma segunda grafia equivalente composta apenas pelas letras a a z, os dígitos 0 a 9 e hifens. Essa grafia é chamada de punycode, e sempre começa com xn--. Os navegadores convertem um domínio para sua forma punycode antes de usá-lo, então a forma punycode é a que o Watcher compara.

Para encontrar a forma punycode, visite a URL do frame e leia a barra de endereços do seu navegador após o carregamento da página, ou use qualquer conversor online de punycode.

Não substitua por uma grafia em inglês parecida, como cafe.example.com por café.example.com. O Watcher aceita isso, porque é uma origem válida, mas nunca coincide com a verdadeira origem do frame, então o frame é silenciosamente deixado sem análise.

As Palavras-Chave <same_origin> e <unsafe_all_origins>

O mecanismo de acessibilidade que o Watcher usa, o axe-core, aceita duas palavras-chave em sua própria configuração equivalente, e você pode encontrá-las na documentação do axe-core ou em uma configuração que está migrando:

• <same_origin> significa "a própria origem desta página." O Watcher aceita, mas não tem efeito, pois sua própria origem é sempre permitida.
• <unsafe_all_origins> significa "todas as origens, incluindo aquelas que você não listou." O Watcher o rejeita com um erro, pelas razões descritas em Decidir Quais Origens Confiar.

Capturar Alterações Feitas Dentro de um Frame

A análise automática detecta alterações na página de nível superior. Não pode detectar uma alteração feita dentro de um frame, seja ele de mesma origem ou de origem cruzada. Um frame permitido é, portanto, analisado a partir da última alteração na página de nível superior.

Isso importa quando você interage com conteúdo dentro de um frame. A interação altera o conteúdo do frame, a página de nível superior permanece inalterada, e assim nenhuma análise automática é realizada:

// Interacting inside the frame doesn't trigger an automatic analysis
await page.frameLocator('#pay').getByRole('button', { name: 'Continue' }).click()

// Analyze explicitly to capture the resulting state
await controller.analyze()

Chame analyze() após a interação para capturar o estado resultante. Uma análise que você solicita explicitamente é sempre realizada. Veja Controle Suas Análises para saber como obter um objeto controlador em seu framework de teste.

Encontre os Frames Que Você Está Perdendo

Watcher relata os frames de origem cruzada que ignorou, quer você tenha configurado ou não allowedOrigins. Isso significa que você pode descobrir quais incorporações estão faltando nos seus resultados antes de configurar qualquer coisa.

O diagnóstico cross_origin_frame_not_allowlisted nomeia cada origem ignorada e inclui a linha allowedOrigins para colar na sua configuração. Em uma página com muitas incorporações de terceiros, a lista é limitada, e o restante é resumido como "e mais N."

Os diagnósticos aparecem apenas na saída de depuração, e cada um é relatado no máximo uma vez por execução de teste.

JavaScript e TypeScript: defina a variável de ambiente DEBUG ao executar seus testes.

DEBUG=axe-watcher:* npx playwright test

Java: os controladores registram cada diagnóstico no nível DEBUG, então configure seu framework de logging para mostrar mensagens DEBUG para Axe Watcher. Com a integração do Selenium, você também pode chamar enableDebugLogger() em AxeWatcher.

Outros dois diagnósticos relatam frames que foram permitidos, mas ainda não analisados. Ambos são descritos sob Limitações:

• cross_origin_frame_unscannable, para um frame isolado sem allow-same-origin.
• cross_origin_frame_timed_out, para um frame que não retornou resultados a tempo.

Se você prefere que a cobertura do frame apareça nos seus resultados em vez de na saída de depuração, ative melhores práticas. A regra frame-tested do axe-core distingue "nenhum problema neste frame" de "este frame nunca foi analisado": um frame que o Watcher não conseguiu alcançar é relatado como precisando de revisão. Como é uma regra de melhores práticas, um conjunto de regras limitado às regras WCAG omite-a.

Problemas encontrados dentro de um frame são atribuídos ao estado da página que incorpora o frame, e não a um estado de página separado próprio.

Limitações

A limitação que você provavelmente encontrará é que a análise automática não pode ver alterações feitas dentro de um frame, descritas sob Capturar Alterações Feitas Dentro de um Frame. O restante está abaixo.

Um Frame Isolado Precisa de allow-same-origin

Um frame cujo atributo sandbox omite allow-same-origin tem uma origem opaca, que nenhuma entrada de lista de permitidos pode nomear, por isso não pode ser analisado, não importa o que você listar. Assim que você listar sua origem, o Watcher a relata com o diagnóstico cross_origin_frame_unscannable. Até você o fazer, é relatado como cross_origin_frame_not_allowlisted como qualquer outro frame ignorado. Adicione allow-same-origin ao atributo sandbox para analisar o frame.

Apenas allow-same-origin importa aqui. Um frame isolado que omite allow-scripts ainda é analisado normalmente, porque o script de conteúdo do Watcher roda em um mundo isolado e é executado mesmo onde os próprios scripts da página estão bloqueados.

Incorporações que Redirecionam

Uma incorporação cujo src redireciona para outra origem, como um domínio de nível mais alto redirecionando para www ou http redirecionando para https, acaba em uma origem que não é aquela que você listou, portanto não é analisada. Liste a origem para a qual o frame realmente acaba indo, em vez daquela em seu src.

Frames Aninhados em Mais de um Nível Não São Relatados

Os diagnósticos de cobertura de frames são relatados a partir da página de nível superior, sobre os frames que ela incorpora diretamente. Um frame que não pôde ser alcançado, mas está aninhado a dois ou mais níveis de profundidade, não aparecerá na sua saída de depuração, mesmo que seu conteúdo esteja faltando nos resultados.

Um Frame que Nunca Responde Falha na Análise

Um frame que responde ao ping inicial do Watcher, mas nunca retorna resultados falha na análise completamente em vez de sub-relatá-la, e o Watcher relata o diagnóstico cross_origin_frame_timed_out. Se uma incorporação de terceiro lenta faz isso, remova sua origem de allowedOrigins ou aumente runOptions.frameWaitTime.

Orçamento para Análise Mais Lenta

Cada origem que você permite adiciona o conteúdo inteiro daquele frame a cada análise da página. O conteúdo do frame é coletado, transferido para a página de nível superior, e combinado com o restante dos resultados, e tudo isso acontece enquanto seu teste espera.

Quanto tempo isso adiciona cresce com o tamanho e a complexidade do conteúdo do frame, e com o número de frames que você permite. Com a análise automática habilitada, o custo se repete a cada interação que o Watcher analisa, então um conjunto de testes longo com vários frames permitidos pode adicionar uma quantidade substancial de tempo a uma execução. Duas maneiras de mantê-lo gerenciável:

• Restrinja allowedOrigins às incorporações que você realmente precisa cobrir, em vez de todas as origens de terceiros na página.
• Considere ativá-lo por projeto ou por conjunto de testes, para que conjuntos que não utilizam conteúdo em frames não paguem por isso.

Se você quiser medir o efeito em seu próprio conjunto, cronometre uma execução representativa antes e depois de ativar a opção.

Timeouts

Como analisar um frame de origem cruzada inclui esperar que esse frame responda, os timeouts padrão analyze e flush mudam de 5000ms para 10000ms quando allowedOrigins está definido para um array não vazio. Os padrões start e stop permanecem inalterados. Os valores de timeout que você mesmo define são sempre usados como dados, então isso afeta apenas os padrões. Veja Defina Timeouts.

Isso se aplica às integrações JavaScript e TypeScript. O Watcher Java atualmente não suporta timeouts personalizados, e seus valores de timeout não são alterados por essa opção.

Se você definir seus próprios timeouts e depois ativar allowedOrigins, reveja-os. Um valor ajustado para uma página sem conteúdo em frames pode agora estar muito apertado.

Tópicos Relacionados

• Defina Timeouts
• Controle Suas Varreduras
• Melhores Práticas
• Solução de Problemas
• Referência da API para a versão JavaScript e TypeScript do Watcher
• Opções do AxeWatcher