アサーションAPI • JavaScript impatient programmers向け (ES2022版)

9 アサーションAPI

9.1 ソフトウェア開発におけるアサーション

ソフトウェア開発では、*アサーション*は、値またはコードの一部について真でなければならない事実を表明します。真でない場合、例外がスローされます。 Node.jsは、組み込みモジュール assert を介してアサーションをサポートしています。例えば

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

このアサーションは、3足す5の期待される結果が8であることを表明しています。 import文は、推奨される strict バージョンの assert を使用しています。

9.2 本書におけるアサーションの使用方法

本書では、アサーションは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 通常の比較とディープ比較

strict equal() は、値の比較に === を使用します。したがって、オブジェクトは、別のオブジェクトが同じ内容を持っている場合でも、それ自体と等しいだけです (=== はオブジェクトの内容ではなく、IDのみを比較するため)。

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
}
```

クイズ

クイズアプリを参照してください。