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

descriptive-tester

v1.0.5

Published

A simple testing framework that lets you describe your tests.

Downloads

26

Readme

Descriptive Tester

A simple testing library that allows you to describe your tests.

View on NPM

Basic idea

As the name suggests, the library's goal is to enable you to from sentences as a means of describing a test. The two main functions that this library provides are it and should. The it function is used to describe a test and the should function is used to describe a test case.

This library defines the words "test" and "test case" as the following:

  • A test is a group of test cases that are required to pass.
  • Each test focuses on one topic (e.g., math functions).
  • Each test case focuses on a subtopic of a test (e.g., addition).
  • When a test case fails, an error is thrown which gets caught by the parent test.
  • A test case can not be defined outside a test.

A simple example of a test file may look something like:

const { it, should, assert } = require("descriptive-tester");

/**
 * Returns the sum of `a + b`.
 *
 * @param a The first number to add.
 * @param b The second number to add.
 */
function mySumFunc(a, b) {
    return a + b;
}

it("mySumFunc(a, b)", function () {
    should("Add 2 + 2 and return 4", () => assert.equal(mySumFunc(2, 2), 4));
    should("Not add 3 + 2 and return 4", () => assert.notEqual(mySumFunc(3, 2), 4));
});

In the example code, we state that:

  • mySumFunc should add 2 + 2 and return 4.
  • mySumFunc should not add 3 + 2 and return 4. -

If a test case fails, an AssertionError will be thrown and the test (described in it) will catch the error and exit the program.


Usage

Descriptive Tester is easy to set up and use.

Installation

To install this library, you can run:

# Install globally so that CLI can run.
npm install -g descriptive-tester

# Install locally so that the tests have a reference to `main-lib.ts`.
npm install --save-dev descriptive-tester

# Shorter version
# ---------------

# Install globally so that CLI can run.
npm i -g descriptive-tester

# Install locally so that the tests have a reference to `main-lib.ts`.
npm i -D descriptive-tester

Command line usage

After installing Descriptive Tester, you'll be able to call descriptive-tester in your terminal and passing it some test files or directories.

# Pass a file.
descriptive-tester ./my-test-file.js

# Or pass a directory (At the moment RegExp is not supported).
descriptive-tester ./my-test-directory/

# Or pass both directories and files.
descriptive-tester ./math.js ./tests/ ./dom.js

Note: At the moment, the CLI works when it's installed globally. I recommend following the installation instructions of this project above.

Writing some tests

Descriptive Tester exports 2 functions, it and should, and the assert object from Node's assert.strict module.

When importing Descriptive Tester, you can simply write:

const { it, should, assert } = require("descriptive-tester");

After importing this library, you can import your own modules that you want to test. However, for this short tutorial we'll just use some math functions.

When writing a test, the first thing that you need to do is to define the test (i.e., give the test a name). For example:

const { it, should, assert } = require("descriptive-tester");

it("Math.floor", function () {
    // ...
});

After doing this, we can simply write test cases using should. For our example, we are going to test Math.floor and make sure that it floors a number correctly.

const { it, should, assert } = require("descriptive-tester");

it("Math.floor", function () {
    should("Floor 3.4 to 3", () => assert.equal(Math.floor(3.5), 3));
    should("Not floor 5.5 to 6", () => assert.notEqual(Math.floor(5.5), 6));
});

And we've successfully written our first test!

Before we move on though, I'd like to point out how Descriptive Tester describes your tests and makes it both readable and pronounceable.

The test that we wrote can be read as two sentences.

  • Math.floor should floor 3.4 to 3.
  • Math.floor should not floor 5.5 to 6.

Writing tests this way is good because it enables other users to contribute other tests, and also enables people who don't know programming to read your tests as well if their curious.

Running our test

To run our test we can simply type:

descriptive-tester ./math-floor-test.js

Licence

This project is licensed under the MIT license. Please see the LICENSE file for more details.