编辑“︁Next.js API 测试”︁（章节）

= Next.js API 测试 =

== 介绍 ==
'''Next.js API 测试''' 是指在 Next.js 框架中对 API 路由（位于 <code>/pages/api</code> 目录下的端点）进行验证的过程。这些测试确保 API 能够正确处理请求、返回预期的响应，并在错误情况下提供适当的反馈。API 测试通常包括单元测试、集成测试和端到端（E2E）测试。

Next.js 支持多种测试方法，包括使用 Jest、Testing Library、Cypress 等工具。本文将重点介绍如何使用 Jest 和 Supertest 进行 API 测试，并提供详细的代码示例和实际应用场景。

== 测试类型 ==
在 Next.js 中，API 测试主要分为以下几类：
* '''单元测试'''：测试单个 API 路由函数的逻辑。
* '''集成测试'''：验证 API 路由与数据库或其他服务的交互。
* '''端到端测试'''：模拟真实用户请求，检查整个系统的行为。

== 测试工具 ==
常用的测试工具包括：
* '''Jest'''：JavaScript 测试框架，用于运行测试和断言。
* '''Supertest'''：HTTP 断言库，用于模拟 HTTP 请求。
* '''Testing Library'''：用于测试 React 组件（可选，适用于包含前端逻辑的 API）。

== 设置测试环境 ==
首先，安装必要的依赖：
<syntaxhighlight lang="bash">
npm install --save-dev jest supertest @testing-library/react @testing-library/jest-dom
</syntaxhighlight>

在项目根目录下创建 <code>jest.config.js</code> 文件：
<syntaxhighlight lang="javascript">
module.exports = {
  testEnvironment: 'node',
  setupFilesAfterEnv: ['./jest.setup.js'],
};
</syntaxhighlight>

== 编写 API 测试 ==
假设我们有一个简单的 Next.js API 路由 <code>/pages/api/hello.js</code>：
<syntaxhighlight lang="javascript">
export default function handler(req, res) {
  res.status(200).json({ message: 'Hello, world!' });
}
</syntaxhighlight>

=== 单元测试示例 ===
使用 Jest 测试该 API：
<syntaxhighlight lang="javascript">
import handler from '../../pages/api/hello';

describe('/api/hello', () => {
  it('should return a 200 status and a message', () => {
    const req = {};
    const res = {
      status: jest.fn().mockReturnThis(),
      json: jest.fn(),
    };

    handler(req, res);

    expect(res.status).toHaveBeenCalledWith(200);
    expect(res.json).toHaveBeenCalledWith({ message: 'Hello, world!' });
  });
});
</syntaxhighlight>

=== 集成测试示例 ===
使用 Supertest 模拟 HTTP 请求：
<syntaxhighlight lang="javascript">
import request from 'supertest';
import { createServer } from 'http';
import { apiResolver } from 'next/dist/server/api-utils';

describe('/api/hello', () => {
  let server;

  beforeAll(() => {
    server = createServer((req, res) => {
      apiResolver(
        req,
        res,
        undefined,
        require('../../pages/api/hello').default,
        {},
        false
      );
    });
  });

  afterAll(() => server.close());

  it('should return a 200 status and a message', async () => {
    const response = await request(server).get('/api/hello');
    expect(response.status).toBe(200);
    expect(response.body).toEqual({ message: 'Hello, world!' });
  });
});
</syntaxhighlight>

== 实际应用场景 ==
=== 场景 1：用户认证 API ===
假设有一个用户登录 API <code>/pages/api/login.js</code>：
<syntaxhighlight lang="javascript">
export default function handler(req, res) {
  const { email, password } = req.body;
  if (email === 'user@example.com' && password === 'password') {
    res.status(200).json({ token: 'fake-jwt-token' });
  } else {
    res.status(401).json({ error: 'Invalid credentials' });
  }
}
</syntaxhighlight>

测试该 API：
<syntaxhighlight lang="javascript">
describe('/api/login', () => {
  it('should return a token for valid credentials', async () => {
    const response = await request(server)
      .post('/api/login')
      .send({ email: 'user@example.com', password: 'password' });
    expect(response.status).toBe(200);
    expect(response.body.token).toBeDefined();
  });

  it('should return 401 for invalid credentials', async () => {
    const response = await request(server)
      .post('/api/login')
      .send({ email: 'wrong@example.com', password: 'wrong' });
    expect(response.status).toBe(401);
    expect(response.body.error).toBe('Invalid credentials');
  });
});
</syntaxhighlight>

=== 场景 2：数据库交互 ===
如果 API 与数据库交互（如 MongoDB），可以使用 <code>mongodb-memory-server</code> 进行测试：
<syntaxhighlight lang="javascript">
import { MongoMemoryServer } from 'mongodb-memory-server';

describe('/api/users', () => {
  let mongoServer;
  beforeAll(async () => {
    mongoServer = await MongoMemoryServer.create();
    process.env.MONGODB_URI = mongoServer.getUri();
  });

  afterAll(async () => {
    await mongoServer.stop();
  });

  it('should create a user', async () => {
    const response = await request(server)
      .post('/api/users')
      .send({ name: 'John Doe' });
    expect(response.status).toBe(201);
    expect(response.body.name).toBe('John Doe');
  });
});
</syntaxhighlight>

== 高级测试技巧 ==
=== 模拟中间件 ===
如果 API 使用中间件（如身份验证），可以模拟其行为：
<syntaxhighlight lang="javascript">
jest.mock('../../middleware/auth', () => (handler) => (req, res) => {
  req.user = { id: '123' };
  return handler(req, res);
});
</syntaxhighlight>

=== 测试错误处理 ===
确保 API 在异常情况下返回正确的错误响应：
<syntaxhighlight lang="javascript">
it('should handle server errors', async () => {
  jest.spyOn(console, 'error').mockImplementation(() => {});
  const response = await request(server).get('/api/error');
  expect(response.status).toBe(500);
  expect(response.body.error).toBe('Internal Server Error');
});
</syntaxhighlight>

== 总结 ==
Next.js API 测试是确保后端逻辑可靠性的关键步骤。通过结合单元测试、集成测试和端到端测试，可以全面验证 API 的行为。本文介绍了使用 Jest 和 Supertest 的基本方法，并提供了实际应用场景和高级技巧。

<mermaid>
graph TD
  A[API 测试] --> B[单元测试]
  A --> C[集成测试]
  A --> D[端到端测试]
  B --> E[测试单个函数]
  C --> F[测试数据库交互]
  D --> G[模拟用户请求]
</mermaid>

== 另请参阅 ==
* [[Next.js 路由]]
* [[Jest 测试框架]]
* [[Supertest 使用指南]]

[[Category:后端框架]]
[[Category:Next.js]]
[[Category:Next.js测试]]