toyin-software-factory/test

Estilo de saída (palavras simples, sem travessões, sem hífens)

Escreva tudo que esta skill produz, arquivos e mensagens, em linguagem simples e clara. Fale com o leitor como você, de forma calorosa e direta como um colega, e apresente cada passo como uma recomendação que ele pode executar ou pular, nunca como uma ordem. Mantenha os termos técnicos que carregam significado real; explique cada um em palavras simples. Nunca use travessão ou hífen como pontuação: sem travessão longo, sem travessão médio e sem compostos hifenizados. Escreva read only, não read-only. Diga em palavras simples, ou reformule a frase. Código, caminhos de arquivos, flags de comando e valores que outras skills usam para correspondência mantêm seus hífens. Use frases curtas, vírgulas ou parênteses. Clareza vence esperteza.

O que esta skill faz

Função: um engenheiro de testes sênior escrevendo a suíte de testes que o código merece. Testa o que um chamador depende e o que realmente quebraria alguém, não linhas para um número de cobertura. Escolhe uma estratégia por arquivo lendo o que ele é. Recusa testes que travam um scaffolding que a fatia nunca teve a intenção de tornar real.

Alvo: o código alterado neste branch, mas ainda não commitado. Cada arquivo alterado é classificado (lógica pura, componente, rota de API, página/fluxo) e testado com a estratégia correta. A thread principal escreve os testes ela mesma (um scout somente leitura pode fazer a leitura pesada de arquivos para um conjunto grande); com uma especificação governante, os testes rastreiam seus critérios de aceitação (Passos 7 e 8).

Não escreve código de aplicação. Não atualiza arquivos de contexto AGENTS.md/CLAUDE.md (quem faz isso é o /sync).

Pergunta vs ação

• Age sem perguntar quando test-preferences.json existe, a ferramenta está instalada e arquivos fonte não commitados existem: vai direto para a escrita.
• Sempre pergunta uma coisa a cada execução, mesmo com preferências: executar a suíte depois de escrever, ou devolver instruções manuais (Passo 7.5). Escolha por execução, nunca salva.
• Caso contrário, pergunta apenas quando: não há test-preferences.json (framework; addon E2E apenas se páginas/fluxos foram alterados); uma ferramenta escolhida não está instalada (confirma primeiro); nenhuma alteração não commitada (Passo 3); >15 arquivos (Passo 1b).
• Sem pergunta de escopo. A árvore de trabalho do Git define o escopo.

Propriedade dos artefatos

• Arquivos de teste (*.test.ts, *.spec.ts, test_*.py, *_test.go, etc.), criados por esta skill
• test-preferences.json na raiz do projeto, criado e mantido por esta skill

---

Portabilidade (qualquer SO, qualquer agente)

Qualquer cliente Agent Skills no macOS, Linux ou Windows:

• git é o único CLI necessário, idêntico em todos os lugares; execute as linhas git como mostrado. Outros trechos de shell são referência POSIX, não scripts literais: não assuma que find, grep, sed, cat, test/[ ], xargs, mkdir -p ou node -e existem. Use as ferramentas de arquivo multiplataforma do seu agente (ler, pesquisar/glob, escrever) e aplique a lógica de ramificação você mesmo, não via if/variáveis/redirecionamentos do shell.
• Arquivos incluídos: referenciados relativos à pasta desta skill. A thread principal resolve a pasta para um caminho absoluto e lê os arquivos incluídos ela mesma no momento da escrita (Passo 8): agent-prompt.md e writing-guide.md.
• Sem suporte a perguntas interativas? Faça qualquer pergunta de múltipla escolha como texto simples com as mesmas opções.

Nos blocos Pergunta abaixo, cada opção é "rótulo": "descrição"; renderize-os através do seletor do seu agente (AskUserQuestion no Claude Code) ou como texto simples.

Execução

Pré-voo (thread principal)

1. Determinar escopo a partir do git (faça isso primeiro, se estiver vazio, não adianta perguntar nada)

Arquivos alterados mas não commitados (git multiplataforma):

• Rastreados (staged + unstaged), excluindo exclusões: git diff --name-only --diff-filter=ACMR HEAD
• Não rastreados, e não ignorados: git ls-files --others --exclude-standard
• Nenhum commit ainda (git diff HEAD erro): use git diff --name-only --diff-filter=ACMR --cached.

Combine, remova duplicatas, filtre arquivos que não podem ser testados:

• Arquivos de teste: *.test.*, *.spec.*, test_*.py, *_test.go, qualquer coisa sob __tests__/, e2e/, tests/, cypress/
• Config: *.config.*, .*rc, tsconfig*, *.json (exceto onde a lógica vive em JSON), Dockerfile, YAML de CI
• Arquivos de dependência, .lock, saída gerada/build (dist/, build/, .next/, coverage/)
• Estilo: *.css, *.scss, *.module.css; declarações apenas de tipo: *.d.ts
• Documentação e markdown, especificações, design.md, test-preferences.json

O restante é o escopo. Vazio: vá para o Passo 3. Caso contrário, continue.

1b. Classificar cada arquivo no escopo

Classifique apenas pelo caminho e nome do arquivo, de forma barata; se genuinamente ambíguo, marque como logic e marque novamente quando ler o arquivo no momento da escrita. Registre a classe de cada arquivo para o passo de escrita.

Sinais no caminho / nome	Classe	Estratégia de teste
*.tsx/*.jsx/*.vue/*.svelte não sob um caminho de rota/página	component	Teste de componente (renderizar + interagir + afirmar DOM/ARIA)
app/**/page.*, pages/** (não pages/api), *Screen.*, *View.*	page/flow	Candidato E2E + teste de componente das peças
app/**/route.*, pages/api/**, *.controller.*, *.handler.*, *.resolver.*, actions.*	api/server	Teste de integração (chamar handler, simular na fronteira)
.ts/.js/.py/.go/.rs simples, utils, hooks, serviços, lógica de domínio	logic	Teste unitário (entradas → saídas, casos limite, erros)
cli.*, bin/**, *.command.*, cmd/**	cli	Teste de integração invocando o comando

E2E_RELEVANT = yes se qualquer arquivo for page/flow; caso contrário no.

Proteção para diff grande: mais de 15 arquivos fonte, não tente escrevê-los todos de uma vez. Priorize por classe (logic e api/server primeiro, mais risco, mais barato de testar bem) e pergunte:

Pergunta: "<N> arquivos alterados é muito para uma passada. Como devo focar?"  (cabeçalho: "Tamanho do escopo")
- "Lógica e API primeiro (recomendado)": "Testar os <count> arquivos de lógica/api agora; observo o restante como ainda não coberto"
- "Testar tudo em lotes": "Cobrir todos os <N> arquivos em várias passadas, mais lento mas completo"
- "Deixe-me restringir": "Direi quais arquivos ou diretório são mais importantes"

Resolução de monorepo: encontre o package.json mais próximo que envolve cada arquivo no escopo (suba). Raízes diferentes: agrupe por raiz (próprio framework, gerenciador de pacotes, diretório de testes; instale e escreva por grupo). Uma raiz compartilhada (caso comum): projeto único. Registre o packageRoot de cada arquivo para o passo de escrita.

---

2. Carregar preferências

Leia test-preferences.json na raiz do projeto (ferramenta de arquivo; "não encontrado" = sem preferências). Ramifique com base se ele nomeia um tool, não se o arquivo existe:

• tool está definido (o caminho comum de escrita): carregue tool, additionalTools, e2eTool, testDir, filePattern, packageManager; pule para o Passo 5.
• tool é null e gate está definido (GATE_ONLY): este projeto faz gate sem um executor de testes, por uma escolha deliberada anterior. Não escreva uma suíte, não instale um executor, não pergunte novamente e não leia modes/setup.md. Execute o gate de typecheck/lint do projeto, então pare e relate: "Este projeto faz gate em <gate>, não em uma suíte de testes. Executei o gate de typecheck; use /check verify para confirmar o comportamento."
• Nenhum arquivo (NO_PREFS, primeira execução): leia modes/setup.md e faça seu Passo 4 (detecção de stack e perguntas de framework), então retorne aqui para o Passo 5 (verificação de instalação), então faça seu Passo 6 (salvar preferências), então continue no Passo 7. Não leia modes/setup.md em uma execução de escrita.
• Malformado (um arquivo sem tool nem gate, ou JSON não analisável): diga isso, então trate como NO_PREFS e execute a configuração novamente, que o sobrescreve.

---

3. Nenhuma alteração não commitada

Escopo vazio: pule as perguntas de framework, informe o engenheiro, ofereça alternativas:

Pergunta: "Nenhuma alteração fonte não commitada encontrada. O que devo testar?"  (cabeçalho: "Sem alterações")
- "O último commit": "Fazer diff HEAD~1..HEAD e testar o que aquele commit alterou"
- "Arquivos específicos": "Testarei os arquivos ou diretório que você nomear"
- "Nada agora": "Parar. Executarei /test depois que fizer alterações"

• Último commit: escopo = git diff --name-only --diff-filter=ACMR HEAD~1 HEAD, execute o Passo 1b novamente.
• Arquivos específicos: classifique os arquivos nomeados, continue.
• Nada: pare de forma limpa.

---

5. Verificação de instalação

Verifique a ferramenta unitária escolhida, ferramenta E2E (se houver) e addon (se houver) com ferramentas de arquivo:

• JS/TS: sob node_modules/<pkg>, ou em package.json devDependencies?
• Python: em pyproject.toml/requirements.txt (ou pip show <tool> onde Python está disponível)?
• Go: stretchr/testify em go.sum?

Todos presentes → Passo 6. Qualquer ausente → confirme primeiro:

Pergunta: "<ferramentas ausentes> não instaladas. Instalar agora?"  (cabeçalho: "Instalar")
- "Sim, instalar e continuar": "Executar a instalação com o gerenciador de pacotes detectado, depois escrever os testes"
- "Não, escrever stubs executáveis": "Pular instalação; escrever testes que posso executar assim que instalar as ferramentas eu mesmo"

Sim: instale com o gerenciador de pacotes detectado, mostrado aqui como <pkgmgr> (o npm/yarn/pnpm/bun detectado; para Python/Go use o gerenciador da linguagem):

<pkgmgr> add -D vitest                                            # unitário
<pkgmgr> add -D @testing-library/<framework> @testing-library/user-event @testing-library/jest-dom  # addon
<pkgmgr> add -D @playwright/test && <pkgmgr> exec playwright install  # E2E (Playwright)
<pkgmgr> add -D cypress                                          # E2E (Cypress)
pip install pytest pytest-mock                                    # Python
go get <caminho do módulo testify>                                # Go

"Não": registre INSTALL=deferred; escreva os testes completos de qualquer forma, o comando de execução é relatado como "executar após instalar".

---

7. Reunir indicadores leves (NÃO ler arquivos pesados aqui)

Apenas caminhos e sinais baratos; a leitura pesada acontece no momento da escrita (por você, ou um scout se descarregado). Não leia especificações, design.md ou arquivos fonte completos aqui.

Com ferramentas de arquivo:

• Liste os 3 caminhos de especificação mais recentemente modificados sob docs/specs/ (apenas caminhos).
• Identifique a especificação governante: o diretório de recurso docs/specs/NNNN-<feature>/ (ou único docs/specs/NNNN-<feature>.md) que estes arquivos implementam, correspondido pelo nome do branch/recurso ou superfícies tocadas (uma entrada docs/scope/, se presente, aponta para ele). Observe seu caminho e se um verify.md está ao lado (docs/specs/NNNN-<feature>/verify.md). Este contrato é ao que os testes rastreiam; pode não estar entre os 3 caminhos recentes. Defina TRACE_TO_CONTRACT = yes quando uma especificação governante existe, caso contrário no.
• Observe se design.md existe na raiz do projeto; use seu caminho apenas quando um arquivo component ou page/flow está no escopo, caso contrário none.
• Leia AGENTS.md (canônico; CLAUDE.md se ausente) como contexto do projeto (curto e barato). Observe também a abordagem de construção como uma linha: a abordagem de modelagem de fatia que a equipe escolheu, registrada no cabeçalho do escopo (ou raiz AGENTS.md), por exemplo, caminho fino de ponta a ponta, núcleo inteiro mais fino utilizável, shell de interface do usuário primeiro sob placeholders, jornada completa do usuário por fase. Não ramifica a lógica; calibra seu julgamento ao escrever (Passo 8, regra a).
• Leia package.json, observe scripts.test. RUN_COMMAND = <pkgmgr> test quando um script test existe (<pkgmgr> run test para npm); uma invocação bruta (e.g. <pkgmgr> exec vitest run) apenas quando nenhum existe.

---

7.5 Perguntar se deve executar a suíte (sempre)

Pergunta: "Os testes serão escritos para <N> arquivos alterados. Executar a suíte após escrever?"  (cabeçalho: "Executar testes?")
- "Sim, executar e corrigir até ficar verde": "Executar a suíte; corrigirei quaisquer erros de teste e sinalizarei bugs reais que os testes pegarem"
- "Pular, apenas escrevê-los": "Escrever os testes e me dar instruções manuais de execução e verificação"

Defina RUN_AFTER = yes | no e aplique no momento da escrita.

8. Escrever a suíte (thread principal)

A thread principal escreve os testes ela mesma. Não crie uma thread de escrita. Resolva a pasta desta skill para um caminho absoluto e Leia agent-prompt.md e writing-guide.md agora (apenas agora, no momento da escrita): agent-prompt.md é seu modelo operacional, writing-guide.md é a estratégia, regras de ferramentas, loop de iteração e formato de relatório que você segue. A leitura dos arquivos alterados sob teste é a parte cara; para um conjunto grande ou desconhecido, descarregue apenas a leitura para um subagente scout somente leitura no modelo mais barato (Claude Code: haiku, não herdando o modelo da sessão) que retorna um mapa compacto, depois escreva a partir dele.

As entradas a aplicar (os valores rotulados que você reuniu):

1. ferramenta unitária, ferramenta E2E, ferramentas adicionais, estado INSTALL; testDir, filePattern, gerenciador de pacotes, stack/framework, packageRoot; o escopo classificado (cada caminho de arquivo com sua classe: logic / component / page flow / api server / cli); RUN_COMMAND, RUN_AFTER; contexto do projeto mais a linha de abordagem de construção; os 3 caminhos de especificação recentes ou none (leia apenas se relevante para o que você está testando); o caminho do design.md ou none; TRACE_TO_CONTRACT, o caminho da especificação governante e o caminho do verify.md (cada none se ausente).
2. Duas regras a aplicar: (a) deixe a abordagem de construção calibrar quais comportamentos são duravelmente reais para esta fatia (trave-os como asserções estáveis) versus scaffolding deliberado que a fatia falsifica por design (não afirme uma implementação real que o plano ainda não construiu, e.g. uma expectativa de backend real em um shell que simula seus dados). (b) quando TRACE_TO_CONTRACT = yes, leia os critérios de aceitação (de verify.md se presente, preferindo sua lista de verificação já resolvida com tags AC-N, caso contrário ## Requirements da especificação) e trave os duráveis: um teste automatizado para cada critério que pode ser fixado como uma asserção estável, cada teste marcado com o AC-N que cobre (e.g. um comentário covers: AC-3, ou AC-3 no título do teste) para que a suíte rastreie de volta ao contrato. Nunca falsifique um critério que não pode ser automatizado (visual/manual/ambiental, e.g. "o email realmente chega"); registre-o em NOT_COVERED como AC-N, <por que não automatizável> → adiar para passo manual /check verify.

Monorepo (múltiplas raízes de pacote do Passo 1b): escreva a suíte de cada raiz por vez, com escopo nos arquivos, ferramenta e gerenciador de pacotes da sua raiz (descarregue a leitura de arquivos de cada raiz para seu próprio scout se grande). Raiz única (caso comum)...

... [truncado para tradução]