@jsenv/assert

assert

@jsenv/assert is the NPM package used by jsenv to write tests.

It can be resumed by the following quote:

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

Example

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

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

There is 200+ examples in ./tests/

How it works

assert does nothing when comparison is successfull but throws an error when comparison is failing.

Features

Colors

The message produced have colors that helps to see the diff. Each color have a meaning described below:

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

Comparison understands JavaScript and makes the diff more redable

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

This includes things like comparison on url parts, date parts, http headers and many more.

Multiline diff

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`,
  },
});

Keep long diff readable

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

Keep nested diff readable

When the diff is very deep the message omits the parents to keep the message concise and readable

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),
});

And much more

• Support comparison between value having circular references
• Can detect diff on prototypes
• Can detect diff on object integrity (Object.freeze, Object.seal and Object.preventExtensions)
• Can detect diff on property descriptors
• Can detect diff on symbols

Usage in Node.js

npm i --save-dev @jsenv/assert

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

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

Usage in a 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>