fix

Visão geral do fix skill

O que o fix skill faz

O fix skill é um fluxo de depuração focado para testes Playwright com falhas constantes ou intermitentes. Ele ajuda um agente de IA a sair de “este teste quebrou” para uma causa raiz provável, reproduzindo a falha, capturando evidências com trace e classificando o problema com uma taxonomia de testes flaky, em vez de tentar adivinhar apenas pelo erro da asserção.

Melhor uso para depurar testes Playwright

Instale este skill se você mantém testes end-to-end e vê com frequência mensagens como “test failing”, “flaky test”, “passes locally but fails in CI” ou “intermittent failure”. Ele é especialmente útil para equipes que usam Playwright em CI, onde as falhas podem vir de timing, isolamento de testes, diferenças de ambiente ou pressão na infraestrutura.

Por que ele é mais útil que um prompt genérico

Um prompt genérico de depuração costuma pular direto para alterações no código. O fix skill impõe uma sequência melhor: reproduzir primeiro, fazer burn-in se a falha desaparecer, capturar traces e só então mapear os sintomas para categorias. O arquivo complementar flaky-taxonomy.md traz ramos de diagnóstico e padrões de correção concretos, incluindo await ausente, estado compartilhado, diferenças de viewport/fonte/timezone apenas no CI, crashes de browser e instabilidade relacionada a workers.

Limitações importantes antes de instalar

Este não é um corretor universal de bugs. O escopo é testes Playwright, e ele pressupõe que o agente consiga inspecionar seu arquivo de teste, executar comandos Playwright e ler saídas como traces, screenshots, logs ou texto de falha do CI. Ele não inclui scripts auxiliares; o valor vem do fluxo de trabalho e da taxonomia, não de automação.

Como usar o fix skill

Instalação do fix e arquivos para inspecionar primeiro

Instale o skill em um ambiente compatível com skills usando:

npx skills add alirezarezvani/claude-skills --skill fix

Depois de instalar, leia SKILL.md primeiro para entender o fluxo de execução; em seguida, abra flaky-taxonomy.md para ver a árvore de decisão e correções comuns. O caminho do repositório é engineering-team/playwright-pro/skills/fix, e os arquivos-fonte úteis são intencionalmente pequenos: não há scripts, regras ou arquivos de metadados ocultos para configurar.

Entradas de que o fix skill precisa

Para melhores resultados, forneça pelo menos uma destas entradas:

• Caminho do arquivo de teste, como e2e/login.spec.ts
• Nome exato do teste ou string de --grep
• Mensagem de falha, stack trace ou erro de asserção
• Se a falha acontece localmente, no CI ou em ambos
• Se passa sozinho, mas falha na suíte completa
• Caminho de trace, screenshot, vídeo ou artefato de CI, se disponível
• Configuração relevante do Playwright, especialmente workers, retries, projects, viewport, timezone e base URL

Prompt fraco: “Fix my flaky checkout test.”

Prompt melhor: “Use the fix skill for Debugging e2e/checkout.spec.ts, test should submit paid order. It passes locally alone, fails in CI about 30% of runs, and the failure is Timeout 5000ms exceeded waiting for getByRole('button', { name: 'Pay' }). CI uses 4 workers and retries=2. Suggest the reproduction commands, likely category, and minimal code/config changes.”

Fluxo prático de uso do fix

Comece pelo arquivo exato que está falhando:

npx playwright test <file> --reporter=list

Se passar, trate como potencialmente flaky e rode burn-in:

npx playwright test <file> --repeat-each=10 --reporter=list

Se o problema aparecer apenas com concorrência, rode com paralelismo:

npx playwright test --fully-parallel --workers=4 --repeat-each=5

Depois, capture evidências com trace:

npx playwright test <file> --trace=on --retries=0

Peça ao agente para classificar a falha antes de editar. As categorias esperadas são timing/async, isolamento de testes, ambiente ou infraestrutura. Isso evita correções ruins comuns, como adicionar waitForTimeout arbitrário, aumentar timeouts globais ou esconder uma race real atrás de retries.

Padrão de prompt para melhores resultados

Use um prompt que separe evidências do pedido:

“Use the fix skill. Diagnose before changing code. Test: <file> / <test name>. Reproduction result: <passes/fails command>. CI/local behavior: <details>. Trace or screenshot: <path or summary>. Current suspicion: <optional>. Please categorize using flaky-taxonomy.md, explain the evidence, propose the smallest safe fix, and list the command to verify it.”

Essa estrutura ajuda o skill a produzir um plano de depuração testável, em vez de um patch especulativo.

FAQ do fix skill

O fix serve apenas para testes flaky?

Não. O fix skill lida tanto com testes Playwright que falham de forma consistente quanto com falhas intermitentes. Para falhas determinísticas, ele ainda começa com reprodução e captura de trace. Para falhas intermitentes, adiciona burn-in e verificações com workers paralelos para expor padrões de timing, isolamento ou infraestrutura.

Quando eu não devo usar este skill?

Não use como ferramenta principal para testes unitários, testes de integração backend, bugs de produção sem cobertura Playwright ou depuração ampla de arquitetura da aplicação. Ele ainda pode oferecer ideias gerais, mas seus comandos, taxonomia e exemplos foram escritos para testes end-to-end com Playwright.

Como ele se compara ao Playwright trace viewer sozinho?

O trace viewer mostra o que aconteceu; o fix skill ajuda a decidir o que aquele trace significa. Por exemplo, um elemento ausente pode indicar uma race assíncrona, estado vazado de um teste anterior, diferença de viewport no CI ou dependência de rede. A taxonomia transforma artefatos em um caminho de diagnóstico e em um tipo de correção sugerido.

O fix é amigável para iniciantes?

Sim, desde que a pessoa consiga executar comandos Playwright e compartilhar erros. Iniciantes se beneficiam da sequência explícita de comandos e da tabela de categorias. Ainda assim, o skill não substitui conhecimentos básicos de setup do projeto: o Playwright já precisa estar instalado, a suíte de testes precisa ser executável e os artefatos precisam estar acessíveis.

Como melhorar o fix skill

Forneça evidências de falha mais fortes ao fix

A melhoria mais importante é aumentar a qualidade das entradas. Inclua os comandos exatos já testados e seus resultados. “Fails in CI” é menos útil do que “fails in CI with 4 workers, passes locally with one worker, fails locally with --fully-parallel --workers=4 --repeat-each=5.” Esse único detalhe aponta para isolamento ou paralelismo, em vez de timing genérico.

Evite modos comuns de falha na depuração

Não peça um patch antes do diagnóstico. Resultados ruins comuns incluem adicionar sleeps fixos, elevar timeouts globais, ativar mais retries ou reescrever seletores sem confirmar a causa. Peça ao skill para declarar a categoria, as evidências, a menor correção segura e o comando de verificação antes de editar código.

Itere depois da primeira correção

Depois de aplicar uma mudança proposta, rode novamente o menor comando de verificação que faça sentido. Se a correção mirou timing, use burn-in. Se mirou isolamento, compare o comportamento de um teste sozinho com o da suíte. Se mirou ambiente de CI, reproduza com configurações mais próximas do CI, como Docker, workers, timezone, viewport ou serviços de rede mockados.

Estenda o guia do fix para o seu projeto

As equipes podem melhorar os resultados locais adicionando notas específicas do projeto perto do fluxo do skill: configurações comuns de CI, serviços conhecidos por gerar flakes, resets obrigatórios de dados de teste, fixtures padrão, estratégia de mocks e convenções preferidas de locators. O fix skill funciona melhor quando sua taxonomia é combinada com os padrões reais de falha do seu repositório.