Communitygithub.com

lguidolin/graphql-contract-testing

Verwenden, wenn Sie eine GraphQL-Abfrage/Mutation schreiben, die UI und Test gemeinsam nutzen, oder wenn Sie Route/Schema-Kontrakttests oder Smoke-Tests erstellen. Symptome: Kopieren einer Abfrage in einen Test, Test, der auf Abfragetext prüft, Schemaänderung, die den UI-Build nicht bricht, oder RLS/Berechtigungsdrift. Stichwörter: graphql-codegen, typed document, contract test, route smoke test.

Was ist graphql-contract-testing?

Diese Skill ermöglicht die Implementierung von GraphQL-Kontrakttests, die verhindern, dass Schemaänderungen oder Berechtigungsdrifts unbemerkt die UI beeinträchtigen. Der Kernansatz besteht darin, immer typisierte Dokumente zu verwenden, die sowohl von der UI als auch von Tests importiert werden – niemals kopierte Abfragestrings. Dadurch wird sichergestellt, dass eine Änderung an einer Abfrage sofort sowohl den Build (über TypeScript und graphql-codegen) als auch die Laufzeittests betrifft. Die Skill unterstützt sowohl Kompilierzeit-Tests (DB→UI) durch Codegen gegen das Live-Schema als auch Laufzeit-Tests (UI→DB, Berechtigungen) durch Ausführung der gemeinsamen Dokumente im realen Aufrufpfad mit verschiedenen Rollen (RLS). Zusätzlich werden Routen-Smoke-Tests definiert, die prüfen, ob eine Route grundsätzlich funktioniert (rendern ohne Fehler, minimale Elemente vorhanden). Die Enforcement erfolgt in CI über graphql-codegen + tsc für die Kompilierzeit und separate Laufzeit-Contracts- und Smoke-Tests gegen eine Seed-DB. Diese Skill ist ideal für Entwicklerteams, die mit GraphQL-APIs arbeiten und sicherstellen möchten, dass Änderungen am Schema oder an Berechtigungen sofort erkannt werden, bevor sie die Produktion erreichen.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lguidolin/agent-skills/tree/main/skills/graphql-contract-testing
Original anzeigen→Alle Skills durchsuchen

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

Dokumentation

GraphQL-Kontrakttests

Übersicht

Tests, die auf der Naht zwischen Schichten sitzen und brechen, wenn sich eine Seite ohne Zustimmung der anderen bewegt – tests-as-a-control angewandt auf Grenzen. Die goldene Regel: Teste den Kontrakt – die Datenform und Zugriffssemantik, auf die der Konsument angewiesen ist – niemals den Abfragestring selbst. Ein Test, der bei einer kosmetischen Abfrageänderung bricht, ist ein Change-Detector-Anti-Pattern; ein Test, der bricht, wenn sich die garantierte Form oder Berechtigung verschiebt, ist ein Kontrollmechanismus.

§1 – Der GraphQL-Abfragekontrakt

  • Jede Operation wird einmal als typisiertes Dokument an einem bekannten Ort verfasst, exportiert und kann importiert werden. Die UI importiert es; der Test importiert exakt dasselbe Artefakt – niemals eine neu getippte Kopie. Das Kopieren einer Abfrage in einen Test tötet den Kontrakt leise (die Bearbeitung der UI-Abfrage bricht den Test nicht mehr). DRY wird lasttragend.
  • Es bricht konstruktionsbedingt in beide Richtungen:
    • DB → UI-Drift, zur Kompilierzeit. graphql-codegen generiert TypeScript-Typen aus dem Live-Schema. Wird ein verwendetes Feld umbenannt oder entfernt, schlägt tsc bei jeder Verwendung und dem gemeinsamen Dokument fehl – der Build bricht, bevor ein Benutzer ein leeres Panel sieht. Deshalb ist Codegen gegen das Live-Schema zwingend erforderlich.
    • UI → DB / Berechtigungsdrift, zur Laufzeit. Das gemeinsame Dokument wird gegen eine geseedete Test-DB durch den echten Aufrufpfad unter Rollenkontext ausgeführt und prüft auf die zurückgegebene Form und das Zugriffsergebnis – nicht den Abfragetext.
  • Kontrakttests und die RLS-Rollenmatrix sind derselbe Rahmen. Führen Sie das eine Dokument als Rolle A (erwarte Daten) und Rolle B (erwarte verweigert/leer) durch PostGraphile aus. Ein Mechanismus beweist drei Dinge: Abfrage entspricht noch Schema, UI-Annahmen gelten noch, RLS erzwingt noch die Grenze.

Ausgearbeitetes Beispiel – wie ein echter Fehler gefangen wird

  • DB→UI: Eine Migration entfernt equipment.is_active. Codegen generiert aus dem neuen Schema; der generierte Typ verliert das Feld; tsc schlägt fehl auf dem gemeinsamen Dokument und jeder Komponente, die es verwendet – beim Build gefangen, vor dem Merge. Kein Test prüft „Abfragetext == X."
  • UI→DB: Ein Entwickler erweitert die UI-Abfrage, um cancellation_reason abzurufen (RLS stellt es nur erhöhten Rollen zur Verfügung). Der Laufzeittest, der als einfaches Mitglied läuft, prüft die mitgliedssichtbare Form, erhält nun null/verweigert und schlägt fehl – erzwingt die Frage „Wollten wir das wirklich freigeben?"

§2 – Routenkontrakt- und Smoke-Tests

  • Routen aus einer einzigen Quelle aufgezählt. Jede Route hat einen Smoke-Test: rendern ohne Fehler + zeigt einen minimalen, erforderlichen Elementsatz (eine Überschrift, einen Orientierungspunkt, ein zentrales Steuerelement – keine detaillierte Interaktion).
  • Hinzufügen/Entfernen einer Route erzwingt eine entsprechende Teständerung – eine neue URL ist ohne ihren Smoke-Test unvollständig; eine entfernte URL entfernt ihren Test. URLs erscheinen oder verschwinden nie still.
  • Explizit KEINE detaillierten UI/Interaktionstests – bewusst, umfangbegrenzt. Die Frage ist „Funktioniert diese URL und rendert das Wesentliche", nichts weiter.

Durchsetzung: graphql-codegen + tsc in CI (blockierend) für die Kompilierzeithälfte; Laufzeit-Kontrakt- + Routen-Smoke-Tests in CI gegen eine gesedete DB.

Vollständige Begründung: Artikel XV der Verfassung, gebündelt unter 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.

Verwandte Skills

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