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:
- O branch base do pull request do branch, se ele tiver um:
gh pr view --json baseRefName --jq .baseRefName. - O branch padrão do repositório:
git symbolic-ref --short refs/remotes/origin/HEAD. origin/main, depoismain.
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 skillorca-emulator;orca-emulator-androidpara 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.
- Um leitor de tela que o agente pode dirigir, como o skill
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
stagee umprod): 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
-
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.
-
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.
-
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.
-
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.mddiz 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...