assert-what-the-generator-found
Um gerador que quebra avisa que falhou; um que emite saída plausível não avisa nada. Teste o que ele encontrou, nunca que ele rodou.
Conferida por quem revisou e leu o cartão, não reivindicada pelo próprio arquivo. Um cartão que o agente destila durante uma execução que consumiu conteúdo não confiável nasce contaminado e fica retido para revisão antes de alguma vez ser recuperado.
Quando ele vem à mente
- escrevi um gerador de código
- testando um dump de schema
- a saída parece certa
- extraindo a estrutura de uma biblioteca
Evite e Verifique são onde costuma estar o valor. Faça é a seção que todo mundo escreve.
O corpo do cartão acima é uma tradução. O original em inglês é o que a CLI importa, o que o agente lê em execução e o que o hash abaixo atesta.
Gatilho
Você escreveu algo que lê uma representação e emite outra: um dump de schema, um extrator de referências, uma migration, um scraper, um construtor de índice. Qualquer coisa cuja saída ninguém lê por completo porque há volume demais.
Não se aplica a uma função que retorna um único valor conferível a olho nu. O risco aqui é específico de uma saída grande o bastante para que "parece certo" seja a única revisão que ela jamais receberá.
Faça
- Antes de escrever o teste, nomeie a contagem. Quantos comandos, linhas, arquivos ou campos deveriam sair? Consiga esse número de algum lugar que não seja o gerador — a fonte, a documentação, uma contagem manual.
- Afirme a contagem, ou um piso sobre ela.
assert len(groups) >= 10, nãoassert result. - Afirme a presença de itens específicos e nomeados que você sabe que devem existir. Três ou quatro bastam, e escolha itens de formatos diferentes de entrada.
- Se o gerador classifica coisas, afirme que cada classe é não vazia. Um classificador que coloca tudo em um único balde é a falha que isso pega.
Evite
assert build() — passa quando o gerador retorna uma lista vazia, uma lista parcial, ou uma lista
em que cada item é sutilmente do tipo errado.
Evite também confiar em isinstance ao percorrer uma estrutura de terceiros. Bibliotecas
empacotam suas próprias dependências (vendoring): um TyperGroup não é uma instância do
click.Group que seu arquivo importou, porque o Typer distribui sua própria cópia do Click.
Pergunte se o objeto tem o que você precisa — um mapeamento commands, um método items — em
vez de qual classe ele afirma ser. Duck-typing sobrevive a uma dependência vendorizada e a um bump
de versão major; uma checagem de classe não sobrevive a nenhum dos dois, e falha classificando
errado em vez de levantar um erro.
Verifique
Quebre o gerador de propósito e observe o teste falhar. Comente a recursão nos subcomandos, ou faça a checagem de tipo rejeitar tudo, e rode a suíte.
Se a suíte ainda passar, o teste está apenas afirmando que o gerador rodou, e você escreveu exatamente o teste que esta skill existe para prevenir.
Risco
Fixar (hard-coding) uma contagem exata transforma o teste em tarefa de manutenção: todo comando
legitimamente adicionado o deixa vermelho. Prefira um piso (>= 10) mais itens nomeados, e reserve
contagens exatas para coisas que genuinamente não deveriam mudar sem uma decisão.
Também há um limite. Essas afirmações pegam um gerador que descartou uma categoria inteira. Elas não pegam um que erra um único campo em um item, e fingir o contrário é, por si só, uma forma de falsa confiança.
Como usar
O cartão é dado. Clone o repositório e importe pelo caminho — o que chega pela rede é tratado como contaminado e fica retido para aprovação, que é o comportamento desejável e a razão de não haver um instalador de uma linha aqui.
git clone https://github.com/brcampidelli/chimera-agent.gitchimera skills-import chimera-agent/skills/assert-what-the-generator-found/SKILL.mdIntegridade
SHA-256 do arquivo como publicado. Quem importa pode conferir que o que recebeu é o que esta página mostrou.
0ffc1fdde72d3f2c416461f0f312ca5ca2a43d3b1ff33aaf7b20be155de711c9