assertron

A supplementary assertion library that runs on Node.js, Bun, Deno and the browser.

The shipped code imports no platform builtins, so the same esm/ and cjs/ output loads everywhere. CI runs a smoke test against the build output on Node, Bun and Deno on every pull request, so that claim is executed rather than asserted.

Install

# npm
npm install assertron

# yarn
yarn add assertron

# pnpm
pnpm install assertron

#rush
rush add -p assertron

Usage

assertron provides a collection of assertion methods:

• assertron.false(value): asserts the provided value is false.
• assertron.falsy(value): asserts the provided value is falsy.
• assertron.isInstanceof(value, ClassType): asserts value instanceof ClassType.
• assertron.pathEqual(actual, expected): asserts the two paths are equal regardless of operating system differences.
• assertron.rejects(promise): asserts the promise rejects.
• assertron.repeat(fn, times): repeat the specified function n times and return the last result.
  If the result is a promise, it will run the function sequentially.
• assertron.resolves(promise): asserts the promise resolves.
• assertron.satisfies(actual, expected): checks if actual meets the requirements specified by expected.
  Each property in expected can be a value, a RegExp, or a predicate function.
  It uses satisfier internally to check for validity.
  Check out satisfier for more detail.

import a from 'assertron' // assertron is also exported as default.

// these passes
a.satisfies({ a: 1, b: 2 }, { a: 1 })
a.satisfies({ a: 'foo', b: 'boo' }, { a: /foo/ })
a.satisfies({ a: 1, b, 2 }, { a: n => n === 1 })

// these fails
a.satisfies({ a: 1 }, { a: 2 })
a.satisfies({ a: 1 }, { a: 1, b: 2 })
a.satisfies({ a: 'foo' }, { a: /boo/ })
a.satisfies({ a: 1 }, { a: () => false })

• assertron.throws(...): asserts the promise, function, or async function throws (or rejects) an error.

import { assertron } from 'assertron'

await assertron.throws(Promise.reject(new Error('foo')))
assertron.throws(() => { throw new Error('foo') })
await assertron.throws(() => Promise.reject(new Error('foo')))

const e1 = await assertron.throws(Promise.reject(new SpecificError('foo')), SpecificError)
const e2 = assertron.throws(() => { throw new SpecificError('foo') }, SpecificError)
const e3 = await assertron.throws(() => Promise.reject(new SpecificError('foo')), SpecificError)

• assertron.true(value): asserts the provided value is true.
• assertron.truthy(value): asserts the provided value is truthy.

AssertOrder

Assert the code is executed in the expected order.

• order.once(step: number): asserts the step step executed once.

import { AssertOrder } from 'assertron'

const o = new AssertOrder()
function foo() {
  o.once(1)
}

foo()
foo() // throws

import { AssertOrder } from 'assertron'

const o = new AssertOrder()
function foo() {
  o.once(1)
}

function boo() {
  o.once(2)
}

foo()
boo()

• order.atLeastOnce(step: number): assert the step executed at least once.

import { AssertOrder } from 'assertron'

const o = new AssertOrder()

for (let i = 0; i < 10; i++)
  o.atLeastOnce(1)


o.once(2)

• order.exactly(step: number, times: number): asserts the step step executed exactly n times

import { AssertOrder } from 'assertron'

const o = new AssertOrder()

for (let i = 0; i < 4; i++)
  o.exactly(1, 3) // throws at i === 3

• order.any(steps: number[], handler?: (step: number) => void): asserts any of the steps steps executed.

import { AssertOrder } from 'assertron'

const o = new AssertOrder()

for (let i = 1; i <= 4; i++) {
  if (i % 2)
    o.any([1, 3])
  else
    o.any([2, 4])
}

There are other methods available. Use TypeScript to discover them!

Contribute

yarn

# start making changes
git checkout -b <branch>
yarn watch

# after making change(s)
git commit -m "<commit message>"
git push

# create PR

NPM Commands

There are a few useful commands you can use during development.

yarn test

yarn watch

yarn verify