Skill Suite Tests

Skill para orientar Codex e Cursor na criação de testes automatizados guiados por risco. Você informa a parte do sistema e o risco relevante. O agente inspeciona a stack, escolhe a menor fronteira capaz de provar o comportamento, implementa os testes, executa a suíte e relata evidências.

Ver apresentação

Comece em 2 minutos

Você precisa de Git e do Codex ou Cursor. Chaves de API e configuração no GitHub ficam fora do uso comum.

No terminal com o Codex CLI, adicione o catálogo do projeto:

codex plugin marketplace add andreferraro/skill-suite-tests --ref main

Reinicie o ChatGPT desktop, abra Plugins Directory, escolha o catálogo Skill Suite Tests e instale o plugin de mesmo nome. O marketplace do repositório é uma fonte Git para distribuição direta; ele ainda não faz parte do diretório público universal da OpenAI.

No Codex CLI ou IDE, também é possível instalar somente a skill:

Use $skill-installer para instalar:
https://github.com/andreferraro/skill-suite-tests/tree/main/skills/skill-suite-tests

Depois, faça um pedido com alvo e risco:

Use $skill-suite-tests no checkout. Cubra cálculo do total, idempotência do pagamento e rollback quando a persistência falhar.

No Cursor, abra Customize > Rules > Add Rule > Remote Rule (GitHub), informe a URL do repositório e use:

/skill-suite-tests Teste a recuperação de senha. Cubra loading, erro, teclado, acessibilidade e respostas assíncronas obsoletas.

Veja a instalação detalhada e os exemplos de uso.

Como a skill prova que ajuda

A certificação é um experimento pareado. Baseline e tratamento recebem o mesmo agente, modelo, pedido, projeto e contrato de evidência. A única diferença é o uso explícito da skill. A release passa quando essa diferença produz testes melhores de forma repetível.

Falhas individuais permanecem nos artefatos e participam da consolidação. Um baseline perfeito pode empatar em um caso, mas a release ainda precisa demonstrar ganho agregado sem regressão relevante.

Leia a metodologia completa e consulte o relatório auditável da v0.4.0.

Distribuição desde v0.5.0

A v0.5.0 adota o formato instalável atual do ChatGPT e Codex:

• manifesto em .codex-plugin/plugin.json;
• catálogo Git em .agents/plugins/marketplace.json;
• runtime único em skills/skill-suite-tests;
• instalação portátil no Cursor pelo mesmo repositório.

Os arquivos executados pela skill mantêm o mesmo conteúdo certificado na v0.4.0. A mudança reorganiza o pacote e atualiza o instalador dos evals, sem alterar instruções, scripts, schema ou referências. Por isso, a certificação técnica continua identificada como v0.4.0 até uma mudança funcional do runtime exigir nova rodada paga.

Holdout em projeto open source

Além das fixtures controladas, o runtime incluído na v0.4.0 foi aplicado ao hook de importação CSV do Atomic CRM. Com o mesmo modelo, projeto, pedido e contrato, o mutation score passou de 60% no baseline para 80% com a skill. O tratamento aprovou o gate técnico, preservou o código de produção e matou quatro dos cinco defeitos ocultos.

Consulte os testes gerados, relatórios estruturados, comandos e resultados de cada mutação. O holdout comprova ganho em uma execução real e complementa a certificação de três repetições da v0.4.0.

Estado da v0.4.0

A versão v0.4.0 fortalece testes de estados assíncronos, cancelamento, callbacks obsoletos e guards repetidos. Foi certificada no commit 635c8e2 com Codex e Cursor, três repetições por caso e baselines equivalentes reaproveitados por fingerprint. O relatório consolidado preserva as medianas, os gates, a falha individual e os links para todas as execuções.

Baseline versus skill

Os valores são medianas de três repetições por agente, caso e modo. A certificação exige aprovação crítica em pelo menos duas repetições. As falhas individuais continuam disponíveis nos artefatos dos runs e participam da mediana.

O que esta skill é

• Um guia operacional para agentes com acesso ao código, terminal e ferramentas do projeto.
• Um processo de seleção de testes por risco, arquitetura, fronteira e oráculo.
• Uma matriz de rastreabilidade entre risco, mecanismo protetivo, estado, cenário e oráculo.
• Um pacote com detector de contexto, schema de evidência, validador e referências técnicas.
• Uma skill agnóstica no núcleo, com benchmark inicial em Web, API e eventos.

Framework de testes autônomo, runner e infraestrutura própria ficam fora do escopo. A skill reutiliza o que existe no projeto e pede uma decisão quando falta requisito, baseline, contrato ou ambiente autorizado.

Suporte

O suporte validado cobre as três fixtures, os 12 mutantes, os evals pareados da v0.4.0 e o holdout no Atomic CRM. Outros ecossistemas continuam como suporte adaptável, sem benchmark publicado.

O que pode ser testado

• Frontend: componentes, telas, navegação, estado, teclado, acessibilidade e comportamento visual.
• Backend: regras de domínio, serviços, jobs, banco, cache, transações e concorrência.
• APIs: HTTP, REST, GraphQL, gRPC, contratos, protocolo e versionamento.
• Integrações: webhooks, filas, eventos, retries, DLQ, ordering e idempotência.
• Jornadas: interface, serviços, dados e efeitos observáveis de ponta a ponta.
• Qualidade: segurança, performance, resiliência, observabilidade e experiência.

A classificação usa quatro eixos:

Em fluxos assíncronos, a skill separa estados que possuem proteções diferentes. Cancelamento durante parsing, processamento ou espera entre lotes vira cenários distintos quando cada fase pode falhar de uma forma própria. O teste confirma o estado cancelado antes de liberar callbacks obsoletos, usando payload capaz de causar um efeito proibido caso o guard falhe. Erros fatais e erros parciais retornados com os dados também recebem oráculos distintos. A prova de sensibilidade remove temporariamente cada proteção relevante e confirma que o cenário correspondente detecta a falha.

Instalação

Instalar e usar a skill no Codex ou no Cursor não exige OPENAI_API_KEY, CURSOR_API_KEY nem configuração no GitHub. Essas credenciais pertencem somente aos benchmarks automatizados mantidos neste repositório.

O repositório segue os formatos atuais de distribuição: plugin para ChatGPT e Codex, skill portátil para Cursor e instalação local pelo Skill Installer.

O plugin está disponível pelo marketplace Git deste repositório. A publicação no diretório público da OpenAI exige submissão e verificação do desenvolvedor em uma etapa separada.

ChatGPT desktop e Codex como plugin

Adicione o marketplace pelo Codex CLI:

codex plugin marketplace add andreferraro/skill-suite-tests --ref main

Depois:

1. Reinicie o ChatGPT desktop.
2. Abra Plugins Directory.
3. Selecione o catálogo Skill Suite Tests.
4. Instale o plugin Skill Suite Tests.

O plugin distribui a skill que está em skills/skill-suite-tests. Ele não possui MCP, serviço externo nem autenticação própria. Marketplaces de repositório são voltados a autoria, teste e distribuição direta; a disponibilidade pode variar entre as superfícies do ChatGPT e do Codex.

Para receber versões novas do catálogo:

codex plugin marketplace upgrade skill-suite-tests

Codex CLI ou IDE com Skill Installer

Envie:

Use $skill-installer para instalar:
https://github.com/andreferraro/skill-suite-tests/tree/main/skills/skill-suite-tests

Esse modo instala apenas o runtime da skill em ~/.codex/skills/skill-suite-tests.

Cursor pela interface

1. Abra Customize.
2. Entre em Rules e clique em Add Rule.
3. Selecione Remote Rule (GitHub).
4. Informe https://github.com/andreferraro/skill-suite-tests.
5. Confira skill-suite-tests em Customize > Skills.

Conferência

No Codex CLI ou IDE:

/skills

No Cursor, abra Customize > Skills. Nos dois casos, procure por skill-suite-tests.

Codex detecta skills instaladas automaticamente. Se ela ainda estiver ausente, reinicie a ferramenta.

Como usar

No Codex, mencione a skill com $:

Use $skill-suite-tests na criação de pagamentos. Prove idempotência sob chamadas concorrentes e rollback após falha no insert.

No Cursor, selecione a skill com /:

/skill-suite-tests Teste a recuperação de senha. Cubra loading, anúncio de erro, teclado, acessibilidade e respostas assíncronas obsoletas.

O pedido funciona melhor com estas informações:

1. Alvo: tela, componente, endpoint, serviço, job, evento ou jornada.
2. Comportamento: regra, critério de aceite, contrato ou bug conhecido.
3. Risco: falha e impacto que precisam ser detectados.
4. Ambiente: local, CI, staging, browser, banco ou broker disponível.
5. Restrições: dados, serviços externos, carga, duração e permissões.
6. Entrega: criar, executar, diagnosticar ou preparar os testes.

Exemplo para uma jornada:

Use $skill-suite-tests no checkout. Cubra UI, API, persistência, evento de pedido criado e confirmação ao cliente. Reutilize a stack atual e execute o conjunto mínimo capaz de provar esses riscos.

Exemplo para performance:

Use $skill-suite-tests na busca. Prepare smoke, carga e pico. Marque thresholds ausentes como <definir> e execute somente no ambiente autorizado.

Entrega do agente

A resposta humana apresenta:

• suporte validado ou adaptável;
• classificação nos quatro eixos;
• base de teste e riscos rastreáveis;
• fronteiras, cenários, dados e oráculos;
• arquivos alterados;
• comandos executados e resultados;
• prova de sensibilidade;
• limitações e itens <definir>.

Automações também podem exigir test-evidence.json. O contrato está em skills/skill-suite-tests/schemas/test-evidence.v1.json e há um exemplo validado.

python skills/skill-suite-tests/scripts/validate_test_evidence.py test-evidence.json

Credenciais e custo

O uso comum acontece dentro do Codex ou do Cursor instalado pelo usuário e segue o plano ou provedor configurado nessa ferramenta.

Os secrets OPENAI_API_KEY e CURSOR_API_KEY aparecem apenas nos benchmarks de manutenção. Quem instala a skill para testar um sistema não precisa cadastrar esses secrets.

Os benchmarks pagos nunca são acionados por push, pull request, merge ou release. A execução exige abertura manual do workflow, escolha do escopo, confirmação do teto de chamadas e autorização explícita. Com a autorização desmarcada, o workflow mostra o plano e encerra sem chamar agentes. O runner também rejeita a execução sem --max-agent-calls.

Uma chamada não tem preço fixo. O valor depende do modelo e dos tokens processados. O teto controla a quantidade de chamadas e evita execuções acidentais; o consumo em moeda deve ser acompanhado nos provedores.

Evals

Os evals comparam o mesmo agente, projeto e pedido em dois modos: baseline sem a skill e tratamento com invocação explícita. Os dois modos recebem o mesmo schema e validador do relatório, evitando vantagem artificial de formato. Os testes gerados precisam passar na implementação correta, detectar os mutantes, cobrir os riscos, preservar produção e manifests e gerar evidência válida. O gate também rejeita agente, caso, modo ou repetição ausente ou duplicada.

Consulte evals/README.md para casos, mutações, pontuação, comandos e gates.

Validação determinística local:

python -m unittest discover -s tests -v
python scripts/validate_repository.py
python evals/validate_fixtures.py

Essa validação não usa agentes nem consome créditos de API.

Estrutura

• .codex-plugin/plugin.json: identidade e metadados do plugin.
• .agents/plugins/marketplace.json: catálogo instalável pelo repositório.
• skills/skill-suite-tests/: fonte única do runtime distribuído.
• skills/skill-suite-tests/SKILL.md: contrato e fluxo do agente.
• skills/skill-suite-tests/scripts/: detectores, validação de evidência e prova de sensibilidade.
• skills/skill-suite-tests/schemas/test-evidence.v1.json: contrato JSON Schema.
• skills/skill-suite-tests/references/: taxonomia, oráculos, ecossistemas e bases técnicas.
• evals/: fixtures, graders, mutantes, runner e agregador.
• tests/: testes unitários dos scripts e do harness.

Segurança operacional

• Credenciais dos benchmarks entram somente por variáveis de ambiente ou GitHub Actions secrets.
• O runner remove tokens e credenciais alheias antes de iniciar agentes.
• Cada execução usa um contêiner descartável com raiz somente leitura.
• O agente recebe somente a fixture e um home temporário. Graders, mutantes, repositório e credenciais de produção ficam fora do contêiner.
• Carga, estresse, fuzz externo e injeção de falhas exigem ambiente autorizado.
• Cleanup fica restrito aos recursos criados pelo teste.

Contribuição e release

Leia o guia de contribuição, a política de segurança e o código de conduta antes de abrir uma contribuição.

O repositório usa Gitflow:

• main: versões publicadas.
• develop: integração.
• feature/*: mudanças em desenvolvimento.
• release/*: preparação da versão.
• hotfix/*: correções originadas de main.

Commits seguem Conventional Commits. Uma release que altera o runtime exige qualidade estrutural, fixtures verdes e aprovação manual do benchmark com Codex e Cursor. Uma release restrita a empacotamento ou documentação pode reutilizar a certificação anterior somente quando a equivalência do runtime for validada e registrada.

As branches estão protegidas no GitHub:

• develop exige pull request atualizado, checks de qualidade e conversas resolvidas;
• main exige os mesmos controles de qualidade;
• as regras também valem para administradores e bloqueiam force push e exclusão das branches.

Os evals pagos ficaram fora dos checks automáticos obrigatórios. O gate de eficácia continua sendo critério de publicação da versão, executado uma única vez quando a release estiver pronta.

Certificação da v0.4.0

Configuração atual em Settings > Secrets and variables > Actions:

As chaves devem ser cadastradas diretamente no GitHub. Evite colocá-las em arquivos, comandos com valor literal, commits ou mensagens do PR.

Execuções que compõem a certificação:

• Codex: repetição 1, repetição 2 e repetição 3.
• Cursor: repetição 1, repetição 2 e repetição 3.

Os tratamentos foram executados no commit certificado e consolidados pelo mesmo agregador usado no gate de release. Os baselines foram restaurados por fingerprint a partir de execuções equivalentes. A falha individual do Codex em Web na terceira repetição foi preservada e contou na mediana. Repetir a certificação exige uma nova decisão explícita de custo. Os critérios e os tetos de chamadas estão em evals/README.md.

Referências

• Skills no ChatGPT e Codex
• Empacotamento e marketplaces de plugins
• Codex em modo não interativo
• Agent Skills no Cursor
• Cursor CLI em modo headless
• Apresentação da Skill Suite Tests