@dmail/assert

assert

Compare two values with extreme accuracy. If values differ, an error is thrown with a readable message.

Introduction

assert is what I use all the time to write unit tests.
This function helps me to know if the actual value produced in a test matches what is expected.

As a result, the function signature looks like this:

assert({ actual, expected })

assert does nothing when actual and expected comparison is successfull.
assert throw an error if actual and expected comparison is failing.

assert comparison

actual and expected can be different objects but they must deeply look alike in every aspects possible in JavaScript.

To better understand if comparison will fail or not let's see some successfull comparison first and some failing comparisons afterwards.

Successfull comparison examples

import { assert } from "@dmail/assert"

// dates
{
  const actual = new Date()
  const expected = new Date()

  assert({ actual, expected })
}

// errors
{
  const actual = new Error("message")
  const expected = new Error("message")

  assert({ actual, expected })
}

// objects without prototype
{
  const actual = Object.create(null)
  const expected = Object.create(null)

  assert({ actual, expected })
}

// regexps
{
  const actual = /ok/
  const expected = /ok/

  assert({ actual, expected })
}

Failing comparison examples

Various code examples where comparison between actual and expected is failing.
Each code example is followed with the console output.

Failing on value

Code

import { assert } from "@dmail/assert"

const actual = 10
const expected = "10"

try {
  assert({ actual, expected })
} catch (e) {
  console.log(e.message)
}

Console output

AssertionError: unequal values.
--- found ---
10
--- expected ---
"10"
--- at ---
value

Failing on prototype

Code

import { assert } from "@dmail/assert"

const actual = new TypeError()
const expected = new Error()

try {
  assert({ actual, expected })
} catch (e) {
  console.log(e.message)
}

Console output

AssertionError: unequal prototypes.
--- prototype found ---
global.TypeError.prototype
--- prototype expected ---
global.Error.prototype
--- at ---
value[[Prototype]]

Failing on property value

Code

import { assert } from "@dmail/assert"

const actual = { foo: true }
const expected = { foo: false }

try {
  assert({ actual, expected })
} catch (e) {
  console.log(e.message)
}

Console output

AssertionError: unequal values.
--- found ---
true
--- expected ---
false
--- at ---
value.foo

Failing on properties order

Code

import { assert } from "@dmail/assert"

const actual = { foo: true, bar: true }
const expected = { bar: true, foo: true }

try {
  assert({ actual, expected })
} catch (e) {
  console.log(e.message)
}

Console output

AssertionError: unexpected properties order.
--- properties order found ---
"foo"
"bar"
--- properties order expected ---
"bar"
"foo"
--- at ---
value

Failing on property configurability

Code

import { assert } from "@dmail/assert"

const actual = Object.defineProperty({}, "answer", { value: 42 })
const expected = { answer: 42 }

try {
  assert({ actual, expected })
} catch (e) {
  console.log(e.message)
}

Console output

AssertionError: unequal values.
--- found ---
"non-configurable"
--- expected ---
"configurable"
--- at ---
value.answer[[Configurable]]

Why assert is so strict ?

As stated, assert is very strict on actual / expected comparison.
In fact, you cannot be more strict except by using ===.

It is like that because unit test are testing your public interface.
And any subtle change in that interface might break things using it.

In scenarios where you don't fully control what you're testing you can provide a subset of what you want to test.

Let's illustrate this with an example:

• you want to test a function called whatever
• you want to ensure it returns an object with answer: 42
• you don't want to ensure returned object contains only answer: 42

import { assert } from "@dmail/assert"
import { whatever } from "./whatever.js"

const { answer } = whatever()
const actual = { answer }
const expected = { answer: 42 }

assert({ actual, expected })

How to use

npm install --save-dev @dmail/assert

You can refer on browser example and node example below to go further.

browser example

<script src="https://unpkg.com/@dmail/assert@latest/dist/global/main.js"></script>

<script>
  const { assert } = window.__dmail_assert__
  assert({
    actual: { foo: false },
    expected: { foo: true },
  })
</script>

Screnshot below is a part of console content after executing above code inside chrome.

node.js example

const { assert } = require("@dmail/assert")

assert({
  actual: { foo: false },
  expected: { foo: true },
})

Screnshot below is a part of terminal output after executing above code inside node.js.

Interactive browser example

— see https://dmail.github.io/assert/browser-interactive-example/browser-interactive-example.html.

Interactive node example

— see https://dmail.github.io/assert/node-interactive-example/node-interactive-example.html