Jsert

Jsert is a lightweight JavaScript library for writing unit tests for web applications. It offers significant flexibility for developers to write unit tests with minimal restrictions. Designed for simplicity, it allows for the rapid creation and execution of tests on both the client side (browser) and server side (Node.js).

---

Initialization

Jsert can be used in different environments by adjusting the target configuration option to ensure logs are formatted correctly for the specific output.

Browser Environment

In a browser, Jsert defaults to console targeting, which uses CSS for styling logs in the developer tools.

// Import or include the Jsert class
const jsert = new Jsert({
	group: "Web App Suite",
	target: "console"
})

Node.js (Terminal) Environment

For Node.js or other CLI environments, set the target to terminal to enable ANSI escape code coloring.

// Import the Jsert class
const Jsert = require("./jsert.js")

const jsert = new Jsert({
	group: "API Server Tests",
	target: "terminal"
})

---

Usage

Writing tests involves registering a test case with a name and a function, then executing the suite using the run() method. Inside the test function, this refers to the specific test object required by the assertion methods.

const jsert = new Jsert({group: "Math Tests", target: "terminal"})

// Define a test
jsert.test("Addition check", function () {
	const sum = 2 + 2
	jsert.passWhenEquals(this, sum, 4)
})

// Run all tests
jsert.run()

---

Documentation: Assertion Functions

The following functions are available within the Jsert class to validate logic and state within your tests.

passWhen

/**
 * Standard strict equality assertion.
 * @param {Object} test - The current test context (usually 'this').
 * @param {boolean} condition - The expression to evaluate.
 * @returns {void}
 */
passWhen(test, condition)

passWhenWithoutStrict

/**
 * Loose equality assertion (non-strict).
 * @param {Object} test - The current test context (usually 'this').
 * @param {*} condition - The expression to evaluate using loose equality (==).
 * @returns {void}
 */
passWhenWithoutStrict(test, condition)

passWhenEquals

/**
 * Asserts strict equality between two values.
 * @param {Object} test - The current test context.
 * @param {*} actual - The value produced by the code.
 * @param {*} expected - The value expected to be produced.
 * @returns {void}
 */
passWhenEquals(test, actual, expected)

passWhenNotEquals

/**
 * Asserts strict inequality between two values.
 * @param {Object} test - The current test context.
 * @param {*} actual - The value produced by the code.
 * @param {*} unexpected - The value that the actual result should NOT match.
 * @returns {void}
 */
passWhenNotEquals(test, actual, unexpected)

passWhenTruthy

/**
 * Asserts that a value is truthy.
 * @param {Object} test - The current test context.
 * @param {*} actual - The value to check for truthiness.
 * @returns {void}
 */
passWhenTruthy(test, actual)

passWhenFalsy

/**
 * Asserts that a value is falsy.
 * @param {Object} test - The current test context.
 * @param {*} actual - The value to check for falsiness.
 * @returns {void}
 */
passWhenFalsy(test, actual)

passWhenNull

/**
 * Asserts that a value is exactly null.
 * @param {Object} test - The current test context.
 * @param {*} actual - The value to check.
 * @returns {void}
 */
passWhenNull(test, actual)

passWhenNotNull

/**
 * Asserts that a value is not null.
 * @param {Object} test - The current test context.
 * @param {*} actual - The value to check.
 * @returns {void}
 */
passWhenNotNull(test, actual)

passWhenTypeIs

/**
 * Asserts the type of a value. Handles standard types and 'array'.
 * @param {Object} test - The current test context.
 * @param {*} actual - The value to inspect.
 * @param {string} expectedType - The expected type (e.g., 'string', 'number', 'array').
 * @returns {void}
 */
passWhenTypeIs(test, actual, expectedType)

passWhenHasLength

/**
 * Asserts that a collection (array or string) has a specific length.
 * @param {Object} test - The current test context.
 * @param {Array|string} collection - The object to measure.
 * @param {number} expectedLength - The required length.
 * @returns {void}
 */
passWhenHasLength(test, collection, expectedLength)

passWhenIncludes

/**
 * Asserts that an array includes a specific item.
 * @param {Object} test - The current test context.
 * @param {Array} array - The array to search.
 * @param {*} item - The item to look for.
 * @returns {void}
 */
passWhenIncludes(test, array, item)

passWhenEmpty

/**
 * Asserts that a collection is empty (length of 0).
 * @param {Object} test - The current test context.
 * @param {Array|string} collection - The collection to check.
 * @returns {void}
 */
passWhenEmpty(test, collection)

passWhenMatch

/**
 * Asserts deep equality between two objects or arrays.
 * @param {Object} test - The current test context.
 * @param {*} obj1 - The first object/array.
 * @param {*} obj2 - The second object/array to compare against.
 * @returns {void}
 */
passWhenMatch(test, obj1, obj2)