npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

clutch-assert

v5.1.1

Published

Combine Ava's assertion API with Power Assert

Downloads

1,108

Readme

Clutch Assert NPM package Build Status Coverage Greenkeeper

"The only assert library that truly comes in clutch"

What is this?!

"That's a great question, I'm glad you asked"

This project is essentially a combination of ideas from two other projects ava and power-assert.

It combines the api of ava's assertions with the power of power-assert and also provides a handy .keys assertion which can be useful if switching from chai.

Why/When should I use this?

The library can be very helpful when porting an older codebase to use ava for testing. Using clutch assert will allow you to incrementally convert all of your assertions to ava style assertions and then once you're ready to switch just replace the word assert with ava's assertion mixin variable.

Note: ava does not have the .keys assertion

Quick Start

Install clutch-assert

$ npm install --save clutch-assert

Instruct your test runner to require the clutch-assert loader before running tests. You will not get enhanced assertion messages if you neglect to require the loader

Example using mocha

$(npm bin)/mocha --require clutch-assert/loader path/to/test/mocha_node.js

By default the loader will instrument all files in a directory named test, if your tests are located elsewhere you must provide that path to the loader as detailed under loader configuration.

Usage

const assert = require('clutch-assert');

assert.is(1 + 1, 2);

Note: Make sure to name the variable assert, due to the way the underlying dependencies work power-assert won't work correctly if the variable is named something else.

Loader Configuration

By default the loader instruments all files under the test directory, this can be changed by placing a .clutchrc in the root of your project which should be a json file with a directory top-level key.

Example

{
  "directory": "test/unit"
}

Using Other Loaders

The power-assert loaders do not have support for the .keys assertion by default. If you wish to use that assertion you must import the patterns from clutch assert and configure the loader to use those patterns.

Here is an example using espower-loader

const espower = require('espower-loader');
const patterns = require('clutch-assert/lib/patterns');

espower({
  cwd: process.cwd(),
  pattern: 'test/**/*.js',
  espowerOptions: {
    patterns: pattern.ENHANCED,
  },
});

API

.pass([message])

Passing assertion.

.fail([message])

Failing assertion.

.truthy(value, [message])

Assert that value is truthy.

.falsy(value, [message])

Assert that value is falsy.

.true(value, [message])

Assert that value is true.

.false(value, [message])

Assert that value is false.

.is(value, expected, [message])

Assert that value is equal to expected.

.not(value, expected, [message])

Assert that value is not equal to expected.

.deepEqual(value, expected, [message])

Assert that value is deeply equal to expected.

.notDeepEqual(value, expected, [message])

Assert that value is not deeply equal to expected.

.keys(object, keys, [message])

Assert that object contains all of and only the keys specified

.throws(fn, expected, [message]])

Assert that an error is thrown. fn must be a function which should throw. The thrown value must be an error. It is returned so you can run more assertions against it.

expected can be a constructor, in which case the thrown error must be an instance of the constructor. It can be a string, which is compared against the thrown error's message, or a regular expression which is matched against this message. You can also specify a matcher object with one or more of the following properties:

  • instanceOf: a constructor, the thrown error must be an instance of
  • is: the thrown error must be strictly equal to expected.is
  • message: either a string, which is compared against the thrown error's message, or a regular expression, which is matched against this message
  • name: the expected .name value of the thrown error
  • code: the expected .code value of the thrown error

Example:

const fn = () => {
  throw new TypeError('hello there');
};

test('throws', t => {
  const error = t.throws(() => {
    fn();
  }, TypeError);

  t.is(error.message, 'hello there');
});

.throwsAsync(thrower, expected, [message]])

Assert that an error is thrown. thrower can be an async function which should throw, or a promise that should reject. This assertion must be awaited.

The thrown value must be an error. It is returned so you can run more assertions against it.

expected can be a constructor, in which case the thrown error must be an instance of the constructor. It can be a string, which is compared against the thrown error's message, or a regular expression which is matched against this message. You can also specify a matcher object with one or more of the following properties:

  • instanceOf: a constructor, the thrown error must be an instance of
  • is: the thrown error must be strictly equal to expected.is
  • message: either a string, which is compared against the thrown error's message, or a regular expression, which is matched against this message
  • name: the expected .name value of the thrown error
  • code: the expected .code value of the thrown error

Example:

test('throws', async t => {
  await t.throwsAsync(async () => {
    throw new TypeError('hello there');
  }, {instanceOf: TypeError, message: 'hello there'});
});
const promise = Promise.reject(new TypeError('hello there'));

test('rejects', async t => {
  const error = await t.throwsAsync(promise);
  t.is(error.message, 'hello there');
});

.notThrows(fn, [message])

Assert that no error is thrown. fn must be a function which shouldn't throw.

.notThrowsAsync(nonThrower, [message])

Assert that no error is thrown. nonThrower can be an async function which shouldn't throw, or a promise that should resolve.

Like the .throwsAsync() assertion, you must wait for the assertion to complete:

test('resolves', async t => {
  await t.notThrowsAsync(promise);
});

.regex(contents, regex, [message])

Assert that contents matches regex.

.notRegex(contents, regex, [message])

Assert that contents does not match regex.

.ifError(error, [message])

Assert that error is falsy.

Customization API

clutch-assert provides an API for customization through which you can customize clutch-assert by changing some options.

const assert = require('clutch-assert').customize({
  output: {
    maxDepth: 2,
  },
});

options

options has two top-level keys. assertion and output.

options.assertion

Customization options for empower module. See empower API documentation for details. Note that some default values are different from empower's (modifyMessageOnRethrow: true and saveContextOnRethrow: true).

options.output

Customization options for power-assert-formatter module. See power-assert-formatter API documentation for details.

default values

Customizable properties and their default values are as follows.

const assert = require('clutch-assert').customize({
  assertion: {
    destructive: false,
    modifyMessageOnRethrow: true,
    saveContextOnRethrow: true,
    patterns: [
      'assert.truthy(value, [message])',
      'assert.falsy(value, [message])',
      'assert.true(value, [message])',
      'assert.false(value, [message])',
      'assert.is(value, expected, [message])',
      'assert.not(value, expected, [message])',
      'assert.deepEqual(value, expected, [message])',
      'assert.notDeepEqual(value, expected, [message])',
      'assert.regex(contents, regex, [message])',
      'assert.notRegex(contents, regex, [message])',
      'assert.keys(object, keys, [message])',
    ],
  },
  output: {
    lineDiffThreshold: 5,
    maxDepth: 1,
    anonymous: 'Object',
    circular: '#@Circular#',
    lineSeparator: '\n',
    ambiguousEastAsianCharWidth: 2,
    widthOf: "(Function to calculate width of string. Please see power-assert-formatter's documentation)"
    stringify: "(Function to stringify any target value. Please see power-assert-formatter's documentation)"
    diff: "(Function to create diff string between two strings. Please see power-assert-formatter's documentation)"
    writerClass: "(Constructor Function for output writer class. Please see power-assert-formatter's documentation)"
    renderers: [
      './built-in/file',
      './built-in/assertion',
      './built-in/diagram',
      './built-in/binary-expression'
    ],
  },
});