Communitygithub.com

lguidolin/teste-de-contrato-graphql

Use ao escrever uma query/mutation GraphQL que a interface e um teste compartilharão, ou ao construir testes de contrato/rota ou smoke tests. Sintomas — copiar uma query para um teste, um testar que verifica o texto da query, mudança de esquema que não quebrou a build da UI, ou desvio de RLS/permissão. Palavras-chave — graphql-codegen, typed document, teste de contrato, smoke test de rota.

O que é teste-de-contrato-graphql?

Este skill define uma abordagem rigorosa para testes de contrato GraphQL, garantindo que a interface do usuário (UI), os testes e o esquema de banco de dados permaneçam sincronizados. A ideia central é tratar as queries GraphQL como artefatos compartilhados e versionados, que são testados tanto em tempo de compilação (via geração de tipos com `graphql-codegen` contra o esquema ativo) quanto em tempo de execução (contra um banco de dados semeado, sob diferentes contextos de função). Isso quebra o anti-padrão de copiar queries para testes — a mesma query é importada tanto pela UI quanto pelo teste, tornando a DRY uma exigência estrutural. O skill também cobre testes de contrato de rota e smoke tests, onde cada URL de rota tem um smoke test que verifica renderização sem erros e a presença de elementos essenciais, garantindo que nenhuma rota seja adicionada ou removida silenciosamente. Ele é útil especialmente em projetos que usam PostGraphile, RLS (Row-Level Security) e codegen contra um esquema ativo, e se baseia na 'constituição de engenharia' da equipe para justificar sua abordagem.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lguidolin/agent-skills/tree/main/skills/graphql-contract-testing
Ver original→Navegar por todas as habilidades

Perguntar na sua IA favorita

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

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Documentação

Teste de Contrato GraphQL

Visão Geral

Testes que se situam na costura entre camadas e quebram quando um dos lados se move sem o consentimento do outro — testes-como-controle aplicados a fronteiras. A regra cardinal: afirme sobre o contrato — a forma dos dados e as semânticas de acesso que o consumidor depende — nunca sobre a string da query em si. Um teste que quebra por uma edição cosmética na query é um anti-padrão de detector de mudanças; um teste que quebra quando a forma garantida ou permissão se move é um controle.

§1 — O Contrato de Query GraphQL

  • Cada operação é criada uma vez como um documento tipado em um local conhecido, exportado para ser importado. A UI o importa; o teste importa o mesmo artefato — nunca uma cópia redigitada. Copiar uma query em um teste mata silenciosamente o contrato (editar a query da UI não quebra mais o teste). DRY tornado estrutural.
  • Ele quebra em ambas as direções, por construção:
    • Derivação DB → UI, em tempo de compilação. graphql-codegen gera tipos TypeScript a partir do esquema ativo. Renomeie ou remova um campo usado e tsc falha em cada uso e no documento compartilhado — a build quebra antes que o usuário veja um painel vazio. É por isso que codegen contra o esquema ativo é obrigatório.
    • Derivação UI → DB / permissão, em tempo de execução. O documento compartilhado executa contra um banco de teste semeado através do caminho real de chamada, sob contexto de função, afirmando sobre a forma retornada e o resultado do acesso — não o texto da query.
  • Testes de contrato e a matriz de funções RLS são o mesmo harness. Execute o mesmo documento através do PostGraphile como função A (espera dados) e função B (espera negado/vazio). Um mecanismo prova três coisas: a query ainda corresponde ao esquema, as suposições da UI ainda são válidas, o RLS ainda impõe a fronteira.

Exemplo prático — como um bug real é capturado

  • DB→UI: uma migração remove equipment.is_active. Codegen regenera a partir do novo esquema; o tipo gerado perde o campo; tsc falha no documento compartilhado e em cada componente que o usa — capturado na build, antes do merge. Nenhum teste afirma "texto da query == X."
  • UI→DB: um desenvolvedor amplia a query da UI para puxar cancellation_reason (RLS expõe apenas para funções elevadas). O teste de execução rodando como um membro comum afirma a forma visível ao membro, agora recebe nulo/negado, e falha — forçando "nós pretendíamos expor isso?"

§2 — Testes de Rota e Smoke Tests

  • Rotas enumeradas a partir de uma única fonte. Cada rota tem um smoke test: renderiza sem erro + mostra um conjunto mínimo de elementos obrigatórios (um título, um marco, um controle chave — não interação detalhada).
  • Adicionar/remover uma rota força uma mudança de teste correspondente — uma nova URL está incompleta sem seu smoke test; uma URL removida remove seu teste. URLs nunca aparecem ou desaparecem silenciosamente.
  • Explícitamente NÃO é teste detalhado de UI/interação — deliberado, escopo limitado. A pergunta é "esta URL funciona e renderiza o essencial," nada mais.

Imposição: graphql-codegen + tsc no CI (bloqueante) para a parte de tempo de compilação; testes de contrato em tempo de execução + smoke tests de rota no CI contra um banco de dados semeado.

Raciocínio completo: Artigo XV da constituição, empacotado em engineering-constitution/references/engineering-constitution.md.

Individual skills in this repo

This repo contains 18 individual skills — each has its own dedicated page.

lguidolin/change-hygiene-and-code-craft

Use when writing or refactoring code, structuring a commit or PR, or deciding whether to abstract duplication. Symptoms — mixing reorg with logic changes, a PR doing several things at once, a file growing large, the second copy of similar code, or unsure whether to DRY something up.

lguidolin/cloud-delivery-aks

Use when deploying to Kubernetes or Azure Kubernetes Service (AKS), configuring cloud secrets, setting up progressive rollout/canary, per-PR ephemeral environments, or k8s health probes. Keywords — Kubernetes, AKS, Key Vault, Argo Rollouts, Flagger, canary, blue-green, liveness, readiness, PodDisruptionBudget, HPA, rollback, GHCR.

lguidolin/commit-history-rewrite

Use when an existing repository has messy commit history that needs to conform to conventional commits before adopting release-please, or when intermediate WIP/fixup/merge commits need to be cleaned up.

lguidolin/conventional-commits-and-releases

Use when committing, writing a commit message, opening a PR that will be squash-merged, or configuring automated versioning/changelogs. Keywords — conventional commits, release-please, semver, feat/fix/chore, breaking change, changelog.

lguidolin/defense-in-depth-security

Use when handling untrusted input, secrets, authentication/authorization, or dependencies — or threat-modeling a new surface. Keywords — STRIDE, threat model, least privilege, secrets management, supply chain, dependency scanning, input validation, audit log, defense in depth.

lguidolin/designing-before-building

Use when starting a feature, fixing a non-trivial bug, or about to write implementation code — before any code exists. Symptoms you need this: "this is simple, I'll just code it", reaching for the editor before a design is approved, or an idea that hasn't been turned into a spec and plan.

lguidolin/engineering-constitution

Use when starting work in a project that follows the engineering constitution, orienting to its rules, or deciding which engineering practice applies to a task — spec writing, commits, testing, security, deploys, database, or UI work.

lguidolin/init-repo-CI

Use when setting up a new repository with conventional commits, release-please, and CI automation, or when retrofitting an existing repository that lacks automated versioning and PR validation workflows.

lguidolin/interface-craft-and-accessibility

Use when building or styling UI — components, layouts, forms, design tokens — or making accessibility decisions. Keywords — a11y, WCAG, keyboard navigation, focus state, contrast, design system, minimalist UI, component reuse, ARIA, semantic HTML.

lguidolin/merge-gates-and-automation

Use when setting up or changing CI, pre-push hooks, or a task runner, or deciding what must pass before merge. Symptoms — tempted to put authoritative checks only in a local hook, skip CI, bypass with --no-verify, or unsure what gates a merge vs. runs locally.

lguidolin/observability-and-slos

Use when adding logging, metrics, tracing, health checks, SLOs, or alerting — or when building a service surface that needs to be operable and debuggable. Keywords — structured logs, OpenTelemetry, correlation id, RED metrics, liveness, readiness, SLI, SLO, error budget, alerting.

lguidolin/performance-and-scale

Use when working on hot paths, list endpoints, pagination, data-access in loops, or public interfaces/schemas. Symptoms — unbounded queries, N+1 access, no latency budget, optimizing without measuring, or changing an interface many consumers depend on. Keywords — pagination, N+1, Hyrum's Law, performance budget, bundle size.

lguidolin/postgres-postgraphile-rls-and-sql

Use when writing PostgreSQL, PostGraphile config, Row-Level Security policies, SQL schema files, or working on the Browser→App→PostGraphile→Postgres data path. Keywords — RLS, SECURITY DEFINER, search_path, pgSettings, grants, roles, GraphQL depth limit, query cost, statement_timeout, SQL file organization.

lguidolin/recording-decisions

Use when a design or architecture decision has been made and needs to be captured — writing a decision record or ADR, updating a decision index, noting a deferred idea, or superseding a past decision. Keywords — ADR, decision record, rationale, rejected alternatives, dependency index.

lguidolin/resilience-and-deploy-safety

Use when planning a deploy, designing a rollback, or responding to an incident or writing a postmortem. Keywords — deploy safety, rollback, immutable artifact, progressive delivery, canary, blast radius, incident response, blameless postmortem, error budget.

lguidolin/ship-it

Use when the user wants to ship work — push, PR, archive decision records, merge, and clean up. Handles the full lifecycle from committing final changes through post-merge cleanup including converting specs/plans to compact decision records.

lguidolin/tests-as-a-control

Use when writing or modifying tests, when a test breaks during a refactor, or when testing permission/role rules. Symptoms — tempted to edit a test to make it pass, testing only the happy path, a deny-test that started passing, flaky tests, or unsure what to assert.

lguidolin/zero-downtime-migrations

Use when changing a database schema where data must survive the change — adding/removing/renaming columns, constraints, indexes, or backfilling. Symptoms — a destructive migration bundled with a code deploy, a NOT NULL column with a backfill, a table-locking UPDATE, or a rename. Keywords — expand/contract, parallel change, backfill, NOT VALID, CREATE INDEX CONCURRENTLY, graphile-migrate.

Habilidades Relacionadas

steipete/sag

ElevenLabs text-to-speech with mac-style say UX.

community

steipete/oracle

Oracle CLI second-model review/debug/refactor/design with selected files, dry-run token checks, API or browser engine.

community

steipete/peekaboo

Capture and automate macOS UI with the Peekaboo CLI.

community

mattpocock/design-an-interface

Generate multiple radically different interface designs for a module using parallel sub-agents. Use when user wants to design an API, explore interface options, compare module shapes, or mentions "design it twice".

community

mattpocock/prototype

Build a throwaway prototype to flesh out a design — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route.

community

mattpocock/grill-me

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

community