Test Batched GraphQL Requests with Examples

TL;DR

Send a JSON array of GraphQL operation objects, then assert one ordered result per operation. Cover mixed success, validation errors, variables, authorization isolation, mutations, batch limits, complexity budgets, and safe error responses before enabling batching in production.

Key Takeaways

• Treat JSON array batching as an optional HTTP transport feature, not a GraphQL specification requirement.
• Test response count and index order so every result maps to the operation sent at the same position.
• Prove that one invalid operation cannot cancel, alter, or hide the results of valid batch neighbors.
• Verify authorization independently for every operation and prevent identity or context leakage across entries.
• Enforce operation-count, payload-size, complexity, timeout, and rate limits before expensive work begins.
• Use stable GraphQL error codes and resolver call counts instead of relying only on HTTP status or timing.

These graphql batched requests testing examples prove more than whether a server accepts a JSON array. A reliable suite verifies response ordering, operation isolation, authorization, partial errors, mutations, and resource limits for every entry in the batch.

This tutorial builds a small Node.js endpoint and a Vitest suite you can paste into an empty project. For the wider strategy around schemas, resolvers, security, subscriptions, and delivery pipelines, read the Modern GraphQL API Testing Complete Guide.

HTTP array batching is not required by the core GraphQL specification. It is a server or gateway capability, so first document whether your deployed stack supports it and what contract it promises. The examples below make that contract explicit and testable.

What You Will Build

By the end, you will have:

• A runnable Express and GraphQL endpoint that accepts a JSON array of operations.
• Tests for successful batches, variables, aliases, and ordered responses.
• Mixed-result tests in which invalid and unauthorized entries stay isolated.
• Mutation tests that document sequential execution and visible side effects.
• Count, byte-size, aggregate-complexity, and timeout-oriented safeguards.
• A reusable coverage matrix for application, gateway, and production-path testing.

The lab deliberately uses an in-memory data set. That keeps results deterministic and lets resolver counters prove whether rejected work executed.

Prerequisites

Use Node.js 22 or a current supported LTS release and npm 10 or newer. Create the project and install the runtime and test dependencies:

mkdir graphql-batch-lab
cd graphql-batch-lab
npm init -y
npm install express graphql
npm install --save-dev vitest supertest
mkdir -p src test

Replace the relevant fields in package.json with these scripts and ES module setting:

{
  "type": "module",
  "scripts": {
    "start": "node src/server.js",
    "test": "vitest run",
    "test:watch": "vitest"
  }
}

You need no external API key or database. Use curl for manual checks and Vitest plus Supertest for automated HTTP assertions.

Step 1: Create a Deterministic GraphQL Schema

Create src/schema.js. It exposes a viewer query, a user lookup, and a mutation whose state you can inspect. Resolver counters make early-rejection claims measurable.

import { buildSchema, defaultFieldResolver } from 'graphql';

export const schema = buildSchema(`
  type Query {
    viewer: User!
    user(id: ID!): User
  }

  type Mutation {
    renameUser(id: ID!, name: String!): User!
  }

  type User {
    id: ID!
    name: String!
    email: String!
  }
`);

const initialUsers = [
  { id: '1', name: 'Asha', email: 'asha@example.test' },
  { id: '2', name: 'Noah', email: 'noah@example.test' }
];

let users = structuredClone(initialUsers);
export const calls = { viewer: 0, user: 0, renameUser: 0 };

export function resetState() {
  users = structuredClone(initialUsers);
  Object.keys(calls).forEach((key) => { calls[key] = 0; });
}

export const rootValue = {
  viewer(_args, context) {
    calls.viewer += 1;
    return users.find((user) => user.id === context.userId);
  },
  user({ id }) {
    calls.user += 1;
    return users.find((user) => user.id === id) ?? null;
  },
  renameUser({ id, name }) {
    calls.renameUser += 1;
    const user = users.find((candidate) => candidate.id === id);
    if (!user) throw new Error('User not found');
    user.name = name;
    return user;
  }
};

export const fieldResolver = (source, args, context, info) => {
  const root = rootValue[info.fieldName];
  if (source === undefined && root) return root(args, context, info);
  return defaultFieldResolver(source, args, context, info);
};

The .test email domain prevents examples from resembling real customer data. resetState gives every test a clean starting point, while counters expose unexpected execution.

Verify: run node -e "import('./src/schema.js').then(m => console.log(m.schema.getQueryType().name))". It prints Query. If Node reports an import error, check that package.json contains "type": "module".

Step 2: Implement an Explicit Batch Contract

Create src/app.js. The endpoint accepts either one operation object or an array. It validates the envelope, limits the batch, executes every accepted entry independently, and preserves input order with Promise.all.

import express from 'express';
import { execute, parse, validate } from 'graphql';
import { fieldResolver, rootValue, schema } from './schema.js';

export const MAX_BATCH_SIZE = 5;

function publicError(message, code) {
  return { errors: [{ message, extensions: { code } }] };
}

async function runOperation(operation, contextValue) {
  if (!operation || typeof operation.query !== 'string') {
    return publicError('A GraphQL query string is required.', 'BAD_REQUEST');
  }

  let document;
  try {
    document = parse(operation.query);
  } catch {
    return publicError('The GraphQL document is invalid.', 'GRAPHQL_PARSE_FAILED');
  }

  const errors = validate(schema, document);
  if (errors.length > 0) {
    return {
      errors: errors.map((error) => ({
        message: error.message,
        extensions: { code: 'GRAPHQL_VALIDATION_FAILED' }
      }))
    };
  }

  return execute({
    schema,
    document,
    rootValue,
    contextValue,
    variableValues: operation.variables,
    operationName: operation.operationName,
    fieldResolver
  });
}

export function createApp() {
  const app = express();
  app.use(express.json({ limit: '32kb' }));

  app.post('/graphql', async (request, response) => {
    const isBatch = Array.isArray(request.body);
    const operations = isBatch ? request.body : [request.body];

    if (isBatch && operations.length === 0) {
      return response.status(400).json(publicError('Batch cannot be empty.', 'EMPTY_BATCH'));
    }
    if (operations.length > MAX_BATCH_SIZE) {
      return response.status(413).json(publicError('Batch limit exceeded.', 'BATCH_LIMIT_EXCEEDED'));
    }

    const contextValue = { userId: request.get('x-user-id') ?? '1' };
    const results = await Promise.all(
      operations.map((operation) => runOperation(operation, contextValue))
    );
    return response.status(200).json(isBatch ? results : results[0]);
  });

  return app;
}

Create src/server.js:

import { createApp } from './app.js';

createApp().listen(4000, () => {
  console.log('GraphQL endpoint: http://localhost:4000/graphql');
});

This contract returns HTTP 200 for an accepted envelope even when an individual GraphQL result contains errors. It returns an HTTP error when the entire transport envelope is unacceptable. Your production convention may differ, but it must be documented and consistent.

Verify: run npm start, then send a two-entry array:

curl -s http://localhost:4000/graphql \
  -H 'content-type: application/json' \
  --data '[{"query":"{ viewer { id name } }"},{"query":"{ user(id: \"2\") { id name } }"}]'

The response is an array with Asha at index 0 and Noah at index 1.

Step 3: Add Successful GraphQL Batched Requests Testing Examples

Create test/batch.test.js. Start with the transport invariants: the result is an array, its length equals the request length, and each index maps to the same request index.

import { beforeEach, describe, expect, test } from 'vitest';
import request from 'supertest';
import { createApp, MAX_BATCH_SIZE } from '../src/app.js';
import { calls, resetState } from '../src/schema.js';

const app = createApp();
const post = (payload, headers = {}) =>
  request(app).post('/graphql').set(headers).send(payload);

describe('GraphQL HTTP array batching', () => {
  beforeEach(resetState);

  test('returns one ordered result per operation', async () => {
    const response = await post([
      { query: 'query First { user(id: "2") { name } }' },
      { query: 'query Second { user(id: "1") { name } }' },
      { query: '{ viewer { id } }' }
    ]);

    expect(response.status).toBe(200);
    expect(response.body).toHaveLength(3);
    expect(response.body.map((result) => result.data)).toEqual([
      { user: { name: 'Noah' } },
      { user: { name: 'Asha' } },
      { viewer: { id: '1' } }
    ]);
  });

  test('coerces variables independently for each entry', async () => {
    const query = 'query User($id: ID!) { user(id: $id) { id name } }';
    const response = await post([
      { query, variables: { id: '1' } },
      { query, variables: { id: '2' } }
    ]);

    expect(response.body[0].data.user.name).toBe('Asha');
    expect(response.body[1].data.user.name).toBe('Noah');
    expect(calls.user).toBe(2);
  });
});

Do not identify results by operation name alone. Names can be omitted or repeated across independent entries. Positional mapping is the interoperable contract for a plain JSON array unless your vendor defines a separate identifier field.

Variables belong to their own operation object. A server that accidentally shares the first variables object across the batch can return valid-looking but incorrect data, which is why the second test uses one document with different values.

Verify: run npm test. Vitest reports two passing tests. Temporarily reverse the two expected names and confirm the ordering assertion fails with a clear index-level diff.

Step 4: Test Mixed Success and Error Isolation

A batch often contains valid, invalid, and runtime-failing operations together. One bad entry must not erase successful neighbors unless your documented gateway contract rejects the entire envelope before GraphQL processing. Add these tests inside the existing describe block:

test('isolates validation failure from valid neighbors', async () => {
  const response = await post([
    { query: '{ user(id: "1") { name } }' },
    { query: '{ unknownField }' },
    { query: '{ user(id: "2") { name } }' }
  ]);

  expect(response.status).toBe(200);
  expect(response.body[0]).toEqual({ data: { user: { name: 'Asha' } } });
  expect(response.body[1].data).toBeUndefined();
  expect(response.body[1].errors[0].extensions.code)
    .toBe('GRAPHQL_VALIDATION_FAILED');
  expect(response.body[2]).toEqual({ data: { user: { name: 'Noah' } } });
  expect(calls.user).toBe(2);
});

test('reports malformed operation objects at their index', async () => {
  const response = await post([
    { query: '{ viewer { id } }' },
    { variables: { id: '1' } },
    null
  ]);

  expect(response.body[0].data.viewer.id).toBe('1');
  expect(response.body[1].errors[0].extensions.code).toBe('BAD_REQUEST');
  expect(response.body[2].errors[0].extensions.code).toBe('BAD_REQUEST');
  expect(calls.viewer).toBe(1);
});

Assert useful invariants rather than exact framework prose. Error messages can change during dependency upgrades, while documented extensions.code, index, response shape, and side-effect count should remain stable. Also test syntax errors, missing required variables, the wrong variable type, an unknown operationName, and multiple operations without a selected name.

Partial GraphQL data is different from a mixed batch. A single operation may contain both data and errors when a nullable field fails. Preserve that object at its index and avoid flattening all errors into one batch-level array.

Verify: run npx vitest run test/batch.test.js. Both new tests pass, successful neighbors retain their correct indexes, and only two user resolvers execute in the validation case.

Step 5: Verify Authorization and Context Isolation

The sample authenticates once per HTTP request through x-user-id, which means all entries intentionally share one principal. Test that behavior, then decide whether your real service permits per-operation credentials. Most should not, because accepting identity material inside GraphQL variables invites inconsistent enforcement.

Add an authorization rule at the beginning of renameUser in src/schema.js:

renameUser({ id, name }, context) {
  calls.renameUser += 1;
  if (context.userId !== id) {
    const error = new Error('You cannot rename this user.');
    error.extensions = { code: 'FORBIDDEN' };
    throw error;
  }
  const user = users.find((candidate) => candidate.id === id);
  if (!user) throw new Error('User not found');
  user.name = name;
  return user;
}

Then test an allowed and forbidden mutation in one authenticated batch:

test('applies the request identity to every operation', async () => {
  const mutation = `
    mutation Rename($id: ID!, $name: String!) {
      renameUser(id: $id, name: $name) { id name }
    }
  `;
  const response = await post([
    { query: mutation, variables: { id: '1', name: 'Asha QA' } },
    { query: mutation, variables: { id: '2', name: 'Noah QA' } }
  ], { 'x-user-id': '1' });

  expect(response.body[0].data.renameUser.name).toBe('Asha QA');
  expect(response.body[1].data).toBeNull();
  expect(response.body[1].errors[0].extensions.code).toBe('FORBIDDEN');
});

In production, verify object authorization below the root field too. A shared request context may safely share an authenticated principal, correlation ID, and request-scoped DataLoader. It must not reuse mutable authorization decisions keyed only by field name. Cache authorization by principal, object identifier, action, and tenant, or keep decisions local to the resolver.

Add two tenant fixtures if the API is multi-tenant. Query tenant A and tenant B objects in alternating entries, then assert no object, error detail, cache entry, or trace attribute crosses the boundary.

Verify: run npm test. The first mutation succeeds, the second returns FORBIDDEN, and querying user 2 afterward still returns Noah, not Noah QA.

Step 6: Document Mutation Ordering and Side Effects

The GraphQL execution algorithm serializes top-level mutation fields inside one operation. It does not define ordering across separate operations in an HTTP batch. Our Promise.all implementation can run separate mutations concurrently, so clients must not depend on cross-entry order.

Use a single mutation operation when one write depends on another. Use separate batch entries only for independent writes or when your server explicitly guarantees a stronger contract. Add this test to document the safe pattern:

test('serializes dependent mutation fields inside one operation', async () => {
  const response = await post({
    query: `
      mutation TwoRenames {
        first: renameUser(id: "1", name: "First") { name }
        second: renameUser(id: "1", name: "Second") { name }
      }
    `
  }, { 'x-user-id': '1' });

  expect(response.body.data.first.name).toBe('First');
  expect(response.body.data.second.name).toBe('Second');
  expect(calls.renameUser).toBe(2);
});

Next, add a batch containing a successful write and a forbidden write, then query both records. This proves whether your implementation treats the batch as independent operations or a transaction. The tutorial contract keeps the successful write and reports the failed neighbor. Do not assume a shared database transaction unless the API contract explicitly promises one.

Retries deserve special attention. If a proxy retries the whole batch after a connection failure, already committed mutations may run twice. Use idempotency keys for retryable write operations, persist each key with its result, and test duplicate batches. A request-level key may be too coarse when entries commit independently, so define whether the key identifies the batch or each operation.

Verify: run the targeted test. first.name is First, second.name is Second, and the final query returns Second. This proves order within one mutation operation, not across batch entries.

Step 7: Enforce Batch, Payload, and Complexity Limits

Batching reduces network overhead but can multiply server work behind one HTTP request. Apply limits at several layers instead of trusting operation count alone.

Add count boundary tests:

test('accepts exactly the configured batch maximum', async () => {
  const operation = { query: '{ viewer { id } }' };
  const response = await post(Array(MAX_BATCH_SIZE).fill(operation));
  expect(response.status).toBe(200);
  expect(response.body).toHaveLength(MAX_BATCH_SIZE);
  expect(calls.viewer).toBe(MAX_BATCH_SIZE);
});

test('rejects one entry above the limit before execution', async () => {
  const operation = { query: '{ viewer { id } }' };
  const response = await post(Array(MAX_BATCH_SIZE + 1).fill(operation));
  expect(response.status).toBe(413);
  expect(response.body.errors[0].extensions.code)
    .toBe('BATCH_LIMIT_EXCEEDED');
  expect(calls.viewer).toBe(0);
});

A five-entry maximum is illustrative, not a universal recommendation. Choose limits from legitimate client operations, resolver fan-out, dependency capacity, and gateway behavior. Charge rate limits by operation count or calculated cost, not merely one HTTP request. Otherwise a client can multiply allowed work by the batch maximum.

Use parsed AST complexity rather than query string length. Enforce both a per-operation ceiling and an aggregate batch budget before execution. The GraphQL query complexity security testing tutorial shows how to test aliases, depth, list multipliers, and zero resolver execution.

Verify: run the full test file. The exact boundary executes five viewer resolvers. Six entries receive BATCH_LIMIT_EXCEEDED, and the viewer counter remains zero. Also send a body larger than 32 KB manually and confirm Express returns the status your error middleware documents.

Step 8: Run GraphQL Batched Requests Testing Examples on the Deployed Path

An in-process suite proves application behavior, but a CDN, WAF, API gateway, GraphQL router, or serverless platform may alter array bodies, status codes, timeouts, and size limits. Run the same contract tests against a deployed test URL with real authentication and synthetic data.

Record one request correlation ID for the envelope and a child operation index or operation ID for each entry. Logs and traces should answer four questions: which batch was received, which operations were accepted, which result index failed, and how much work each entry consumed. Do not put raw query text or variables into unrestricted logs. Use operation names and persisted-document hashes, and redact sensitive values.

Test cancellation with a controlled slow dependency. Disconnect the client or exceed the gateway deadline, then prove database queries, fetch calls, and timers receive an abort signal. A timeout response is not enough if orphaned resolvers continue consuming resources. Test partial upstream failure too: one dependency error should map to the correct operation index without corrupting neighboring results.

If the deployed stack uses persisted queries, batch unknown hashes, known hashes, and hash-query mismatches together. Assert cache isolation and stable error codes. If it supports incremental delivery, verify whether batching is prohibited or how multipart responses identify their originating operation. Never infer that behavior from single-operation tests.

Verify: compare local and deployed results for the same fixture batch. Response length, order, data, error codes, and resolver-side audit events should agree. Document any intentional gateway difference in the contract test configuration.

Troubleshooting

The server returns 400 for every array -> Confirm that HTTP batching is enabled by your GraphQL server or gateway. Array batching is optional. If unsupported, test the documented rejection and send independent requests instead.

Results appear in completion order -> Preserve the original index when launching work and assemble results by that index. Promise.all preserves input order, but manually pushing results from asynchronous callbacks does not.

One invalid query rejects the entire batch -> Separate envelope validation from per-operation parse and validation. Reject the envelope only for batch-wide faults such as an empty array, excessive count, invalid JSON, or oversized bytes.

Variables leak between operations -> Pass each entry's own variables object to execution. Avoid mutating shared request objects, and test one query document with different variables at adjacent indexes.

Authorization results leak across entries -> Audit request-scoped caches and DataLoader keys. Include tenant, principal, object ID, and action where relevant, and add alternating allowed and forbidden operations to the same batch.

The limit test passes but production overloads -> Count alone does not model work. Add weighted per-operation and aggregate complexity, pagination caps, request bytes, rate charging, deadlines, concurrency controls, and deployed-path tests.

Best Practices

• Publish whether array batching is supported and define request and response shapes.
• Preserve one result per operation in input order, including error results.
• Validate and coerce every entry independently.
• Authenticate the HTTP request once, then authorize every object and action.
• Reject unacceptable batch envelopes before parsing or executing expensive work.
• Apply per-operation and aggregate cost limits.
• Charge quotas by operation count or cost rather than HTTP request count.
• Avoid dependent mutations across separate batch entries.
• Make write retries idempotent and test duplicate delivery.
• Correlate envelope traces with operation indexes without logging secrets.
• Test through the gateway and other production intermediaries.
• Keep a single-operation regression test so batching changes do not break ordinary clients.

Do not enable batching only because it lowers request count. Measure downstream concurrency, database load, cache behavior, and tail latency under representative traffic. A small controlled batch can help a client, while unrestricted batching can become a rate-limit and denial-of-service bypass.

Interview Questions and Answers

Use these questions to explain the contract and the test evidence, not merely the happy-path request format.

Q: Is GraphQL HTTP batching part of the GraphQL specification?

No. A JSON array of operation objects is an implementation-specific HTTP transport capability. Confirm support and document its request, response, error, and limit behavior before writing assumptions into clients.

Q: How do you map batch responses to requests?

For plain array batching, assert that result count equals operation count and index n corresponds to request index n. Do not rely on completion timing or unique operation names unless a vendor contract defines identifiers.

Q: What should happen when one operation is invalid?

An accepted batch normally keeps a result at that index with parse or validation errors while valid neighbors complete. Batch-wide envelope faults can reject the whole request. Tests should distinguish these two layers.

Q: How do you test authorization in a batch?

Mix allowed and forbidden operations under one authenticated request. Assert each result, inspect final state, and verify caches cannot reuse a decision across principals, tenants, objects, or actions.

Q: Why is an operation-count limit insufficient?

Operations have different cost. Enforce byte size, per-operation complexity, aggregate complexity, pagination, deadlines, concurrency, and cost-aware rate limits in addition to count.

Q: Are batched mutations transactional or ordered?

Not by default. Top-level fields within one mutation operation execute serially, but separate operations in an HTTP batch have no standard cross-operation ordering or atomicity guarantee. Dependent writes should stay in one defined operation or use an explicit workflow.

Where To Go Next

You now have runnable graphql batched requests testing examples for ordering, variables, partial errors, authorization, mutations, limits, and deployed behavior. Place them within the complete modern GraphQL API testing strategy, then adapt the fixtures to your schema and gateway.

Next, add GraphQL query complexity security tests so individually cheap operations cannot exceed an aggregate budget. Use the GraphQL subscriptions and WebSockets tutorial for connection and event-stream behavior, and protect schema evolution with GraphQL deprecation validation using schema diff. For the surrounding HTTP controls, add API authorization test cases and API rate limiting test scenarios.

Conclusion

Good GraphQL batch testing proves positional mapping, independent validation, authorization isolation, safe mutation behavior, and bounded resource use. Assert results and side effects together, because a correct-looking error is not protective if rejected resolvers already ran.

Start with the eight-step lab, then run the same fixtures through your real gateway with representative authentication and persisted operations. Keep batching optional, measured, and protected by aggregate limits.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• Selenium Test Web Components Slots Tutorial: Test Web Component Slots with Selenium
• AI test data generation with Faker and LLMs (2026)
• Automating Jira to test case with n8n (2026)
• Boundary Value Analysis With Examples (2026)
• Building a test case generator with LangChain (2026)
• Connecting Claude to your test suite with MCP (2026)