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>