TestLab.js

"Test Smarter, Not Harder!"

TestLab.js is a simple, lightweight JavaScript testing framework designed to make unit testing a breeze. It includes useful assertions, easy test setup, and hooks. Whether you're testing a small function or running a full suite of tests, TestLab.js helps you test your code effectively and efficiently.

Table of Contents

• Installation
• Usage
• Running Tests
• Test Timeout
• Assertions
• Custom Settings
• Contributing
• License
• Additional Features
• Contact Information

Installation

To install TestLab.js, use npm:

npm install testlab.js --save-dev

or yarn:

yarn add testlab.js --dev

This will install TestLab.js as a development dependency in your project.

Usage

Here's the basic example to get started with TestLab.js:

const testlabjs = require('testlab.js'); // Import TestLab.js

// Example test
testlabjs.test('should add two numbers', t => {
    const result = 1 + 2;
    t.is(result, 3); // Assert that result is 3
});

Here's a more advanced example of using TestLab.js:

const testlabjs = require('testlab.js'); // Import TestLab.js

// Execute a method before any tests start
testlabjs.beforeAll(t => {
    t.name = 'John Smith;'; // Add a value to the t object
    t.mockValue = [];
    console.log('I have executed before any tests start');
});

// Execute a method before each single test
testlabjs.beforeEach(t => {
    t.mockValue = [1, 2, 3];
});

// Example test
testlabjs.test('Does the mock method throw an error and is it the expected message', t => {
    const mock = () => { throw Error('This is part one of the message : this is part two of the message') };
    const error = t.throws(() => mock()); // Executes the mock function and checks for thrown error
    t.regex(error.message, /message/); // Check if the message contans the word "message"
});

// Execute a method after each single test
testlabjs.afterEach(() => {
    console.log('I have executed after each test');
});

// Execute a method after all tests have ran
testlabjs.afterAll(() => {
    console.log('I have executed after all tests have ran');
});

Running Tests

To run your tests, use the following script:

testlabjs

or, you can run tests by executing this method:

const testlabjs = require('testlab.js');

testlabjs.run();

Test Timeout

Set a timeout for your tests to prevent them from hanging indefinitely:

const testlabjs = require('testlab.js); // Import TestLab.js

// Set the timeout
testlabjs.configure({ timeout: 10000 });

Assertions

TestLab.js comes with several built-in assertions for different use cases. Here’s a complete list of available assertions (and more to come in future versions):

Equality

• t.deepEqual(actual, expected, message = '') Asserts that the action value is deeply equal to the expected value. Useful for comparing objects and arrays.
• t.is(actual, expected, message = '') Asserts that the actual value is strictly equal to the expected value (using ===).
• t.isEqual(actual, expected, message = '') Similar to t.is(), but allows for type coersion.

Comparion

• t.isGreaterThan(actual, expected, message = '') Asserts that the actual value is greater than the expected value.
• t.isLessThan(actual, expected, message = '') Asserts that the actual value is less than the expected value.

Type and Instance

• t.isInstanceOf(actual, constructor, message = '') Asserts the that the actual value is an instance of the given constructor function.

Negations

• t.not(actual, expected, message = '') Asserts that the actual value is not equal to the expected value.
• t.notEqual(actual, expected, message = '') Asserts that the actual value is not equal to the expected value (using !==).
• t.notGreaterThan(actual, expected, message = '') Assert that the actual value is not greater than the expected value.
• t.notLessThan(actual, expected, message = '') Asserts that the actual value is not less than the expected value.
• t.notInstanceOf(actual, constructor, message = '') Asserts that the actual value is not an instance of the given constructor.

Throws Assertions

• t.throws(fn, message = '') Asserts that the given function fn throws an error when executed.
• t.throwsAsync(fn, message = '') Asserts that the given asynchronous function fn throws an error when executed.
• t.notThrows(fn, message = '') Asserts that the given function fn does not throw an error when executed.
• t.nowThrowsAsync(fn, message = '') Asserts that the given asychronous fuction fn does not throw an error when executed.

Boolean Assertions

• t.true(value, message = '') Asserts that the value is truthy (i.e., evaluates to true).
• t.false(value, message = '') Asserts that the value is falsy (i.e., evaluates to false).

Custom Settings

TestLab.js allows you to modify all the available configuration values. To set a setting value:

const testlabjs = require('testlab.js'); // Import TestLab.js

// Set a setting
testlabjs.configure({ testDirectory: 'tests' });

To get a setting value:

const testlabjs = require('testlab.js'); // Import TestLab.js

// Get a setting value
const value = testlabjs.getConfig('timeout'); // Gets the timeout value
console.log(`Timeout is ${value}.`);

All Available Settings

• testDirectory: Specifies the directory where your test files are located. This setting allows you to define the folder or path containing the tests you want to execute.
• usePattern: Whether to use patterns inside the test directory path. For example: 'tests/*.test.js'.
• timeout: Sets a custom timeout (in milliseconds) for individual tests. If a test exceeds the specified time, it will be aborted, and an error will be reported. This is useful to avoid tests running indefinitely due to unforeseen issues or delays.
• debug: Enables debug mode during the test execution. When this option is active, additional debug information will be printed to the console, which can be helpful for diagnosing issues with the tests or the framework itself.
• paralell: Whether to execute the tests in parallel.
• resultsToJsonFile: Whether to write test results to a JSON file.
• resultsJsonFilePath: The file to write the test results JSON summary.

Default Settings

Below are the default values for the available settings:

• testDirectory: path.join(process.cwd(), 'tests)
• timeout: 5000 ms
• debug: false
• paralell: true
• resultsToJsonFile: false
• resultsJsonFilePath: testresults.json

Contributing

We welcome contributions to TestLab.js! To contribute:

1. Fork the Repository.
2. Clone your fork to your local machine
3. Create a new branch for your feature or bugfix.
4. Make your changes, add tests if neccessary.
5. Submit a pull request with a clear description of the changes. Please ensure that your code follows the existing coding style and passes all tests before submitting a pull request.

License

TestLab.js is released under the GNU General Public License Version 3, 29 June 2007. For full license details, see the LICENSE file.

Additional Features

• Test Hooks: TestLab.js supports setup and teardown hooks, which are executed before or after individual tests or before and after all tests:
  • beforeEach()
  • afterEach()
  • beforeAll()
  • afterAll()
• Diff Output: TestLab.js includes diff output to highlight what changed when an assertion fails.

Conact Information

Main Author: Sam Wilcox Email: [email protected] GitHub: https://github.com/nodebysam/TestLab.js Submit bugs at: https://github.com/nodebysam/TestLab.js/issues