How to Test a GraphQL API in CI

A GraphQL endpoint is one POST route, so a test sends a query in the body and asserts on data and errors.

POST a JSON { "query": "..." } payload to /graphql, then assert the errors array is absent and data has the shape you expect.

Steps

• POST the query as JSON to the /graphql route.
• Assert errors is null or absent, then check data.
• Pass variables in the variables field, not by string interpolation.

Workflow

jobs:
  graphql:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          npm start &
          npx wait-on http://localhost:4000/graphql
      - run: |
          resp=$(curl -sf http://localhost:4000/graphql \
            -H 'content-type: application/json' \
            -d '{"query":"{ viewer { id name } }"}')
          echo "$resp" | jq -e '.errors | not'
          echo "$resp" | jq -e '.data.viewer.id'

Gotchas

• GraphQL returns HTTP 200 even for query errors, so assert on the errors field, not the status code.
• For typed suites, generate a client from the schema so query changes fail at compile time.

Related guides