Cara Menggunakan Supertest untuk Testing HTTP API di Node.js

Dalam lanskap API yang berkembang pesat, tim membutuhkan dua hal: umpan balik cepat di tingkat kode dan validasi ujung ke ujung yang dapat dipercaya di seluruh lingkungan. Supertest menghadirkan yang pertama—asersi HTTP yang sangat cepat untuk layanan Node.js. Dan ketika Anda siap untuk berkolaborasi lintas peran, menjalankan pengujian skenario, meniru dependensi, dan mempublikasikan dokumentasi, platform pengujian API seperti Apidog melengkapi gambaran tersebut. Panduan resmi dan objektif ini menjelaskan cara menggunakan Supertest untuk menguji API, di mana keunggulannya, dan cara memasangkannya dengan Apidog untuk mempercepat pengiriman dengan percaya diri.

Apidog

button

Apa Itu Supertest?

Supertest adalah pustaka Node.js yang ringan untuk menguji server HTTP. Ini dibangun di atas superagent dan memungkinkan Anda menulis asersi ekspresif terhadap kode status, header, dan badan respons—tanpa perlu menjalankan klien eksternal. Ini ideal ketika Anda:

Membutuhkan pengujian cepat dan deterministik selama pengembangan
Ingin menguji kontroler/router dekat dengan kode
Lebih memilih jejak dependensi minimal dan waktu eksekusi yang cepat
Mengapa tim menyukai Supertest di antara alat pengujian API modern:
Asersi berantai yang sederhana dengan .expect()
Bekerja dengan test runner apa pun (Jest, Mocha, Vitest)
Menerima URL yang sedang berjalan atau http.Server/aplikasi Express dalam proses
Berintegrasi dengan mudah dengan CI dan alat cakupan kode

Ketika Anda membutuhkan kolaborasi, tata kelola kepatuhan API, orkestrasi lingkungan, dan pengujian visual, Anda akan melengkapi Supertest dengan platform pengujian API seperti Apidog. Sisa artikel ini menunjukkan cara melakukan keduanya.

button

Instal dan Siapkan Supertest

Anda dapat menginstal Supertest dalam hitungan menit. Gunakan npm, pnpm, atau yarn:

# npm   npm install --save-dev supertest jest

# pnpm  pnpm add -D supertest jest

# yarn

yarn add -D supertest jest

API Express minimal (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;

Pengujian sederhana (app.test.js) menggunakan 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!');

  });

});

Perbarui package.json untuk menjalankan pengujian:

{

  "scripts": {

    "test": "jest"

  }

}

Jalankan pengujian Anda:

npm test

Jika Anda lebih suka Mocha atau Vitest, Supertest bekerja dengan cara yang sama—API .expect() identik.

Menulis Asersi Supertest yang Hebat

Kekuatan Supertest berasal dari asersi berantainya—cepat ditulis dan mudah dibaca. Berikut adalah pola yang akan Anda gunakan setiap hari:

Status dan header

request(app)

  .get('/users')

  .expect(200)

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

Validasi struktur badan dengan fungsi kustom

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

  });

Pencocokan badan yang tepat atau regex

request(app)

  .get('/health')

  .expect(200)

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



request(app)

  .get('/health')

  .expect(200)

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

Auth, kueri, dan payload

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

  });

Pertahankan cookie di seluruh permintaan menggunakan 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');

});

Tips: Jaga agar pengujian tetap kecil dan deterministik. Supertest unggul dalam memvalidasi kontroler, middleware, dan adapter secara terpisah.

Supertest dalam CI/CD dan Monorepo

Untuk menjaga kualitas tetap konsisten, jalankan Supertest di CI untuk setiap pull request. Pengaturan umum:

Jalankan suite unit + Supertest secara paralel untuk kecepatan
Gunakan database pengujian (kontainer atau penyimpanan dalam memori)
Isi kumpulan data kecil per file pengujian untuk menghindari keterkaitan antar-pengujian
Gagal cepat pada regresi kontrak (status, header, skema)

Contoh cuplikan 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

Dalam monorepo, jalankan hanya pengujian yang terpengaruh dan cache node_modules untuk mempercepat siklus umpan balik. Overhead minimal Supertest membuatnya sangat cocok untuk basis kode yang besar.

Kapan Menggunakan Platform Pengujian API

Supertest sangat bagus untuk umpan balik cepat di tingkat kode. Namun, realitas produksi menuntut lebih banyak:

Kolaborasi lintas tim (produk, backend, frontend, QA)
Desain dan tata kelola API yang mengutamakan kontrak (OpenAPI)
Server mock untuk membuka blokir pengembangan front-end
Pengujian skenario berbasis data dan asersi visual
Variabel multi-lingkungan, rahasia, dan data pengujian
Orkestrasi CI dan dokumentasi yang dapat dibagikan serta interaktif

Di sinilah platform pengujian API seperti Apidog bersinar. Ini menyatukan desain API, mocking, pengujian, debugging, dan dokumentasi untuk menjaga tim tetap selaras dan gerbang kualitas Anda tetap tahan lama.

button

Mengapa Apidog Melengkapi Supertest

Rancang dan versi spesifikasi OpenAPI secara visual atau impor spesifikasi yang ada
Otomatis-buat server mock untuk memparalelkan pekerjaan front-end dan back-end
Buat pengujian dengan asersi visual dan ekstraksi variabel
Validasi respons terhadap spesifikasi Anda dan cegah penyimpangan skema
Publikasikan dokumentasi API online interaktif yang dapat dikonsumsi oleh tim dan mitra Anda

Alur Kerja Gabungan: Supertest + Apidog

Gunakan Supertest untuk pemeriksaan yang berpusat pada pengembang dan Apidog untuk kolaborasi ujung ke ujung. Berikut adalah pembagian tanggung jawab yang pragmatis:

Tugas	Supertest	Apidog
Pemeriksaan unit kontroler/middleware	Sangat Baik	Komplementer
Regresi kontrak cepat (status/header)	Sangat Baik	Sangat Baik
Tata kelola skema (OpenAPI)	Manual	Kelas Satu
Server mock untuk front-end	Terbatas	Bawaan
Skenario berbasis data	Terbatas	Kelas Satu
Orkestrasi CI di seluruh lingkungan	Baik	Kelas Satu
Kolaborasi tim/dokumen	Minimal	Kelas Satu

Contoh alur:

Definisikan atau impor spesifikasi API di Apidog. Selaraskan bidang, kesalahan, dan versi.
Hasilkan mock sehingga front-end dapat segera memulai.
Implementasikan endpoint di Node.js; tulis pemeriksaan Supertest untuk status/header/payload.
Di Apidog, buat pengujian skenario dan asersi visual terhadap spesifikasi yang sama.
Jaga penggabungan dengan kedua suite di CI. Publikasikan dokumen dari Apidog.

Pola Supertest Tingkat Lanjut

Beberapa tips tambahan yang bermanfaat:

Pusatkan request = request(app) atau URL dasar Anda dalam helper untuk menghindari pengulangan
Gunakan factory/fixture untuk payload yang dapat diulang
Gabungkan Supertest dengan validator skema (misalnya, ajv) untuk menegakkan kontrak respons
Untuk streaming atau SSE, uji header dan pola chunk; untuk WebSockets, gunakan klien khusus protokol ditambah pengujian integrasi di Apidog
Pertahankan linter dan formatter yang ketat untuk menjaga keterbacaan di bawah tekanan tenggat waktu

Kesimpulan: Pendekatan Seimbang terhadap Kualitas API

API berkualitas dibangun dengan kecepatan dan ketelitian. Supertest memberi pengembang cara yang cepat dan ekspresif untuk memverifikasi endpoint dekat dengan kode—sempurna untuk siklus umpan balik yang ketat dan menangkap regresi sebelum lolos dari branch. Ini sederhana, dapat diandalkan, dan teruji di berbagai backend Node.js.

Namun, seiring pertumbuhan sistem, Anda membutuhkan kolaborasi, tata kelola kontrak, dan eksekusi yang sadar lingkungan. Di sinilah Apidog—platform pengujian API terintegrasi—meningkatkan alur kerja Anda. Dengan menyatukan desain kontrak (OpenAPI), server mock, asersi visual, variabel lingkungan, dan orkestrasi CI, Apidog membantu tim bergerak selaras dari ide hingga pengiriman. Front-end, back-end, dan QA dapat berbagi sumber kebenaran yang sama sementara Supertest terus menjaga jalur kode Anda dengan asersi yang cepat dan deterministik.

Jika Anda menginginkan kecepatan yang percaya diri, gunakan keduanya:

Pertahankan Supertest untuk pengujian tingkat kode yang cepat yang disukai pengembang
Adopsi Apidog untuk merancang kontrak API, membuka blokir tim dengan mock, memvalidasi respons terhadap spesifikasi, dan mempublikasikan dokumen

Pendekatan seimbang ini menghasilkan API yang tidak hanya benar hari ini tetapi juga tangguh seiring berkembangnya produk Anda. Mulailah menulis pemeriksaan Supertest Anda sekarang—dan hidupkan dalam pipeline kelas produksi dengan Apidog.

button