วิธีใช้ Supertest ทดสอบ HTTP API ใน Node.js

ในภูมิทัศน์ API ที่มีการพัฒนาอย่างรวดเร็ว ทีมต่างๆ ต้องการสองสิ่ง: การตอบรับที่รวดเร็วในระดับโค้ด และการตรวจสอบความถูกต้องแบบ end-to-end ที่น่าเชื่อถือในสภาพแวดล้อมต่างๆ Supertest มอบสิ่งแรก นั่นคือการยืนยัน HTTP ที่รวดเร็วสุดขีดสำหรับบริการ Node.js และเมื่อคุณพร้อมที่จะทำงานร่วมกันในหลากหลายบทบาท รันการทดสอบสถานการณ์ จำลอง Dependencies และเผยแพร่เอกสารประกอบ แพลตฟอร์มทดสอบ API อย่าง Apidog จะช่วยเติมเต็มภาพรวม คู่มืออย่างเป็นทางการและเป็นกลางนี้จะอธิบายวิธีใช้ Supertest ในการทดสอบ API จุดเด่นของมัน และวิธีจับคู่กับ Apidog เพื่อเร่งการส่งมอบด้วยความมั่นใจ

Apidog

Supertest คืออะไร?

Supertest เป็นไลบรารี Node.js น้ำหนักเบาสำหรับการทดสอบ HTTP Server สร้างขึ้นบน superagent และช่วยให้คุณสามารถเขียนการยืนยันที่แสดงผลได้ดีกับรหัสสถานะ, ส่วนหัว (headers) และเนื้อหาการตอบกลับ—โดยไม่ต้องเรียกใช้ไคลเอนต์ภายนอก เหมาะอย่างยิ่งเมื่อคุณ:

• ต้องการการทดสอบที่รวดเร็วและกำหนดผลได้ในระหว่างการพัฒนา
• ต้องการทดสอบ Controller/Router ใกล้กับโค้ด
• ชอบการพึ่งพิง (dependency) น้อยที่สุดและรันไทม์ที่รวดเร็ว
• ทำไมทีมถึงชอบ Supertest ท่ามกลางเครื่องมือทดสอบ API สมัยใหม่:
• การยืนยันที่เรียบง่ายและสามารถเชื่อมโยงกันได้ด้วย .expect()
• ทำงานร่วมกับ Test Runner ใดก็ได้ (Jest, Mocha, Vitest)
• รองรับทั้ง URL ที่กำลังทำงานอยู่ หรือ http.Server/Express app ที่ทำงานในกระบวนการเดียวกัน
• รวมเข้ากับ CI และเครื่องมือวัด Code Coverage ได้ง่าย

เมื่อคุณต้องการการทำงานร่วมกัน, การกำกับดูแลการปฏิบัติตามข้อกำหนด API, การจัดการสภาพแวดล้อม และการทดสอบด้วยภาพ คุณจะต้องเสริม Supertest ด้วยแพลตฟอร์มทดสอบ API อย่าง Apidog ส่วนที่เหลือของบทความนี้จะแสดงวิธีดำเนินการทั้งสองอย่าง

ติดตั้งและตั้งค่า Supertest

คุณสามารถติดตั้ง Supertest ได้ในไม่กี่นาที ใช้ npm, pnpm หรือ yarn:

# npm   npm install --save-dev supertest jest

# pnpm  pnpm add -D supertest jest

# yarn

yarn add -D supertest jest

Express API แบบง่าย (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;

การทดสอบแบบง่าย (app.test.js) โดยใช้ 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!');

  });

});

อัปเดต package.json เพื่อรันการทดสอบ:

{

  "scripts": {

    "test": "jest"

  }

}

รันการทดสอบของคุณ:

npm test

หากคุณชอบ Mocha หรือ Vitest, Supertest ก็ทำงานเหมือนกัน—API .expect() นั้นเหมือนกันทุกประการ

การเขียน Supertest Assertions ที่ยอดเยี่ยม

พลังของ Supertest มาจากการยืนยันแบบเชื่อมโยงกัน—เขียนได้รวดเร็วและอ่านง่าย นี่คือรูปแบบที่คุณจะใช้ทุกวัน:

• สถานะและส่วนหัว (headers)

request(app)

  .get('/users')

  .expect(200)

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

• ตรวจสอบโครงสร้าง Body ด้วยฟังก์ชันที่กำหนดเอง

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');

  });

• การจับคู่ Body แบบตรงตัวหรือ Regex

request(app)

  .get('/health')

  .expect(200)

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



request(app)

  .get('/health')

  .expect(200)

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

• การยืนยันตัวตน, Query และ Payloads

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');

  });

• คงสถานะคุกกี้ข้ามคำขอโดยใช้ 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');

});

เคล็ดลับ: รักษาการทดสอบให้เล็กและกำหนดผลได้ Supertest เก่งในการตรวจสอบ Controller, Middleware และ Adapter แบบแยกส่วน

Supertest ใน CI/CD และ Monorepos

เพื่อให้คุณภาพคงที่ ให้รัน Supertest ใน CI สำหรับทุก Pull Request การตั้งค่าทั่วไป:

• รัน Unit Test + Supertest Suite พร้อมกันเพื่อความเร็ว
• ใช้ฐานข้อมูลสำหรับทดสอบ (คอนเทนเนอร์หรือ In-memory Store)
• เตรียมข้อมูลชุดเล็กๆ สำหรับแต่ละไฟล์ทดสอบเพื่อหลีกเลี่ยงการพึ่งพาระหว่างการทดสอบ
• ล้มเหลวอย่างรวดเร็วเมื่อเกิด Contract Regression (สถานะ, ส่วนหัว, Schema)

ตัวอย่างโค้ด 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

ใน Monorepos ให้รันเฉพาะการทดสอบที่ได้รับผลกระทบและแคช node_modules เพื่อเร่งวงจรการตอบรับ Supertest มีโอเวอร์เฮดน้อยที่สุด ทำให้เหมาะอย่างยิ่งสำหรับโค้ดเบสขนาดใหญ่

เมื่อไหร่ควรใช้แพลตฟอร์มทดสอบ API

Supertest ยอดเยี่ยมสำหรับการตอบรับที่รวดเร็วในระดับโค้ด แต่ความเป็นจริงของการผลิตต้องการมากกว่านั้น:

• การทำงานร่วมกันข้ามทีม (ผลิตภัณฑ์, แบ็คเอนด์, ฟรอนต์เอนด์, QA)
• การออกแบบและการกำกับดูแล API แบบ Contract-first (OpenAPI)
• Mock Server เพื่อปลดบล็อกการพัฒนาส่วนหน้า
• การทดสอบสถานการณ์ที่ขับเคลื่อนด้วยข้อมูลและการยืนยันด้วยภาพ
• ตัวแปรสภาพแวดล้อมหลายชุด, ความลับ และข้อมูลทดสอบ
• การจัดการ CI และเอกสารประกอบที่แชร์ได้และโต้ตอบได้

นี่คือจุดที่แพลตฟอร์มทดสอบ API อย่าง Apidog เปล่งประกาย มันรวม การออกแบบ API, การจำลอง, การทดสอบ, การดีบัก และ เอกสารประกอบ เข้าไว้ด้วยกัน เพื่อช่วยให้ทีมทำงานสอดคล้องกันและเกณฑ์คุณภาพของคุณคงทน

ทำไม Apidog จึงช่วยเสริม Supertest

• ออกแบบและจัดการเวอร์ชันข้อกำหนด OpenAPI ด้วยภาพ หรือนำเข้าข้อกำหนดที่มีอยู่
• สร้าง Mock Server โดยอัตโนมัติ เพื่อทำงานส่วนหน้าและส่วนหลังพร้อมกัน
• สร้างการทดสอบด้วยการยืนยันด้วยภาพและการดึงตัวแปร
• ตรวจสอบการตอบกลับเทียบกับข้อกำหนดของคุณและป้องกัน Schema Drift
• เผยแพร่เอกสาร API ออนไลน์แบบโต้ตอบที่ทีมและพันธมิตรของคุณสามารถใช้งานได้

เวิร์กโฟลว์แบบผสมผสาน: Supertest + Apidog

ใช้ Supertest สำหรับการตรวจสอบที่เน้นนักพัฒนา และ Apidog สำหรับการทำงานร่วมกันแบบ end-to-end นี่คือการแบ่งความรับผิดชอบอย่างเป็นรูปธรรม:

ตัวอย่างเวิร์กโฟลว์:

• กำหนดหรือนำเข้าข้อกำหนด API ใน Apidog จัดแนว Field, ข้อผิดพลาด และเวอร์ชัน
• สร้าง Mock เพื่อให้ส่วนหน้าสามารถเริ่มต้นได้ทันที
• ใช้งาน Endpoint ใน Node.js; เขียน Supertest Check สำหรับสถานะ/ส่วนหัว/Payload
• ใน Apidog สร้างการทดสอบสถานการณ์และการยืนยันด้วยภาพเทียบกับข้อกำหนดเดียวกัน
• ควบคุมการรวมโค้ดด้วย Suite ทั้งสองใน CI เผยแพร่เอกสารจาก Apidog

รูปแบบ Supertest ขั้นสูง

เคล็ดลับเพิ่มเติมบางประการที่ให้ผลลัพธ์ที่ดี:

• รวม request = request(app) หรือ Base URL ไว้ใน Helper เพื่อหลีกเลี่ยงการทำซ้ำ
• ใช้ Factory/Fixture สำหรับ Payload ที่ทำซ้ำได้
• รวม Supertest เข้ากับ Schema Validator (เช่น ajv) เพื่อบังคับใช้ Response Contract
• สำหรับการสตรีมมิ่งหรือ SSE ให้ทดสอบส่วนหัวและรูปแบบ Chunk; สำหรับ WebSockets ให้ใช้ไคลเอนต์เฉพาะโปรโตคอลพร้อมกับการทดสอบ Integration ใน Apidog
• ใช้ Linter และ Formatter ที่เข้มงวดเพื่อรักษาความสามารถในการอ่านภายใต้แรงกดดันจากกำหนดเวลา

บทสรุป: แนวทางที่สมดุลสู่คุณภาพ API

API ที่มีคุณภาพสร้างขึ้นด้วยความเร็วและความเข้มงวด Supertest มอบวิธีที่รวดเร็วและแสดงออกได้ดีสำหรับนักพัฒนาในการตรวจสอบ Endpoint ใกล้กับโค้ด—เหมาะอย่างยิ่งสำหรับวงจรการตอบรับที่กระชับและการจับ Regression ก่อนที่จะหลุดออกจาก Branch มันเรียบง่าย, เชื่อถือได้ และผ่านการทดสอบมาแล้วในแบ็คเอนด์ Node.js จำนวนมาก

อย่างไรก็ตาม เมื่อระบบเติบโตขึ้น คุณต้องการการทำงานร่วมกัน, การกำกับดูแล Contract และการรันที่รับรู้สภาพแวดล้อม นั่นคือจุดที่ Apidog—แพลตฟอร์มทดสอบ API แบบรวม—ยกระดับเวิร์กโฟลว์ของคุณ ด้วยการรวมการออกแบบ Contract (OpenAPI), Mock Server, การยืนยันด้วยภาพ, ตัวแปรสภาพแวดล้อม และการจัดการ CI เข้าไว้ด้วยกัน Apidog ช่วยให้ทีมทำงานสอดคล้องกันตั้งแต่แนวคิดจนถึงการส่งมอบ ส่วนหน้า, ส่วนหลัง และ QA สามารถใช้แหล่งข้อมูลเดียวกันได้ ในขณะที่ Supertest ยังคงปกป้องเส้นทางโค้ดของคุณด้วยการยืนยันที่รวดเร็วและกำหนดผลได้

หากคุณต้องการความเร็วที่มั่นใจได้ ให้ใช้ทั้งสองอย่าง:

• คง Supertest ไว้สำหรับการทดสอบระดับโค้ดที่รวดเร็วซึ่งนักพัฒนาชื่นชอบ
• นำ Apidog มาใช้เพื่อออกแบบ API Contract, ปลดบล็อกทีมด้วย Mock, ตรวจสอบการตอบกลับเทียบกับข้อกำหนด และเผยแพร่เอกสาร

แนวทางที่สมดุลนี้ให้ผลลัพธ์เป็น API ที่ไม่เพียงถูกต้องในวันนี้ แต่ยังคงทนเมื่อผลิตภัณฑ์ของคุณพัฒนาขึ้น เริ่มเขียน Supertest Check ของคุณตอนนี้—และนำมันมาใช้ใน Pipeline ระดับ Production ด้วย Apidog