It Testing Framework

Common errors

• ReferenceError: it is not defined

  cause Attempting to use `it.describe` or `it.should` without correctly importing the `it` module first, or trying to use `it` globally in a scope where it hasn't been passed as an argument.
  fix Ensure you have `const it = require('it');` at the top of your test file, and that the `it` object is passed into your `describe` and test callbacks: `it.describe('My Suite', function(it) { ... })`.

• TypeError: assert.isFunction is not a function

  cause Using `assert.isFunction` or similar non-standard `assert` methods with Node.js's built-in `assert` module, which does not provide these methods.
  fix Replace calls to `assert.isFunction` with standard Node.js `assert` methods like `assert.strictEqual(typeof myVar, 'function')` or consider using an alternative assertion library like Chai (`assert`, `expect`, or `should` styles) which offers a broader range of assertions.

• SyntaxError: Cannot use import statement outside a module

  cause Trying to use `import { it } from 'it';` in a Node.js environment that is not configured for ES Modules, or when the `it` package itself is a CommonJS module.
  fix Use the CommonJS `require` syntax: `const it = require('it');`. If you are in an ES Module context, you may need to use `import it from 'it'` if it provides a default export, or consider a build step that transforms CommonJS to ESM.

Warnings

• breaking The `it` framework primarily uses CommonJS modules (`require`) and does not natively support ECMAScript Modules (ESM) `import` syntax. Attempting to use `import` directly in modern Node.js environments configured for ESM will result in errors.
  Fix: Ensure your project uses CommonJS, or transpile your code if you must use ESM syntax. Use `const it = require('it');` to import the module.
• gotcha The `assert` module examples in the original `it` documentation (e.g., `assert.isFunction`) may imply a custom `assert` library or an older Node.js environment. Node.js's built-in `assert` module (especially in modern versions) primarily offers methods like `assert.strictEqual`, `assert.ok`, etc., and does not include `isFunction` directly. Using `assert.isFunction` with Node's built-in `assert` will result in a `TypeError`.
  Fix: Use standard Node.js `assert` methods (e.g., `assert.strictEqual`, `assert.ok`, `assert.throws`). If `assert.isFunction` is desired, you may need to install a separate assertion library (e.g., Chai's `assert` interface) and import it explicitly.
• gotcha The `it` object is explicitly passed as an argument to `it.describe` and individual `it.should` (or `it()`) callbacks. This means `it` is not a global variable available throughout your test file. If you omit the parameter in a nested describe or test, `it` will be `undefined` within that scope.
  Fix: Always include `it` as a parameter in your `describe` and `should` callback functions (e.g., `it.describe('suite', function(it) { ... })`) to ensure the testing context is available.
• deprecated This package appears to be abandoned or in long-term maintenance, with no significant updates in recent years. Its reliance on older Node.js versions (>=0.10.1) and older CI systems (Travis CI, Testling CI) suggests it may not be compatible with newer JavaScript features, Node.js APIs, or modern testing practices.
  Fix: Consider migrating to a more actively maintained testing framework like Jest, Mocha, or Vitest for modern JavaScript development.

Install

• npm install it npm
• yarn add it yarn
• pnpm add it pnpm

Imports

• it
  wrong:

  import { it } from 'it';

  correct:

  const it = require('it');

  The primary testing function/object is exported via CommonJS. Direct ESM `import` statements will likely fail without a transpiler or wrapper.
• it.describe
  wrong:

  describe('suite name', function() { /* ... */ });

  correct:

  const it = require('it');
  it.describe('suite name', function(it) { /* ... */ });

  Unlike some frameworks, `it.describe` is a method of the imported `it` object, and the `it` context itself is passed into the callback, not a global.
• it.should
  wrong:

  should('do something', function() { /* ... */ });

  correct:

  const it = require('it');
  it.describe('suite', function(it) { it.should('do something', function() { /* ... */ }); });

  `it.should` is a convenience method for defining individual tests, acting as an alias for `it('should do something', ...)`.

Quickstart

Demonstrates defining a simple JavaScript class and writing hierarchical tests using `it.describe` and `it.should` with Node.js's built-in `assert` module.

var Person = function (name, age) {
    this.name = name;
    this.age = age;

    this.getOlder = function (years) {
        if (years > 0) {
            this.age = this.age + years;
        }
    };
};

var it = require("it"),
    assert = require("assert"); // Node.js built-in assert module

it.describe("Person Object Tests", function (it) {

    it.should("correctly set name", function () {
        var person = new Person("Alice", 30);
        assert.strictEqual(person.name, "Alice");
    });

    it.should("correctly set age", function () {
        var person = new Person("Bob", 25);
        assert.strictEqual(person.age, 25);
    });

    it.describe("#getOlder method", function (it) {

        it.should("increase age by positive numbers", function () {
            var person = new Person("Charlie", 40);
            person.getOlder(5);
            assert.strictEqual(person.age, 45);
        });

        it.should("not modify age for negative numbers", function () {
            var person = new Person("David", 20);
            person.getOlder(-3);
            assert.strictEqual(person.age, 20);
        });
    });
});
// To run this, save as a .js file and execute with Node.js: `node your-test-file.js`.
// Alternatively, if `it` CLI is installed globally: `it your-test-file.js`.