# Graysurf Agent Kit GRAPHQL API Testing

> GraphQL API Testing

- Skill: `tomevault-io/graysurf-agent-kit-graphql-api-testing` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/graysurf-agent-kit-graphql-api-testing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/graysurf-agent-kit-graphql-api-testing/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/graysurf-agent-kit-graphql-api-testing

---


# GraphQL API Testing

## Contract

Prereqs:

- `api-gql` available on `PATH` (install via `brew install nils-cli`).
- `jq` recommended for pretty-printing/assertions (optional).
- `setup/graphql/` exists (or bootstrap from template) with operations, vars, and optional endpoint/jwt presets.

Inputs:

- Operation + variables: `setup/graphql/operations/<op>.graphql` and `setup/graphql/operations/<vars>.json`.
- Optional flags/env: `--env`, `--url`, `--jwt`, `--config-dir`, `--no-history` (plus `GQL_URL`, `ACCESS_TOKEN`, `GQL_JWT_VALIDATE_ENABLED`,
  `GQL_JWT_VALIDATE_STRICT`, `GQL_JWT_VALIDATE_LEEWAY_SECONDS`).

Outputs:

- Response JSON printed to stdout; errors printed to stderr.
- Optional history file under `setup/graphql/.gql_history` (gitignored; disabled via `--no-history`).
- Optional markdown report via `api-gql report`.

Exit codes:

- `0`: request completed successfully
- non-zero: invalid inputs/missing files/http error/client error

Failure modes:

- Invalid GraphQL/variables JSON, or missing config files.
- Auth missing/invalid (JWT) or network/timeout/connection failures.

## Goal

Make GraphQL API calls reproducible via:

- `setup/graphql/operations/*.graphql` + `*.json` (operations + variables)
- `setup/graphql/endpoints.env` (+ optional `endpoints.local.env`)
- `setup/graphql/jwts.env` (+ optional `jwts.local.env`)
- `setup/graphql/schema.env` (+ committed schema SDL, e.g. `schema.gql`)
- `setup/graphql/prompt.md` (optional, committed; project context for LLMs: what to test, DB tooling, other test utilities)

## TL;DR (fast paths)

Call an existing operation:

```bash
api-gql call \
  --env local \
  --jwt default \
  setup/graphql/operations/<operation>.graphql \
  setup/graphql/operations/<variables>.json \
| jq .
```

Generate a report (includes a replayable `## Command` by default):

```bash
api-gql report \
  --case "<test case name>" \
  --op setup/graphql/operations/<operation>.graphql \
  --vars setup/graphql/operations/<variables>.json \
  --env local \
  --jwt default \
  --run
```

Generate a report from a copied `api-gql`/`gql.sh` command snippet (no manual rewriting):

```bash
api-gql report-from-cmd '<paste an api-gql/gql.sh command snippet>'
```

Replay the last run (history):

```bash
api-gql history --command-only
```

Resolve committed schema SDL (for LLMs to author new operations):

```bash
api-gql schema --config-dir setup/graphql
```

## Flow (decision tree)

- If `setup/graphql/prompt.md` exists → read it first for project-specific context.
- No `setup/graphql/` yet → bootstrap from template:
- `cp -R "$AGENT_HOME/skills/tools/testing/graphql-api-testing/assets/scaffold/setup/graphql" setup/`
- Have schema but no operation yet → resolve schema (`api-gql schema`) then add `setup/graphql/operations/<name>.graphql` + variables json.
- Have operation → run with `api-gql call`.
- Need a markdown report → use `api-gql report --run` (or `--response`).

## Notes (defaults)

- History is on by default: `setup/graphql/.gql_history` (gitignored); one-off disable with `--no-history` (or `GQL_HISTORY_ENABLED=false`).
- Reports include `## Command` by default; disable with `--no-command` (or `GQL_REPORT_INCLUDE_COMMAND_ENABLED=false`).
- Variables: any numeric `limit` fields (including nested pagination inputs) are normalized to at least `GQL_VARS_MIN_LIMIT` (default: 5;
  set `GQL_VARS_MIN_LIMIT=0` to disable).
- Prefer `--config-dir setup/graphql` in automation for deterministic discovery.

## CI / E2E (optional)

In CI, use `api-gql call` as the runner and `jq -e` as assertions (exit code is the contract):

```bash
set -euo pipefail

api-gql call \
  --config-dir setup/graphql \
  --env staging \
  --jwt ci \
  setup/graphql/operations/<operation>.graphql \
  setup/graphql/operations/<variables>.json \
| jq -e '(.errors? | length // 0) == 0 and .data != null' >/dev/null
```

Notes:

- Many GraphQL servers return HTTP 200 even when `.errors` is present, so assert it explicitly.
- If you don’t want CI jobs to write history, add `--no-history` (or set `GQL_HISTORY_ENABLED=false`).

## References

- Full guide (project template): `skills/tools/testing/graphql-api-testing/references/GRAPHQL_API_TESTING_GUIDE.md`
- Report contract: `skills/tools/testing/graphql-api-testing/references/GRAPHQL_API_TEST_REPORT_CONTRACT.md`
- Report template: `skills/tools/testing/graphql-api-testing/references/GRAPHQL_API_TEST_REPORT_TEMPLATE.md`

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/graysurf) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->