9 斷言 API

9.1 軟體開發中的斷言

在軟體開發中，斷言陳述值或程式碼區塊必須為真的事實。若否，則會擲回例外。Node.js 透過內建模組 assert 支援斷言，例如

import * as assert from 'assert/strict';
assert.equal(3 + 5, 8);

此斷言陳述 3 加 5 的預期結果為 8。import 陳述式使用assert 的建議 strict 版本。

9.2 本書如何使用斷言

在本書中，斷言有兩種用法：記錄程式碼範例中的結果，以及實作測試驅動練習。

9.2.1 透過斷言在程式碼範例中記錄結果

在程式碼範例中，斷言表達預期的結果。以以下函式為例

function id(x) {
  return x;
}

id() 傳回其參數。我們可以使用斷言顯示其作用

assert.equal(id('abc'), 'abc');

在範例中，我通常會省略匯入 assert 的陳述式。

使用斷言的動機是

• 您可以精確地指定預期結果。
• 程式碼範例可以自動測試，這可以確保它們確實有效。

9.2.2 透過斷言實作測試驅動練習

本書的練習是測試驅動的，透過測試架構 Mocha。測試中的檢查是透過 assert 的方法進行。

以下是一個此類測試的範例

// For the exercise, you must implement the function hello().
// The test checks if you have done it properly.
test('First exercise', () => {
  assert.equal(hello('world'), 'Hello world!');
  assert.equal(hello('Jane'), 'Hello Jane!');
  assert.equal(hello('John'), 'Hello John!');
  assert.equal(hello(''), 'Hello !');
});

有關更多資訊，請參閱 §10「開始使用測驗和練習」。

9.3 一般比較與深度比較

嚴格的 equal() 使用 === 來比較值。因此，一個物件只會等於它自己，即使另一個物件具有相同的內容（因為 === 僅比較物件的身分，而不比較其內容）。

assert.notEqual({foo: 1}, {foo: 1});

deepEqual() 是用來比較物件的較佳選擇。

assert.deepEqual({foo: 1}, {foo: 1});

此方法也適用於陣列。

assert.notEqual(['a', 'b', 'c'], ['a', 'b', 'c']);
assert.deepEqual(['a', 'b', 'c'], ['a', 'b', 'c']);

9.4 快速參考：assert 模組

有關完整文件，請參閱 Node.js 文件。

9.4.1 一般等號

• function equal(actual: any, expected: any, message?: string): void

  actual === expected 必須為 true。如果不是，則會擲回 AssertionError。

  assert.equal(3+3, 6);

• function notEqual(actual: any, expected: any, message?: string): void

  actual !== expected 必須為 true。如果不是，則會擲回 AssertionError。

  assert.notEqual(3+3, 22);

最後一個選用參數 message 可用來解釋所聲明的內容。如果聲明失敗，訊息會用來設定擲回的 AssertionError。

let e;
try {
  const x = 3;
  assert.equal(x, 8, 'x must be equal to 8')
} catch (err) {
  assert.equal(
    String(err),
    'AssertionError [ERR_ASSERTION]: x must be equal to 8');
}

9.4.2 深度等號

• function deepEqual(actual: any, expected: any, message?: string): void

  actual 必須與 expected 深度相等。如果不是，則會擲回 AssertionError。

  assert.deepEqual([1,2,3], [1,2,3]);
  assert.deepEqual([], []);
  
  // To .equal(), an object is only equal to itself:
  assert.notEqual([], []);

• function notDeepEqual(actual: any, expected: any, message?: string): void

  actual 必須與 expected 深度不相等。如果是，則會擲回 AssertionError。

  assert.notDeepEqual([1,2,3], [1,2]);

9.4.3 預期例外

如果您想要（或預期）收到例外，則需要 throws()：此函式會呼叫其第一個參數，函式 block，並且只有在擲回例外時才會成功。其他參數可用來指定此例外必須是什麼樣子。

• function throws(block: Function, message?: string): void

  assert.throws(
    () => {
      null.prop;
    }
  );

• function throws(block: Function, error: Function, message?: string): void

  assert.throws(
    () => {
      null.prop;
    },
    TypeError
  );

• function throws(block: Function, error: RegExp, message?: string): void

  assert.throws(
    () => {
      null.prop;
    },
    /^TypeError: Cannot read properties of null \(reading 'prop'\)$/
  );

• function throws(block: Function, error: Object, message?: string): void

  assert.throws(
    () => {
      null.prop;
    },
    {
      name: 'TypeError',
      message: "Cannot read properties of null (reading 'prop')",
    }
  );

9.4.4 另一個工具函式

• function fail(message: string | Error): never

  呼叫時，總是會擲回 AssertionError。這偶爾會對單元測試有用。

  try {
    functionThatShouldThrow();
    assert.fail();
  } catch (_) {
    // Success
  }