assert

The assert package provides runtime assertion utilities that work in any JavaScript runtime. The API is compatible with Node.js node:assert so you can use the same assertions in Node.js, Deno, Bun, Cloudflare Workers, and browsers.

Installation

The assert package is included with Remix. No additional installation is needed.

Import

import {
  assert,
  ok,
  equal,
  notEqual,
  deepEqual,
  notDeepEqual,
  strictEqual,
  notStrictEqual,
  throws,
  doesNotThrow,
  rejects,
  doesNotReject,
  match,
  doesNotMatch,
  fail,
  AssertionError,
} from 'remix/assert'

API

assert(value, message?)

Asserts that value is truthy. Throws AssertionError if it is not.

assert(user != null, 'User must exist')
assert(items.length > 0, 'Expected at least one item')

ok(value, message?)

Alias for assert. Asserts that value is truthy.

ok(response.ok, 'Expected a successful response')

equal(actual, expected, message?)

Asserts loose equality using ==.

equal(result, 42)

notEqual(actual, expected, message?)

Asserts loose inequality using !=.

notEqual(status, 'error')

strictEqual(actual, expected, message?)

Asserts strict equality using ===.

strictEqual(typeof value, 'string')
strictEqual(count, 0)

notStrictEqual(actual, expected, message?)

Asserts strict inequality using !==.

notStrictEqual(token, undefined)

deepEqual(actual, expected, message?)

Asserts deep equality by recursively comparing properties.

deepEqual(result, { name: 'Alice', age: 30 })
deepEqual(items, [1, 2, 3])

notDeepEqual(actual, expected, message?)

Asserts that two values are not deeply equal.

notDeepEqual(updated, original)

throws(fn, expected?, message?)

Asserts that fn throws an error. Optionally checks the error against expected (a RegExp, Error class, or validation function).

throws(() => {
  JSON.parse('invalid')
})

throws(
  () => { throw new TypeError('bad type') },
  TypeError,
)

throws(
  () => { throw new Error('not found') },
  /not found/,
)

doesNotThrow(fn, message?)

Asserts that fn does not throw an error.

doesNotThrow(() => {
  JSON.parse('{}')
})

rejects(asyncFn, expected?, message?)

Asserts that an async function or promise rejects.

await rejects(
  async () => { await fetchUser('invalid-id') },
  /not found/,
)

doesNotReject(asyncFn, message?)

Asserts that an async function or promise does not reject.

await doesNotReject(async () => {
  await fetchUser('valid-id')
})

match(string, regexp, message?)

Asserts that a string matches a regular expression.

match(email, /^[^@]+@[^@]+$/, 'Expected a valid email')

doesNotMatch(string, regexp, message?)

Asserts that a string does not match a regular expression.

doesNotMatch(password, /^\s*$/, 'Password must not be blank')

fail(message?)

Always throws an AssertionError. Useful for marking code paths that should be unreachable.

switch (status) {
  case 'active': return handleActive()
  case 'inactive': return handleInactive()
  default: fail(`Unexpected status: ${status}`)
}

AssertionError

The error class thrown by all assertion functions. Extends Error with actual, expected, and operator properties.

try {
  strictEqual(1, 2)
} catch (error) {
  if (error instanceof AssertionError) {
    console.log(error.actual)   // 1
    console.log(error.expected) // 2
    console.log(error.operator) // 'strictEqual'
  }
}

Examples

Route Handler Guards

import { assert } from 'remix/assert'

router.map(userRoute, async ({ params }) => {
  let user = await db.users.find(params.id)
  assert(user != null, 'User not found')

  return Response.json(user)
})

Validating Configuration

import { ok, strictEqual } from 'remix/assert'

ok(process.env.DATABASE_URL, 'DATABASE_URL is required')
strictEqual(typeof port, 'number', 'Port must be a number')

Testing

The assert functions integrate naturally with the test package:

import { describe, it } from 'remix/test'
import { strictEqual, deepEqual } from 'remix/assert'

describe('math', () => {
  it('adds numbers', () => {
    strictEqual(1 + 1, 2)
  })

  it('returns an array', () => {
    deepEqual(range(3), [0, 1, 2])
  })
})

Related

• test --- The Remix test runner with built-in assertions.