- API
describeexpectitmodnotpackrun.createRelativePathsrun.createTestRunnerrun.getPathsrun.isESFilerun.isFilerun.isJSFilerun.isTSFiletoAlmostEqualtoBetoBeGreaterThantoBeGreaterThanOrEqualtoBeInstanceOftoBeLessThantoBeLessThanOrEqualtoContainElementtoContainStringtoEqualtoExisttoMatchtoMatchObjecttoRejecttoThrow
Runs a test suite; a collection of steps.
description: A description of the test suite.runSuite: A callback that runs steps.
A promise if runSuite is asynchronous, void otherwise.
// Synchronous
const isEven = (num: number) => num % 2 === 0;
describe("isEven", it => {
it("should return true for multiples of 2", expect => {
expect(isEven(2), toEqual(true));
expect(isEven(100), toEqual(true));
});
it("should return true for 0", expect => {
expect(isEven(0), toEqual(true));
});
// More it
});// Asynchronous
// Remember to wrap this in an async function if you are using an environment
// that does not support top level await.
const delay = timeMilliseconds => {
return new Promise(resolve => {
setTimeout(() => resolve(), timeMilliseconds);
});
};
await describe("delay", async it => {
await it("should delay by 1s", async expect => {
const time = performance.now();
await delay(1000);
expect(performance.now() - time, toBeGreaterThanOrEqual(1000));
});
// More it
});Runs an assertion.
expectation: The known value to assert.assert: The function used for assertion.
A promise if assert is asynchronous, void otherwise.
// Synchronous
expect(true, toEqual(true)); // PASSED// Asynchronous
// Remember to wrap this in an async function if you are using an environment
// that does not support top level await.
const reject = () => {
return new Promise((_, reject) => reject(new Error()));
};
await expect(reject, toReject(Error)); // PASSEDRuns a step; a collection of assertions.
description: Description of the step.test: The callback that runs assertions.
A promise if test is asynchronous, void otherwise.
// Synchronous
const isEven = (num: number) => num % 2 === 0;
it("returns true if number is even", expect => {
expect(isEven(2), toEqual(true)); // PASSED
// More expect
});// Asynchronous
// Remember to wrap this in an async function if you are using an environment
// that does not support top level await.
const delay = timeMilliseconds => {
return new Promise(resolve => {
setTimeout(() => resolve(), timeMilliseconds);
});
};
await it("should delay by 1000ms", async expect => {
const time = performance.now();
await delay(1000);
expect(performance.now() - time, toBeGreaterThanOrEqual(1000));
});Runs a module; a collection of test suites.
description: A description of the module.runModule: A callback that runs suites.
A promise if runModule is asynchronous, void otherwise.
// Synchronous
mod("Math", describe => {
describe("isEven", it => {
it("should return true for multiples of 2", expect => {
expect(isEven(2), toEqual(true));
expect(isEven(1000), toEqual(true));
});
it("should return true for 0", expect => {
expect(isEven(0), toEqual(true));
});
});
});// Asynchronous
// Remember to wrap this in an async function if you are using an environment
// that does not support top level await.
await mod("Time", async describe => {
// Asynchronous code
});Inverts the actual of an assertion.
confirm: A callback for assertion.The callback can be returned by other assertion functions liketoEqual.
void
expect(true, not(toEqual(false))); // PASSEDRuns a package; a collection of mods.
description: A description of the package.runPackage: A callback that runs mods.
A promise if runPackage is asynchronous, void otherwise.
// Synchronous
pack("Utils", mod => {
// mod code
});// Asynchronous
// Remember to wrap this in an async function if you are using an environment
// that does not support top level await.
await pack("Utils", async mod => {
// mod code
});Creates relative paths from absolute paths.
absolutePaths: Absolute paths for which to create relative paths.entry: The entry paths for both the absolute paths and relative paths.
An Array of relative paths.
Creates a function that runs tests.
options: An object containing the following properties:
entry: an object specifying the entry points of the test runner.isMatch: a function that checks if a file path meets certain conditions.importModule: a function that imports the module containing tests.getTestRunner: a function that gets the function that runs tests from the imported module.
A function that runs the tests. The function doesn't take any parameters and returns a promise that resolves to void or undefined.
// Deno
import {
run,
type ModuleImporter,
type TestModule,
type TestRunner
} from "https://deno.land/x/testjs/mod.ts";
const { createTestRunner, isTSFile } = run;
const relative = "./src";
// Checkout run.getPaths for equivalent in Node
const absolute = new URL(relative, import.meta.url).pathname;
const entry = { relative, absolute };
const importModule: ModuleImporter = path => import(path);
// Assuming the the test modules export run
const getTestRunner = (mod: TestModule): TestRunner => mod.run;
const runTSTests = createTestRunner({
entry,
isMatch: isTSFile,
importModule,
getTestRunner
});
runTSTests();Gets all paths in a given directory that match a particular condition.
isMatch: The function that checks whether the file pathmeets a particular condition.
An Array of matching paths.
// Deno
import { run } from "https://deno.land/x/testjs/mod.ts";
const { getPaths, isTSFile } = run;
const dir = new URL("./src", import.meta.url).pathname;
const getTSFiles = getPaths(isTSFile);
const paths = getTSPaths(dir);
console.log(paths); // ['/home/testjs/repos/testjs/src/main.test.ts']// Node ES
import { fileURLToPath } from "url";
import path, { dirname } from "path";
import { run } from "@test-bdd/testjs";
const { getPaths, isTSFile } = run;
const currentFilePath = fileURLToPath(import.meta.url);
const currentDirPath = dirname(currentFilePath);
const dir = path.join(currentDirPath, "src");
const getTSFiles = getPaths(isTSFile);
const paths = getTSPaths(dir);
console.log(paths); // ['/home/testjs/repos/testjs/src/main.test.ts']// Node CommonJS
const path = require("path");
const { run } = require("@test-bdd/testjs");
const { getPaths, isTSFile } = run;
const dir = path.join(__dirname, "src");
const getTSFiles = getPaths(isTSFile);
const paths = getTSPaths(dir);
console.log(paths); // ['/home/testjs/repos/testjs/src/main.test.ts']Checks if a given path is for an ES (TypeScript or JavaScript) test file.
Valid test file extensions are prefixed with .test, _test, .spec, or _spec.
path: The path to a file or directory.
true if path is for an ES file, false otherwise.
const path = "/src/main.test.ts";
console.log(isESFile(path)); // trueChecks if a given path is for a file.
path: The path to a file or directory.
true if path is for a file, false otherwise.
const path = "/src/main.test.ts";
console.log(isFile(path)); // trueChecks if a given path is for a JavaScript test file.
This includes Node.js files such as those having extensions mjs and cjs.
Valid test file extensions are prefixed with .test, _test, .spec, or _spec.
path: The path to a file or directory.
A true if path is for a JavaScript file, false otherwise.
const path = "/src/main.test.js";
console.log(isJSFile(path)); // trueChecks if a given path is for a TypeScript test file.
Valid test file extensions are prefixed with .test, _test, .spec, or _spec.
path: The path to a file or directory.
A true if path is for a TypeScript file, false otherwise.
const path = "/src/main.test.ts";
console.log(isTSFile(path)); // trueAsserts if the given numbers are almost equal. Numbers are considered to be almost equal if the difference between them is withing a particular tolerance.
tolerance:The tolerance within which the difference between values must be to be considered almost equal. The default tolerance is 1e-7.
A function for asserting.
expect(0.1 + 0.3, toAlmostEqual(0.3)); // PASSEDAsserts the referential equality of two values.
For primitive values, it has the same functionality as toEqual.
actual: The value to be compared to.
Confirm; a function that takes the value passed to expect
and compares it to actual.
const array1 = [1];
const array2 = array1;
const array3 = [1];
const bool = true;
expect(array2, toBe(array1)); // PASSED
expect(array2, toBe(array3)); // FAILED
expect(array2, toBe([1])); // FAILED
expect(bool, toBe(true)); // PASSEDAsserts if one number is greater than another.
actual: The value to be compared to.
Confirm; a function that takes the value passed to expect
and checks if it is greater than actual.
expect(2, toBeGreaterThan(1)); // PASSEDAsserts if one number is greater than or equal to another.
actual: The value to be compared to.
Confirm; a function that takes the value passed to expect
and checks if it is greater than or equal to actual.
expect(2, toBeGreaterThanOrEqual(1)); // PASSED
expect(1, toBeGreaterThanOrEqual(1)); // PASSEDAsserts if a given value is an instance of another value.
actual: A class or constructor.
Confirm; a function that takes the value passed to expect
and checks if it is an instance of actual.
expect(new Date(), toBeInstanceOf(Date)); // PASSED
expect(1000, toBeInstanceOf(Date)); // FAILEDAsserts if one number is less than another.
actual: The value to be compared to.
Confirm; a function that takes the value passed to expect
and checks if it is less than actual.
expect(1, toBeLessThan(2)); // PASSEDAsserts if one number is less than or equal another.
actual: The value to be compared to.
Confirm; a function that takes the value passed to expect
and checks if it is less than or equal actual.
expect(1, toBeLessThanOrEqual(2)); // PASSED
expect(1, toBeLessThanOrEqual(1)); // PASSEDAsserts if a given value is an element of an array.
actual: A value that maybe an element of an array.
Confirm; a function that takes the array passed to expect
and checks if it contains actual.
// With a primitive
expect([1], toContainElement(1)); // PASSED// With an object
const obj = { name: "Test" };
expect([obj], toContainElement(obj)); // PASSEDAsserts if a given string contains a given substring.
actual: A substring that may be contained in another string.
Confirm; a function that takes the string passed to expect
and checks if it contains actual.
expect("Test", toContainString("T")); // PASSED
expect("Test", toContainString("E")); // FAILEDAsserts if two values are structurally equal.
actual: The value to be compared to.
Confirm; a function that takes the value passed to expect
and compares it to actual.
// With a primitive
expect(true, toEqual(true)); // PASSED// With an object
const obj = { name: "Test" };
expect(obj, toEqual({ name: "Test" })); // PASSEDAsserts if a given value is null or undefined.
Confirm; a function that takes the value passed to expect
and checks if it is null or undefined.
expect(false, toExist()); // PASSED
expect(null, toExist()); // FAILEDAsserts if a string matches a RegExp or another string.
actual: ARegExporstring.Ifactualis astring, it is converted to aRegExp.
Confirm; a function that takes the string passed to expect
and checks if it matches actual.
expect("Test", toMatch("T")); // PASSED
expect("Test", toMatch("E")); // PASSEDAsserts if an object matches a subset of the properties of another object.
actual: The object to be matched against.
Confirm; a function that takes the object passed to expect
and checks if it matches actual.
const user = { username: "johndoe", age: 19 };
expect(user, toMatchObject({ username: "johndoe" })); // PASSEDAsserts if a given function rejects.
Err: An constructor that returns an errora given function is expected to reject with.message: A message the error thrown is expected to have.
Confirm; a function that takes the function passed to expect
and checks if it rejects. If Err is given, it also checks if the function rejects
with the error returned by Err.
const reject = () => {
return new Promise((_, reject) => reject(new Error("Error occurred")));
};
expect(reject, toReject()); // PASSED
expect(reject, toReject(Error, "TypeError occurred")); // FAILEDAsserts if a given function throws.
Err: A constructor of an error a given function is expected to throw.message: The message the error thrown is expected to have.
Confirm; a function that takes the function passed to expect
and checks if it throws.
If Err is provided, it also checks if the error thrown matches Err.
const throwError = () => {
throw new Error();
};
expect(throwError, toThrow(Error)); // PASSED
expect(throwError, toThrow(Error, "An unknown error occurred")); // FAILED