exray

Home | Docs | GitHub | npm | Changelog | YouTube | Lightweight assertion testing framework

exray can be installed from the official npm package repository. It is highly recommended to install the latest version, which is installed by default with the following command.

npm i exray@1.1.2

Is there a way we can make exray better? Please report all bugs, issues, and new feature requests to the issues page in the official repository. For critical security issues, please send an email to exray@nicfv.com.

Thank you for your interest in contributing to exray! exray is an open source software package maintained by Nicolas Ventura (@nicfv) and built by users like you! You are allowed to fork the repository as permitted by the MIT License terms. Contributions are welcome by submitting a pull request. Please follow the existing code styling if submitting a pull request. Thank you for your consideration!

If exray is only used during the testing phase of development, it can be installed as a devDependency instead of a dependency. The difference here is that when you pack up your package, or when other people install your package, it will contain all dependencies, but no devDependencies. To install exray as a devDependency, use the following command in your project directory.

npm i -D exray

exray contains a simple, lightweight assertion testing framework for JavaScript and TypeScript projects. If any one of the exray tests fail, it will throw an exception and halt program execution. Exceptions can be caught using the standard try ... catch block.

exray exports one namespace, X, that includes several different test types, all of which can be simply derived from X.isTrue(...). Each test type throws a unique exception message if failed. Custom exception messages are optional, but always recommended for clarity to explain why a test may have failed.

Here are a few quickstart examples written in JavaScript that showcase some out-of-box features of the exray package.

Normally, a unit test will return true or false to determine if it passes or fails. If this is the case, you almost certainly want to use the X.isTrue() function. X.isFalse() can be used if a test needs to return false in order to pass. Here are a few simple examples of tests that will always pass using these functions.

1. Copy the source code
2. Paste into a new file
3. Save as Assert-Boolean-Values.mjs
4. Run this command in your terminal

   node Assert-Boolean-Values.mjs

import { X } from 'exray';

// This function always returns true.
function alwaysReturnsTrue() {
    return true;
}
// This test should pass
X.isTrue(alwaysReturnsTrue());

// This function always returns false.
function alwaysReturnsFalse() {
    return false;
}
// This test should pass
X.isFalse(alwaysReturnsFalse());

// Show that all tests passed.
console.log('All tests passed!');

All tests passed!

Exceptions can be caught with standard try ... catch blocks like in this example. There is a bug in our return8() function that is discovered by the X.eq() method. Since we caught the error, the script continues to run normally.

1. Copy the source code
2. Paste into a new file
3. Save as Catching-Exceptions.mjs
4. Run this command in your terminal

   node Catching-Exceptions.mjs

import { X } from 'exray';

// Oops! There was a logic
// error in returns8()!
function returns8() {
    return 9;
}

try {
    // This test will fail
    X.eq(returns8(), 8);
} catch (e) {
    console.log(e.message);
}

console.log('...Still processing...');

Exception found in test #1! The test value of 9 was not equal to the expected value of 8.
...Still processing...

We can also use exray to run comparisons on numeric values. The following example shows a few equivalents to using the math tests (e.g. gt) as compared to the standard true() and false() tests. Using the math tests are preferred for 2 reasons.

1. More descriptive default exception message
2. Forces the developer to provide 2 explicit inputs into the test (true() and false() only require a single boolean input)

1. Copy the source code
2. Paste into a new file
3. Save as Math-Comparisons.mjs
4. Run this command in your terminal

   node Math-Comparisons.mjs

import { X } from 'exray';

// 5 is greater than 4
X.gt(5, 4);
X.isTrue(5 > 4);

// 2 is less than or equal to 2
X.le(2, 2);
X.isTrue(2 <= 2);

// 3 is not equal to 0
X.ne(3, 0)
X.isTrue(3 !== 0);
X.isFalse(3 === 0);

// Show that all tests passed.
console.log('All tests passed!');

All tests passed!

In some cases, we may want to override the default exception message. This can easily be done by adding an additional string argument at the end of any test. This can help determine which test failed from a script of several tests. Even if a message is overwritten, it will still say which test number failed.

In this example scenario, we want to check the price of an item and continue processing if it is below a certain threshold. Since we are catching these exceptions, the script will continue to run anyway, but will immediately exit the try block and advance straight into the catch block. Notice how the output does not contain the string "Processing item."

1. Copy the source code
2. Paste into a new file
3. Save as Custom-Message.mjs
4. Run this command in your terminal

   node Custom-Message.mjs

import { X } from 'exray';

// Here's a simulation of
// an API to obtain the
// list price of an item.
function getPrice() {
    return 50;
}

// Let's say our cap is $40 to
// continue processing. We can
// assert that the price is less
// than or equal to $40 or throw
// an error. For this example,
// we will catch the exception.
try {
    X.le(getPrice(), 40);
    console.log('Processing item.');
} catch (e) {
    console.log(e.message);
}

// Here is the same logic using
// a custom exception message.
try {
    X.le(getPrice(), 40, 'Price exceeded $40 limit.');
    console.log('Processing item.');
} catch (e) {
    console.log(e.message);
}

Exception found in test #1! The test value of 50 was not less than nor equal to the expected value of 40.
Exception found in test #2! Price exceeded $40 limit.