API 设计 / 系统课时

集成测试 GraphQL HTTP 接口

集成测试 GraphQL HTTP 接口

这一节要把 GraphQL 测试从 Resolver 单测推进到 HTTP 边界:测试客户端发送真实请求,服务端依次完成请求解析、GraphQL 解析与校验、Context 构造、Resolver 执行和错误序列化,最终用状态码与响应体同时验收接口契约。

学习目标

  • 区分 Resolver 单测与 GraphQL HTTP 集成测试的覆盖边界
  • 用完整请求验证变量、请求头、Context、Resolver 与响应体
  • 分别断言请求阶段错误和执行阶段错误,避免只检查 HTTP 200

集成测试应该覆盖哪一层

Resolver 单测适合验证业务函数,但它不会发现请求体格式、变量绑定、Schema 校验、请求头到 Context 的转换以及错误序列化问题。HTTP 集成测试应从 /graphql 入口发起请求,让一次测试至少穿过 HTTP、GraphQL 文档解析、校验、Context 和 Resolver。

本节示例约定:语法或校验失败返回 HTTP 400;请求已成功进入执行阶段,但 Resolver 抛出 GraphQL 错误时返回 HTTP 200,并把错误放进 errors。这是示例服务的契约,实际项目应按所用 GraphQL HTTP 实现的文档固定断言,不要把某个框架的状态码习惯当成通用规则。

GraphQL HTTP 集成测试覆盖链路

用一个可执行用例贯穿整条请求链

下面使用 Node.js 18+ 的内置 fetch、http 与 assert,配合 graphql 包搭一个最小服务。项目需要已安装 graphql 依赖。测试同时验证成功请求、未知字段校验失败以及 Context 中缺少令牌时的 Resolver 错误。

js
// integration.mjs
import assert from 'node:assert/strict';
import { once } from 'node:events';
import { createServer } from 'node:http';
import {
  GraphQLError,
  buildSchema,
  execute,
  parse,
  validate,
} from 'graphql';

const schema = buildSchema(`
  type Query {
    greeting(name: String!): String!
    secret: String!
  }
`);

const rootValue = {
  greeting: ({ name }, context) =>
    `hello ${name} via ${context.requestId}`,
  secret: (_args, context) => {
    if (context.token !== 'test-token') {
      throw new GraphQLError('Authentication required', {
        extensions: { code: 'UNAUTHENTICATED' },
      });
    }
    return '42';
  },
};

function sendJson(response, status, body) {
  response.writeHead(status, { 'content-type': 'application/json' });
  response.end(JSON.stringify(body));
}

const server = createServer(async (request, response) => {
  if (request.method !== 'POST' || request.url !== '/graphql') {
    sendJson(response, 404, { error: 'Not Found' });
    return;
  }

  const chunks = [];
  for await (const chunk of request) chunks.push(chunk);

  let payload;
  try {
    payload = JSON.parse(Buffer.concat(chunks).toString('utf8'));
  } catch {
    sendJson(response, 400, { errors: [{ message: 'Invalid JSON' }] });
    return;
  }

  let document;
  try {
    document = parse(payload.query);
  } catch (error) {
    sendJson(response, 400, { errors: [{ message: error.message }] });
    return;
  }

  const validationErrors = validate(schema, document);
  if (validationErrors.length > 0) {
    sendJson(response, 400, {
      errors: validationErrors.map((error) => ({ message: error.message })),
    });
    return;
  }

  const contextValue = {
    requestId: request.headers['x-request-id'] ?? 'none',
    token: request.headers.authorization?.replace(/^Bearer\s+/, ''),
  };

  const result = await execute({
    schema,
    document,
    rootValue,
    contextValue,
    variableValues: payload.variables,
  });
  sendJson(response, 200, result);
});

server.listen(0, '127.0.0.1');
await once(server, 'listening');

const { port } = server.address();
const endpoint = `http://127.0.0.1:${port}/graphql`;

async function post(body, headers = {}) {
  const response = await fetch(endpoint, {
    method: 'POST',
    headers: { 'content-type': 'application/json', ...headers },
    body: JSON.stringify(body),
  });
  return { status: response.status, body: await response.json() };
}

try {
  const success = await post(
    {
      query: 'query ($name: String!) { greeting(name: $name) }',
      variables: { name: 'Ada' },
    },
    { 'x-request-id': 'req-1' },
  );
  assert.equal(success.status, 200);
  assert.deepEqual(success.body, {
    data: { greeting: 'hello Ada via req-1' },
  });

  const invalid = await post({ query: '{ missingField }' });
  assert.equal(invalid.status, 400);
  assert.match(invalid.body.errors[0].message, /Cannot query field/);

  const unauthorized = await post({ query: '{ secret }' });
  assert.equal(unauthorized.status, 200);
  assert.equal(
    unauthorized.body.errors[0].extensions.code,
    'UNAUTHENTICATED',
  );

  console.log(
    'integration checks passed: success=200, validation=400, resolver-error=200',
  );
} finally {
  server.close();
  await once(server, 'close');
}

执行测试脚本:

bash
node integration.mjs

预期输出:

text
integration checks passed: success=200, validation=400, resolver-error=200

端口由操作系统动态分配,因此实际端口可视为 <PORT>;测试不依赖固定端口,也更适合并行运行。

断言响应时不要只看 data

成功路径至少应断言状态码、关键 data 字段和由请求头产生的 Context 效果。失败路径则应先判断错误发生在哪一阶段:HTTP/JSON、GraphQL parse 或 validate 属于请求阶段;Resolver 抛错属于执行阶段。

对于执行错误,优先断言稳定的 extensions.code,例如 UNAUTHENTICATED,不要把完整英文错误文案当成长期 API。这样既能验证客户端可依赖的错误契约,又不会因文案调整产生无意义的测试失败。

把集成测试放进回归链路

持续集成中应让这类用例在 Schema 或 Resolver 变更后自动执行,并把非零退出码作为阻断条件。对最重要的查询与 Mutation 保留少量高价值端到端用例,再用 Resolver 单测覆盖大量业务分支,可以在反馈速度和真实覆盖之间取得更好的平衡。

当一次 GraphQL 请求能从 HTTP 边界稳定走到 Resolver,并且成功、校验失败和执行失败都拥有明确断言时,这套测试才真正覆盖了接口契约,而不只是“调用过某个函数”。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

集成测试 GraphQL HTTP 接口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通