Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
request
✓ import request from 'supertest-graphql'
✗ const request = require('supertest-graphql')
This is the default export for HTTP-based GraphQL requests (queries/mutations). `supertest-graphql` ships with ESM and CJS support, but modern usage in testing often leans towards ESM.
supertestWs
✓ import { supertestWs } from 'supertest-graphql'
✗ import request, { supertestWs } from 'supertest-graphql'
`supertestWs` is a named export specifically for testing GraphQL subscriptions over WebSockets. It is separate from the default `request` export.
gql
✓ import gql from 'graphql-tag'
✗ import { gql } from 'supertest-graphql'
While `gql` is often used with `supertest-graphql`, it's an export from the `graphql-tag` package, not `supertest-graphql` itself. Remember to install `graphql-tag` separately.
This quickstart demonstrates how to use `supertest-graphql` to test both GraphQL queries and mutations against an Express-based GraphQL server, including variable passing and setting custom headers for authentication.
import request from 'supertest-graphql'
import gql from 'graphql-tag'
import express from 'express'
import { graphqlHTTP } from 'express-graphql'
import { buildSchema } from 'graphql'
// Minimal GraphQL server setup for demonstration
const schema = buildSchema(`
type Pet {
name: String
petType: String
}
type Query {
pets: [Pet]
}
type Mutation {
addPet(name: String!, petType: String!): Pet
}
`)
const root = {
pets: () => [
{ name: 'Buddy', petType: 'Dog' },
{ name: 'Whiskers', petType: 'Cat' }
],
addPet: ({ name, petType }) => ({ name, petType })
}
const app = express()
app.use('/graphql', graphqlHTTP({ schema: schema, rootValue: root, graphiql: false }))
// --- supertest-graphql usage ---
describe('GraphQL API tests', () => {
test('should fetch pets via query', async () => {
const { data } = await request(app)
.query(gql`
query {
pets {
name
petType
}
}
`)
.expectNoErrors()
.expect(200)
expect(data.pets).toHaveLength(2)
expect(data.pets[0].name).toBe('Buddy')
})
test('should add a pet via mutation', async () => {
const newPetName = 'Fido'
const newPetType = 'Dog'
const { data } = await request(app)
.mutate(gql`
mutation AddPet($name: String!, $petType: String!) {
addPet(name: $name, petType: $petType) {
name
petType
}
}
`)
.variables({ name: newPetName, petType: newPetType })
.expectNoErrors()
.expect(200)
expect(data.addPet.name).toBe(newPetName)
expect(data.addPet.petType).toBe(newPetType)
})
test('should handle authorization via headers', async () => {
const authToken = process.env.AUTH_TOKEN ?? 'some_secret_token'
const { data } = await request(app)
.set('Authorization', `Bearer ${authToken}`)
.query(gql`
query {
pets {
name
}
}
`)
.expectNoErrors()
.expect(200)
expect(data.pets).toHaveLength(2)
})
})
Errors
Common errors & fixes
TypeError: request(...).query is not a function
You are likely trying to use the `request` function imported from `supertest` directly, instead of `supertest-graphql`'s extended `request` function.
fixEnsure you are importing `request` from `supertest-graphql`: `import request from 'supertest-graphql'`.
expected no errors but got 1 error(s) in GraphQL response: Syntax Error: Unexpected Name "blooop".
The GraphQL query string provided to `.query()` or `.mutate()` is syntactically incorrect or malformed, causing the GraphQL server to return a parsing error.
fixReview your GraphQL query or mutation string for syntax errors. Use `gql` from `graphql-tag` for better IDE support and error checking during development.
Error: GraphQL error: Cannot query field "nonExistentField" on type "MyType".
The GraphQL query is valid syntactically but requests a field that does not exist on the specified type in your GraphQL schema.
fixVerify that the fields requested in your query or mutation precisely match the fields defined in your GraphQL schema. This often indicates a mismatch between the test query and the actual API schema.
Audit
Dependencies
graphqlrequiredRequired for parsing GraphQL queries (e.g., with `gql` tag) and understanding GraphQL types.
supertestrequiredThe core HTTP assertion library that `supertest-graphql` extends. Essential for its functionality.
graphql-tagoptionalCommonly used alongside `supertest-graphql` for parsing GraphQL query strings, especially for `gql` tagged template literals.