@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 a failure.

assert comparison

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

Success examples

const actual = new Error("message")
const expected = new Error("message")

const actual = Object.create(null)
const expected = Object.create(null)

const actual = new Date()
const expected = new Date()

const actual = /ok/
const expected = /ok/

Failure examples

• constructor failure

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

• type failure

const actual = 10
const expected = "10"

• primitive / object failure

const actual = new String("foo")
const expected = "foo"

• property value failure

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

• property order failure

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

• property description failure

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

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