assert

A powerful assertion library focused on providing clear, informative, and visual feedback for JavaScript tests.

equal() is my favorite assertion. If the only available assertion in every test suite was equal(), almost every test suite in the world would be better for it.

— Eric Elliot in Rethinking Unit Test Assertion

Simple Yet Powerful

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

assert({
  actual: {
    foo: true,
  },
  expect: {
    foo: false,
  },
});

There is 200+ examples in ./tests/

Features

Color-Coded Diffs

Error messages use colors with specific meanings to make differences clear:

| Color | Meaning | | ------ | --------------------------------------------- | | grey | same in actual and expect | | red | different from expect | | green | different from actual | | yellow | exists only in actual / exists only in expect |

JavaScript-Aware Comparisons

The library understands JavaScript types and provides meaningful differences:

assert({
  actual: 149600000,
  expect: 1464301,
});

Special handling extends to URLs, dates, HTTP headers, and more.

Beautiful Multiline String Diffs

assert({
  actual: {
    foo: `Hello,
my name is Benjamin
and my brother is joe`,
  },
  expect: {
    foo: `Hello,
my name is Ben
and my brother is joe`,
  },
});

Smart Formatting for Readability

Long diffs remain readable:

assert({
  actual: "http://example_that_is_quite_long.com/dir/file.txt",
  expect: "http://example_that_is_quite_long.com/dir/file.css",
});

Clear Nested Object Comparisons

For deeply nested objects, the message focuses on the important differences:

assert({
  actual: {
    the: {
      nesting: {
        is: {
          very: {
            deep: {
              in: {
                this: {
                  one: {
                    foo: {
                      a: true,
                      tata: { test: true, bar: { a: "1" } },
                    },
                  },
                },
              },
            },
          },
        },
      },
    },
  },
  expect: {
    the: {
      nesting: {
        is: {
          very: {
            deep: {
              in: {
                this: {
                  one: {
                    foo: false,
                  },
                },
              },
            },
          },
        },
      },
    },
  },
});

Custom assertions

assert({
  actual: 50,
  expect: assert.between(100, 200),
});

Advanced JavaScript Features

@jsenv/assert handles complex JavaScript concepts:

• Circular references
• Prototype differences example
• Object integrity differences (Object.freeze, Object.seal and Object.preventExtensions) example
• Property descriptor differences example
• Symbol differences example

Installation

Node.js

npm i --save-dev @jsenv/assert

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

assert({
  actual: true,
  expect: false,
});

Browser

Using NPM

npm i --save-dev @jsenv/assert

<script type="module">
  import { assert } from "@jsenv/assert";

  assert({
    actual: true,
    expect: false,
  });
</script>

Using CDN

<script type="module">
  import { assert } from "https://unpkg.com/@jsenv/assert@latest";

  assert({
    actual: true,
    expect: false,
  });
</script>