الفرق بين المراجعتين ل"Node.js/assert"

من موسوعة حسوب
اذهب إلى التنقل اذهب إلى البحث
ط (تصحيح جملة وجدتها صدفةً.)
ط (استبدال النص - '\[\[تصنيف:(.*)\]\]' ب'{{SUBPAGENAME}}')
 
سطر 984: سطر 984:
 
== مصادر ==
 
== مصادر ==
 
* [https://nodejs.org/dist/latest-v10.x/docs/api/assert.html صفحة Assert في توثيق Node.js الرسمي.]
 
* [https://nodejs.org/dist/latest-v10.x/docs/api/assert.html صفحة Assert في توثيق Node.js الرسمي.]
−
[[تصنيف:Node.js]]
+
[[تصنيف:Node.js|{{SUBPAGENAME}}]]

المراجعة الحالية بتاريخ 11:18، 23 أكتوبر 2018

الاستقرار: 2-مستقر

توفِّر الوحدة assert مجموعةً من اختبارات التوكيد البسيطة التي يمكن استعمالها للتأكد من الثوابت (invariants).

يوجد وضعي توكيد هما: الوضع الصارم (strict mode)، والوضع الإرثي (legacy mode)؛ وينصح باستعمال الوضع الصارم فقط.

للمزيد من المعلومات حول موازنات التساوي المستعملة، ارجع إلى دليل MDN حول موازنات التساوي والتشابه.

الصنف assert.AssertionError

أضيف في الإصدار v0.1.21.

يتفرَّع هذا الصنف الفرعي من الصنف Error الذي يشير إلى فشل عمليَّة التوكيد. جميع الأخطاء التي ترميها الوحدة assert هي نسخةٌ من الصنف AssertError.

new assert.AssertionError(options)

الدالة new assert.AssertionError(options)‎

أضيفت في الإصدار: v0.1.21

  • options: ‏<Object> كائنٌ يحتوي على إحدى القيم التالية:
    • message: ‏<string> سلسلة نصية تمثِّل رسالة الخطأ المراد إظهارها عند فشل التوكيد.
    • actual: ‏<any> أيُّ نوع من أنواع بيانات JavaScript ويمثِّل قيمة الخاصِّيَّة actual في نسخة الخطأ. يُستعمَل داخليًّا من أجل مدخلات الخطأ actual في حال استُخدم assert.strictEqual()‎ مثلًا.
    • expected: ‏<any> أيُّ نوع من أنواع JavaScript ويمثِّل قيمة الخاصِّيَّة expected في نسخة الخطأ. يُستعمَل داخليًّا من أجل مدخلات الخطأ expected في حال استُخدم assert.strictEqual()‎ مثلًا.
    • operator: ‏<string> سلسلة نصية تمثِّل قيمة الخاصَّيِّة operator في نسخة الخطأ. تستخدم داخليًّا للإشارة إلى العمليَّة التي استُخدمت في الموازنة (أو إلى دالة التوكيد التي استدعت الخطأ).
    • stackStartFn: ‏<Function> دالةٌ إن أعطيت، فسيَحذف تتبع المكدس المُولَّد (generated stack trace) جميع الإطارات حتى هذه الدالة المعطاة.

يتفرَّع هذا الصنف الفرعي من الصنف Error الذي يشير إلى فشل عمليَّة التوكيد.

تحتوي جميع النسخ على خاصِّيَّات Error المضمَّنة (مثل الخاصِّيَّة message و الخاصَّيَّة name) وعلى:

  • actual: ‏<any> أيُّ نوع من أنواع JavaScript وهي القيمة الفعليَّة في حال استُخدم assert.strictEqual()‎ مثلًا.
  • generatedMessage: ‏<boolean> قيمةٌ منطقيَّةٌ تحدِّد إن كانت الرسالة قد وُلِّدت تلقائيًّا -عندما تكون true- أم لا.
  • code: ‏<string> سلسلةٌ نصيةٌ تُعيَّن دومًا إلى السلسلة النصيَّة ERR_ASSERTION للإشارة إلى أنَّ الخطأ الحاصل هو خطأ توكيد (assertion error).
  • operator: ‏<string> سلسلة نصية تُعيَّن إلى قيمة المعامل المُمرَّر.

تلقي الشيفرة التالية نظرة سريعة على استعمال هذا التابع:

const assert = require('assert');

// لموازنة رسالة الخطأ لاحقًا AssertionError توليد خطأ توكيد
const { message } = new assert.AssertionError({
  actual: 1,
  expected: 2,
  operator: 'strictEqual'
});

// التأكد من مخرجات الخطأ
try {
  assert.strictEqual(1, 2);
} catch (err) {
  assert(err instanceof assert.AssertionError);
  assert.strictEqual(err.message, message);
  assert.strictEqual(err.name, 'AssertionError [ERR_ASSERTION]');
  assert.strictEqual(err.actual, 1);
  assert.strictEqual(err.expected, 2);
  assert.strictEqual(err.code, 'ERR_ASSERTION');
  assert.strictEqual(err.operator, 'strictEqual');
  assert.strictEqual(err.generatedMessage, true);
}

الوضع الصارم (Strict mode)

سجل التغييرات
الإصدار التغييرات
v9.9.0 أضيفت فروقات الخطأ إلى الوضع الصارم.
v9.9.0 أضيف الوضع الصارم إلى اختبارات التوكيد.

ستُجري أيَّة دالة من دوال التوكيد assert عند استعمالها في الوضع الصارم عمليَّة موازنة صارمة ودقيقة بين كلا الطرفين آنذاك. بناءً على ذلك، إن استعملت الدالة assert.deepEqual()‎ مثلًا في هذا الوضع، فستُنفَّذ بطريقة مماثلة تمامًا للدالة assert.deepStrictEqual()‎ المقابلة لها في الوضع الصارم.

علاوة على ذلك، تُظهِر رسائل الخطأ فرق الخطأ (error diff) بين الكائنات الموازن بينها بدلًا من إظهار جميع الكائنات. هذا الأمر غير موجود في الوضع الإرثي.

يمكن الوصول إلى هذا الوضع وتطبيقه عبر استعمال الأمر التالي:

const assert = require('assert').strict;

مثالٌ عن فرق الخطأ آنف الذكر:

const assert = require('assert').strict;

assert.deepEqual([[[1, 2, 3]], 4, 5], [[[1, 2, '3']], 4, 5]);
// :الناتج هو AssertionError فرق خطأ التوكيد
// Input A expected to strictly deep-equal input B 
// + expected - actual …
// الأسطر المحذوفة هي
//   [
//     [
// ...
//       2,
// -     3
// +     '3'
//     ],
// ...
//     5
//   ]

ملاحظة: لتعطيل الألوان، استعمل متغيِّر البيئة NODE_DISABLE_COLORS. انتبه إلى أنَّ هذا سيؤدي إلى تعطيل الألوان في REPL أيضًا.

الوضع الإرثي (Legacy mode)

الاستقرار: 0-مهمل. استعمل الوضع الصارم عوضًا عنه.

عند استعمال اختبارات التوكيد مباشرةً دون تطبيق الوضع الصارم -باستعمال الخاصِّيَّة strict-، فستُستخدم موازنة التساوي المطلق (Abstract Equality Comparison) مع أي دالة دون إضافة strict إلى اسمها مثل تنفيذ الدالة assert.deepEqual()‎ بدلًا من assert.deepStrictEqual()‎.

يمكن الوصول إلى هذا الوضع وتطبيقه عبر استعمال الأمر التالي:

const assert = require('assert');

ينصح بشدة استعمال الوضع الصارم بدلًا من هذا الوضع، إذ نحصل غالبًا عند استعمال هذا الوضع على نتائج غير متوقعة خصوصًا مع الدالة assert.deepEqual()‎ التي تكون قواعد الموازنة فيها متساهلة جدًا:

// AssertionError تحذير: هذا المثال لن يرمي الخطأ
assert.deepEqual(/a/gi, new Date());

الدالة assert(value[, message])‎

أضيفت في الإصدار: v0.5.9

  • value: ‏<any> أيُّ نوع من أنواع بيانات JavaScript ويمثِّل المدخلات المراد التأكد من كونها صحيحة (truthy).
  • message: ‏<string> | ‏<Error> سلسلة نصية أو كائن من النوع Error وتمثِّل قيمة هذا المعامل المُمرَّر رسالة الخطأ التي سترمى إن لم يكن المعامل value قيمة صحيحة.

هذه الدالة هي اسم بديل للدالة assert.ok()‎.

الدالة assert.deepEqual(actual, expected[, message])‎

سجل التغييرات
الإصدار التغييرات
v9.0.0 توازن الآن الخاصِّيَّة name والخاصِّيَّة message للكائن Error.
v8.0.0 يوازن الآن محتوى الكائن Set والكائن Map.
v6.4.0 - v4.7.1 تعالج أجزاء الكائن TypedArray بشكل صحيح الآن.
v6.1.0 - v4.5.0 يمكن الآن استعمال الكائنات مع المراجع الدائرية (circular references) كمدخلات.
v5.10 - v4.4.3 تعالج الآن الكائنات TypedArray التي ليست من النوع Uint8Array بشكل صحيح.
v0.1.21 أضيفت هذه الدالة.
  • actual: ‏<any> أيُّ نوع من أنواع بيانات JavaScript، ويمثِّل القيمة الأولى المراد التأكد من تساويها مع قيمة ثانية.
  • expected: ‏<any> أيُّ نوع من أنواع بيانات JavaScript، ويمثِّل القيمة الثانية المراد التأكد من تساويها مع القيمة الأولى.
  • message:‏ ‏<string> | ‏<Error> سلسلة نصية أو كائن من النوع Error يرمى عندما لا يكون المعاملان السابقان متساويين.

الوضع الصارم

هو اسم بديل للدالة assert.deepStrictEqual()‎.

الوضع الإرثي

الاستقرار: 0-مهمل. استعمل الوضع الصارم عوضًا عنه.

تتحقَّق هذه الدالة من تساوي المعامل actual مع المعامل expected بالعمق. توازن القيم الأوليَّة باستعمال موازنة التساوي المطلق (==).

يؤخذ بالحسبان الخاصِّيَّات القابلة للإحصاء التابعة للكائن مباشرةً (enumerable own properties). فلا تفحص الدالة assert.deepEqual()‎ الخاصِّيَّة [[Prototype]] للكائن أو الخاصِّيَّات القابلة للإحصاء للنوع Symbol، لذا استعمل الدالة assert.deepStrictEqual()‎ للتحقُّق من التساوي في مثل هذه الحالات.

من المحتمل أن تعيد الدالة assert.deepEqual()‎ نتائج غير متوقعة، إذ لن يرمي المثال التالي الخطأ AssertionError لأنَّ خاصِّيَّات الكائن RegExp غير قابلة للإحصاء:

// AssertionError تحذير: هذا المثال لن يرمي الخطأ
assert.deepEqual(/a/gi, new Date());

هنالك استثناءٌ يخصُّ الكائن Map والكائن Set، إذ توازن عناصر هذه الكائنات أيضًا كما هو متوقع لها. التساوي بالعمق يعني أنَّه حتى الخاصِّيَّات القابلة للإحصاء التابعة للكائنات الأبناء (child objects) توزان ويُتحقَّق من تساويها بين الطرفين أيضًا:

const assert = require('assert');

const obj1 = {
  a: {
    b: 1
  }
};
const obj2 = {
  a: {
    b: 2
  }
};
const obj3 = {
  a: {
    b: 1
  }
};
const obj4 = Object.create(obj1);

assert.deepEqual(obj1, obj1);
// متساويان

// مختلفة b قيم
assert.deepEqual(obj1, obj2);
// AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }

assert.deepEqual(obj1, obj3);
// متساويان

// Prototype تهمل الخاصِّيَّات
assert.deepEqual(obj1, obj4);
// AssertionError: { a: { b: 1 } } deepEqual {}

إن لم تتساوى القيم مع بعضها بعضًا، فسيرمى الخطأ AssertionError مع ضبط قيمة الخاصِّيَّة message إلى قيمة المعامل message المعطى. إن لم تعطَ قيمة المعامل message أو كانت غير معرَّفة (undefined)، فستُستعمل رسالة الخطأ الافتراضيَّة. أمَّا إن كان المعامل message نسخةً من الخطأ Error، فسيرمى حينئذٍ بدلًا من الخطأ AssertionError.

الدالة assert.deepStrictEqual(actual, expected[, message])‎

سجل التغييرات
الإصدار التغييرات
v9.0.0 توازن الآن خاصِّيَّات symbol القابلة للإحصاء.
v9.0.0 توازن الآن القيمة NaN باستعمال الموازنة القيم المماثلة الصفرية (SameValueZero comparison).
v9.0.0 توازن الآن الخاصَّيِّة name والخاصِّيَّة message للكائن Error.
v8.0.0 يوازن الآن محتوى الكائن Set والكائن Map.
v6.4.0 - v4.7.1 تعالج الآن أجزاء الكائن TypedArray بشكل صحيح.
v6.1.0 - v4.5.0 يمكن الآن استعمال الكائنات مع المراجع الدائرية (circular references) كمدخلات.
v5.10 - v4.4.3 تعالج الآن الكائنات TypedArray التي ليست من النوع Uint8Array بشكل صحيح.
v1.2.0 أضيفت هذه الدالة.
  • actual: ‏<any> أيُّ نوع من أنواع بيانات JavaScript، ويمثِّل القيمة الأولى المراد التأكد من تساويها مع قيمة ثانية.
  • expected: ‏<any> أيُّ نوع من أنواع بيانات JavaScript ويمثِّل القيمة الثانية المراد التأكد من تساويها مع القيمة الأولى.
  • message: ‏<string> | ‏<Error> سلسلة نصية أو كائن من النوع Error يرمى عندما لا يكون المعاملان السابقان متساويين.

تتحقَّق هذه الدالة من تساوي المعاملين actual و expected بالعمق. التساوي بالعمق (deep equality) يعني أنَّه حتى الخاصِّيَّات القابلة للإحصاء التابعة للكائنات الأبناء (child objects) توزان ويُتحقَّق من تساويها بين الطرفين أيضًا بشكل تكراري وذلك عبر قواعد الموازنة التالية الذكر.

قواعد الموازنة

  • توازن القيم الأوليَّة (primitive values) باستعمال موازنة القيم المماثلة (SameValue Comparison) عبر Object.is()‎.
  • يجب أن تكون أنواع وسوم الكائنات متماثلة.
  • توازن الخاصِّيَّة [[Prototype]] للكائنات باستعمال موازنة التساوي الصارم (Strict Equality Comparison).
  • تؤخذ الخاصِّيَّات القابلة للإحصاء التابعة للكائن مباشرةً بالحسبان فقط.
  • توازن الخاصِّيَّة name والخاصِّيَّة message للكائن Error دومًا حتى لو كانتا من النوع الغير قابل للإحصاء.
  • توازن خاصِّيَّات النوع Symbol القابلة للإحصاء أيضًا.
  • توازن مغلفات الكائن (object wrappers) بوصفها كائنات وقيم غير مغلفة.
  • توازن خاصِّيَّات الكائن Object دون ترتيب.
  • توازن مفاتيح الخريطة (map) وعناصر المجموعة (set) دون ترتيب.
  • توقف الموازنة التكرارية عندما يختلف كلا الطرفين أو يقابل كلا الطرفين مرجعًا دائريًّا (circular references).
  • لا تعتمد موازنة الكائن WeakMap والكائن WeakSet على قِيَمِهِمَا فقط.

تفحَّص المثال التالي لفهم أعمق لهذه القواعد:

const assert = require('assert').strict;

// 1 !== '1' هذا سيفشل لأن
assert.deepStrictEqual({ a: 1 }, { a: '1' });
// AssertionError: Input A expected to strictly deep-equal input B:
// + expected - actual
//   {
// -   a: 1
// +   a: '1'
//   }

// الكائنات التالية ليس لها خاصِّيَّات مرتبطة بها مباشرةً
const date = new Date();
const object = {};
const fakeDate = {};
Object.setPrototypeOf(fakeDate, Date.prototype);

// مختلفة [[Prototype]] خاصِّيَّات
assert.deepStrictEqual(object, fakeDate);
// AssertionError: Input A expected to strictly deep-equal input B:
// + expected - actual
// - {}
// + Date {}

// أنواع وسوم مختلفة
assert.deepStrictEqual(date, fakeDate);
// AssertionError: Input A expected to strictly deep-equal input B:
// + expected - actual
// - 2018-04-26T00:49:08.604Z
// + Date {}

assert.deepStrictEqual(NaN, NaN);
// موازنة محقَّقة بسبب استعمال موازنة القيم المماثلة


// أعداد غير مغلفة مختلفة
assert.deepStrictEqual(new Number(1), new Number(2));
// AssertionError: Input A expected to strictly deep-equal input B:
// + expected - actual
// - [Number: 1]
// + [Number: 2]

assert.deepStrictEqual(new String('foo'), Object('foo'));
// موازنة محقَّقة لأن قيمة السلسلة النصية والكائن هي نفسها عند إزالة التغليف عنها

assert.deepStrictEqual(-0, -0);
// OK

// استعمال أصفار مختلفة مع موازنة القيم المتماثلة
assert.deepStrictEqual(0, -0);
// AssertionError: Input A expected to strictly deep-equal input B:
// + expected - actual
// - 0
// + -0

const symbol1 = Symbol();
const symbol2 = Symbol();
assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol1]: 1 });
// موازنة محققة لاستعمال نفس الرمز في كلا الكائنين
assert.deepStrictEqual({ [symbol1]: 1 }, { [symbol2]: 1 });
// AssertionError [ERR_ASSERTION]: Input objects not identical:
// {
//   [Symbol()]: 1
// }

const weakMap1 = new WeakMap();
const weakMap2 = new WeakMap([[{}, {}]]);
const weakMap3 = new WeakMap();
weakMap3.unequal = true;

assert.deepStrictEqual(weakMap1, weakMap2);
// موازنة صحيحة لعدم التحقُّق من تساوي القيم


// weakMap1 لا يمتلكها الكائن weakMap3 الموازنة التالية غير محقَّقة لوجود خاصِّيَّة في الكائن 
assert.deepStrictEqual(weakMap1, weakMap3);
// AssertionError: Input A expected to strictly deep-equal input B:
// + expected - actual
//   WeakMap {
// -   [items unknown]
// +   [items unknown],
// +   unequal: true
//   }

إن لم تتساوى القيم مع بعضها بعضًا، فسيُرمى الخطأ AssertionError مع ضبط قيمة الخاصِّيَّة message إلى قيمة المعامل message المعطى. إن لم تعطَ قيمة المعامل message أو كانت غير معرَّفة (undefined)، فستُستعمل رسالة الخطأ الافتراضيَّة. أمَّا إن كان المعامل message نسخةً من الخطأ Error، فسيرمى حينئذٍ بدلًا من الخطأ AssertionError.

الدالة assert.doesNotReject(block[, error][, message])‎

أضيفت في الإصدار: v10.0.0

  • block: ‏<Function> | ‏<Promise> كائن من النوع Promise أو دالةٌ تعيد الكائن Promise الذي يراد التأكد من قبوله.
  • error: ‏<RegExp> | ‏<Function> كائن من النوع RegExp أو دالةٌ.
  • message: ‏<string> | ‏<Error> سلسلة نصية (String) أو كائنٌ من النوع Error.

إن كان المعامل block المعطى كائنًا من النوع Promise، فستنتظر هذه الدالة اكتمال هذا الكائن ثمَّ تتأكد من قبوله (resolved). أمَّا إن كان ذاك المعامل المعطى دالةً، فستَسدعِي الدالة assert.doesNotReject()‎ تلك الدالة المعطاة وتنتظر اكتمال الكائن Promise المعاد ثمَّ تتأكد من أنَّه مقبول.

إن كان المعامل block دالةً ورَمت هذه الدالة خطأً بشكل متزامن، فستعيد الدالة assert.doesNotReject()‎ حينذاك كائن Promise مرفوض (rejected) مع ذلك الخطأ. أمَّا إن كان المعامل block دالةً ولكنها لا تعيد كانئًا من النوع Promise، فستعيد الدالة assert.doesNotReject()‎ حينذاك كائن Promise مرفوض مع الخطأ ERR_INVALID_RETURN_VALUE. يُتخطى في كلا الحالتين معالج الخطأ.

ملاحظة: استعمال الدالة assert.doesNotReject()‎ غير مفيد صراحةً لأنَّ الفائدة التي نجنيها من تتبع الكائن Promise المرفوض ثمَّ رفضه مجدَّدًا قليلة جدًا. عوضًا عن ذلك، أرى أن تضيف تعليقًا بجانب جزء الشيفرة المحدَّد يشرح بأنَّه بنبغي عدم رفض الكائن، وأبقي رسالة الخطأ معبِّرة قدر الإمكان.

يمكن أن يكون المعامل error صنفًا (Class)، أو كائنًا من النوع RegExp، أو دالةً صالحة. انظر قسم الدالة assert.throws()‎ للمزيد من التفاصيل.

بجانب السلوك الطبيعي الذي تسلكه الدوال غير المتزامنة (async function) عبر انتظار اكتمال الوعود (Promise)، نجد أيضًا أنَّها تتصرَّف بطريقة مماثلة تمامًا للدالة assert.doesNotThrow()‎.

(async () => {
  await assert.doesNotReject(
    async () => {
      throw new TypeError('Wrong value');
    },
    SyntaxError
  );
})();

assert.doesNotReject(Promise.reject(new TypeError('Wrong value')))
  .then(() => {
    // ...
  });

الدالة assert.doesNotThrow(block[, error][, message])‎

سجل التغييرات
الإصدار التغيير
v5.00.0-v4.4.5 أصبح المعامل message يؤخذ بالحسبان.
v4.2.0 يمكن أن يكون المعامل error الآن دالةً سهميَّة (arrow function).
v0.1.21 أضيفت هذه الدالة.
  • block: ‏<Function> دالةٌ يراد التأكد من أنَّها لا ترمي أيَّ خطأٍ.
  • error: ‏<RegExp> | ‏<Function> كائن من النوع RegExp أو دالةٌ.
  • message: ‏<string> | ‏<Error> سلسلة نصية (String) أو كائنٌ من النوع Error.

تتأكد هذه الدالة من أنَّ المعامل block لا يرمي أيَّ خطأٍ.

ملاحظة: استعمال الدالة assert.doesNotThrow()‎ غير مفيد حقيقةً لأنَّ الفائدة التي نجنيها من تتبع الخطأ المرمي ثمَّ رميه مجدَّدًا قليلةٌ جدًا. عوضًا عن ذلك، أرى أن تضيف تعليقًا بجانب جزء الشيفرة المحدَّد يشرح بأنَّه بنبغي عدم رمي الخطأ، وأبقي رسالة الخطأ معبِّرة قدر الإمكان.

عندما تُستدعَى الدالة assert.doesNotThrow()‎، فإنَّها تستدعي بدورها الدالة block المعطاة مباشرةً.

إن رُمِيَ خطأٌ وكان مماثلًا للنوع المحدَّد في المعامل error، فسيرمى الخطأ AssertionError حينئذٍ. أمَّا إن كان الخطأ المرمي مختلفًا عن الخطأ المعطى في المعامل error أو كانت قيمة المعامل error هي undefined أو لم تعطَ مطلقًا، فسينتشر هذا الخطأ حينئذٍ مرةً أخرى إلى من استدعاه.

يمكن أن يكون المعامل error صنفًا (Class)، أو كائنًا من النوع RegExp، أو دالةً صالحة. انظر قسم الدالة assert.throws()‎ للمزيد من التفاصيل.

سيرمي المثال التالي مثلًا الخطأ TypeError لأنَّه لم يتطابق مع نوع الخطأ المحدَّد في دالة التوكيد:

assert.doesNotThrow(
  () => {
    throw new TypeError('Wrong value');
  },
  SyntaxError
);

أمَّا المثال التالي سيرمي الخطأ AssertionError مع الرسالة 'Got unwanted exception...‎':

assert.doesNotThrow(
  () => {
    throw new TypeError('Wrong value');
  },
  TypeError
);

إن رُمِيَ الخطأ AssertionError وكانت هنالك قيمة معطاة للمعامل message، فسيُضاف محتوى المعامل message المعطى إلى رسالة الخطأ AssertionError:

assert.doesNotThrow(
  () => {
    throw new TypeError('Wrong value');
  },
  /Wrong value/,
  'Whoops'
);
// AssertionError: Got unwanted exception: Whoops

الدالة assert.equal(actual, expected[, message])‎

أضيفت في الإصدار: v0.1.21

  • actual: ‏<any> أيُّ نوع من أنواع بيانات JavaScript، ويمثِّل القيمة الأولى المراد التأكد من تساويها مع قيمة ثانية.
  • expected: ‏<any> أيُّ نوع من أنواع بيانات JavaScript ويمثِّل القيمة الثانية المراد التأكد من تساويها مع القيمة الأولى.
  • message: ‏<string> | ‏<Error>  سلسلة نصية أو كائن من النوع Error يرمى عندما لا يكون المعاملان السابقان متساويين.

الوضع الصارم

هو اسم بديل للدالة assert.StrictEqual()‎.

الوضع الإرثي

الاستقرار: 0-مهمل. استعمل الوضع الصارم عوضًا عنه.

تتحقَّق هذه الدالة من تساوي المعامل actual مع المعامل expected بشكل سطحي عبر موازنة التساوي المطلق (==).

const assert = require('assert');

assert.equal(1, 1);
// موازنة صحيحة: 1 == 1
assert.equal(1, '1');
// موازنة صحيحة: 1 == '1'

assert.equal(1, 2);
// :موازنة غير صحيحة وسيرمى الخطأ
// AssertionError: 1 == 2
assert.equal({ a: { b: 1 } }, { a: { b: 1 } });
// :موازنة غير صحيحة وسيرمى الخطأ
// AssertionError: { a: { b: 1 } } == { a: { b: 1 } }

إن لم تتساوى القيم مع بعضها بعضًا، فسيُرمى الخطأ AssertionError مع ضبط قيمة الخاصِّيَّة message إلى قيمة المعامل message. إن لم تعطَ قيمة المعامل message أو كانت غير مُعرَّفة (undefined)، فستُستعمل رسالة الخطأ الافتراضيَّة. أمَّا إن كان المعامل message نسخةً من الخطأ Error، فسيرمى حينئذٍ بدلًا من الخطأ AssertionError.

الدالة assert.fail([message])‎

أضيفت في الإصدار: v0.1.21

  • message: ‏<string> | ‏<Function> سلسلة نصية أو كائن من النوع Error، وقيمته الافتراضيَّة هي 'Failed'.

ترمي هذه الدالة الخطأ AssertionError مع رسالة الخطأ المُمرَّرة إليه (أو رسالة الخطأ الافتراضيَّة إن لم يُمرَّر إليه أيُّ شيء). إن كان المعامل message نسخةً من الخطأ Error، فسيرمى حينئذٍ بدلًا من الخطأ AssertionError.

const assert = require('assert').strict;

assert.fail();
// AssertionError [ERR_ASSERTION]: Failed

assert.fail('boom');
// AssertionError [ERR_ASSERTION]: boom

assert.fail(new TypeError('need array'));
// TypeError: need array

كانت الدالة assert.fail()‎ تقبل أن يُمرَّر إليها أكثر من معاملين إلا أنَّ هذا السلوك قد أهمل. انظر القسم التالي لتفاصيل أوسع.

الدالة assert.fail(actual, expected[, message[, operator[, stackStartFunction]]])‎

سجل التغييرات
الإصدار التغيير
v10.0.0 استعمال الدالة assert.fail()‎ مع أكثر من معامل واحد قد أهمل، وسيُصدَر تحذيرٌ إن استعمل في تلك الحالة.
v0.1.21 أضيفت هذه الدالة.

الاستقرار: 0-مهمل: استعمل الدالة assert.fail([message])‎ أو أيَّة دالة توكيد أخرى.

  • actual: ‏<any>  أيُّ نوع من أنواع بيانات JavaScript.
  • expected: ‏<any> أيُّ نوع من أنواع بيانات JavaScript.
  • message: ‏<string> | ‏<Error> سلسلة نصية أو كائن من النوع Error.
  • operator: ‏<string> سلسلة نصية، وقيمته الافتراضيَّة هي '‎!=‎'.
  • stackStartFunction: ‏<Function> دالةٌ، وقيمته الافتراضيَّة هي assert.fail.

إن كان المعامل message قيمة خطأ (falsy)، فستُعيَّن رسالة الخطأ إلى قيمة المعامل actual والمعامل expected، وتفصل قيمة المعامل operator بينهما.

إن أعطي المعامل actual والمعامل expected فقط، فستُضبط قيمة المعامل operator الافتراضيَّة إلى '‎!=‎'.

إن أعطي المعامل message وكان ثالث ثلاثة، فسيُمثِّل رسالة الخطأ وسيُخزَّن المعاملان الآخران كخاصِّيَّات في الكائن المَرمي.

إن أعطي المعامل stackStartFunction، فستزال جميع إطارات المكدس التي تقع فوق هذه الدالة المعطاة من متتبع المكدس (stacktrace، ارجع إلى Error.captureStackTrace).

أخيرًا، إن لم يمرَّر أيُّ معاملٍ، فستُستعمَل الرسالة Failed كرسالة افتراضيَّة.

const assert = require('assert').strict;

assert.fail('a', 'b');
// AssertionError [ERR_ASSERTION]: 'a' != 'b'

assert.fail(1, 2, undefined, '>');
// AssertionError [ERR_ASSERTION]: 1 > 2

assert.fail(1, 2, 'fail');
// AssertionError [ERR_ASSERTION]: fail

assert.fail(1, 2, 'whoops', '>');
// AssertionError [ERR_ASSERTION]: whoops

assert.fail(1, 2, new TypeError('need array'));
// TypeError: need array

في الحالات الثلاث الأخيرة من الشيفرة السابقة، ليس للمعاملات actual، و expected، و operator أيُّ تأثير على رسالة الخطأ. في المثال التالي، يستعمل المعامل stackStartFunction لتقطيع استثناء مُتتبِّع الأخطاء:

function suppressFrame() {
  assert.fail('a', 'b', undefined, '!==', suppressFrame);
}
suppressFrame();
// AssertionError [ERR_ASSERTION]: 'a' !== 'b'
//     at repl:1:1
//     at ContextifyScript.Script.runInThisContext (vm.js:44:33)
//     …

الدالة assert.ifError(value)‎

سجل التغييرات
الإصدار التغيير
v10.0.0 بدلًا من رمي الخطأ الأصلي، أصبح يغلف الآن ضمن الخطأ AssertionError الذي يحوي متتبِّع المكدس كاملًا.
v10.0.0 انحصرت قيمة المعامل value ضمن القيمة undefined والقيمة null فقط. كانت تعامل جميع القيم الخطأ (falsy values) قبل ذلك كأنَّها القيمة null ولا تُرمَى حينئذٍ.
v0.1.97 أضيفت هذه الدالة.
  • value: ‏<any> أيُّ نوع من أنواع بيانات JavaScript.

ترمي هذه الدالة المعامل value إن لم تكن قيمته undefined أو null. هذا التحقُّق مفيد خصوصًا عند التأكد من الوسيط error في دوال رد النداء. يحتوي مُتتبِّع المكدس على جميع الإطارات من الخطأ الممرَّر إلى ifError()‎ من ضمنها الإطارات الجديدة المحتملة للدالة ifError()‎ نفسها. تَفحَّص المثال التالي الذي يشرح ذلك عمليًّا:

const assert = require('assert').strict;

assert.ifError(null);
// OK
assert.ifError(0);
// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 0
assert.ifError('error');
// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 'error'
assert.ifError(new Error());
// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: Error

// إنشاء بعض إطارات خطأ عشوائية
let err;
(function errorFrame() {
  err = new Error('test error');
})();

(function ifErrorFrame() {
  assert.ifError(err);
})();
// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: test error
//      ifErrorFrame في
//    at errorFrame في

الدالة assert.notDeepEqual(actual, expected[, message])‎

سجل التغييرات
الإصدار التغييرات
v9.0.0 يمكن الآن موازنة الخاصِّيَّة name والخاصِّيَّة message للكائن Error.
v8.0.0 يمكن الآن موازنة محتوى الكائن Set والكائن Map.
v6.4.0 - v4.7.1 تعالج أجزاء الكائن TypedArray بشكل صحيح الآن.
v6.1.0 - v4.5.0 يمكن الآن استعمال الكائنات مع المراجع الدائرية (circular references) كمدخلات.
v5.10 - v4.4.3 تعالج الآن الكائنات TypedArray التي ليست من النوع Uint8Array بشكل صحيح.
v0.1.21 أضيفت هذه الدالة.
  • actual: ‏<any> أيُّ نوع من أنواع بيانات JavaScript، ويمثِّل القيمة الأولى المراد التأكد من عدم تساويها مع قيمة ثانية.
  • expected: ‏<any> أيُّ نوع من أنواع بيانات JavaScript ويمثِّل القيمة الثانية المراد التأكد من عدم تساويها مع القيمة الأولى.
  • message: ‏<string> | ‏<Function> سلسلة نصية أو كائن من النوع Error يرمى عندما يكون المعاملان السابقان متساويين.

الوضع الصارم

هو اسم بديل للدالة assert.notDeepStrictEqual()‎.

الوضع الإرثي

الاستقرار: 0-مهمل. استعمل الوضع الصارم عوضًا عنه.

تتحقَّق هذه الدالة من عدم تساوي المعامل actual مع المعامل expected بالعمق، أي تعمل بشكل معاكس تمامًا للدالة assert.deepEqual()‎.

const assert = require('assert');

const obj1 = {
  a: {
    b: 1
  }
};
const obj2 = {
  a: {
    b: 2
  }
};
const obj3 = {
  a: {
    b: 1
  }
};
const obj4 = Object.create(obj1);

assert.notDeepEqual(obj1, obj1);
// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }

assert.notDeepEqual(obj1, obj2);
// OK

assert.notDeepEqual(obj1, obj3);
// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }

assert.notDeepEqual(obj1, obj4);
// OK

إن تساوت القيم مع بعضها بعضًا بالعمق، فسيُرمَى الخطأ AssertionError مع ضبط قيمة الخاصِّيَّة message إلى قيمة المعامل message المعطى. إن لم تعطَ قيمة المعامل message أو كانت غير معرَّفة (undefined)، فستُستعمَل رسالة الخطأ الافتراضيَّة. أمَّا إن كان المعامل message نسخةً من الخطأ Error، فسيرمى حينئذٍ بدلًا من الخطأ AssertionError.

الدالة assert.notDeepStrictEqual(actual, expected[, message])‎

سجل التغييرات
الإصدار التغييرات
v9.0.0 لم يعد الصفر السالب ‎-0 والصفر الموجب ‎+0 متساويان بعد الآن.
v9.0.0 توازن الآن القيمة NaN باستعمال موازنة القيم المتماثلة الصفرية (SameValueZero comparison).
v9.0.0 توازن الآن الخاصِّيَّة name والخاصِّيَّة message للكائن Error.
v8.0.0 يوازن الآن محتوى الكائن Set والكائن Map.
v6.4.0 - v4.7.1 تعالج الآن أجزاء الكائن TypedArray بشكل صحيح.
v6.1.0 - v4.5.0 يمكن الآن استعمال الكائنات مع المراجع الدائرية (circular references) كمدخلات.
v5.10 - v4.4.3 تعالج الآن الكائنات TypedArray التي ليست من النوع Uint8Array بشكل صحيح.
v1.2.0 أضيفت هذه الدالة.
  • actual: ‏<any> أيُّ نوع من أنواع بيانات JavaScript، ويمثِّل القيمة الأولى المراد التأكد من عدم تساويها مع قيمة ثانية.
  • expected: ‏<any> أيُّ نوع من أنواع بيانات JavaScript ويمثِّل القيمة الثانية المراد التأكد من عدم تساويها مع القيمة الأولى.
  • message: ‏<string> | ‏<Error> سلسلة نصيَّة أو كائن من النوع Error يرمى عندما يكون المعاملان السابقان متساويين.

تتحقَّق هذه الدالة من عدم تساوي المعاملين actual و expected بالعمق وبشكل دقيق (strict). هذه الدالة هي عكس الدالة assert.deepSreictEqual()‎.

const assert = require('assert').strict;

assert.notDeepStrictEqual({ a: 1 }, { a: '1' });
// محقق

إن تساوت القيم مع بعضها بعضًا بالعمق وبدقة، فسيرمى الخطأ AssertionError مع ضبط قيمة الخاصِّيَّة message إلى قيمة المعامل message. إن لم تعطَ قيمة المعامل message أو كانت غير معرَّفة (undefined) فستُستعمل رسالة الخطأ الافتراضية. أمَّا إن كان المعامل message نسخةً من الخطأ Error، فسيرمى حينئذٍ بدلًا من الخطأ AssertionError.

الدالة assert.notEqual(actual, expected[, message])‎

أضيفت في الإصدار: v0.1.21

  • actual: ‏<any> أيُّ نوع من أنواع بيانات JavaScript، ويمثِّل القيمة الأولى المراد التأكد من عدم تساويها مع قيمة ثانية.
  • expected: ‏<any> أي نوع من أنواع بيانات JavaScript، ويمثِّل القيمة الثانية المراد التأكد من عدم تساويها مع القيمة الأولى.
  • message: ‏<string> | ‏<Error> سلسلة نصية أو كائن من النوع Error يرمى عندما يكون المعاملان السابقان متساويين.

الوضع الصارم

هو اسم بديل للدالة assert.notStrictEqual()‎.

الوضع الإرثي

الاستقرار: 0-مهمل. استعمل الوضع الصارم عوضًا عنه.

تتحقَّق هذه الدالة من عدم تساوي المعامل actual مع المعامل expected سطحيًّا باستعمال موازنة التساوي المطلق (‎!=‎).

const assert = require('assert');

assert.notEqual(1, 2);
// محقق

assert.notEqual(1, 1);
// AssertionError: 1 != 1

assert.notEqual(1, '1');
// AssertionError: 1 != '1'

إن تساوت القيم مع بعضها بعضًا، فسيرمى الخطأ AssertionError مع ضبط قيمة الخاصِّيَّة message إلى قيمة المعامل message المعطى. إن لم تعطَ قيمة المعامل message أو كانت غير معرَّفة (undefined)، فستُستعمل رسالة الخطأ الافتراضيَّة. أمَّا إن كان المعامل message نسخةً من الخطأ Error، فسيرمى حينئذٍ بدلًا من الخطأ AssertionError.

الدالة assert.notStrictEqual(actual, expected[, message])‎

سجل التغييرات
الإصدار التغيير
v10.0.0 تغيَّرت الموازنة المستعملة من الموازنة الصارمة إلى Object.is()‎.
v0.1.21 أضيفت هذه الدالة.
  • actual: ‏<any> أيُّ نوع من أنواع بيانات JavaScript، ويمثِّل القيمة الأولى المراد التأكد من عدم تساويها مع قيمة ثانية.
  • expected: ‏<any> أيُّ نوع من أنواع بيانات JavaScript، ويمثِّل القيمة الثانية المراد التأكد من عدم تساويها مع القيمة الأولى.
  • message: ‏<string> | ‏<Error> سلسلة نصية أو كائن من النوع Error يرمى عندما يكون المعاملان السابقان متساويين.

تتحقَّق هذه الدالة من عدم تساوي المعامل actual مع المعامل expected بالوضع الصارم باستعمال موازنة القيم المتماثلة.

const assert = require('assert').strict;

assert.notStrictEqual(1, 2);
// محقق

assert.notStrictEqual(1, 1);
// AssertionError [ERR_ASSERTION]: Identical input passed to notStrictEqual: 1

assert.notStrictEqual(1, '1');
// محقق

إن تساوت القيم مع بعضها بعضًا في الوضع الصارم، فسيرمى الخطأ AssertionError مع ضبط قيمة الخاصِّيَّة message إلى قيمة المعامل message المعطى. إن لم تعطَ قيمة المعامل message أو كانت غير معرَّفة (undefined)، فستُستعمل رسالة الخطأ الافتراضيَّة. أمَّا إن كان المعامل message نسخةً من الخطأ Error، فسيرمى حينئذٍ بدلًا من الخطأ AssertionError.

الدالة assert.ok(value[, message])‎

أضيفت في الإصدار: v0.1.21

  • value: ‏<any> أيُّ نوع من أنواع بيانات JavaScript ويمثل المدخلات المراد التأكد من كونها صحيحة (truthy).
  • message: ‏<string> | ‏<Error>  سلسلة نصية أو كائن من النوع Error، وتمثِّل قيمة هذا المعامل رسالة الخطأ التي ستُرمى إن لم يكن المعامل value قيمة صحيحة.

تتحقَّق هذه الدالة إن كانت قيمة المعامل value هي قيمة صحيحة (truthy)، وهي مماثلة لاستدعاء الدالة assert.equal()‎ بالشكل assert.equal(!!value, true, message)‎.

إن لم يكن المعامل value قيمة صحيحة، فسيُرمى الخطأ AssertionError مع ضبط قيمة الخاصِّيَّة message إلى قيمة المعامل message المعطى. إن كانت قيمة المعامل message هي undefined، فستُستعمل رسالة الخطأ الافتراضيَّة. أمَّا إن كان المعامل message نسخةً من الخطأ Error، فسيرمى حينئذٍ بدلًا من الخطأ AssertionError. أمَّا إن لم يعطَ المعامل message مطلقًا، فستعيَّن قيمته إلى العبارة: 'No value argument passed to `assert.ok()`‎'.

انتبه إلى أنَّ رسالة الخطأ في repl ستختلف عن تلك المرميَّة في ملف. تَفحَّص الحالة الخامسة والسادسة في الشيفرة التالية:

const assert = require('assert').strict;

assert.ok(true);
// محقق
assert.ok(1);
// محقق

assert.ok();
// AssertionError: No value argument passed to `assert.ok()`

assert.ok(false, 'it\'s false');
// AssertionError: it's false

// :repl في
assert.ok(typeof 123 === 'string');
// AssertionError: false == true

// :test.js في ملف مثل
assert.ok(typeof 123 === 'string');
// AssertionError: The expression evaluated to a falsy value:
//
//   assert.ok(typeof 123 === 'string')

assert.ok(false);
// AssertionError: The expression evaluated to a falsy value:
//
//   assert.ok(false)

assert.ok(0);
// AssertionError: The expression evaluated to a falsy value:
//
//   assert.ok(0)

// :الذي يُعدُّ اسمًا بديلًا لهذه الدالة `assert()` يمكن استعمال
assert(0);
// AssertionError: The expression evaluated to a falsy value:
//
//   assert(0)

الدالة assert.rejects(block[, error][, message])‎

أضيفت في الإصدار: v10.0.0

  • block: ‏<Promise> | ‏<Function> كائن من النوع Promise أو دالةٌ تعيد الكائن Promise الذي يراد التأكد من رفضه.
  • error:‏ <RegExp> | ‏<Function>  كائن من النوع RegExp، أو دالةٌ، أو كائن من النوع Object، أو من النوع Error.
  • message: ‏<string> | ‏<Error> سلسلة نصية (String) أو كائنٌ من النوع Error.

إن كان المعامل block المعطى كائنًا من النوع Promise، فستنتظر هذه الدالة اكتمال هذا الكائن ثمَّ تتأكد من رفضه (rejected). أمَّا إن كان ذاك المعامل المعطى دالةً، فستسدعي الدالة assert.rejects()‎ تلك الدالة المعطاة وتنتظر اكتمال الكائن Promise المعاد ثمَّ تتأكد من أنَّه مرفوض (rejected).

إن كان المعامل block دالةً ورمت هذه الدالة خطأً بشكل متزامن، فستعيد الدالة assert.rejects()‎ حينذاك كائن Promise مرفوض مع ذلك الخطأ. أمَّا إن كان المعامل block دالةً ولكنها لا تعيد كانئًا من النوع Promise، فستعيد الدالة assert.rejects()‎ حينذاك كائن Promise مرفوض أيضًا مع الخطأ ERR_INVALID_RETURN_VALUE. يُتخطى في كلا الحالتين معالج الخطأ.

بجانب السلوك الطبيعي الذي تسلكه الدوال غير المتزامنة (async function) عبر انتظار اكتمال الوعود (Promise)، نجد أيضًا أنها تتصرَّف بطريقة مماثلة تمامًا للدالة assert.throws()‎.

يمكن أن يكون المعامل error صنفًا (Class)، أو كائنًا من النوع RegExp، أو دالةً صالحة، أو كائنًا من النوع Object، أو نسخةً من الخطأ Error، إذ سيُتحقق في الحالتين الأخيرتين من كل خاصِّيَّة غير قابلة للإحصاء (non-enumerable، من ضمنها الخاصِّيَّة message والخاصِّيَّة name).

إن أعطي المعامل message، فسيضاف محتواه إلى الخطأ AssertionError إن فشل رفض الكائن Promise المعطى في المعامل block.

(async () => {
  await assert.rejects(
    async () => {
      throw new TypeError('Wrong value');
    },
    {
      name: 'TypeError',
      message: 'Wrong value'
    }
  );
})();


assert.rejects(
  Promise.reject(new Error('Wrong value')),
  Error
).then(() => {
  // ...
});

انتبه إلى أنَّه لا يمكن أن يكون المعامل error سلسلةً نصيةً. إن مُرَّرت سلسلة نصية كمعامل ثانٍ إلى الدالة assert.reject()‎، فسيُفترض أنَّ المعامل error لم يعطَ وستُمثِّل هذه السلسلة قيمة المعامل message. هذا الأمر قد يؤدي إلى حدوث لَبسٍ في المعاملات. تفحَّص رجاءً المثال الموجود في الدالة assert.thows()‎ بعناية خصوصًا حيث استعملت سلسلة نصية كمعامل ثانٍ.

الدالة assert.strictEqual(actual, expected[, message])‎

سجل التغييرات
الإصدار التغيير
v10.0.0 تغيَّرت عمليَّة الموازنة المستعملة من الموازنة الصارمة إلى Object.is()‎.
v0.1.21 أضيفت هذه الدالة.
  • actual: ‏<any> أيُّ نوع من أنواع بيانات JavaScript، ويمثِّل القيمة الأولى المراد التأكد من عدم تساويها مع قيمة ثانية.
  • expected: ‏<any> أيُّ نوع من أنواع بيانات JavaScript ويمثِّل القيمة الثانية المراد التأكد من عدم تساويها مع القيمة الأولى.
  • message: ‏<string> | ‏<Error>  سلسلةٌ نصيةٌ أو كائن من النوع Error يرمى عندما يكون المعاملان السابقان متساويين.

تتحقَّق هذه الدالة من تساوي المعامل actual مع المعامل expected في الوضع الصارم باستعمال موازنة القيم المتماثلة.

const assert = require('assert').strict;

assert.strictEqual(1, 2);
// AssertionError [ERR_ASSERTION]: Input A expected to strictly equal input B:
// + expected - actual
// - 1
// + 2

assert.strictEqual(1, 1);
// OK

assert.strictEqual(1, '1');
// AssertionError [ERR_ASSERTION]: Input A expected to strictly equal input B:
// + expected - actual
// - 1
// + '1'

إن لم تكن القيم متساوية مع بعضها بعضًا في الوضع الصارم، فسيُرمى الخطأ AssertionError مع ضبط قيمة الخاصِّيَّة message إلى قيمة المعامل message. إن لم تعطَ قيمة المعامل message أو كانت غير معرَّفة (undefined) فستُستعمل رسالة الخطأ الافتراضيَّة. أمَّا إن كان المعامل message نسخةً من الخطأ Error، فسيرمى حينئذٍ بدلًا من الخطأ AssertionError.

الدالة assert.throws(block[, error][, message])‎

سجل التغييرات
الإصدار التغيير
v10.2.0 يمكن أن يكون المعامل error كائنًا (Object) يحتوي على تعابير نمطية.
v9.9.0 يمكن أن يكون المعامل error كائنًا (Object) أيضًا.
v4.2.0 يمكن أن يكون المعامل error دالةً سهميةً.
v0.1.21 أضيفت هذه الدالة.

تتأكد هذه الدالة من أنَّ المعامل block قد رمى خطأً.

يمكن أن يكون المعامل error صنفًا (Class)، أو كائنًا من النوع RegExp، أو دالةً صالحة، أو كائن (Object) صالح ويُتحقَّق في هذه الحالة من تساوي كل خاصِّيَّة بالعمق في الوضع الصارم، أو نسخةً من الخطأ Error ويُتحقَّق أيضًا في هذه الحالة من تساوي كل خاصِّيَّة بالعمق في الوضع الصارم من ضمنها الخاصِّيَّات غير القابلة لإحصاء (مثل الخاصِّيَّة name والخاصِّيَّة message). إن استعمل كائن مع المعامل error، فمن الممكن حينها استعمال التعابير النمطيَّة (regular expression) خصوصًا عندما يُتحقَّق من صحة خاصِّيَّة السلسلة النصية. تفحَّص الشيفرة التالية التي تشرح ذلك عمليًّا.

إن أعطي المعامل message، فسيضاف محتواه إلى الخطأ AssertionError إن فشل المعامل block برمي خطأٍ.

استعمال كائن صالح مخصَّص ونسخةٌ من الكائن Error مع المعامل error:

const err = new TypeError('Wrong value');
err.code = 404;
err.foo = 'bar';
err.info = {
  nested: true,
  baz: 'text'
};
err.reg = /abc/i;

assert.throws(
  () => {
    throw err;
  },
  {
    name: 'TypeError',
    message: 'Wrong value',
    info: {
      nested: true,
      baz: 'text'
    }
    // .انتبه إلى أن خاصِّيَّات الكائن الصالح هي التي سيتحقَّق منها فقط
    // يتطلب استعمال كائنات متشعبة أن تكون جميع الخاصِّيَّات موجودة. خلا
    // .ذلك، ستفشل عملية التأكد
  }
);


// :error استعمال التعابير النمطية للتأكد من خاصِّيَّات الكائن 
assert.throws(
  () => {
    throw err;
  },
  {
    // هما سلسلتان نصيتان وسيطابق استعمال التعابير `name` والخاصِّيَّة `message` الخاصِّيَّة
    // .النمطية معهما السلسلة النصية. إن فشلا، فسيرمى خطأ
    name: /^TypeError$/,
    message: /Wrong/,
    foo: 'bar',
    info: {
      nested: true,
      // ليس بالإمكان استعمال التعابير النمطية من أجل الخاصِّيَّات المتشعبة
      baz: 'text'
    },
    // على تعبير نمطي وسيُمرَّر الكائن الصالح إن احتوى تعبيرًا `reg` تحتوي الخاصِّيَّة
    // نمطيًّا مماثلًا فقط
    reg: /abc/i
  }
);

// `message` والخاصِّيَّة `name` سيفشل التأكد التالي بسبب  اختلاف الخاصِّيَّة
assert.throws(
  () => {
    const otherErr = new Error('Not found');
    otherErr.code = 404;
    throw otherErr;
  },
  err // `message` و `name` و `code` هذا التأكد من أجل الخاصِّيَّات
);

التأكد من رسالة الخطأ باستعمال الكائن RegExp (ينفَّذ استعمال التعبير النمطي ‎.toString على الكائن error وسيتضمَّن بالتالي اسم الخطأ):

assert.throws(
  () => {
    throw new Error('Wrong value');
  },
  Error
);

التأكد من رسالة الخطأ باستعمال الكائن RegExp (ينفَّذ استعمال التعبير النمطي ‎.toString على الكائن error وسيتضمَّن بالتالي اسم الخطأ):

assert.throws(
  () => {
    throw new Error('Wrong value');
  },
  /^Error: Wrong value$/
);

التأكد من كائن error مخصص:

assert.throws(
  () => {
    throw new Error('Wrong value');
  },
  function(err) {
    if ((err instanceof Error) && /value/.test(err)) {
      return true;
    }
  },
  'unexpected error'
);

انتبه إلى أنَّه لا يمكن أن يكون المعامل error سلسلةً نصيةً. إن مُرَّرت سلسلة نصية كمعامل ثانٍ إلى الدالة assert.throws()‎، فسيُفترض أنَّ المعامل error لم يعطَ وستمثِّل هذه السلسلة قيمة المعامل message. هذا الأمر قد يؤدي إلى حدوث لَبسٍ في المعاملات. سيؤدي استعمال الرسالة نفسها كرسالة الخطأ المرمي إلى ظهورها في الخطأ ERR_AMBIGUOUS_ARGUMENT. اقرأ رجاءً المثال التالي بتمعُّن إن أردت استعمال سلسلة نصية كمعامل ثانٍ:

function throwingFirst() {
  throw new Error('First');
}
function throwingSecond() {
  throw new Error('Second');
}
function notThrowing() {}

//.الوسيط الثاني هو سلسلة نصية، وترمي مدخلات الدالة خطأً
// لن يُرمَى في الحال الأولى خطأ بسبب عدم تطابقه مع رسالة الخطأ 
// .التي رمتها مدخلات الدالة
assert.throws(throwingFirst, 'Second');

// في المثال التالي، لا يستفاد من الرسالة عبر رسالة الخطأ. ولما لم
// ،يكن من الواضح إن كان المستخدم ينوي مطابقة رسالة الخطأ
// `ERR_AMBIGUOUS_ARGUMENT` الخطأ Node.js فسترمي
assert.throws(throwingSecond, 'Second');
// :يُرمَى الخطأ
// TypeError [ERR_AMBIGUOUS_ARGUMENT]

// تستعمل هذه السلسلة النصية (كرسالة) فقط في حال عدم رمي الدالة خطأً
assert.throws(notThrowing, 'Second');
// AssertionError [ERR_ASSERTION]: Missing expected exception: Second

// :إن كنت تنوي مطابقة رسالة الخطأ، فافعل ما يلي
assert.throws(throwingSecond, /Second$/);
// لن يرمى خطأٌ بسبب تطابق رسالتي الخطأ

assert.throws(throwingFirst, /Second$/);
// :في هذه الحالة، سيرمى الخطأ التالي
// Error: First
//     at throwingFirst (repl:2:9)

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

مصادر

مجلوبة من "https://wiki.hsoub.com/index.php?title=Node.js/assert&oldid=20924"