Hướng Dẫn Kiểm Thử API HTTP trong Node.js với Supertest

Trong bối cảnh API đang phát triển nhanh chóng, các nhóm cần hai điều: phản hồi nhanh ở cấp độ mã và xác thực đầu cuối đáng tin cậy trên các môi trường. Supertest mang lại điều đầu tiên—các khẳng định HTTP cực nhanh cho các dịch vụ Node.js. Và khi bạn sẵn sàng cộng tác giữa các vai trò, chạy các bài kiểm tra kịch bản, tạo giả lập các phụ thuộc và xuất bản tài liệu, một nền tảng kiểm thử API như Apidog sẽ hoàn thiện bức tranh. Hướng dẫn chính thức, khách quan này giải thích cách sử dụng Supertest để kiểm thử API, những ưu điểm của nó và cách kết hợp nó với Apidog để tăng tốc quá trình phân phối với sự tự tin.

Apidog

button

Supertest là gì?

Supertest là một thư viện Node.js nhẹ để kiểm thử các máy chủ HTTP. Nó được xây dựng dựa trên superagent và cho phép bạn viết các khẳng định rõ ràng đối với mã trạng thái, tiêu đề và nội dung phản hồi—mà không cần khởi tạo các máy khách bên ngoài. Nó lý tưởng khi bạn:

Cần các bài kiểm tra nhanh, có tính xác định trong quá trình phát triển
Muốn kiểm thử các bộ điều khiển/bộ định tuyến gần với mã nguồn
Ưu tiên dấu chân phụ thuộc tối thiểu và thời gian chạy nhanh
Lý do các nhóm thích Supertest trong số các công cụ kiểm thử API hiện đại:
Các khẳng định đơn giản, có thể nối chuỗi với .expect()
Hoạt động với bất kỳ trình chạy kiểm thử nào (Jest, Mocha, Vitest)
Chấp nhận một URL đang chạy hoặc một ứng dụng http.Server/Express đang chạy trong tiến trình
Tích hợp dễ dàng với CI và các công cụ đo độ bao phủ mã

Khi bạn cần cộng tác, quản trị tuân thủ API, điều phối môi trường và kiểm thử trực quan, bạn sẽ bổ sung Supertest bằng một nền tảng kiểm thử API như Apidog. Phần còn lại của bài viết này sẽ chỉ ra cách thực hiện cả hai.

button

Cài đặt và Thiết lập Supertest

Bạn có thể cài đặt Supertest trong vài phút. Sử dụng npm, pnpm hoặc yarn:

# npm   npm install --save-dev supertest jest

# pnpm  pnpm add -D supertest jest

# yarn

yarn add -D supertest jest

Một API Express tối thiểu (app.js):

const express = require('express');

const app = express();



app.get('/greet', (req, res) => {

  const name = req.query.name || 'World';

  res.json({ message: `Hello, ${name}!` });

});



module.exports = app;

Một bài kiểm tra đơn giản (app.test.js) sử dụng Supertest + Jest:

const request = require('supertest');

const app = require('./app');



describe('GET /greet', () => {

  it('greets anonymously', async () => {

    const res = await request(app)

      .get('/greet')

      .expect('Content-Type', /json/)

      .expect(200);



    expect(res.body.message).toBe('Hello, World!');

  });



  it('greets by name', async () => {

    const res = await request(app)

      .get('/greet?name=Alice')

      .expect('Content-Type', /json/)

      .expect(200);



    expect(res.body.message).toBe('Hello, Alice!');

  });

});

Cập nhật package.json để chạy kiểm thử:

{

  "scripts": {

    "test": "jest"

  }

}

Chạy các bài kiểm thử của bạn:

npm test

Nếu bạn thích Mocha hoặc Vitest, Supertest hoạt động tương tự—API .expect() là giống hệt.

Viết các khẳng định Supertest hiệu quả

Sức mạnh của Supertest đến từ các khẳng định có thể nối chuỗi của nó—nhanh để viết và dễ đọc. Dưới đây là các mẫu bạn sẽ sử dụng hàng ngày:

Trạng thái và tiêu đề

request(app)

  .get('/users')

  .expect(200)

  .expect('Content-Type', /json/);

Xác thực cấu trúc nội dung với một hàm tùy chỉnh

request(app)

  .get('/users')

  .expect(200)

  .expect(res => {

    if (!Array.isArray(res.body)) throw new Error('Expected an array');

    if (res.body.length === 0) throw new Error('Expected at least one user');

  });

Khớp chính xác nội dung hoặc biểu thức chính quy

request(app)

  .get('/health')

  .expect(200)

  .expect({ status: 'ok' });



request(app)

  .get('/health')

  .expect(200)

  .expect(/"status":"ok"/);

Xác thực, truy vấn và tải trọng

request(app)

  .post('/posts')

  .set('Authorization', 'Bearer test-token')

  .send({ title: 'Hello', body: 'World' })

  .expect(201)

  .expect(res => {

    if (!res.body.id) throw new Error('Missing id');

  });

Duy trì cookie giữa các yêu cầu bằng cách sử dụng agent

const agent = request.agent(app);

await agent.get('/login').expect(200);

await agent.get('/me').expect(200).expect(res => {

  if (!res.body.user) throw new Error('Expected authenticated user');

});

Mẹo: Giữ các bài kiểm thử nhỏ và có tính xác định. Supertest xuất sắc trong việc xác thực các bộ điều khiển, middleware và bộ điều hợp một cách độc lập.

Supertest trong CI/CD và Monorepos

Để duy trì chất lượng nhất quán, hãy chạy Supertest trong CI cho mỗi yêu cầu kéo (pull request). Một thiết lập điển hình:

Chạy song song các bộ kiểm thử đơn vị + Supertest để tăng tốc độ
Sử dụng cơ sở dữ liệu kiểm thử (container hoặc bộ nhớ trong)
Gieo dữ liệu nhỏ cho mỗi tệp kiểm thử để tránh ghép nối giữa các bài kiểm thử
Thất bại nhanh chóng khi có sự hồi quy hợp đồng (trạng thái, tiêu đề, lược đồ)

Ví dụ đoạn mã GitHub Actions:

name: api-tests

on: [push, pull_request]

jobs:

  test:

    runs-on: ubuntu-latest

    steps:

      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4

        with:

          node-version: '20'

      - run: npm ci

      - run: npm test -- --ci

Trong các monorepo, chỉ chạy các bài kiểm thử bị ảnh hưởng và lưu vào bộ nhớ cache node_modules để tăng tốc vòng lặp phản hồi. Chi phí tối thiểu của Supertest làm cho nó rất phù hợp với các cơ sở mã lớn.

Khi nào nên sử dụng Nền tảng kiểm thử API

Supertest rất tuyệt vời cho phản hồi nhanh, ở cấp độ mã. Nhưng thực tế sản xuất đòi hỏi nhiều hơn:

Cộng tác đa nhóm (sản phẩm, backend, frontend, QA)
Thiết kế và quản trị API theo hợp đồng trước (OpenAPI)
Máy chủ giả lập để giải phóng phát triển front-end
Kiểm thử kịch bản dựa trên dữ liệu và khẳng định trực quan
Biến môi trường đa dạng, bí mật và dữ liệu kiểm thử
Điều phối CI và tài liệu tương tác, có thể chia sẻ

Đây là lúc một nền tảng kiểm thử API như Apidog tỏa sáng. Nó hợp nhất thiết kế API, giả lập, kiểm thử, gỡ lỗi và tài liệu để giữ các nhóm đồng bộ và các cổng chất lượng của bạn bền vững.

button

Tại sao Apidog bổ sung cho Supertest

Thiết kế và quản lý phiên bản thông số kỹ thuật OpenAPI trực quan hoặc nhập các thông số kỹ thuật hiện có
Tự động tạo máy chủ giả lập để song song hóa công việc front-end và back-end
Xây dựng các bài kiểm thử với khẳng định trực quan và trích xuất biến
Xác thực phản hồi theo thông số kỹ thuật của bạn và ngăn chặn sự trôi lệch lược đồ
Xuất bản tài liệu API trực tuyến tương tác mà nhóm của bạn và đối tác có thể sử dụng

Quy trình làm việc kết hợp: Supertest + Apidog

Sử dụng Supertest cho các kiểm tra tập trung vào nhà phát triển và Apidog cho cộng tác đầu cuối. Dưới đây là sự phân chia trách nhiệm thực tế:

Nhiệm vụ	Supertest	Apidog
Kiểm tra đơn vị bộ điều khiển/middleware	Tuyệt vời	Bổ sung
Hồi quy hợp đồng nhanh (trạng thái/tiêu đề)	Tuyệt vời	Tuyệt vời
Quản trị lược đồ (OpenAPI)	Thủ công	Hàng đầu
Máy chủ giả lập cho front-end	Hạn chế	Tích hợp sẵn
Các kịch bản dựa trên dữ liệu	Hạn chế	Hàng đầu
Điều phối CI trên các môi trường	Tốt	Hàng đầu
Cộng tác nhóm/tài liệu	Tối thiểu	Hàng đầu

Luồng ví dụ:

Định nghĩa hoặc nhập thông số kỹ thuật API vào Apidog. Thống nhất về các trường, lỗi và phiên bản.
Tạo giả lập để front-end có thể bắt đầu ngay lập tức.
Triển khai các điểm cuối trong Node.js; viết các kiểm tra Supertest cho trạng thái/tiêu đề/tải trọng.
Trong Apidog, xây dựng các bài kiểm thử kịch bản và khẳng định trực quan dựa trên cùng thông số kỹ thuật.
Kiểm soát việc hợp nhất bằng cả hai bộ kiểm thử trong CI. Xuất bản tài liệu từ Apidog.

Các mẫu Supertest nâng cao

Một vài mẹo bổ sung mang lại hiệu quả:

Tập trung request = request(app) hoặc URL cơ sở của bạn vào một hàm trợ giúp để tránh lặp lại
Sử dụng factory/fixture cho các tải trọng có thể lặp lại
Kết hợp Supertest với các trình xác thực lược đồ (ví dụ: ajv) để thực thi các hợp đồng phản hồi
Đối với streaming hoặc SSE, kiểm tra tiêu đề và các mẫu chunk; đối với WebSockets, sử dụng một máy khách cụ thể cho giao thức cộng với các bài kiểm thử tích hợp trong Apidog
Giữ một linter và formatter nghiêm ngặt để duy trì khả năng đọc dưới áp lực thời hạn

Kết luận: Một cách tiếp cận cân bằng đối với chất lượng API

Các API chất lượng được xây dựng với cả tốc độ và sự chặt chẽ. Supertest cung cấp cho các nhà phát triển một cách nhanh chóng, biểu cảm để xác minh các điểm cuối gần mã—hoàn hảo cho các vòng lặp phản hồi chặt chẽ và phát hiện các hồi quy trước khi chúng thoát khỏi một nhánh. Nó đơn giản, đáng tin cậy và đã được thử nghiệm qua nhiều backend Node.js.

Tuy nhiên, khi các hệ thống phát triển, bạn cần sự cộng tác, quản trị hợp đồng và thực thi nhận biết môi trường. Đó là nơi Apidog—một nền tảng kiểm thử API tích hợp—nâng cao quy trình làm việc của bạn. Bằng cách hợp nhất thiết kế hợp đồng (OpenAPI), máy chủ giả lập, khẳng định trực quan, biến môi trường và điều phối CI, Apidog giúp các nhóm di chuyển đồng bộ từ ý tưởng đến phân phối. Front-end, back-end và QA có thể chia sẻ cùng một nguồn thông tin đáng tin cậy trong khi Supertest tiếp tục bảo vệ các đường dẫn mã của bạn bằng các khẳng định nhanh chóng, có tính xác định.

Nếu bạn muốn tốc độ tự tin, hãy sử dụng cả hai:

Giữ Supertest cho các bài kiểm thử nhanh, ở cấp độ mã mà các nhà phát triển yêu thích
Áp dụng Apidog để thiết kế hợp đồng API, giải phóng các nhóm bằng giả lập, xác thực phản hồi theo thông số kỹ thuật và xuất bản tài liệu

Cách tiếp cận cân bằng này tạo ra các API không chỉ đúng đắn hôm nay mà còn kiên cường khi sản phẩm của bạn phát triển. Hãy bắt đầu viết các kiểm tra Supertest của bạn ngay bây giờ—và đưa chúng vào hoạt động trong một quy trình sản xuất với Apidog.

button