الـ Node test runner والـ debugging: tests من غير مكتبات

01 / ملخص الدرس

node --test و describe و test و assert/strict، والـ spec reporter، و npm test. اختبار الأخطاء بـ assert.throws، و mock.fn لتسجيل النداءات، و mock.timers للتحكم في الوقت. والـ debugging: util.inspect بـ depth و console.dir و console.trace، و node --inspect مع Chrome DevTools و debugger.

ضمن مسارباك إند Node.js للإنتاج — من تحت الصفر21 / 122

02 / شرح الدرس مكتوبًا

نص شرح المعلم والكود الذي كتبه ونتيجة تشغيله، بنفس ترتيب الدرس.

أهلًا بيك. كل ما الـ backend يكبر، كل تعديل بقى ممكن يكسر حاجة في حتة تانية. والحل: tests. code صغير بيشغّل الـ code بتاعك ويتأكد إن النتيجة صح، وبيتشغّل في تواني قبل أي deploy. و Node فيه test runner جاهز، من غير Jest ولا Mocha. price dot js فيه function بتحوّل سعر مكتوب لقروش. وفي package dot json، الـ script اسمه test بيشغّل node dash dash test. describe بتجمع tests مع بعض. test واحد لكل سلوك. و assert dot equal بيقارن النتيجة بالمتوقع. assert dot throws بيتأكد إن الـ function بترمي. وآخر test متعمد فيه غلطة في المتوقع: تلاتة وتسعة وتسعين قرش مكتوبة أربعمية. npm test.

price.test.js

import { test, describe } from "node:test";
import assert from "node:assert/strict";
import { toPiasters } from "./price.js";

describe("toPiasters", () => {
  test("جنيهات صحيحة", () => {
    assert.equal(toPiasters("12"), 1200);
  });
  test("بكسور بالنقطة والفصلة", () => {
    assert.equal(toPiasters("12.5"), 1250);
    assert.equal(toPiasters("12,05"), 1205);
  });
  test("بيرفض الكلام", () => {
    assert.throws(() => toPiasters("abc"), TypeError);
  });
  test("bug: سعر بمسافات", () => {
    assert.equal(toPiasters(" 3.99 "), 400);
  });
});

المخرجات

$ npm test

> test
> node --test --test-reporter=spec

▶ toPiasters
  ✔ جنيهات صحيحة (1.849502ms)
  ✔ بكسور بالنقطة والفصلة (0.259117ms)
  ✔ بيرفض الكلام (0.440845ms)
  ✖ bug: سعر بمسافات (1.889432ms)
✖ toPiasters (6.12307ms)
ℹ tests 4
ℹ suites 1
ℹ pass 3
ℹ fail 1
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 82.640452

✖ failing tests:

test at price.test.js:16:3
✖ bug: سعر بمسافات (1.889432ms)
  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
  
  399 !== 400
  
      at TestContext.<anonymous> (file:///home/you/my-backend/price.test.js:17:12)
      at Test.runInAsyncScope (node:async_hooks:228:14)
      at Test.run (node:internal/test_runner/test:1118:25)
      at Suite.processPendingSubtests (node:internal/test_runner/test:787:18)
      at Test.postRun (node:internal/test_runner/test:1247:19)
      at Test.run (node:internal/test_runner/test:1175:12)
      at async Suite.processPendingSubtests (node:internal/test_runner/test:787:7) {
    generatedMessage: true,
    code: 'ERR_ASSERTION',
    actual: 399,
    expected: 400,
    operator: 'strictEqual',
    diff: 'simple'
  }

علامة صح خضرا قدام كل test نجح. والأخير: علامة غلط، والتفاصيل تحت: Expected values to be strictly equal، وبعدها تلتمية تسعة وتسعين مش زي أربعمية، يعني اللي طلع، واللي كنا متوقعينه. والـ summary: tests أربعة، pass تلاتة، fail واحد. و npm test خرج بـ exit code غير zero، فلو ده CI، الـ deploy هيقف. الغلطة هنا في الـ test نفسه، فنصلّحه. صلّحنا المتوقع. وزودنا describe لـ isExpired: الوقت حاجة صعب تختبرها، لأنه بيتغيّر. mock dot timers بيخليك تتحكم في الـ Date: تحدده على وقت معين، وتقدّمه بـ tick. وآخر test: mock dot fn، function مزيفة بتسجّل كل مرة اتنادت وبإيه. مفيدة لما عايز تتأكد إن الإيميل اتبعت من غير ما تبعته بجد. npm test.

price.test.js

import { test, describe, mock } from "node:test";
import assert from "node:assert/strict";
import { toPiasters, isExpired } from "./price.js";

describe("toPiasters", () => {
  test("جنيهات صحيحة", () => {
    assert.equal(toPiasters("12"), 1200);
  });
  test("بكسور بالنقطة والفصلة", () => {
    assert.equal(toPiasters("12.5"), 1250);
    assert.equal(toPiasters("12,05"), 1205);
  });
  test("بيرفض الكلام", () => {
    assert.throws(() => toPiasters("abc"), TypeError);
  });
  test("سعر بمسافات", () => {
    assert.equal(toPiasters(" 3.99 "), 399);
  });
});

describe("isExpired", () => {
  test("بيتحكم في الوقت بـ mock.timers", (t) => {
    t.mock.timers.enable({ apis: ["Date"], now: new Date("2026-01-01T00:00:00Z") });
    assert.equal(isExpired("2026-01-01T00:00:01Z"), false);
    t.mock.timers.tick(2000);
    assert.equal(isExpired("2026-01-01T00:00:01Z"), true);
  });
});

test("mock.fn بتسجّل كل نداء", () => {
  const send = mock.fn(() => "sent");
  send("[email protected]");
  assert.equal(send.mock.callCount(), 1);
  assert.deepEqual(send.mock.calls[0].arguments, ["[email protected]"]);
});

المخرجات

$ npm test

> test
> node --test --test-reporter=spec

▶ toPiasters
  ✔ جنيهات صحيحة (1.246821ms)
  ✔ بكسور بالنقطة والفصلة (0.344988ms)
  ✔ بيرفض الكلام (1.800062ms)
  ✔ سعر بمسافات (0.290437ms)
✔ toPiasters (5.365552ms)
▶ isExpired
  ✔ بيتحكم في الوقت بـ mock.timers (1.160786ms)
✔ isExpired (1.556126ms)
✔ mock.fn بتسجّل كل نداء (1.523516ms)
ℹ tests 6
ℹ suites 2
ℹ pass 6
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 113.869784

كله أخضر: ستة tests. وفيه flags مفيدة: dash dash watch: يعيد الـ tests كل ما تحفَظ ملف. dash dash test-only: يشغّل بس الـ tests اللي معلّم عليها only. و dash dash experimental-test-coverage: يقولك أنهي سطور ما اتختبرتش. الـ debugging. console dot log بتطبع الـ objects لحد عمق معين بس، والباقي بيبقى Object بين square brackets. util dot inspect بـ depth null بيطبع كل حاجة. console dot dir بـ depth بتختار العمق. و console dot trace بتطبع الرسالة ومعاها مين نادى الـ function دي. نشغّل.

main.js

import util from "node:util";

const order = { id: 7, user: { name: "مُنى", address: { city: { name: "Cairo", zone: { code: 11 } } } } };

console.log(order);
console.log(util.inspect(order, { depth: null, colors: false }));
console.dir(order, { depth: 1 });

function charge(amount) {
  console.trace("charge اتنادت منين؟");
}
charge(250);

المخرجات

$ node main.js
{ id: 7, user: { name: 'مُنى', address: { city: [Object] } } }
{
  id: 7,
  user: {
    name: 'مُنى',
    address: { city: { name: 'Cairo', zone: { code: 11 } } }
  }
}
{ id: 7, user: { name: 'مُنى', address: [Object] } }

Trace: charge اتنادت منين؟
    at charge (file:///home/you/my-backend/main.js:10:11)
    at file:///home/you/my-backend/main.js:12:1
    at ModuleJob.run (node:internal/modules/esm/module_job:430:25)
    at async onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:661:26)
    at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:101:5)

أول طباعة: city اتحوّلت Object، مش شايف جُوّاها. التانية: كله باين لحد code. التالتة: عمق واحد بس. و trace طبعت على الـ stderr الرسالة والـ stack: charge اتنادت من main dot js. ولما الموضوع يبقى أعقد: node dash dash inspect، وتفتح Chrome على chrome colon slash slash inspect، وتحط breakpoints، وتمشي سطر سطر، وتشوف كل المتغيرات. ولو كتبت كلمة debugger في الـ code، البرنامج هيقف عندها. التحدي: tests تمسك الـ bugs. هتنقل slugify لملف لوحدها. وتكتب ست tests على الأقل: إنجليزي، ورموز في الأطراف، وعربي، وحروف لاتيني بعلامات زي café، وفاضي، ورقم بدل string. وتشغّل npm test. ولو test فشل، صلّح slugify نفسها. ممكن café تفاجئك. الحالات في الكومنت.

تمرين

انقل slugify لـ slug.js، واكتب في slug.test.js ست tests (إنجليزي، رموز، عربي، café، فاضي، رقم ← TypeError)، وشغّل npm test.

الحل. slug dot js فيها الـ function. و slug dot test dot js فيها describe وست tests، كل واحد بيختبر حالة واحدة واسمه بيوصفها. npm test.

slug.test.js

import { test, describe } from "node:test";
import assert from "node:assert/strict";
import { slugify } from "./slug.js";

describe("slugify", () => {
  test("كلمتين إنجليزي", () => {
    assert.equal(slugify("Hello World"), "hello-world");
  });
  test("بيشيل الرموز من الأطراف", () => {
    assert.equal(slugify("  --Node.js 24!!  "), "node-js-24");
  });
  test("عربي", () => {
    assert.equal(slugify("أهلًا بيك"), "أهلًا-بيك");
  });
  test("لاتيني بعلامات", () => {
    assert.equal(slugify("Café Crème"), "café-crème");
  });
  test("فاضي", () => {
    assert.equal(slugify(""), "");
  });
  test("مش string", () => {
    assert.throws(() => slugify(42), TypeError);
  });
});

المخرجات

$ npm test

> test
> node --test --test-reporter=spec

▶ toPiasters
  ✔ جنيهات صحيحة (1.216135ms)
  ✔ بكسور بالنقطة والفصلة (0.343389ms)
  ✔ بيرفض الكلام (1.92542ms)
  ✔ سعر بمسافات (0.298808ms)
✔ toPiasters (5.396768ms)
▶ isExpired
  ✔ بيتحكم في الوقت بـ mock.timers (1.125024ms)
✔ isExpired (1.486344ms)
✔ mock.fn بتسجّل كل نداء (1.439166ms)
▶ slugify
  ✔ كلمتين إنجليزي (1.238543ms)
  ✔ بيشيل الرموز من الأطراف (0.248163ms)
  ✔ عربي (0.314391ms)
  ✖ لاتيني بعلامات (1.635523ms)
  ✔ فاضي (0.235799ms)
  ✔ مش string (0.654126ms)
✖ slugify (7.28007ms)
ℹ tests 12
ℹ suites 3
ℹ pass 11
ℹ fail 1
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 209.352735

✖ failing tests:

test at slug.test.js:15:3
✖ لاتيني بعلامات (1.635523ms)
  AssertionError [ERR_ASSERTION]: Expected values to be strictly equal:
  + actual - expected
  
  + 'caf-cr-me'
  - 'café-crème'
        ^
  
      at TestContext.<anonymous> (file:///home/you/my-backend/slug.test.js:16:12)
      at Test.runInAsyncScope (node:async_hooks:228:14)
      at Test.run (node:internal/test_runner/test:1118:25)
      at Suite.processPendingSubtests (node:internal/test_runner/test:787:18)
      at Test.postRun (node:internal/test_runner/test:
…

العربي عدّى، بس test الـ café فشل! بص على اللي طلع: caf dash cr dash me. الـ é اتشالت واتحط مكانها dash. ليه؟ لأن الـ regex بتسمح بـ a لـ z، والحروف العربية بالمدى بتاعها، و é حرف تالت خالص مش في الاتنين. وده بالزبط فايدة الـ tests: الـ bug ده كان هيطلع للمستخدمين في روابط شكلها غريب. الحل الأحسن: نستخدم Unicode property في الـ regex: backslash p capital L للحروف، و capital M للتشكيل، و N للأرقام، مع flag u. npm test تاني.

slug.js

export function slugify(title) {
  return title.trim().toLowerCase().replace(/[^\p{L}\p{M}\p{N}]+/gu, "-").replace(/^-|-$/g, "");
}

المخرجات

$ npm test

> test
> node --test --test-reporter=spec

▶ toPiasters
  ✔ جنيهات صحيحة (0.856268ms)
  ✔ بكسور بالنقطة والفصلة (0.249268ms)
  ✔ بيرفض الكلام (1.352415ms)
  ✔ سعر بمسافات (0.170932ms)
✔ toPiasters (3.59193ms)
▶ isExpired
  ✔ بيتحكم في الوقت بـ mock.timers (0.726006ms)
✔ isExpired (0.936204ms)
✔ mock.fn بتسجّل كل نداء (0.924029ms)
▶ slugify
  ✔ كلمتين إنجليزي (2.790479ms)
  ✔ بيشيل الرموز من الأطراف (0.258711ms)
  ✔ عربي (1.202104ms)
  ✔ لاتيني بعلامات (0.397423ms)
  ✔ فاضي (0.267306ms)
  ✔ مش string (1.207132ms)
✔ slugify (9.120812ms)
ℹ tests 12
ℹ suites 3
ℹ pass 12
ℹ fail 0
ℹ cancelled 0
ℹ skipped 0
ℹ todo 0
ℹ duration_ms 171.146703

الستة خضرا، وبقت تشتغل مع أي لغة. كده خلصنا قسم JavaScript و Node. القسم الجاي: HTTP و Express، بنبدأ بـ HTTP نفسه: الـ methods والـ status codes والـ headers.

03 / دروس المسار (122)