graphql-test-strategy

name	graphql-test-strategy
description	Analyzes a GraphQL API codebase and generates a production-grade TEST_STRATEGY.md covering testing levels, performance, security, automation, and tooling. Use when starting a new GraphQL project, preparing for a QA audit, or formalizing testing practices for engineering leadership review.
metadata	{"author":"denaliweb123-oss"}

GraphQL Test Strategy Generator

Instructions

Act as a Senior QA Architect. Create a comprehensive GraphQL Test Strategy Document for a production-grade supergraph, written at a level of technical depth ready for engineering leadership review.

Step 1: Explore the Codebase

Before writing anything, gather the following context by reading relevant files:

• Schema: GraphQL schema file(s) or the code-first schema builder (e.g., Pothos, Nexus, type-graphql). Identify all types, queries, mutations, subscriptions, and field-level nullability.
• Existing tests: Any test files — note what is already covered and what tooling is used (Jest, Vitest, Bun test, etc.).
• Resolvers: How resolvers are implemented, whether DataLoaders are used, and where N+1 patterns may exist.
• Data sources: Databases, external APIs, in-memory packages. Note what serves as the "source of truth."
• Infrastructure/deployment: Deployment target (Cloudflare Workers, Lambda, Node.js server, etc.) and any resource constraints (memory limits, cold starts, rate limits).
• Security config: Auth plugins, depth limiting, query complexity, introspection settings, rate limiting.
• CI/CD: Existing GitHub Actions or pipeline config files to understand what already runs in CI.
• README / CLAUDE.md: For any domain-specific context or constraints already documented.

Step 2: Identify Risk Areas

Based on the codebase exploration, identify:

1. Complexity hotspots: Deeply nested relationships that could exhaust memory or trigger N+1.
2. Filter/input attack surface: Any user-supplied regex, nested input objects, or dynamic query building.
3. Public contract surface: Fields/types that are consumed by external clients and must not break.
4. Nullability gaps: Fields that should be nullable but are not (or vice versa) — these cause runtime errors.
5. Missing coverage: Resolvers or edge cases with no existing tests.

Step 3: Generate TEST_STRATEGY.md

Write the document to the project root as TEST_STRATEGY.md. Use the following structure — include only sections relevant to the actual codebase; omit sections that don't apply:

# Test Strategy Document
## GraphQL API — Production-Grade Test Strategy

**Role:** Senior QA Architect
**Scope:** [describe the API and its public URL if known]
**Context:** [deployment target, schema builder, filter engine, resource constraints]
**Audience:** Engineering Leadership

---

## 0. Strategic Intent & Discovery

### 0.1 Discovery Questions
Write each as an explicit question. Follow each with: *Answer: [what was found and how it shaped testing].*
- Data integrity: how the source of truth is validated through schema transformations
- Resource constraints: what limits apply (memory, CPU, rate limits)
- Consumer safety: how breaking changes are prevented for public consumers

### 0.2 Priority Scenarios (Risk-Based)
List the 3–5 highest-risk scenarios with a concrete failure mode, severity rating (Critical / High / Medium), and blast radius.

### 0.3 Out of Scope & Trade-offs
Each exclusion must name the item, the reason for deferral (time / cost / feasibility), and the proxy signal that will substitute.

### 0.4 AI Methodology
Document the model used, the exact prompt, what the AI produced, and specific changes made during human review.

---

## 1. Schema Governance & Type Safety

Cover:
- Code-first vs SDL-first approach in this project
- Automated breaking change detection: tool used (graphql-inspector, Rover Subgraph Checks), CI integration, and exit criteria
- Schema snapshot testing for response structure regression
- Client code generation if applicable
- Schema linting rules (graphql-eslint)

---

## 2. Testing Levels

### 2.1 Unit Tests — Resolver Logic
- Extract complex logic from resolvers into standalone functions; test those directly with Jest or Bun test
- Cover: field splitting, type coercion, null guards, validation helpers
- Tooling: [name the test runner used in this project]

### 2.2 Integration Tests — Schema-Driven
 Execute full GraphQL operations against the in-memory server (yoga.fetch, Apollo test utils, etc.)
 Key scenarios: happy paths, nullability edge cases, filter combinations, error paths
 Snapshot testing: capture JSON response shapes and fail CI on structural drift


 Schema diffing strategy (graphql-inspector diff against main/production)
 Exit criteria: zero breaking changes without explicit approval and version bump


 Define the 3–5 highest-value user flows that must work end-to-end
 Tooling: Playwright or Cypress against a deployed staging environment
 Trigger: pre-release gate only (not on every PR)

---



Cover only what is relevant to the actual schema and deployment:
 : disabled in production (), enabled for authenticated developers in non-production
 : hard limit value and plugin used (e.g., )
 : cost budget, plugin used (e.g., ), and what triggers a block
 : requests/minute threshold and enforcement layer (CDN, middleware, or plugin)
 : validation applied to user-supplied regex inputs before execution
 : scope-based plugin and which fields are gated (if auth is present)

---



 : how N+1 patterns are identified in tests (query counts, tracing assertions)
 : which resolvers use DataLoaders, batching window, and cache scope
 : tool (k6, Artillery), target throughput, and latency thresholds for critical queries
 : how cache-hit rates are validated (headers, tracing, or observability tooling)
 : tracing and monitoring tooling (Apollo GraphOS, Stellate, or equivalent)

---




List concrete, measurable gates with current status:
| Gate | Target | Status |


Ordered list of CI steps grounded in the actual pipeline config. Recommended order:
 Lint & type check
 Schema diff (breaking change detection)
 Unit & integration tests
 Schema snapshot validation
 Security checks (depth, complexity, ReDoS fuzz)
 E2E tests (staging, pre-release only)

---



List the recommended tools per concern, distinguishing between currently in use and recommended additions:
| Concern | Tool | Status |
|---|---|---|
| Functional testing | Jest / Bun test | [In use / Recommended] |
| Schema validation | graphql-inspector or Rover | [In use / Recommended] |
| Monitoring & tracing | Apollo GraphOS | [In use / Recommended] |
| Load testing | k6 or Artillery | [In use / Recommended] |
| E2E | Playwright | [In use / Recommended] |
| Query complexity | graphql-query-complexity | [In use / Recommended] |

---




Use  only for items verified against the source (cite file:line).


Use  for all items not confirmed in source. Do not guess.

Step 4: Review Before Saving

Before writing the file:

• Confirm every [x] checklist item by citing the specific file and line number that implements it. If you cannot verify it, mark it [ ].
• Remove any section that has no real content for this project — do not pad with placeholder text.
• Ensure all resource constraints (memory limits, CPU budgets, rate limits) are specific numbers sourced from config files, not generic placeholders.
• Security and performance sections must reflect only what is found or concretely recommended for this codebase — not generic industry patterns.
• Tone must be technical and precise, suitable for an engineering leadership review.

Write the final document to TEST_STRATEGY.md in the project root.

---

Source: denaliweb123-oss/countries — distributed by TomeVault.