Standard Assertions (@std/assert)

Overview Jump to heading#

A library of assertion functions. If the assertion is false an AssertionError will be thrown which will result in pretty-printed diff of the failing assertion.

This module is browser compatible, but do not rely on good formatting of values for AssertionError messages in browsers.

import { assert } from "@std/assert";

assert("I am truthy"); // Doesn't throw
assert(false); // Throws `AssertionError`

Add to your project Jump to heading#

deno add jsr:@std/assert

See all symbols in @std/assert on

What is an assertion? Jump to heading#

An assertion is a check that must be true. If it isn’t, the program throws an AssertionError with a helpful message and diff so you can quickly spot what went wrong.

In tests, assertions verify behavior. In application code, they can document and guard invariants (preconditions/postconditions). In TypeScript, some assertions (like assert(condition)) also narrow types after the check.

When to use @std/assert? Jump to heading#

The utilities in this package make test failures clear and actionable ( allowing for pretty diffs and focused messages). Improve the readability of your tests by codifying expectations in-line.

Assertions help to prevent silent bugs by failing fast when assumptions are violated.

Use assertions liberally in your tests to verify behavior and catch regressions.

Examples Jump to heading#

import {
  assert,
  assertAlmostEquals,
  assertArrayIncludes,
  assertEquals,
  assertExists,
  assertFalse,
  assertMatch,
  assertNotEquals,
  assertObjectMatch,
  assertRejects,
  assertStrictEquals,
  assertThrows,
} from "@std/assert";

// Basic truthiness and type narrowing
const value: unknown = "hello";
assert(typeof value === "string", "Expected a string");
// value is now narrowed to string

// Deep structural equality (objects/arrays)
assertEquals({ a: 1, b: [1, 2] }, { a: 1, b: [1, 2] });
assertNotEquals([1, 2], [1, 2, 3]);

// Strict (reference/identity) equality for primitives/refs
assertStrictEquals(1, 1);
assertFalse(false);
assertExists("non-empty"); // not null or undefined

// Pattern & numeric comparisons
assertMatch("deno.land", /deno/);
assertAlmostEquals(0.1 + 0.2, 0.3, 1e-15);

// Collections
assertArrayIncludes([1, 2, 3], [2, 3]);
assertObjectMatch(
  { id: 42, name: "A", meta: { ok: true } },
  { name: "A", meta: { ok: true } }, // subset must match
);

// Errors: sync vs async
assertThrows(() => JSON.parse("not json"), SyntaxError);
await assertRejects(() => fetch("https://deno.land/404"));

Choosing the right equality Jump to heading#

Assertions for equality come in two main flavors:

assertEquals Jump to heading#

Compares values recursively by structure and content. For arrays, order matters; for plain objects, key order doesn’t. It’s best for comparing serialized-style data (objects, arrays, numbers, strings, booleans).

assertStrictEquals Jump to heading#

Checks that both operands are the exact same value (for primitives) or reference (for objects), using semantics similar to Object.is.

For example:
assertStrictEquals({ x: 1 }, { x: 1 }) fails (different references)
assertEquals({ x: 1 }, { x: 1 }) passes
assertStrictEquals(NaN, NaN) passes (like Object.is)

Examples Jump to heading#

// Deep vs strict
assertEquals({ a: 1 }, { a: 1 }); // ✅ same structure/content
// assertStrictEquals({ a: 1 }, { a: 1 });   // ❌ different references

const obj = { a: 1 };
assertStrictEquals(obj, obj); // ✅ same reference

// Arrays: order matters for equality
assertEquals([1, 2, 3], [1, 2, 3]); // ✅
// assertEquals([1, 2, 3], [3, 2, 1]);       // ❌ different order

// Numbers: floating point
// Prefer assertAlmostEquals for inexact math
// assertEquals(0.1 + 0.2, 0.3);             // ❌
assertAlmostEquals(0.1 + 0.2, 0.3, 1e-15); // ✅

• Use assertEquals for comparing data shapes and values; use assertStrictEquals when you care about reference identity or exact primitive equality.
• For partial object checks, reach for assertObjectMatch instead of asserting the entire object.
• When comparing large nested structures, assertEquals is comprehensive but more expensive—prefer strict or targeted checks when performance matters in hot test suites.

Writing good failure messages Jump to heading#

All assertions accept an optional message as the last argument. Write messages to help developers understand where the failure occured and how to fix it. Keep messages concise and user-focused:

assert(Array.isArray(items), "items must be an array");
assertEquals(result.status, 200, "API should return 200 OK");

Testing patterns Jump to heading#

Use with Deno.test:

Deno.test("adds numbers", () => {
  assertEquals(1 + 2, 3);
});

Deno.test("throws on invalid JSON", () => {
  assertThrows(() => JSON.parse("nope"), SyntaxError);
});

Deno.test("rejects for failed fetch", async () => {
  await assertRejects(() => fetch("https://deno.land/404"));
});

Tips Jump to heading#

• When doing floating point maths, use assertAlmostEquals, which has a tolerance for numeric comparisons.
• For partial object checks, use assertObjectMatch instead of asserting the entire shape.
• assert(condition) has an assertion signature in TS (asserts condition), which narrows types after the check.
• Prefer assertRejects for promises and assertThrows for sync code, don’t mix them.

See also Jump to heading#

• @std/expect offers a Jest-style BDD assertion API if you prefer fluent matchers.