MiniSpec

MiniSpec is a lightweight test/spec execution engine for TypeScript and JavaScript, inspired by RSpec and minitest.

It works out-of-the-box with CommonJS, ESM and TypeScript.

Its purpose is to remain lightweight, without any runtime dependency and really low number of development dependencies.

Why another test/spec execution engine?

The idea of MiniSpec came from the need to write some unit-tests for a tiny library written in TypeScript. All testing framework were pretty big - with a lot of dependencies - and may not work well out-of-the-box with TypeScript.

MiniSpec goal is to remain lightweight, without runtime dependency. Its main purpose is to add a bunch of tests to small JavaScript or TypeScript projects.

Its name comes from the combination of minitest, and RSpec. Minitest for the idea of having a small and easy to maintain test/spec engine. RSpec for the spec syntax and for some output formats.

Why does weight matter?

Less dependencies and a lightweight library means less resources consumed while downloading it and executing it. It also reduces the potential attack surface.

That means also fewer features. That is why MiniSpec purpose is to be used with small projects, which do not need advanced testing capabilities offered by more popular alternatives.

Usage

Installation

To install MiniSpec, add it to your dev dependencies:

$ npm install --save-dev minispec

or with yarn:

$ yarn add minispec --dev

Check install

To make sure it is working as expected, create a file named validate_minispec_install.mjs in your project root directory:

// validate_minispec_install.mjs

import assert from 'assert'
import MiniSpec, { describe, it } from 'minispec'

describe('minispec', async () => {
  it('is working', async () => {
    assert.ok(true)
  })
})

MiniSpec.execute()

Then run the following:

$ node validate_minispec_install.mjs

The expected output should look like the following:

minispec
  is working

Finished in 3 milliseconds (discovering took 1 milliseconds, execution took 2 milliseconds)
1 test, no failure 👏

Congrats, MiniSpec is working fine! You can delete the file validate_minispec_install.mjs and start writing your own specs.

Writing tests

Due to its nature, MiniSpec comes with less magic than other test framework. You'll have to write a little bit of code to set it up. But don't worry, nothing complicated: only basic JavaScript/TypeScript.

The big picture

In a typical setup, you'll have an entrypoint for MiniSpec which will be responsible for loading MiniSpec, importing your tests, configuring your test environment, then executing the tests. It may look like this:

// ./specs/minispec_entrypoint.mjs

import MiniSpec from 'minispec'

import './calculator_spec.mjs'

MiniSpec.execute()

Then your test files may look like the following:

// ./specs/calculator_spec.mjs

import assert from 'assert/strict'
import { describe, context, beforeEach, it } from 'minispec'

import Calculator from '../src/calculator.mjs'

describe('Calculator', async () => {
  let calculator

  beforeEach(async () => {
    calculator = new Calculator()
  })

  describe('.sum(a, b)', async () => {
    context('when a and b are valid numbers', async () => {
      let a = 40
      let b = 2

      it('returns the sum of a and b', async () => {
        assert.equal(calculator.sum(a, b), 42)
      })
    })
  })
})

Assuming the following calculator:

// ./src/calculator.mjs

export default class Calculator {
  constructor() {}
  sum(a, b) {
    return a + b
  }
}

You can then run your tests:

$ node ./specs/minispec_entrypoint.mjs

You can also make it part of your package scripts in your package.json:

{
  "scripts": {
    "test": "node ./specs/minispec_entrypoint.mjs"
  }
}

Now you can run your tests using:

$ npm test

More documentation

To go further, you can follow the documentation:

• Organizing your Specs and the MiniSpec Entrypoint
• Writing specs
• Before and After hooks
• Reporters