O que Automação QA com Python (pytest e Playwright) faz?
Contrato de Entrega
- Trate este skill como o loop interno de QA, após a expectativa de negócio estar clara.
- Complete uma entrega imediata por invocação. Não passe automaticamente do design para implementação, integração ou reparo de falhas.
- Mantenha API e UI como modos separados. No modo UI, use chamadas de API apenas para setup, limpeza ou verificações pós-condição vinculadas ao cenário de UI.
- Passe pelos portões
Clarified,ReadyeVerifiedcom evidências; invocar o skill não é evidência de conclusão.
Pré-voo
- Leia
references/common-rules.md. - Resolva
<skill-dir>para o diretório que contém esteSKILL.md; execute scripts empacotados a partir desse diretório, não do projeto alvo. - Identifique a raiz do projeto alvo e leia suas instruções, manifestos, testes relevantes e
git statusantes de editar. - Identifique o material de origem, o resultado esperado, os limites do ambiente, a propriedade dos dados e o método de verificação; exija um comando para rotas que produzem código.
- Se um resultado esperado não puder ser encontrado ou confirmado, pare no design do teste e marque o cenário como exploratório/manual, em vez de inventar uma asserção.
Selecione uma Rota
Escolha exatamente uma rota de entrega com base no resultado imediato solicitado pelo usuário. Trate o material de origem e o modo API/UI como entradas para a rota, não como rotas adicionais.
| Rota | Use quando a entrega imediata for | Referência obrigatória | Concluído quando |
|---|---|---|---|
test-design | Uma matriz de cobertura ou recomendação de automação, sem código | references/test-design.md | Resultados esperados, camada, prioridade, dados e decisão de automação estão explícitos |
new-project | Um scaffold mínimo executável de pytest em um alvo novo/vazio | Guia do modo selecionado | O scaffold valida e pelo menos um teste smoke significativo coleta ou executa |
existing-project | A menor alteração de teste compatível em um repositório existente | references/existing-project.md + guia do modo selecionado | As convenções do projeto são preservadas e a verificação afetada passa |
delivery-integration | CI, Jenkins, relatórios, portões de release ou smoke de performance | references/delivery-integrations.md | A integração solicitada é adicionada e as partes verificáveis localmente são validadas |
failure-analysis | Classificação ou reparo baseado em evidências de um teste com falha | references/failure-analysis.md | A causa raiz é suportada, ou a próxima sonda ausente é nomeada |
Não combine rotas apenas porque uma tarefa contém um requisito, um repositório existente e um fluxo de UI. Por exemplo, adicionar cobertura de checkout a um projeto Playwright existente é existing-project no modo ui; carregue test-design.md como orientação de suporte quando os pontos de teste ainda não estiverem aprovados.
Selecione um Modo Quando Necessário
- Para
test-design, deixe a matriz selecionar a camada confiável mais baixa; não force API ou UI antes dessa decisão. - Selecione
apipara comportamento de endpoint, contratos, autenticação, validação, estado e integrações. Leiareferences/api-mode.md. - Selecione
uipara comportamento do navegador, validação do cliente, interação dependente de layout e jornadas críticas do usuário. Leiareferences/ui-mode.md. - Não exija um modo para trabalho exclusivo de entrega ou análise de falhas quando o projeto existente e as evidências já determinam a stack.
- Se a entrega solicitada criasse suites paralelas de API e UI, peça ao usuário para escolher uma. Chamadas de API para setup/limpeza na UI não contam como uma suite de API paralela.
Carregar Referências Condicionais
- Leia
references/test-design.mdpara requisitos, histórias de usuário, tickets de bug, escopo de release, screenshots ou qualquer alteração cujos pontos de teste não estejam aprovados. - Leia
references/test-data.mdpara login, criar/atualizar/deletar, uploads, dados de seed, setup/cleanup ou verificações de estado do lado do servidor. - Leia
references/flaky-diagnosis.mdpara falhas intermitentes, temporização, esperas, retentativas, polling, UI dinâmica ou interferência paralela. - Leia
references/api-contracts.mdpara schemas, contratos, compatibilidade, permissões, papéis, tenants, ownership ou cobertura de códigos de erro. - Leia
references/advanced-ui.mdpara Appium/mobile, regressão visual, múltiplas abas/janelas, downloads, uploads, diálogos, iframes ou estado complexo do navegador.
Portões e Ativos do Projeto
Passe por estes portões em ordem:
- Clarified: fonte, proprietário ou autoridade, resultado esperado, escopo e não-escopo estão explícitos.
- Ready: rota, modo (quando necessário), arquivos alvo para trabalho que produz código, limite de dados/limpeza, segurança do ambiente e método de verificação estão explícitos.
- Verified: rotas que produzem código executaram o comando alvo e a regressão relevante; rotas apenas de design rastreiam cada resultado esperado até uma fonte aprovada. Informe cada parte não verificada e o motivo.
Se o projeto alvo possui um TEST_PLAN.md ou suas instruções exigem um, leia-o antes de selecionar a cobertura, defina o cenário ativo como In Progress antes da implementação e marque-o como Automated somente após a verificação. Não introduza TEST_PLAN.md em projetos que não o utilizam, a menos que o usuário ou as regras do projeto exijam.
Execute a Rota Selecionada
- Para
existing-project, inspecione o repositório e leia os arquivos relatados antes de editar. - Informe a rota selecionada, modo, entrega imediata, arquivos alvo e não-escopo explícito.
- Produza ou confirme pontos de teste antes do código quando o comportamento esperado ainda não estiver aprovado.
- Faça a menor alteração que complete a rota selecionada; preserve a estrutura do projeto existente e evite trabalho adjacente de backlog.
- Execute primeiro a verificação alvo específica, depois o comando de regressão relevante.
- Atualize o status do plano de teste do projeto somente após o portão correspondente ser aprovado.
- Pare na condição de conclusão da rota selecionada e retorne o handoff. Não invoque outro skill ou rota automaticamente.
Para test-design, não edite código de automação. Para failure-analysis, não edite quando o resultado solicitado for apenas diagnóstico; repare somente quando o usuário solicitou uma correção e as evidências suportam a causa raiz.
Ferramentas Empacotadas
Substitua <skill-dir> pelo diretório absoluto deste skill.
Inspecionar um projeto existente:
python "<skill-dir>/scripts/inspect_project.py" "<project-dir>"
Criar scaffold apenas em um alvo novo ou vazio:
python "<skill-dir>/scripts/scaffold.py" --mode api --out "<output-dir>" --project-name "<name>"
python "<skill-dir>/scripts/scaffold.py" --mode ui --out "<output-dir>" --project-name "<name>"
O scaffold se recusa a sobrescrever arquivos existentes. Não use --force a menos que o usuário explicitamente peça para substituir arquivos gerados.
Validar código Python/TOML gerado ou editado:
python "<skill-dir>/scripts/validate_generated.py" "<project-dir>"
python "<skill-dir>/scripts/validate_generated.py" "<project-dir>" --collect
Use o próprio comando de teste do projeto alvo como verificação primária para projetos existentes. Trate o status partial do validador como não verificado; instale dependências no ambiente do projeto alvo antes de declarar que a coleta passou. Para execução de UI, garanta que o navegador Playwright necessário esteja instalado.
Handoff
Relate:
- rota e modo selecionados;
- fonte do requisito e resultado esperado usados como oráculo;
- arquivos alterados, mais o status do
TEST_PLAN.mdquando aplicável; - comandos de verificação e resultado exato (pass, fail, partial ou skipped);
- trabalho não verificado, risco restante e a próxima decisão se outra rota for necessária.
Não Escopo
- Não construa frameworks híbridos API+UI por padrão.
- No modo UI, não adicione cobertura ampla de endpoints de API; chamadas de API são apenas para setup, limpeza ou verificações pós-condição vinculadas ao cenário de UI.
- Não adicione CI, Jenkins, Allure, Appium, automação desktop, regressão visual ou testes de performance por padrão; adicione-os apenas quando explicitamente solicitados e escopados.
- Não crie
.env, armazene credenciais, chame sistemas de produção ou invente tokens reais. - Não adicione dependência de API LLM dentro do projeto de teste gerado. O agente hospedeiro realiza raciocínio e reparo.