Node.js mocha-they

The package extends Mocha with a new they function as an alternative to it. Its purpose is the execution of a test with multiple configuration settings.

This package was originally written to test ssh2-fs, ssh2-exec and Nikita. For example, in those packages, each test is run twice: the first time on a local environment and a second time on a remote environment with SSH.

Installation

This is OSS and licensed under the MIT license.

npm i -D mocha-they

Usage

Main steps:

1. Import the configure function from the mocha-they package.
2. If using Typescript, type the configuration argument.
3. Initialize they by calling configure with an array of configurations.
4. Use the they function just like it.

The package exports a function, configure. It is written in Typescript and exported in both CommonJs and ESM.

import { configure } from "mocha-they";
// Or (they is an alias of configure)
import { they } from "mocha-they";
// Or (ESM only)
import configure from "mocha-they";

Test functions receive a new argument.

For Typescript users, configure is a generic. The first type is required and defines the configuraiton object. The second is optional when before is used to alter the configuration

function configure<T>(configs: (T | (() => T))[]): They<T>;
function configure<T, U>(
  configs: (T | (() => T))[],
  before: (config: T) => U,
  after?: (config: U) => void,
): They<U>;

Call the configure function with an array of values to initialize they.

A configuration may be of any type. The value is passed as the first argument of the test handler function.

Functions receive a special treatment. They are called before the test and its value is passed to the tet handler as first argument.

interface Config {
  ssh?: {
    host: string;
    username: string | undefined;
  };
}
const they = configure<Config>([
  {
    ssh: undefined,
  },
  {
    ssh: { host: "127.0.0.1", username: process.env.USER },
  },
  () => ({
    ssh: { host: "localhost" },
  }),
]);

interface Config {
  ssh?: {
    host: string;
    username: string | undefined;
  };
}
const they = configure<Config>(
  [
    {
      ssh: undefined,
    },
    {
      ssh: { host: "127.0.0.1", username: process.env.USER },
    },
    () => ({
      ssh: { host: "localhost" },
    }),
  ],
  (config: Config) => {},
);

Finally, use they just like it.

describe("Test mocha-they", function () {
  they("With a promise", function (conf: Config) {
    // Run test
    return promise.resolve();
  });
  they("With a callback", function (conf: Config, next) {
    // Run test
    return next();
  });
});

Example

The Javascript example is executed with npx mocha samples/usage-javascript.js.

import { configure } from "mocha-they";

const they = configure([
  {
    ssh: undefined,
  },
  {
    ssh: { host: "127.0.0.1", username: process.env.USER },
  },
]);
describe("Test mocha-they", function () {
  they("Call 2 times", function (conf) {
    if (conf.ssh === undefined) {
      console.info(" ".repeat(6) + "Got null.");
    } else {
      console.info(" ".repeat(6) + "Got an ssh configuration.");
    }
  });
});

The Typescript example is executed with npx mocha samples/usage-typescript.ts.

import { configure } from "mocha-they";

interface Config {
  ssh?: {
    host: string;
    username: string | undefined;
  };
}

const they = configure<Config>([
  {
    ssh: undefined,
  },
  {
    ssh: { host: "127.0.0.1", username: process.env.USER },
  },
]);

describe("Test mocha-they", function () {
  they("Call 2 times", function (conf: Config) {
    if (conf.ssh === undefined) {
      console.info(" ".repeat(6) + "Got null.");
    } else {
      console.info(" ".repeat(6) + "Got an ssh configuration.");
    }
  });
});

The configuration elements can be anything. When an an object, an optional label property can be provided to customized the message output.

It returns a new function which behave exactly like the it function in mocha. The only difference is the presence of the configuration element as the first argument of the test. Like with it, you can customize Mocha with the only and skip directives.

Example using the before and after configuration hooks

A more complexe example covers the usage of before and after. In this example, an ssh object is converted to a fake SSH client and the connection is closed after the tests.

Test before/after usage
    SSH client not connected
  ✔ Called 3 times (local)
    connected to 127.0.0.1
    SSH client called
  ✔ Called 3 times (ssh object)
    connected to localhost
    SSH client called
  ✔ Called 3 times (2)

Release

Versions are incremented using semantic versioning. Test and publishing are handled with Github Actions. To create a new version and publish it to NPM, run:

npm run release
# Or (`git push` is only supported for the release script)
npm run release:<major|minor|patch>
git push --follow-tags origin master

The NPM publication is handled with the GitHub action.

Contributors

The project is sponsored by Adaltas, a company based in Paris, France. Adaltas offers support and consulting on distributed system, big data and open source.

• David Worms: https://github.com/wdavidw