Mocha Test Helper Suite

1.0.0 verified Thu Apr 23 auth: no javascript abandoned

node-test-helper is a legacy testing utility suite designed to simplify Mocha test setup by providing globally available assertions, mocking utilities, and test structure variables. Currently at version 1.0.0, the package's development appears to be abandoned, with no significant code updates in the past few years, despite a recent npm publish. Its approach relies heavily on CommonJS `require()` to inject global variables and functions (like `describe`, `it`, `expect`, `stub`, `TEST_NAME`) into the test environment, diverging significantly from modern modular JavaScript testing practices. It also presumes a `make`-based workflow for test execution rather than `npm scripts`, limiting its direct applicability in contemporary Node.js projects. Key differentiators (at the time of its creation) included simplifying boilerplate by abstracting away direct `require` calls for Mocha, Chai, and Sinon in individual test files, and offering an `init` command to scaffold a basic test directory structure and Makefile.

Common errors

error ReferenceError: describe is not defined ↓

cause The `node-test-helper` package, which sets up global test utilities, has not been properly loaded in your test file.

fix

Ensure require("node-test-helper"); is at the very top of your test file, or in a bootstrap file loaded before your tests.

error make: *** No rule to make target 'test'. Stop. ↓

cause The `make` command cannot find a `Makefile` in the current directory, or the `Makefile` does not contain a `test` target.

fix

Run node-test-helper init to generate the default Makefile and test directory structure, or ensure you are executing make test from the directory containing your Makefile.

error Error: Cannot find module 'node-test-helper' ↓

cause The `node-test-helper` package has not been installed in your project's `node_modules`.

fix

Install the package locally: npm install node-test-helper --save-dev.

error ReferenceError: expect is not defined ↓

cause `node-test-helper` has been loaded, but the `chai` assertion library (which provides `expect`) is missing as a peer dependency.

fix

Install Chai as a development dependency: npm install chai --save-dev.

Warnings

breaking The package exclusively uses CommonJS `require()` for initialization and pollutes the global scope. It is not compatible with ES Modules (`import`/`export`) without significant configuration or a transpilation step, and attempting to use `import` will lead to `ReferenceError` or incorrect setup. ↓

fix Ensure your test files are in a CommonJS context and use `require("node-test-helper");` at the top of each test file where globals are needed.

gotcha This library relies on injecting test utilities (like `describe`, `it`, `expect`, `stub`) as global variables. This practice is generally considered an anti-pattern in modern JavaScript development due to potential conflicts, reduced code clarity, and difficulty in static analysis. ↓

fix While this is the intended usage, for new projects, consider using a modern testing framework and assertion library (e.g., Jest, Vitest, or Mocha/Chai with explicit imports) that avoids global pollution.

deprecated Test execution is heavily coupled to `make` commands and a specific `Makefile` structure. Modern Node.js projects typically use `npm scripts` for test orchestration, offering greater portability and platform independence. ↓

fix Adapt your project to use `make test`, or manually configure `npm scripts` to invoke the underlying `mocha` command with appropriate options, ensuring `node-test-helper` is required globally or via `--require` flags.

gotcha The package depends on `mocha`, `chai`, `sinon`, and `sinon-chai` being installed in your project. If these dependencies are missing, global functions like `describe` or `expect` will not be available, leading to `ReferenceError`s. ↓

fix Always install `mocha`, `chai`, `sinon`, and `sinon-chai` as dev dependencies: `npm install --save-dev mocha chai sinon sinon-chai`.

Install

npm install node-test-helper

yarn add node-test-helper

pnpm add node-test-helper

Imports

Side Effect Global Setup
wrong
```
import 'node-test-helper';
```
correct
```
require("node-test-helper");
```
This CommonJS `require` call is essential. It initializes the testing environment and injects global variables (like `describe`, `it`, `expect`, `stub`, `TEST_NAME`, etc.) from Mocha, Chai, and Sinon into the global scope. Direct ESM `import` statements will not achieve the intended setup.
expect
wrong
```
import { expect } from 'node-test-helper';
```
correct
```
// Available globally after require("node-test-helper");
```
`expect` is part of the Chai assertion library made globally available by `node-test-helper`'s side-effect require. It is not a named export from `node-test-helper` itself.
TEST_NAME
wrong
```
import { TEST_NAME } from 'node-test-helper';
```
correct
```
// Available globally after require("node-test-helper");
```
`TEST_NAME` is a global variable provided by `node-test-helper` to represent the current test file's name. It is not an importable symbol.

Quickstart

This quickstart demonstrates how to set up and run a basic test file using `node-test-helper`'s global variable injection and a `make` command, including an asynchronous test example.

const fs = require('fs');
const path = require('path');

// Create a mock package.json to avoid 'make' install issues in a real quickstart
fs.writeFileSync('package.json', JSON.stringify({ name: 'my-test-app', version: '1.0.0', devDependencies: { 'node-test-helper': '^1.0.0', 'mocha': '^10.0.0', 'chai': '^4.0.0', 'sinon': '^17.0.0', 'sinon-chai': '^3.0.0' } }), 'utf8');

// Simulate npm install for quickstart context
console.log('Simulating npm install...');
// In a real environment, you'd run `npm install` here.
// For a quickstart, we're assuming dependencies are met if we just show the test file.

// Create a Makefile for 'make test'
const makefileContent = `
TEST_RUNNER = ./node_modules/.bin/mocha
TEST_OPTS = --recursive -t 30000 -R spec

test:
	@NODE_ENV=test $(TEST_RUNNER) $(TEST_OPTS) test/unit/

.PHONY: test
`;
fs.writeFileSync('Makefile', makefileContent, 'utf8');

// Create test directory structure
fs.mkdirSync('test/unit', { recursive: true });

// Create a sample test file
const testContent = `
//-- test/unit/sample.test.js
require("node-test-helper");

describe(TEST_NAME, function() {
  describe("without callback", function() {
    it("should be successful", function() {
      expect(true).to.be.true;
    });
  });

  describe("with callback", function() {
    it("should be successful asynchronously", function(done) {
      setTimeout(() => {
        expect(false).to.be.false;
        done();
      }, 10);
    });
  });
});
`;
fs.writeFileSync('test/unit/sample.test.js', testContent, 'utf8');

console.log("To run the tests, first ensure mocha, chai, sinon, and sinon-chai are installed locally (e.g., 'npm install'). Then run: `make test`");
console.log("Expected output will show '2 passing'.");