Esse relatório pode descrever um problema de layout, uma solicitação com falha, um botão invisível ou uma interação específica do navegador. Antes de alterar o código, um desenvolvedor precisa identificar o comportamento exato e as condições que o acionam.
Um relatório de bug útil combina etapas escritas, detalhes do ambiente, evidências visuais e uma expectativa testável. Este artigo mostra como reunir essas evidências e converter um defeito de layout responsivo em um teste de regressão Playwright.
1. Descreva uma falha observável
Considere uma caixa de diálogo de configurações hipotética que se estende além da borda direita de uma viewport estreita. O botão Salvar fica difícil de alcançar.
Um relatório útil diria:
Na versão 2.8.1, abrir as configurações de perfil em uma janela de visualização de 390 × 844 pixels CSS causa estouro horizontal. Esperado: a caixa de diálogo cabe na janela de visualização e Salvar permanece acessível.
Isto descreve algo que outro desenvolvedor pode inspecionar. “O CSS está errado” propõe uma causa antes que a investigação a estabeleça.
Inclua o estado inicial, ações, comportamento esperado, comportamento real e frequência de reprodução. Se o defeito ocorrer apenas com um nome de exibição longo, registre essa condição usando dados sintéticos.
2. Capture detalhes relevantes do ambiente
Bugs responsivos dependem da janela de visualização do navegador, que pode ser diferente da resolução da tela. A proporção de pixels do dispositivo também afeta a forma como os pixels CSS se relacionam com os pixels de exibição.
O auxiliar a seguir cria um pequeno instantâneo do ambiente. Execute-o nas ferramentas de desenvolvimento do seu aplicativo ou no console do navegador:
function collectDebugContext({ build, screenId }) {
const visual = window.visualViewport;
return {
capturedAt: new Date().toISOString(),
build,
screenId,
viewport: {
width: window.innerWidth,
height: window.innerHeight
},
documentWidth: document.documentElement.clientWidth,
devicePixelRatio: window.devicePixelRatio,
visualViewport: visual ? {
width: visual.width,
height: visual.height,
scale: visual.scale
} : null,
language: navigator.language
};
}
console.log(JSON.stringify(
collectDebugContext({
build: '2.8.1',
screenId: 'profile-settings'
}),
null,
2
));
Passe o identificador de build do seu processo de lançamento em um aplicativo real. Uma versão inserida manualmente pode facilmente tornar-se imprecisa.
O auxiliar usa um identificador de tela explícito em vez de copiar o URL completo, que pode conter IDs de registros privados ou parâmetros de consulta. Ele também deixa o nome do navegador, a versão do navegador, o sistema operacional e a configuração de zoom para o repórter fornecer.
Registre esses detalhes quando eles afetarem a reprodução. O instantâneo é um contexto, não uma impressão digital completa do dispositivo.
Para definições de dimensionamento, consulte as referências do MDN para largura interna e dispositivoPixelRatio.
3. Use vídeo para explicar a interação
Uma captura de tela mostra o estado final. Uma gravação pode mostrar como o usuário chegou até ela: abrindo a caixa de diálogo, rolando para os lados e tentando acessar Salvar.
AS ÁGUAS é uma plataforma de criação e edição de vídeo baseada em navegador com ferramentas de corte, corte, sobreposições de texto, legendas automáticas e gravação de tela. Para desenvolvedores, pode servir como um recurso para preparar demonstrações claras de bugs ou explicar uma correção durante a revisão.
Grave com uma conta de demonstração. Mostre o estado inicial, execute a sequência de reprodução mais curta e faça uma breve pausa na falha.
Ao editar a gravação no veed, remova configurações não relacionadas, preservando a sequência que desencadeia o problema. Adicione um rótulo curto para a construção e a janela de visualização e revise as legendas contendo termos técnicos.
Mantenha a gravação original junto com a versão editada. O corte pode ocultar informações importantes, incluindo a borda da janela de visualização que demonstra um defeito de estouro.
O vídeo deve complementar as etapas escritas. Um colega de equipe deve ser capaz de reproduzir o problema sem transcrever a narração.
4. Combine evidências visuais com diagnósticos do navegador
Uma gravação mostra um comportamento visível, mas não consegue estabelecer por que o aplicativo se comportou dessa maneira.
Use o painel Elementos para inspecionar as dimensões calculadas da caixa de diálogo. Verifique larguras fixas, larguras mínimas, preenchimento e filhos que não podem encolher. Use o painel Rede se a falha envolver uma solicitação.
SitePoints guia para DevTools do navegador, inspeção de rede e desempenho fornece informações básicas sobre essas investigações.
Para uma medição rápida de estouro:
const root = document.documentElement;
console.table({
layoutWidth: root.clientWidth,
contentWidth: root.scrollWidth,
overflowPixels: Math.max(
0,
root.scrollWidth - root.clientWidth
)
});
Isso mede o estouro horizontal no nível do documento. Não localiza o elemento responsável nem prova que o diálogo o causou. O estouro dentro de um contêiner de rolagem aninhado precisa de inspeção separada.
Se aparecer uma exceção, anexe seu rastreamento de pilha relevante e a compilação associada. SitePoints artigo sobre registro de erros do lado do cliente explica a função do contexto de erro na depuração.
Revise a saída do console, as gravações e as exportações de rede antes de compartilhá-las. Esses artefatos podem conter credenciais ou dados de aplicativos.
5. Reduza a reprodução antes de escrever um teste
Reproduza a falha com o mínimo de dependências possível.
Requer uma função de conta específica? Um rótulo longo? Uma resposta atrasada da API? Um navegador específico? Altere uma condição de cada vez e registre o resultado.
Para o exemplo do diálogo, imagine que a investigação identifica:
.settings-dialog {
width: 640px;
padding: 24px;
}
Uma largura fixa pode exceder uma janela de visualização estreita. Uma possível correção é:
.settings-dialog {
box-sizing: border-box;
width: min(640px, calc(100% - 32px));
max-height: calc(100dvh - 32px);
overflow-y: auto;
}
Isso pressupõe que o bloco que contém a caixa de diálogo abrange a janela de visualização. Verifique essa suposição no layout real do seu componente.
Inspecione também o conteúdo filho. Sequências longas e ininterruptas e itens flexíveis com dimensionamento mínimo restritivo ainda podem transbordar após a correção da caixa de diálogo externa.
6. Converta o comportamento esperado em um teste de regressão
O teste abaixo pressupõe um projeto existente do Playwright Test e uma aplicação local em http://localhost:3000. A página expõe um botão Configurações de perfil e uma caixa de diálogo acessível chamada Configurações de perfil.
Adapte a rota, os dados de configuração e os nomes acessíveis à sua aplicação:
import { test, expect } from '@playwright/test';
test.use({
viewport: { width: 390, height: 844 }
});
test('profile settings fits a narrow viewport', async ({ page }) => {
await page.goto('http://localhost:3000/settings');
await page.getByRole('button', {
name: 'Profile settings',
exact: true
}).click();
const dialog = page.getByRole('dialog', {
name: 'Profile settings',
exact: true
});
await expect(dialog).toBeVisible();
await expect.poll(async () => {
return dialog.evaluate(element => {
const bounds = element.getBoundingClientRect();
const width = document.documentElement.clientWidth;
return bounds.left >= -1 && bounds.right <= width + 1;
});
}).toBe(true);
await expect.poll(() => page.evaluate(() => {
const root = document.documentElement;
return root.scrollWidth - root.clientWidth;
})).toBeLessThanOrEqual(1);
});
A tolerância de um pixel acomoda pequenas diferenças de arredondamento. Escolha tolerâncias com base no comportamento que você está testando.
A sondagem verifica novamente a geometria enquanto a caixa de diálogo é estabelecida. Evita inserir um atraso fixo arbitrário. Dramaturgo documentação de afirmação explica a repetição de afirmações e pesquisas.
Este teste verifica limites horizontais e estouro de documento. Isso não prova que Salvar seja acessível pelo teclado, que o foco seja gerenciado corretamente ou que o envio do formulário funcione. Adicione verificações focadas para esses comportamentos quando eles pertencerem ao defeito.
SitePoints guia para automação confiável do navegador com Playwright fornece leitura adicional sobre a estrutura do teste e o estado do navegador.
7. Preservar artefatos de diagnóstico
Para uma investigação local, execute:
npx playwright test --trace on
npx playwright show-report
Os rastreamentos do Playwright permitem inspecionar ações gravadas, instantâneos do DOM e outros detalhes de execução. Eles complementam a gravação do usuário com evidências da reprodução automatizada.
Para CI, uma configuração possível é:
import { defineConfig } from '@playwright/test';
export default defineConfig({
retries: process.env.CI ? 1 : 0,
use: {
trace: 'on-first-retry'
}
});
Isso captura um rastreamento na primeira tentativa, portanto, o rastreamento depende da ocorrência real de uma nova tentativa. Use o guia oficial do Trace Viewer para escolher uma política adequada ao seu projeto.
Mantenha o resultado da falha original quando uma nova tentativa for aprovada. Uma nova tentativa aprovada pode indicar um comportamento intermitente em vez de um defeito resolvido.
Depois que a correção for verificada, um breve passo a passo editado pelo Veed pode explicar o comportamento antes e depois para o controle de qualidade ou outro revisor. Anexe-o junto com o teste de regressão e descreva exatamente o que o teste cobre.
Feche o relatório com evidências
Uma resolução útil conecta o sintoma relatado à alteração verificada: a caixa de diálogo cabe na janela de visualização relatada, o excesso de documento está ausente e o teste de regressão cobre essa condição.
Registre quaisquer limites, como navegadores ou métodos de entrada que ainda não foram testados.
O resultado é um relatório de bug que se torna uma investigação repetível, uma correção revisável e um teste durável para alterações futuras.
