Teste e Depuração de Frontend

O que Teste e Depuração de Frontend faz?

Contrato de Invocação

Esta skill deve funcionar a partir de prompts normais do usuário. Não exija que o usuário especifique roteamento do Browser, capturas de tela, formato do relatório ou política de fallback.

Use esta skill quando o usuário pedir para usar o plugin Build Web Apps, plugin web dev, plugin frontend dev ou a skill de teste/depuração de frontend para uma mudança, teste ou investigação de bug em um frontend renderizado.

Exemplos que devem acionar este fluxo de trabalho completo:

• faça uma melhoria na área de busca de transações do painel web e use o plugin web dev
• use o plugin frontend dev para polir este painel
• depure esta UI com o plugin Build Web Apps
• teste este aplicativo localhost e corrija a interação quebrada

A partir de um prompt breve, infira a superfície alvo a partir do repositório, URL do aplicativo/navegador atualmente aberto, arquivos próximos ou servidor de desenvolvimento em execução. Se a URL alvo não estiver clara, inspecione os scripts do repositório e as portas locais em execução antes de perguntar ao usuário.

Para qualquer mudança de código em uma superfície frontend renderizada, faça o loop de validação por padrão:

1. Identifique o fluxo alvo.
2. Escolha o caminho do Browser abaixo.
3. Faça a menor edição útil.
4. Valide o comportamento renderizado.
5. Responda com o relatório final de QA.

Escolha o Caminho do Browser

Primeiro, classifique a disponibilidade do Browser:

• Disponível: o plugin Browser e sua skill browser estão listados na sessão. Leia e siga essa skill antes de qualquer ação no navegador.
• Ausente: o plugin Browser ou a skill browser não está listada. Use o Playwright comum e registre Plugin Browser não disponível.
• Falha na invocação: o Browser parece disponível, mas a skill/runtime, configuração do JavaScript REPL do Node, aquisição de aba ou navegação falham. Trate isso como um bloqueio do caminho do Browser.

Não use Playwright comum, Chrome externo ou o comando shell open primeiro quando o Browser estiver disponível.

Mude de uma invocação falha do Browser para o Playwright comum apenas se o usuário já permitiu o fallback ou a tarefa permite explicitamente validação sem Browser. Nesse caso, relate a falha exata do Browser e a decisão de fallback.

Fluxo Alvo

Antes da validação no navegador, defina o fluxo alvo em uma frase:

O fluxo sob teste é: [rota de entrada] -> [ação do usuário ou estado] -> [resultado renderizado esperado].

Se o usuário pediu um teste geral de fumaça, use:

O fluxo sob teste é: aplicativo carrega -> primeira tela significativa é renderizada -> controles visíveis primários respondem sem erros de runtime.

Loop do Plugin Browser

Execute comandos do Browser através da ferramenta JavaScript REPL do Node descrita pela skill do Browser. Não invente um caminho separado de configuração do navegador. Continue usando a mesma vinculação de aba, a menos que a skill do Browser diga o contrário.

Sequência necessária:

1. Carregue o runtime do Browser exatamente como a skill do Browser instrui.
2. Nomeie a sessão com agent.browser.nameSession("...").
3. Adquira uma aba com agent.browser.tabs.selected() ou agent.browser.tabs.new().
4. Navegue com tab.goto(url).
5. Execute as verificações necessárias abaixo.
6. Interaja com localizadores tab.playwright ou APIs de interação da skill do Browser.
7. Após edições, chame await tab.reload(), depois repita as verificações e a interação com falha.

Para cada ação de mudança de UI, colete a prova mais barata de que o próximo estado está correto: snapshot novo do DOM, texto/estado visível, mudança de URL, controle focado, toast, modal, captura de tela ou log do console.

Verificações Necessárias do Browser

Execute estas verificações antes de afirmar que o aplicativo renderizado funciona:

1. Identidade da página: await tab.url() e await tab.title() correspondem à página pretendida.
2. Não está em branco: await tab.playwright.domSnapshot() contém conteúdo significativo do aplicativo, não um shell vazio.
3. Sem sobreposição de framework: o snapshot ou captura de tela não mostra uma sobreposição de erro do Next.js, Vite, Webpack ou framework.
4. Saúde do console: await tab.dev.logs({ levels: ["error", "warn"], limit: 50 }) não tem erros relevantes do aplicativo, ou cada erro relevante é explicado.
5. Evidência de captura de tela: await display(await tab.playwright.screenshot({ fullPage: false })) suporta afirmações visuais.
6. Prova de interação: pelo menos uma interação do fluxo alvo é exercitada e seguida por uma verificação de estado.

Para trabalho visual, adicione o viewport de desktop e um de tamanho mobile quando prático. Para trabalho orientado por referência, mantenha um pequeno registro de discrepâncias: evidência de referência, evidência renderizada, correção ou desvio intencional.

Loop do Playwright

Use este ramo quando o Browser não estiver disponível, ou quando o usuário permitiu fallback após uma falha de invocação do Browser.

Use esta ordem:

1. Encontre scripts em package.json.
2. Inicie o aplicativo com o gerenciador de pacotes do repositório e mantenha o host solicitado exato.
3. Prefira o script e2e do repositório se presente.
4. Caso contrário, execute pnpm exec playwright test ou o equivalente do gerenciador de pacotes quando o Playwright estiver configurado.
5. Se não houver fluxo de trabalho Playwright no projeto, verifique o Playwright com pnpm exec playwright --version, então capture uma captura de tela com pnpm exec playwright screenshot <url> /tmp/frontend-check.png.
6. Para depuração mais profunda, crie um pequeno script Playwright temporário fora do código fonte confirmado que abre a URL, captura erros do console, capturas de tela e executa a interação alvo.
7. Após edições, execute novamente o mesmo comando ou script.

Não instale novas dependências de navegador a menos que a tarefa exija e o usuário tenha permitido mudanças de dependências.

Lista de Verificação de Validação

• Mantenha o host solicitado exato.
• Verifique se os controles atualizam o estado real da UI.
• Verifique o primeiro viewport antes de rolar, mais desktop e um viewport de tamanho mobile quando prático.
• Procure por corte, sobreposição, texto ilegível, quebra de linha, mudança de layout, ativos faltando, problemas de z-index, armadilhas de rolagem, carregamento obsoleto e estados quebrados.
• Para trabalho orientado por referência, compare a captura de tela renderizada com a referência e mantenha um pequeno registro de discrepâncias.
• Uma compilação bem-sucedida não é suficiente quando a validação renderizada foi solicitada.

Relatório de Resposta Final de QA

Para qualquer execução de validação de UI renderizada não trivial, escreva a resposta final como um engenheiro de QA verificando uma mudança de código. A resposta deve facilitar para o usuário ou revisor do PR entender o que mudou, o que foi testado, qual evidência prova isso e o que permanece não testado.

Use este formato:

• Resumo: um ou dois tópicos explicando a mudança visível ao usuário e se o QA passou.
• Ambiente: URL, viewport(s), classificação de disponibilidade do Browser e motivo do fallback se o Playwright foi usado.
• Mudanças Verificadas: arquivos ou superfícies alterados, mais o comportamento específico voltado ao usuário esperado.
• Verificações: uma tabela de aprovado/reprovado para identidade da página, verificação de página em branco, verificação de sobreposição de framework, saúde do console, evidência de captura de tela e prova de interação.
• Loop de Interação: caminho de interação exato testado, incluindo o controle ou fluxo de trabalho exercitado e a mudança de estado observada.
• Evidência: descreva a evidência da captura de tela nas seções de QA, então coloque as capturas de tela reais juntas no final da resposta como imagens consecutivas. Inclua quantas capturas de tela forem úteis para provar os estados antes, depois, interação, responsivo, erro ou corrigido relevantes.
• Comandos / APIs do Browser: liste a sequência principal de comandos e APIs do Browser usada, sem despejar logs ruidosos.
• Risco Restante: viewports, fluxos, navegadores, estados de dados ou limitações conhecidas não testados.

Se problemas foram encontrados, comece com Descobertas antes do resumo. Cada descoberta deve incluir o que o usuário vê, etapas de reprodução, evidência de captura de tela/DOM/console, provável proprietário ou arquivo quando conhecido, e a correção feita ou bloqueador restante.

Ao usar capturas de tela do Browser que devem ser mostradas ao usuário, emita ou exiba a captura de tela através do runtime do Browser para que possa ser referenciada no chat. Ao usar capturas de tela do Playwright, salve-as fora do repositório e referencie-as no chat. Inclua várias capturas de tela quando elas ajudarem a verificar estados ou fluxos distintos.

Não intercale capturas de tela ao longo do relatório escrito. Coloque uma pequena seção Capturas de Tela no final, e faça dela uma galeria de imagens consecutivas com uma imagem por linha. Adicione rótulos curtos apenas quando eles esclarecerem o estado, por exemplo Antes, Depois, Resultados filtrados, Estado vazio ou Mobile.

Não crie relatórios HTML separados por padrão. Crie um arquivo de relatório independente apenas quando o usuário pedir explicitamente por um, e escreva-o fora do repositório a menos que o usuário peça explicitamente por artefatos confirmados.

Não escreva relatórios, capturas de tela, rastros ou scripts temporários no repositório a menos que o usuário peça explicitamente por artefatos confirmados.

Skills Relacionadas

• Use frontend-app-builder quando a tarefa for criação de design, redesign ou fidelidade a um conceito aceito.
• Use react-best-practices após edições significativas de componentes React/Next.js.
• Não invoque Geração de Imagem para depuração comum. Use-a apenas quando a tarefa exigir criar ou revisar ativos visuais, ou quando frontend-app-builder já estiver conduzindo um loop de fidelidade de conceito a implementação.

Resposta Final

Use o formato de relatório de resposta final de QA acima. Mantenha-o conciso, mas inclua evidência concreta suficiente para que um revisor de PR possa confiar na validação sem executá-la novamente imediatamente.

Se o Browser estava ausente e o Playwright foi usado, termine sugerindo que o usuário instale o plugin Browser para uma melhor experiência de desenvolvimento frontend com navegação no aplicativo, capturas de tela, snapshots do DOM, logs do console e validação de interação.