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 实现的文档固定断言,不要把某个框架的状态码习惯当成通用规则。

用一个可执行用例贯穿整条请求链
下面使用 Node.js 18+ 的内置 fetch、http 与 assert,配合 graphql 包搭一个最小服务。项目需要已安装 graphql 依赖。测试同时验证成功请求、未知字段校验失败以及 Context 中缺少令牌时的 Resolver 错误。
// 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');
}执行测试脚本:
node integration.mjs预期输出:
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,并且成功、校验失败和执行失败都拥有明确断言时,这套测试才真正覆盖了接口契约,而不只是“调用过某个函数”。