plano-de-teste-manual

Escreve um plano de teste para verificar o branch atual no aplicativo em execução — casos com pré-condições, etapas e o resultado esperado exato, divididos entre o que um agente pode executar com um navegador ou simulador iOS e o que um humano precisa fazer manualmente, como teste de leitor de tela, com um ensaio do agente para cada caso humano através da árvore de acessibilidade e, onde um leitor de tela pode ser dirigido, uma transcrição real do leitor de tela. Use quando o usuário solicitar um plano de teste manual, uma checklist de QA, etapas de teste, o que testar manualmente, o que um agente pode testar ou como verificar um branch ou PR no aplicativo. Escreve o plano e depois oferece para fazer login no staging e executar a parte do agente; não executa nada até que o usuário diga sim, e não edita código.

O que é plano-de-teste-manual?

Este skill, chamado 'plano-de-teste-manual', é projetado para gerar um plano de teste abrangente e focado para verificar um branch específico em um aplicativo em execução. Ele preenche a lacuna deixada por testes automatizados, concentrando-se em aspectos que só podem ser validados visualmente ou com dados reais, como layout, comportamento em fluxos reais e interações complexas. O plano categoriza cada caso de teste como executável por um agente (usando um navegador ou simulador iOS) ou manual (exigindo intervenção humana). Antes que um humano execute um caso manual, o agente realiza um 'ensaio' usando a árvore de acessibilidade para detectar problemas óbvios, economizando tempo. O plano é mantido enxuto e direcionado, priorizando casos com maior probabilidade de revelar bugs críticos que não podem ser cobertos por testes de código tradicionais. Ele é escrito e executado tardiamente no ciclo de desenvolvimento, após revisões de código e testes automatizados estarem em vigor. O skill suporta plataformas como web via navegador embutido e iOS via simulador, além de scripts de navegador como Playwright e leitores de tela como VoiceOver. A geração do plano se baseia em fontes essenciais: o diff do branch, o pull request e seus comentários, a issue vinculada e a conversa em andamento, garantindo que o plano seja informado por todas as discussões e decisões relevantes.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MagnusBrogie/agent-skills/tree/HEAD/manual-test-plan

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Plano de teste manual

Escreva o plano para verificar este branch no aplicativo em execução. O plano cobre o que os testes automatizados não podem mostrar: como a alteração se parece e se comporta com dados reais, em fluxos reais, através dos estados que um usuário pode alcançar.

Cada caso é atribuído a quem pode resolvê-lo: um agente dirigindo um navegador, um agente dirigindo um simulador iOS ou um humano. Dê ao agente tudo o que um agente pode resolver. Para os casos que apenas um humano pode resolver, faça com que um agente os tente primeiro como um ensaio, para que os problemas óbvios sejam encontrados antes que uma pessoa gaste tempo com eles e a pessoa saiba onde procurar.

Executar um caso no aplicativo é caro. Um agente dirigindo um navegador gasta muitas vezes os tokens de um teste de código para a mesma verificação, e uma pessoa gasta minutos. Portanto, o plano é pequeno e direcionado: contém os casos com maior probabilidade de expor um bug que importa, e nada que um teste em código possa cobrir igualmente bem. Um bom plano é curto o suficiente para ser executado por completo.

Pela mesma razão, escreva e execute o plano tardiamente: após as revisões que leem o código, após as correções e refatorações que elas geram, e após os testes de código estarem em vigor. Então o plano é executado uma vez, no código que será mesclado, e as passagens anteriores já realizaram as verificações que são baratas. Se o código ainda estiver mudando, diga isso no topo do plano. Se ele mudar após o plano ter sido executado, nomeie os casos que precisam ser executados novamente: aqueles cuja linha "Pega" aponta para o código alterado.

Notas locais. Se um arquivo chamado LOCAL.md estiver ao lado deste arquivo, leia-o antes de começar. Ele contém as próprias configurações padrão do usuário para os projetos em que trabalha (comandos, hosts, contas, caminhos) e não faz parte do skill publicado. Onde ele cobre o projeto em questão, conta como parte das instruções do projeto; onde não cobre, ignore-o.

Reunir as alterações

A solicitação pode nomear um branch base. Se nenhum for fornecido, escolha-o nesta ordem:

  1. O branch base do pull request do branch, se ele tiver um: gh pr view --json baseRefName --jq .baseRefName.
  2. O branch padrão do repositório: git symbolic-ref --short refs/remotes/origin/HEAD.
  3. origin/main, depois main.

Use a ref de rastreamento remota (origin/<branch>) em preferência a um branch local com o mesmo nome. Inclua o trabalho que ainda não foi commitado:

base=$(git merge-base <base> HEAD)
git diff --stat "$base"          # commitado + staged + unstaged
git diff "$base"
git status --short               # arquivos não rastreados não estão no diff; leia-os
git log --oneline "$base"..HEAD

Ler as três fontes que o diff não contém

O diff mostra o que mudou. Ele não mostra para que serve a alteração, o que as pessoas já viram dar errado ou o que foi decidido nesta conversa. Leia todas as três antes de escolher qualquer caso. Elas são entrada obrigatória, não contexto; o plano relata o que foi lido e mostra onde cada fonte o moldou.

1. O pull request e seus comentários

pr=$(gh pr view --json number --jq .number)
gh pr view --json title,body,baseRefName
for kind in "issues/$pr/comments" "pulls/$pr/reviews" "pulls/$pr/comments"; do
  gh api "repos/{owner}/{repo}/$kind" --paginate --jq '.[]
    | select(.user.type != "Bot" and (.body // "") != "")
    | {id, reply_to: .in_reply_to_id, user: .user.login, path, line: (.line // .original_line), body}'
done

As três listas são os comentários da conversa, os resumos das revisões e os comentários inline nas linhas do diff, com a saída do bot omitida. Os bots ainda estão onde um link de implantação geralmente está, então procure por isso separadamente. O ambiente implantado não é onde o plano é executado (veja "Testar uma compilação local" abaixo); o link é para comparações e como fallback:

gh api "repos/{owner}/{repo}/issues/$pr/comments" --paginate \
  --jq '.[] | select(.user.type == "Bot") | .body' | grep -oE 'https?://[^ )|>"]+' | sort -u

Leia a descrição, cada comentário humano e as respostas do autor. Um relatório na descrição conta o mesmo que um em um comentário. Extraia deles:

  • Qualquer coisa que uma pessoa viu no aplicativo: um valor errado, um estado que nunca termina, um fluxo quebrado, uma captura de tela. Cada um se torna um caso que retesta esse relatório exato, independentemente de o código ter mudado desde então. Depois, pergunte onde mais a mesma falha poderia aparecer (as telas irmãs, o mesmo estado alcançado de outra forma) e considere um caso lá.
  • Dúvidas sobre o comportamento levantadas na revisão ("a ordem pode discordar do que é mostrado"): cada uma é um caso candidato, classificado como alta probabilidade, porque um leitor do código já suspeitou dela.
  • Notas de teste na descrição: o que o autor diz que testou e o que diz que não testou. Date as notas em relação ao log de commits (git log --format='%h %ad %s' --date=short "$base"..HEAD): o que foi testado antes de commits posteriores tocarem no mesmo código não foi testado em sua forma atual. Os commits que chegaram após o último teste manual são onde o plano deve mirar primeiro.
  • Links para ambientes implantados: a implantação do próprio branch e a da base, para comparações lado a lado.
  • Decisões tomadas no tópico sobre como algo deve se comportar. Estas resolvem os resultados esperados.

2. A issue

Encontre o identificador da issue no nome do branch, nos assuntos dos commits, no título ou corpo do pull request ou em um comentário de bot de rastreador no pull request. Consulte-o com o rastreador que as instruções do projeto nomeiam, usando a ferramenta disponível para ele. Leia a descrição, os critérios de aceitação, a discussão e quaisquer capturas de tela ou etapas de reprodução anexadas. Extraia dela:

  • O relatório original. Se a issue descreve um bug, suas etapas de reprodução se tornam o primeiro caso no plano: as etapas conforme relatadas, com o comportamento corrigido como resultado esperado. Se a issue for apenas um título, ou apontar para um tópico ou anexo que não pode ser lido, diga isso, reconstrua o caso a partir do título e da descrição do pull request e marque-o como reconstruído.
  • Cada critério de aceitação. Cada um deve terminar em um de três lugares: um caso no plano, um teste nomeado em código que o cobre ou a lista do que foi deixado de fora, com o motivo.
  • Os usuários, dados e plataformas afetados que a issue nomeia, que dizem qual forma de dados e qual dispositivo testar.
  • Issues relacionadas para as quais ela linka, onde descrevem a mesma área falhando de outra forma.

3. A conversa até agora

Volte nesta conversa antes de escrever. Extraia dela:

  • Conclusões da revisão: verifique cada uma contra a árvore atual primeiro, pois pode ter sido corrigida desde então. Uma conclusão que precisa do aplicativo em execução para confirmar ganha um caso: um que confirma a correção ou um que mostra a falha se ela foi deixada. Uma conclusão que um teste em código pode fixar vai para a lista de testes a escrever, não para os casos.
  • Listas "não verificado" e etapas de validação manual de passagens de revisão anteriores. Elas foram escritas para serem verificadas no aplicativo; são a entrada mais direta que existe.
  • O que o usuário disse sobre a alteração: as partes com as quais está preocupado, os estados que mencionou, o que já testou manualmente e o que disse para não gastar tempo. Uma preocupação declarada aumenta a classificação de um caso; "eu já verifiquei isso" o remove.
  • Decisões sobre o comportamento tomadas na conversa, que resolvem resultados esperados que o código sozinho deixa em aberto.
  • O que mudou no código durante a conversa. Código escrito ou reescrito nesta sessão teve o menor teste.

Se a conversa não contiver nada relevante, diga isso no plano; não finja que sim.

Quando uma fonte não pode ser lida

Se gh estiver faltando ou não estiver autenticado, o branch não tiver pull request, nenhuma issue estiver linkada ou o rastreador não puder ser alcançado, prossiga com o que houver. Nomeie cada fonte que não foi lida no topo do plano e diga que o plano pode perder o que ela continha. Não apresente um plano construído apenas a partir do diff como completo.

Ler o que mais influencia o plano

  • Como executar o aplicativo localmente: o comando documentado do projeto para uma compilação local, qual backend ele acessa e quais portas usa. Leia as instruções do projeto para ambientes de teste, contas de teste e flags de recurso, e para quais plataformas o aplicativo é distribuído (web, iOS, Android).

  • O que os testes automatizados cobrem: leia os testes no diff, para que o plano não gaste o tempo de ninguém no que um teste já fixa.

  • Quais ferramentas um agente tem aqui: um navegador que ele pode dirigir e um simulador de dispositivo. No Orca, estes são o navegador embutido (o skill orca-cli) e o Simulador iOS (o skill orca-emulator; orca-emulator-android para Android). Também procure por:

    • Um leitor de tela que o agente pode dirigir, como o skill voiceover, que executa o VoiceOver real do macOS contra uma página e retorna o que ele diz.
    • Um navegador com script (Playwright com um navegador instalado) para o que o navegador embutido não pode fazer. Por exemplo, o navegador embutido pode não colocar uma cópia na área de transferência do sistema, então verificar o que foi copiado precisa de um navegador cuja área de transferência o agente possa ler.

    Observe quais estão disponíveis nesta sessão; o plano diz isso em sua configuração.

Testar uma compilação local, não o branch implantado

Planeje cada caso contra uma compilação local da árvore de trabalho. Um ambiente de recurso ou pré-visualização implantado só tem o que foi commitado e enviado: ele fica atrás do código que está sendo trabalhado, não pode mostrar alterações não commitadas, e uma correção feita durante o teste precisaria de um commit e um push antes de poder ser retestada lá. Uma compilação local mostra o código como ele está agora, e uma correção pode ser retestada imediatamente.

A configuração do plano, portanto, diz:

  • Como construir e iniciar o aplicativo localmente, com o comando exato da documentação do projeto, o diretório para executá-lo e a URL na qual ele serve. Se outras sessões ou árvores de trabalho podem estar executando o aplicativo, diga como escolher portas livres.
  • Qual backend a compilação local acessa. Deve ser o backend de staging ou teste, nunca produção. Uma compilação local apontada para produção executa cada caso, incluindo os simulados e pedidos, contra os sistemas reais dos clientes. Projetos geralmente têm um comando por ambiente (por exemplo, um script stage e um prod): nomeie o de staging no plano e diga em palavras claras que o de produção não deve ser usado. Se a documentação do projeto não deixar claro qual comando visa qual backend, descubra a partir da configuração de compilação e, se ainda não estiver claro, pare e pergunte ao usuário; não adivinhe.
  • Como verificar o backend antes do primeiro caso: veja para onde o aplicativo em execução envia suas solicitações (o host de uma chamada de API no log de rede ou a URL de API configurada) e confirme que é o host de staging. O plano nomeia o host a esperar. Se for o host de produção, pare: não faça login e não execute nenhum caso.
  • Como saber que a compilação é o código atual: inicie-a a partir da árvore de trabalho após a última alteração e reconstrua ou recarregue após qualquer alteração adicional. Se o aplicativo mostrar uma versão ou commit, verifique-o.
  • Como pará-lo quando a execução terminar.

Use um ambiente implantado apenas para:

  • Comparar com a base: a implantação do branch base, ao lado da compilação local do branch, para os casos lado a lado.
  • O que uma compilação local não pode mostrar: um caso sobre a própria implantação, como ativos construídos, cache ou um aplicativo nativo que envolve o site implantado. Antes de tal caso, verifique se a árvore de trabalho está limpa e enviada e se a implantação serve esse commit, e diga isso no caso.
  • Um fallback quando o aplicativo não pode ser construído localmente. Diga o motivo no topo do plano e declare qual commit a implantação serve e o que está na árvore de trabalho que ela não tem.

A mesma regra vale para qualquer ambiente implantado que o plano use: a implantação de staging, nunca a de produção. Onde um branch tem ambas as implantações de staging e produção, forneça apenas a URL de staging no plano.

Determinar o que testar

  1. Liste o que um usuário pode ver ou fazer de diferente. Rastreie cada alteração no diff para fora, até as telas e fluxos que a mostram. Uma alteração no código compartilhado atinge todas as telas que o usam; procure pelos chamadores e liste todos, incluindo aqueles para os quais o branch não era destinado.

  2. Para cada um, decida se precisa do aplicativo em execução. Pergunte se um teste em código poderia resolvê-lo. Se um já o faz, deixe-o de fora. Se um poderia facilmente (uma função pura, um decodificador, uma ordem de classificação, uma função de visualização dado um estado, uma transição de estado), deixe-o de fora dos casos e coloque-o na lista de testes a escrever; essa verificação então é executada em cada alteração de graça, enquanto um caso no aplicativo é pago cada vez. Mantenha apenas o que um teste de código não pode alcançar ou não seria confiável para: como dados reais do backend real passam, o que é renderizado e disposto em um navegador real, como partes que são testadas separadamente se comportam quando unidas, temporização e ordenação de solicitações reais, o estado em que o aplicativo está após navegação real e o que é fornecido à tecnologia assistiva.

  3. Encontre os estados. Para cada tela, leia o código para os ramos que ela pode tomar: carregado, carregando, vazio, erro, dados ausentes ou parciais, valores zero e negativos, valores muito longos, um item e muitos, cada configuração ou modo que altera a exibição, cada tipo de conta ou usuário. Mantenha os estados que o diff toca.

  4. Determine como alcançar cada estado. Nomeie o caminho de navegação e descreva os dados que ele precisa pela sua forma ("um instrumento mantido em duas contas, uma delas sem custo de compra"), não por uma conta que você não confirmou que existe. Onde um estado é difícil de alcançar com dados reais, diga como pode ser produzido (uma flag de recurso, uma resposta reescrita, uma rede limitada, uma configuração) ou marque-o como precisando de uma conta de teste específica.

    Quando um caso depende de uma resposta reescrita, o plano deve tornar a reescrita reproduzível; reference/mocks.md diz como.

    Dê a cada caso um caminho que não dependa de sorte com os dados da conta. Se os dados reais podem não ter o estado, nomeie o controle no aplicativo que o ativa (uma configuração, uma alternância, outra conta) ou...

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Habilidades Relacionadas