كيفية استخدام Supertest لاختبار واجهات برمجة تطبيقات HTTP في Node.js

في مشهد واجهات برمجة التطبيقات (API) سريع التطور، تحتاج الفرق إلى أمرين: ملاحظات سريعة على مستوى الكود والتحقق الموثوق الشامل عبر البيئات. يقدم Supertest الأول – تأكيدات HTTP فائقة السرعة لخدمات Node.js. وعندما تكون مستعدًا للتعاون بين الأدوار، وتشغيل اختبارات السيناريو، ومحاكاة التبعيات، ونشر الوثائق، فإن منصة اختبار واجهات برمجة التطبيقات (API) مثل Apidog تكمل الصورة. يشرح هذا الدليل الرسمي والموضوعي كيفية استخدام Supertest لاختبار واجهات برمجة التطبيقات، وأين يتألق، وكيفية إقرانه بـ Apidog لتسريع التسليم بثقة.

Apidog

ما هو Supertest؟

Supertest هي مكتبة Node.js خفيفة الوزن لاختبار خوادم HTTP. تعتمد على superagent وتتيح لك كتابة تأكيدات معبرة ضد رموز الحالة والرؤوس ونصوص الاستجابة – دون الحاجة إلى تشغيل عملاء خارجيين. إنها مثالية عندما:

• تحتاج إلى اختبارات سريعة ومحددة أثناء التطوير
• ترغب في اختبار وحدات التحكم/الموجهات (controllers/routers) بالقرب من الكود
• تفضل بصمة تبعية (dependency footprint) صغيرة ووقت تشغيل سريع
• لماذا تفضل الفرق Supertest بين أدوات اختبار واجهة برمجة التطبيقات الحديثة:
• تأكيدات بسيطة ومتسلسلة باستخدام .expect()
• يعمل مع أي مشغل اختبار (Jest, Mocha, Vitest)
• يقبل إما عنوان URL قيد التشغيل أو تطبيق http.Server/Express داخل العملية
• يتكامل بسهولة مع أدوات التكامل المستمر (CI) وتغطية الكود

عندما تحتاج إلى التعاون، وحوكمة الامتثال لواجهة برمجة التطبيقات، وتنسيق البيئات، والاختبار المرئي، ستكمل Supertest بمنصة اختبار واجهة برمجة التطبيقات مثل 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 يعمل بنفس الطريقة – واجهة برمجة التطبيقات .expect() متطابقة.

كتابة تأكيدات Supertest رائعة

تأتي قوة Supertest من تأكيداته المتسلسلة – سريعة الكتابة وسهلة القراءة. إليك الأنماط التي ستستخدمها يوميًا:

• الحالة والرؤوس

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"/);

• المصادقة، الاستعلام، والحمولات

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

  });

• الاحتفاظ بملفات تعريف الارتباط (cookies) عبر الطلبات باستخدام 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 في التحقق من وحدات التحكم (controllers) والبرمجيات الوسيطة (middleware) والمحولات (adapters) بشكل منفصل.

Supertest في CI/CD والمستودعات المتعددة (Monorepos)

للحفاظ على جودة متسقة، قم بتشغيل Supertest في التكامل المستمر (CI) لكل طلب سحب (pull request). إعداد نموذجي:

• تشغيل مجموعات اختبار الوحدة + Supertest بالتوازي لزيادة السرعة
• استخدام قاعدة بيانات اختبار (حاويات أو مخزن في الذاكرة)
• تغذية مجموعات بيانات صغيرة لكل ملف اختبار لتجنب الترابط بين الاختبارات
• الفشل السريع عند تراجعات العقد (الحالة، الرؤوس، المخطط)

مثال على مقتطف 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 مؤقتًا لتسريع حلقات التغذية الراجعة. إن النفقات العامة (overhead) الدنيا لـ Supertest تجعلها مناسبة تمامًا لقواعد الأكواد الكبيرة.

متى تستخدم منصة اختبار واجهة برمجة التطبيقات (API)

Supertest ممتاز للحصول على ملاحظات سريعة على مستوى الكود. لكن واقع الإنتاج يتطلب المزيد:

• التعاون بين الفرق (المنتج، الواجهة الخلفية، الواجهة الأمامية، ضمان الجودة)
• تصميم وحوكمة واجهة برمجة التطبيقات بناءً على العقد أولاً (OpenAPI)
• خوادم المحاكاة لفتح الطريق أمام تطوير الواجهة الأمامية
• اختبارات السيناريو المعتمدة على البيانات والتأكيدات المرئية
• متغيرات متعددة البيئات، وأسرار، وبيانات اختبار
• تنسيق التكامل المستمر (CI) ووثائق تفاعلية قابلة للمشاركة

هنا تتألق منصة اختبار واجهة برمجة التطبيقات مثل Apidog. توحد تصميم واجهة برمجة التطبيقات، والمحاكاة، والاختبار، وتصحيح الأخطاء، والتوثيق للحفاظ على توافق الفرق ومتانة بوابات الجودة لديك.

لماذا يكمل Apidog أداة Supertest

• تصميم وإصدار مواصفات OpenAPI بصريًا أو استيراد المواصفات الموجودة
• إنشاء خوادم محاكاة تلقائيًا لموازاة عمل الواجهة الأمامية والخلفية
• بناء الاختبارات باستخدام التأكيدات المرئية واستخراج المتغيرات
• التحقق من صحة الاستجابات مقابل مواصفاتك ومنع انحراف المخطط
• نشر وثائق واجهة برمجة التطبيقات التفاعلية عبر الإنترنت التي يمكن لفريقك وشركائك استخدامها

سير عمل مشترك: Supertest + Apidog

استخدم Supertest للفحوصات التي تركز على المطورين وApidog للتعاون الشامل. إليك تقسيم عملي للمسؤوليات:

مثال على سير العمل:

• حدد أو استورد مواصفات واجهة برمجة التطبيقات في Apidog. وافق على الحقول والأخطاء والإصدارات.
• أنشئ محاكاة حتى تتمكن الواجهة الأمامية من البدء فورًا.
• نفذ نقاط النهاية في Node.js؛ اكتب فحوصات Supertest للحالة/الرؤوس/الحمولات.
• في Apidog، أنشئ اختبارات سيناريو وتأكيدات مرئية مقابل نفس المواصفات.
• تحكم في عمليات الدمج (merges) باستخدام كلا المجموعتين في التكامل المستمر (CI). انشر الوثائق من Apidog.

أنماط Supertest المتقدمة

بعض النصائح الإضافية التي تؤتي ثمارها:

• مركزة request = request(app) أو عنوان URL الأساسي في دالة مساعدة لتجنب التكرار
• استخدام المصانع/التركيبات (factories/fixtures) للحمولات القابلة للتكرار
• الجمع بين Supertest ومُدققات المخطط (مثل ajv) لفرض عقود الاستجابة
• بالنسبة للبث أو SSE، اختبر الرؤوس وأنماط الأجزاء؛ أما بالنسبة لـ WebSockets، فاستخدم عميلًا خاصًا بالبروتوكول بالإضافة إلى اختبارات التكامل في Apidog
• حافظ على أداة تنقيح وتنسيق صارمة للحفاظ على قابلية القراءة تحت ضغط المواعيد النهائية

الخاتمة: نهج متوازن لجودة واجهة برمجة التطبيقات

يتم بناء واجهات برمجة التطبيقات عالية الجودة بالسرعة والدقة. يوفر Supertest للمطورين طريقة سريعة ومعبرة للتحقق من نقاط النهاية بالقرب من الكود – وهو مثالي لحلقات التغذية الراجعة الضيقة واكتشاف الانحدارات قبل أن تنتشر من الفرع. إنه بسيط وموثوق وتم اختباره في العديد من الواجهات الخلفية لـ Node.js.

مع نمو الأنظمة، ومع ذلك، تحتاج إلى التعاون، وحوكمة العقود، والتنفيذ الواعي بالبيئة. هنا ترفع Apidog – وهي منصة اختبار واجهة برمجة تطبيقات متكاملة – مستوى سير عملك. من خلال توحيد تصميم العقود (OpenAPI)، وخوادم المحاكاة، والتأكيدات المرئية، ومتغيرات البيئة، وتنسيق التكامل المستمر (CI)، تساعد Apidog الفرق على التحرك بخطوات متزامنة من الفكرة إلى التسليم. يمكن للواجهة الأمامية والخلفية وضمان الجودة مشاركة نفس مصدر الحقيقة بينما يواصل Supertest حماية مسارات الكود الخاصة بك بتأكيدات سريعة ومحددة.

إذا كنت تريد سرعة واثقة، فاستخدم كليهما:

• احتفظ بـ Supertest للاختبارات السريعة على مستوى الكود التي يحبها المطورون
• اعتماد Apidog لتصميم عقود واجهة برمجة التطبيقات، وفتح المجال للفرق باستخدام المحاكاة، والتحقق من صحة الاستجابات مقابل المواصفات، ونشر الوثائق

ينتج عن هذا النهج المتوازن واجهات برمجة تطبيقات ليست صحيحة اليوم فحسب، بل مرنة أيضًا مع تطور منتجك. ابدأ في كتابة فحوصات Supertest الخاصة بك الآن – واجعلها حقيقة في مسار عمل جاهز للإنتاج باستخدام Apidog.