!Nifty li'l tricks Logo

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

$3

``typescript
import * as testing from "deps";
`

$3

`shell
npm install @nifty-lil-tricks/testing
`

$3

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

`jsonc
{
"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.

$3

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.

`typescript
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:

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

interface HelloWorldConfig {
message: string;
}

type HelloWorldResult = string;

const helloWorldPlugin: Plugin = {
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:

`typescript
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:

`typescript
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();
`

$3

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!