Skip to documentation

Guide · GraphQL

Available

Mock GraphQL as GraphQL

Start from SDL, configure operations against real schema fields, and return selection-set-shaped data. Variables, aliases, validation, persisted queries, and subscriptions stay part of the protocol instead of becoming REST-shaped shortcuts.

In this guide

  • Validate requests against SDL
  • Select scenarios from variables and headers
  • Return GraphQL data and errors
  • Test subscriptions and APQ deterministically

Prerequisites

  • A DotMock workspace you can access
  • The API ID in $API_ID and its published runtime URL in $MOCK_URL when the example calls the mock
On this page
  1. Define the schema first
  2. Configure a query with request data
  3. Use variables and headers for scenarios
  4. Reuse persistent state across operations
  5. Test subscriptions as an event sequence
  6. Dry-run the native operation

Define the schema first

Create a GraphQL workspace and paste or import SDL. DotMock uses the schema to validate operation documents and project configured responses onto the requested selection set.

graphql
type Query { user(id: ID!): User }
type Mutation { createUser(input: CreateUserInput!): User! }
type Subscription { userChanged: User! }

type User { id: ID!, name: String!, email: String!, role: Role! }
input CreateUserInput { name: String!, email: String! }
enum Role { ADMIN MEMBER }

Configure a query with request data

Select query.user, keep a deterministic fallback response, and use GraphQL-specific helpers when a field should reflect the request. Exact expressions preserve JSON types.

Operation
query User($id: ID!) {
  user(id: $id) { id name email role }
}

Response
{
  "id": "{{variable \"id\"}}",
  "name": "Ava Nguyen",
  "email": "[email protected]",
  "role": "MEMBER"
}

Use variables and headers for scenarios

Keep materially different outcomes as ordered scenarios. Match a variable, argument, or request header, then return provider-appropriate data or a GraphQL errors array. Do not encode GraphQL failures as arbitrary HTTP JSON unless the transport itself is failing.

  • variables.input.plan selects a premium mutation response
  • argument id selects a known entity
  • x-test-scenario selects deterministic validation or upstream behavior
  • Unknown fields fail GraphQL validation before response rendering

Reuse persistent state across operations

A mutation can create a record in a workspace-shared map and a later query can read it. Use GraphQL variable or argument references in the state key.

Mutation response
{{state.create "users-by-id"}}

Query response
{{state.get "users-by-id" "$variable.userId" "" null}}

Missing condition
!state.exists("users-by-id", variables["userId"])

Test subscriptions as an event sequence

For subscriptions, match the connection initialization and operation, then define an ordered data sequence and terminal event. Give CI a fixed clock and isolated run ID so event order is repeatable.

  • Validate the WebSocket initialization payload
  • Match operation name and variables
  • Emit ordered data events
  • End with an explicit complete or error event

Dry-run the native operation

The tester validates the document, finds the configured operation, applies the selected scenario, and returns the GraphQL response without persistent effects.

bash
dotmock --json test --api "$API_ID" --kind graphql \
  --target @graphql-target.json \
  --request @graphql-request.json