assert

Псевдоним для ok.

Режим строгих утверждений

Псевдоним для deepStrictEqual.

Устаревший режим утверждений

Стабильность: 3 — устаревший API: используйте вместо него deepStrictEqual.

Проверяет глубокое равенство параметров actual и expected. Рекомендуется использовать вместо него deepStrictEqual. deepEqual может приводить к неожиданным результатам.

Глубокое равенство означает, что перечисляемые собственные свойства дочерних объектов также рекурсивно проверяются по следующим правилам.

Проверяет глубокое равенство параметров actual и expected. «Глубокое» равенство означает, что перечисляемые собственные свойства дочерних объектов также рекурсивно проверяются по следующим правилам.

Ожидает, что входное значение string не будет соответствовать регулярному выражению.

import assert from 'node:assert/strict';

assert.doesNotMatch('I will fail', /fail/);
// AssertionError [ERR_ASSERTION]: The input was expected to not match the ...

assert.doesNotMatch(123, /pass/);
// AssertionError [ERR_ASSERTION]: The "string" argument must be of type string.

assert.doesNotMatch('I will pass', /different/);
// OK

Если значения совпадают или аргумент string имеет тип, отличный от string, выбрасывается [AssertionError](/api/node/assert/#assert со свойством message, равным значению параметра message. Если параметр message не определён, назначается сообщение об ошибке по умолчанию. Если параметр message является экземпляром Error, он будет выброшен вместо [AssertionError](/api/node/assert/#assert.

Ожидает завершения промиса asyncFn или, если asyncFn является функцией, немедленно вызывает эту функцию и ожидает завершения возвращённого промиса. Затем проверяет, что промис не был отклонён.

Если asyncFn является функцией и синхронно выбрасывает ошибку, assert.doesNotReject() вернёт отклонённый Promise с этой ошибкой. Если функция не возвращает промис, assert.doesNotReject() вернёт отклонённый Promise с ошибкой ERR_INVALID_RETURN_VALUE. В обоих случаях обработчик ошибок пропускается.

Использование assert.doesNotReject() на самом деле бесполезно, поскольку мало смысла перехватывать отклонение, а затем снова отклонять промис. Вместо этого можно добавить комментарий рядом с конкретным участком кода, который не должен приводить к отклонению, и сделать сообщения об ошибках максимально информативными.

Если указан, параметр error может быть Class, RegExp или функцией проверки. Подробнее см. в описании throws.

Помимо асинхронного ожидания завершения, функция ведёт себя так же, как doesNotThrow.

import assert from 'node:assert/strict';

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

import assert from 'node:assert/strict';

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

Проверяет, что функция fn не выбрасывает ошибку.

Использование assert.doesNotThrow() на самом деле бесполезно, поскольку нет смысла перехватывать ошибку, а затем выбрасывать её снова. Вместо этого можно добавить комментарий рядом с конкретным участком кода, который не должен приводить к выбросу ошибки, и сделать сообщения об ошибках максимально информативными.

При вызове assert.doesNotThrow() функция fn вызывается немедленно.

Если выброшенная ошибка имеет тот же тип, что указан в параметре error, выбрасывается AssertionError. Если ошибка имеет другой тип или параметр error не определён, ошибка передаётся вызывающему коду.

Если указан, параметр error может быть Class, RegExp или функцией проверки. Подробнее см. в описании throws.

Например, следующий код выбросит TypeError, поскольку в утверждении не указан соответствующий тип ошибки:

import assert from 'node:assert/strict';

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

Однако следующий код приведёт к AssertionError с сообщением «Got unwanted exception...»:

import assert from 'node:assert/strict';

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

Если выбрасывается AssertionError и для параметра message указано значение, значение message будет добавлено к сообщению AssertionError:

import assert from 'node:assert/strict';

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

Режим строгих утверждений

Псевдоним strictEqual.

Режим устаревших утверждений

Стабильность: 3 — устаревший API. Вместо него используйте strictEqual.

Проверяет поверхностное равенство с приведением типов между параметрами actual и expected с помощью оператора ==. Значение NaN обрабатывается особым образом и считается идентичным, если обе стороны равны NaN.

import assert from 'node:assert';

assert.equal(1, 1);
// OK, 1 == 1
assert.equal(1, '1');
// OK, 1 == '1'
assert.equal(NaN, NaN);
// OK

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 не определён, назначается сообщение об ошибке по умолчанию. Если параметр message является экземпляром Error, он будет выброшен вместо AssertionError.

Выбрасывает AssertionError с переданным сообщением об ошибке или сообщением об ошибке по умолчанию. Если параметр message является экземпляром Error, он будет выброшен вместо AssertionError.

import assert from 'node: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() с более чем двумя аргументами можно, но такой способ устарел. Подробнее см. ниже.

Выбрасывает value, если value не равно undefined или null. Это удобно при проверке аргумента error в обратных вызовах. Трассировка стека содержит все кадры из ошибки, переданной в ifError(), включая возможные новые кадры самой функции ifError().

import assert from 'node: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

// Create some random error frames.
let err;
(function errorFrame() {
  err = new Error('test error');
})();

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

Ожидает, что входное значение string будет соответствовать регулярному выражению.

import assert from 'node:assert/strict';

assert.match('I will fail', /pass/);
// AssertionError [ERR_ASSERTION]: The input did not match the regular ...

assert.match(123, /pass/);
// AssertionError [ERR_ASSERTION]: The "string" argument must be of type string.

assert.match('I will pass', /pass/);
// OK

Если значения не совпадают или аргумент string имеет тип, отличный от string, выбрасывается [AssertionError](/api/node/assert/#assert со свойством message, равным значению параметра message. Если параметр message не определён, назначается сообщение об ошибке по умолчанию. Если параметр message является экземпляром Error, он будет выброшен вместо [AssertionError](/api/node/assert/#assert.

Режим строгих утверждений

Псевдоним notDeepStrictEqual.

Режим устаревших утверждений

Стабильность: 3 — устаревший API. Вместо него используйте notDeepStrictEqual.

Проверяет наличие любого глубокого неравенства. Противоположность deepEqual.

import assert from 'node:assert';

const obj1 = {
  a: {
    b: 1,
  },
};
const obj2 = {
  a: {
    b: 2,
  },
};
const obj3 = {
  a: {
    b: 1,
  },
};
const obj4 = { __proto__: 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 не определён, назначается сообщение об ошибке по умолчанию. Если параметр message является экземпляром Error, он будет выброшен вместо AssertionError.

Проверяет строгое глубокое неравенство. Противоположность deepStrictEqual.

import assert from 'node:assert/strict';

assert.notDeepStrictEqual({ a: 1 }, { a: '1' });
// OK

Если значения глубоко и строго равны, выбрасывается AssertionError со свойством message, равным значению параметра message. Если параметр message не определён, назначается сообщение об ошибке по умолчанию. Если параметр message является экземпляром Error, он будет выброшен вместо AssertionError.

Строгий режим утверждений

Псевдоним notStrictEqual.

Устаревший режим утверждений

Стабильность: 3 — устаревшее: вместо этого используйте notStrictEqual.

Проверяет неглубокое неравенство с приведением типов с помощью оператора !=. NaN обрабатывается особым образом и считается идентичным, если обе стороны — NaN.

import assert from 'node:assert';

assert.notEqual(1, 2);
// OK

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

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

Если значения равны, выбрасывается AssertionError со свойством message, равным значению параметра message. Если параметр message не определён, назначается сообщение об ошибке по умолчанию. Если параметр message является экземпляром Error, вместо AssertionError будет выброшен он.

Проверяет строгое неравенство параметров actual и expected, определяемое с помощью Object.is().

import assert from 'node:assert/strict';

assert.notStrictEqual(1, 2);
// OK

assert.notStrictEqual(1, 1);
// AssertionError [ERR_ASSERTION]: Expected "actual" to be strictly unequal to:
//
// 1

assert.notStrictEqual(1, '1');
// OK

Если значения строго равны, выбрасывается AssertionError со свойством message, равным значению параметра message. Если параметр message не определён, назначается сообщение об ошибке по умолчанию. Если параметр message является экземпляром Error, вместо AssertionError будет выброшен он.

Проверяет, является ли value истинным. Эквивалентно assert.equal(!!value, true, message).

Если value не является истинным, выбрасывается AssertionError со свойством message, равным значению параметра message. Если параметр message равен undefined, назначается сообщение об ошибке по умолчанию. Если параметр message является экземпляром Error, вместо AssertionError будет выброшен он. Если аргументы не переданы, message будет присвоена строка:'No value argument passed to `assert.ok()`'.

Обратите внимание: в repl сообщение об ошибке будет отличаться от сообщения, выбрасываемого в файле! Подробнее см. ниже.

import assert from 'node:assert/strict';

assert.ok(true);
// OK
assert.ok(1);
// OK

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

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

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

// In a file (e.g. 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)

import assert from 'node:assert/strict';

// Using `assert()` works the same:
assert(0);
// AssertionError: The expression evaluated to a falsy value:
//
//   assert(0)

assert.partialDeepStrictEqual() Проверяет эквивалентность параметров actual и expected посредством глубокого сравнения, гарантируя, что все свойства параметра expected присутствуют в параметре actual с эквивалентными значениями, без приведения типов. Главное отличие от assert.deepStrictEqual() состоит в том, что assert.partialDeepStrictEqual() не требует наличия всех свойств параметра actual в параметре expected. Этот метод должен всегда проходить те же тестовые случаи, что и assert.deepStrictEqual(), являясь его надмножеством.

import assert from 'node:assert';

assert.partialDeepStrictEqual({ a: 1, b: 2 }, { a: 1, b: 2 });
// OK

assert.partialDeepStrictEqual({ a: { b: { c: 1 } } }, { a: { b: { c: 1 } } });
// OK

assert.partialDeepStrictEqual({ a: 1, b: 2, c: 3 }, { a: 1, b: 2 });
// OK

assert.partialDeepStrictEqual(new Set(['value1', 'value2']), new Set(['value1', 'value2']));
// OK

assert.partialDeepStrictEqual(new Map([['key1', 'value1']]), new Map([['key1', 'value1']]));
// OK

assert.partialDeepStrictEqual(new Uint8Array([1, 2, 3]), new Uint8Array([1, 2, 3]));
// OK

assert.partialDeepStrictEqual(/abc/, /abc/);
// OK

assert.partialDeepStrictEqual([{ a: 5 }, { b: 5 }], [{ a: 5 }]);
// OK

assert.partialDeepStrictEqual(new Set([{ a: 1 }, { b: 1 }]), new Set([{ a: 1 }]));
// OK

assert.partialDeepStrictEqual(new Date(0), new Date(0));
// OK

assert.partialDeepStrictEqual({ a: 1 }, { a: 1, b: 2 });
// AssertionError

assert.partialDeepStrictEqual({ a: 1, b: '2' }, { a: 1, b: 2 });
// AssertionError

assert.partialDeepStrictEqual({ a: { b: 2 } }, { a: { b: '2' } });
// AssertionError

Ожидает выполнения промиса asyncFn или, если asyncFn — функция, немедленно вызывает эту функцию и ожидает завершения возвращённого промиса. Затем проверяет, что промис отклонён.

Если asyncFn — функция и она синхронно выбрасывает ошибку, assert.rejects() вернёт отклонённый Promise с этой ошибкой. Если функция не возвращает промис, assert.rejects() вернёт отклонённый Promise с ошибкой ERR_INVALID_RETURN_VALUE. В обоих случаях обработчик ошибки пропускается.

Помимо асинхронного ожидания завершения, ведёт себя так же, как throws.

Если указан параметр error, он может быть Class, RegExp, функцией проверки, объектом, для которого проверяется каждое свойство, или экземпляром ошибки, для которого проверяется каждое свойство, включая неперечисляемые свойства message и name.

Если указан параметр message, он будет сообщением, предоставленным [AssertionError](/api/node/assert/#assert, если asyncFn не отклонит промис.

import assert from 'node:assert/strict';

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

import assert from 'node:assert/strict';

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

import assert from 'node:assert/strict';

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

error не может быть строкой. Если в качестве второго аргумента передана строка, считается, что error опущен, а строка будет использоваться вместо message. Это может привести к легко пропускаемым ошибкам. Если рассматриваете возможность использовать строку в качестве второго аргумента, внимательно прочитайте пример в throws.

Проверяет строгое равенство параметров actual и expected, определяемое с помощью Object.is().

import assert from 'node:assert/strict';

assert.strictEqual(1, 2);
// AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal:
//
// 1 !== 2

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

assert.strictEqual('Hello foobar', 'Hello World!');
// AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal:
// + actual - expected
//
// + 'Hello foobar'
// - 'Hello World!'
//          ^

const apples = 1;
const oranges = 2;
assert.strictEqual(apples, oranges, `apples ${apples} !== oranges ${oranges}`);
// AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2

assert.strictEqual(1, '1', new TypeError('Inputs are not identical'));
// TypeError: Inputs are not identical

Если значения не равны строго, выбрасывается AssertionError со свойством message, равным значению параметра message. Если параметр message не определён, назначается сообщение об ошибке по умолчанию. Если параметр message является экземпляром Error, вместо AssertionError будет выброшен он.

Ожидает, что функция fn выбросит ошибку.

Если указан параметр error, он может быть Class, RegExp, функцией проверки, объектом проверки, для которого проверяется строгое глубокое равенство каждого свойства, или экземпляром ошибки, для которого проверяется строгое глубокое равенство каждого свойства, включая неперечисляемые свойства message и name. При использовании объекта для проверки строкового свойства можно также использовать регулярное выражение. Примеры см. ниже.

Если указан параметр message, он будет добавлен к сообщению, предоставленному AssertionError, если вызов fn не выбросит ошибку или проверка ошибки завершится неудачей.

Пользовательский объект проверки/экземпляр ошибки:

import assert from 'node:assert/strict';

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',
    },
    // Only properties on the validation object will be tested for.
    // Using nested objects requires all properties to be present. Otherwise
    // the validation is going to fail.
  },
);

// Using regular expressions to validate error properties:
assert.throws(
  () => {
    throw err;
  },
  {
    // The `name` and `message` properties are strings and using regular
    // expressions on those will match against the string. If they fail, an
    // error is thrown.
    name: /^TypeError$/,
    message: /Wrong/,
    foo: 'bar',
    info: {
      nested: true,
      // It is not possible to use regular expressions for nested properties!
      baz: 'text',
    },
    // The `reg` property contains a regular expression and only if the
    // validation object contains an identical regular expression, it is going
    // to pass.
    reg: /abc/i,
  },
);

// Fails due to the different `message` and `name` properties:
assert.throws(
  () => {
    const otherErr = new Error('Not found');
    // Copy all enumerable properties from `err` to `otherErr`.
    for (const [key, value] of Object.entries(err)) {
      otherErr[key] = value;
    }
    throw otherErr;
  },
  // The error's `message` and `name` properties will also be checked when using
  // an error as validation object.
  err,
);

Проверка instanceof с помощью конструктора:

import assert from 'node:assert/strict';

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

Проверка сообщения об ошибке с помощью RegExp:

При использовании регулярного выражения для объекта ошибки выполняется .toString, поэтому оно также включает имя ошибки.

import assert from 'node:assert/strict';

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

Пользовательская проверка ошибки:

Функция должна возвращать true, чтобы указать, что все внутренние проверки пройдены. В противном случае проверка завершится ошибкой AssertionError.

import assert from 'node:assert/strict';

assert.throws(
  () => {
    throw new Error('Wrong value');
  },
  (err) => {
    assert(err instanceof Error);
    assert(/value/.test(err));
    // Avoid returning anything from validation functions besides `true`.
    // Otherwise, it's not clear what part of the validation failed. Instead,
    // throw an error about the specific validation that failed (as done in this
    // example) and add as much helpful debugging information to that error as
    // possible.
    return true;
  },
  'unexpected error',
);

error не может быть строкой. Если в качестве второго аргумента передана строка, считается, что error опущен, а строка будет использоваться вместо message. Это может привести к легко пропускаемым ошибкам. Использование того же сообщения, что и у выброшенной ошибки, приведёт к ошибке ERR_AMBIGUOUS_ARGUMENT. Если рассматриваете возможность использовать строку в качестве второго аргумента, внимательно прочитайте пример ниже:

import assert from 'node:assert/strict';

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

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

function notThrowing() {}

// The second argument is a string and the input function threw an Error.
// The first case will not throw as it does not match for the error message
// thrown by the input function!
assert.throws(throwingFirst, 'Second');
// In the next example the message has no benefit over the message from the
// error and since it is not clear if the user intended to actually match
// against the error message, Node.js throws an `ERR_AMBIGUOUS_ARGUMENT` error.
assert.throws(throwingSecond, 'Second');
// TypeError [ERR_AMBIGUOUS_ARGUMENT]

// The string is only used (as message) in case the function does not throw:
assert.throws(notThrowing, 'Second');
// AssertionError [ERR_ASSERTION]: Missing expected exception: Second

// If it was intended to match for the error message do this instead:
// It does not throw because the error messages match.
assert.throws(throwingSecond, /Second$/);

// If the error message does not match, an AssertionError is thrown.
assert.throws(throwingFirst, /Second$/);
// AssertionError [ERR_ASSERTION]

Из-за неоднозначного и подверженного ошибкам синтаксиса не используйте строку в качестве второго аргумента.