nifty_lil_tricks_testing

Note: this package and selected plugins are currently a work in progress

A selection of useful utilities (or nifty li'l tricks!) for all things testing.

Installation

Note: this package works with TypeScript v5 or later

Deno

import * as testing from "deps";

Node.js

npm install @nifty-lil-tricks/testing

TypeScript

The TypeScript tsconfig.json must contain the following recommended settings:

{
  "compilerOptions": {
    "target": "ES2022",
    "strict": true
  }
}

Note, check the plugin READMEs for any additional TypeScript settings.

Features

The following features are supported

• An extensible setup tests factory that allows one to declaratively setup a test suite for testing with loaded plugins through a simple to use interface.
• Teardown functionality for restoring the state of the environment after tests have run.
• Ready-made plugins to get started with straight-away.

Plugins

The following plugins are available to that make use of the setup tests plugin system.

| Plugin | Description | Status | Npm | Docs | | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | | PostgreSQl | Setup the World's Most Advanced Open Source Relational Database for testing. It has the following features: Setup a Postgresql server in Docker for testing.Setup an existing Postgresql server for testing.Run migrations on the configured Postgresql server.Seed the configured Postgresql server with data. | ✅ | | Docs. | | NestJS Server | Setup a progressive Node.js framework for building efficient, reliable and scalable server-side applications for testing. | ✅ | | Docs | | Express Server | Setup a minimal and flexible Node.js web Express application for testing. | 🚧 | | Docs |

Setup tests

• Quick start
• Setup tests overview

Quick start

import {
  afterEach,
  beforeEach,
  describe,
  it,
} from "testing/bdd.ts";
import { assertEquals } from "testing/asserts.ts";
import {
  setupTestsFactory,
  type SetupTestsTeardown,
} from "@nifty-lil-tricks/testing";

// Define or import a plugin as follows:
const helloWorldPlugin = {
  setup: (config: { message: string }) => {
    // Setup plugin according to config
    return {
      output: config,
      teardown: () => {},
    };
  },
};

// In another file, load plugins as follows to generate a setupTests function:
export const { setupTests } = setupTestsFactory({
  helloWorld: helloWorldPlugin,
});

// Then one can use this in any test file as follows:
describe("Service", () => {
  let teardownTests: SetupTestsTeardown;
  let message: string;

  beforeEach(async () => {
    // Setup tests with configured plugins
    const result = await setupTests({
      helloWorld: { message: "Hello, world!" },
    });
    message = result.outputs.helloWorld.output.message;
    teardownTests = result.teardownTests;
  });

  afterEach(async () => {
    // Teardown tests to restore environment after tests have run
    await teardownTests();
  });

  describe("method", () => {
    it("should test something that relies on the plugin being configured", () => {
      // Some other testing
      assertEquals(message, "Hello, world!");
    });
  });
});

Setup tests overview

setupTestsFactory

One can use the setupTestsFactory to register or load defined plugins. It is only needed to load these once so it is recommended to share the returned setupTests function across all test files.

Each plugin must be given a name that is not one of the reserved plugin names. This returns a function that when run, sets up the tests to use the loaded plugins according to the provided config.

Each plugin must contain the following functions in order to be correctly loaded:

• setup
• teardown

An example of a plugin is as follows:

import {
  type Plugin,
} from "@nifty-lil-tricks/testing";

interface HelloWorldConfig {
  message: string;
}

type HelloWorldResult = string;

const helloWorldPlugin: Plugin<HelloWorldConfig, HelloWorldResult> = {
  setup(config: HelloWorldConfig) {
    // Setup plugin according to config
    return {
      output: config.message,
      teardown() {
        // Teardown any setup resources
      },
    };
  },
};

setupTests

One can use the returned setupTests function use the loaded plugins.

The loaded plugins available to the setupTests function returned from the factory can be configured using config namespaced to the name of the plugin.

For example, if the plugin is named helloWorld, then the config for that plugin must be provided under the helloWorld namespace.

When run, setupTests will return an object with the data returned from the plugin invocation. The data will be namespaced to the plugin name. For example:

import {
  setupTestsFactory,
  type SetupTestsTeardown,
} from "@nifty-lil-tricks/testing";

// Define or import a plugin as follows:
const helloWorldPlugin = {
  setup: (config: { message: string }) => {
    // Setup plugin according to config
    return {
      output: config.message,
      teardown: () => {
        // Teardown any setup resources
      },
    };
  },
};

// In another file, load plugins as follows to generate a setupTests function:
export const { setupTests } = setupTestsFactory({
  helloWorld: helloWorldPlugin,
});

const result = await setupTests({
  helloWorld: { message: "Hello, world!" },
});

result.outputs.helloWorld.output; // "Hello, world!"

Only plugins that are configured will be run. If a plugin is not configured, then it will not be run. The order of the plugins in the config is defined the order in which they defined in the config object. This follows the rules as defined here.

The returned object will also contain a teardown function that when run, will teardown the plugins in the reverse order that they were setup.

teardownTests

One can use the returned teardownTests function to restore the environment to its original state after the tests have run.

For example:

import {
  setupTestsFactory,
  type SetupTestsTeardown,
} from "@nifty-lil-tricks/testing";

// Define or import a plugin as follows:
const helloWorldPlugin = {
  setup: (config: { message: string }) => {
    // Setup plugin according to config
    return {
      output: config.message,
      teardown: () => {
        // Teardown any setup resources
      },
    };
  },
};

// In another file, load plugins as follows to generate a setupTests function:
export const { setupTests } = setupTestsFactory({
  helloWorld: helloWorldPlugin,
});

const result = await setupTests({
  helloWorld: { message: "Hello, world!" },
});

// Teardown tests to restore environment after tests have run
await result.teardownTests();

API

The API Docs can be found here.

Examples

Examples can be found here.

Support

| Platform Version | Supported | Notes | | ---------------- | ------------------ | -------------------------- | | Deno v1 | :white_check_mark: | | | Node.JS v18 | :white_check_mark: | TypeScript v5+ for typings | | Node.JS v20 | :white_check_mark: | TypeScript v5+ for typings | | Web Browsers | :x: | Coming soon |

Useful links

• For help or feedback on this project, join us in GitHub Discussions

License

Nifty li'l tricks packages are 100% free and open-source, under the MIT license.

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.

Contributions

Contributions, issues and feature requests are very welcome. If you are using this package and fixed a bug for yourself, please consider submitting a PR!