{"id":14078,"library":"supertest-graphql","title":"Supertest GraphQL Extension","description":"supertest-graphql extends the popular `supertest` library to provide a streamlined API for testing GraphQL endpoints. It is currently at version 1.1.4 and appears to be in maintenance mode, with minor bug fixes and dependency updates being the primary release activity. The library simplifies sending GraphQL queries, mutations, and even subscriptions over WebSockets, abstracting away the HTTP/WebSocket request details. Key differentiators include its direct integration with `supertest`'s familiar chaining API for assertions and request configuration, explicit methods for queries (`.query()`) and mutations (`.mutate()`), and specific helpers like `.expectNoErrors()` for GraphQL error validation. It also offers dedicated support for testing GraphQL subscriptions via WebSockets, making it a comprehensive tool for end-to-end GraphQL API testing, particularly within a Node.js testing environment like Jest.","status":"maintenance","version":"1.1.4","language":"javascript","source_language":"en","source_url":"https://github.com/alexstrat/supertest-graphql","tags":["javascript","supertest","graphql","test","jest","apollo","typescript"],"install":[{"cmd":"npm install supertest-graphql","lang":"bash","label":"npm"},{"cmd":"yarn add supertest-graphql","lang":"bash","label":"yarn"},{"cmd":"pnpm add supertest-graphql","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for parsing GraphQL queries (e.g., with `gql` tag) and understanding GraphQL types.","package":"graphql","optional":false},{"reason":"The core HTTP assertion library that `supertest-graphql` extends. Essential for its functionality.","package":"supertest","optional":false},{"reason":"Commonly used alongside `supertest-graphql` for parsing GraphQL query strings, especially for `gql` tagged template literals.","package":"graphql-tag","optional":true}],"imports":[{"note":"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.","wrong":"const request = require('supertest-graphql')","symbol":"request","correct":"import request from 'supertest-graphql'"},{"note":"`supertestWs` is a named export specifically for testing GraphQL subscriptions over WebSockets. It is separate from the default `request` export.","wrong":"import request, { supertestWs } from 'supertest-graphql'","symbol":"supertestWs","correct":"import { supertestWs } from 'supertest-graphql'"},{"note":"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.","wrong":"import { gql } from 'supertest-graphql'","symbol":"gql","correct":"import gql from 'graphql-tag'"}],"quickstart":{"code":"import request from 'supertest-graphql'\nimport gql from 'graphql-tag'\nimport express from 'express'\nimport { graphqlHTTP } from 'express-graphql'\nimport { buildSchema } from 'graphql'\n\n// Minimal GraphQL server setup for demonstration\nconst schema = buildSchema(`\n  type Pet {\n    name: String\n    petType: String\n  }\n  type Query {\n    pets: [Pet]\n  }\n  type Mutation {\n    addPet(name: String!, petType: String!): Pet\n  }\n`)\n\nconst root = {\n  pets: () => [\n    { name: 'Buddy', petType: 'Dog' },\n    { name: 'Whiskers', petType: 'Cat' }\n  ],\n  addPet: ({ name, petType }) => ({ name, petType })\n}\n\nconst app = express()\napp.use('/graphql', graphqlHTTP({ schema: schema, rootValue: root, graphiql: false }))\n\n// --- supertest-graphql usage ---\n\ndescribe('GraphQL API tests', () => {\n  test('should fetch pets via query', async () => {\n    const { data } = await request(app)\n      .query(gql`\n        query {\n          pets {\n            name\n            petType\n          }\n        }\n      `)\n      .expectNoErrors()\n      .expect(200)\n    \n    expect(data.pets).toHaveLength(2)\n    expect(data.pets[0].name).toBe('Buddy')\n  })\n\n  test('should add a pet via mutation', async () => {\n    const newPetName = 'Fido'\n    const newPetType = 'Dog'\n\n    const { data } = await request(app)\n      .mutate(gql`\n        mutation AddPet($name: String!, $petType: String!) {\n          addPet(name: $name, petType: $petType) {\n            name\n            petType\n          }\n        }\n      `)\n      .variables({ name: newPetName, petType: newPetType })\n      .expectNoErrors()\n      .expect(200)\n\n    expect(data.addPet.name).toBe(newPetName)\n    expect(data.addPet.petType).toBe(newPetType)\n  })\n\n  test('should handle authorization via headers', async () => {\n    const authToken = process.env.AUTH_TOKEN ?? 'some_secret_token'\n    const { data } = await request(app)\n      .set('Authorization', `Bearer ${authToken}`)\n      .query(gql`\n        query {\n          pets {\n            name\n          }\n        }\n      `)\n      .expectNoErrors()\n      .expect(200)\n    expect(data.pets).toHaveLength(2)\n  })\n})","lang":"typescript","description":"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."},"warnings":[{"fix":"Always chain both GraphQL-specific and HTTP-specific assertions to fully validate responses. For example: `.expectNoErrors().expect(200)`.","message":"`supertest-graphql` relies on `supertest` for HTTP assertions. When testing, remember to use both `supertest-graphql`'s specific assertions (e.g., `.expectNoErrors()`) and `supertest`'s general HTTP assertions (e.g., `.expect(200)`, `.expect('Content-Type', /json/)`).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use `import { supertestWs } from 'supertest-graphql'` and ensure your WebSocket server is properly managing its lifecycle around subscription tests. Refer to the `supertest-graphql` documentation for detailed subscription test patterns.","message":"When testing GraphQL subscriptions, `supertest-graphql` requires a different entry point (`supertestWs`) and expects the server to be manually started and closed (e.g., with `beforeEach`/`afterEach` hooks in your test runner), unlike HTTP requests where `supertest` can often handle a direct application instance.","severity":"gotcha","affected_versions":">=1.1.3"},{"fix":"Install `graphql-tag` (e.g., `npm install graphql-tag`) if you plan to use `gql` for query definitions. Ensure `graphql` is installed and meets the peer dependency requirements of `supertest-graphql`.","message":"`supertest-graphql` does not bundle `graphql-tag` or `graphql`. While it works with raw string queries, using `gql` tagged template literals (from `graphql-tag`) is common for better syntax highlighting and parsing. `graphql` itself is a peer dependency.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'1.1.4':26 'abstract':58 'activ':45 'also':99 'api':16,75,120 'apollo':135 'appear':28 'assert':77 'away':59 'bug':36 'chain':74 'comprehens':112 'configur':80 'current':23 'dedic':101 'depend':39 'detail':63 'differenti':65 'direct':68 'end':116,118 'end-to-end':115 'endpoint':20 'environ':127 'error':96 'even':54 'expectnoerror':93 'explicit':81 'extend':7 'extens':3 'familiar':73 'fix':37 'graphql':2,6,19,50,95,105,119,132 'helper':91 'http/websocket':61 'includ':66 'integr':69 'javascript':130 'jest':129,134 'key':64 'librari':11,47 'like':92,128 'mainten':32 'make':109 'method':82 'minor':35 'mode':33 'mutat':52,87,88 'node.js':125 'offer':100 'particular':122 'popular':9 'primari':43 'provid':13 'queri':51,84,85 'releas':44 'request':62,79 'send':49 'simplifi':48 'specif':90 'streamlin':15 'subscript':55,106 'supertest':1,5,10,71,131 'supertest-graphql':4 'support':102 'test':18,104,121,126,133 'tool':113 'typescript':136 'updat':40 'valid':97 'version':25 'via':107 'websocket':57,108 'within':123","created_at":"2026-04-20T01:57:48.929652+00:00","updated_at":"2026-04-20T01:57:48.929652+00:00","problems":[{"fix":"Ensure you are importing `request` from `supertest-graphql`: `import request from 'supertest-graphql'`.","cause":"You are likely trying to use the `request` function imported from `supertest` directly, instead of `supertest-graphql`'s extended `request` function.","error":"TypeError: request(...).query is not a function"},{"fix":"Review your GraphQL query or mutation string for syntax errors. Use `gql` from `graphql-tag` for better IDE support and error checking during development.","cause":"The GraphQL query string provided to `.query()` or `.mutate()` is syntactically incorrect or malformed, causing the GraphQL server to return a parsing error.","error":"expected no errors but got 1 error(s) in GraphQL response: Syntax Error: Unexpected Name \"blooop\"."},{"fix":"Verify 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.","cause":"The GraphQL query is valid syntactically but requests a field that does not exist on the specified type in your GraphQL schema.","error":"Error: GraphQL error: Cannot query field \"nonExistentField\" on type \"MyType\"."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/alexstrat/supertest-graphql","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/supertest-graphql","openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing","http-networking","web-framework"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}