tramline v0.3.1

Tramline

Tramline is a tiny JavaScript testing framework.

It supports a simple set of assertions as well as basic reporting tools.

This is not intended to replace established testing frameworks - it's an experiment designed for small projects with minimal testing requirements.

Introduction

Tramline is a tiny testing framework for JavaScript source code.

The framework has a minimal set of features for testing lightweight JavaScript in a basic environment.

This is not necessarily suitable for large-scale projects, but is viable as a streamlined alternative to existing test runners for small apps and libraries.

Features

• Test units and runs
• Built-in library of assertions
• Test suite execution timer
• Summary output in the console
• Exit codes for CI environments
• Modular architecture
• Uses ES6 imports
• Zero configuration: tests are defined in classes in files that get automatically discovered by the test runner.

To get started, continue reading this documentation.

API / Getting started

To get started, install Tramline from npm.

The library's default entrypoint has the following exports:

• Tramline - the main Tramline class (uninstantiated)
• Unit - base test unit class, from which your units must extend
• assert - default (truthy) assertion
• assertions - complete assertions library.

Architecture

Tramline is a streamlined zero-configuration test runner.

Tests are defined as classes inside standalone files.

Tests are executed by running the Tramline runner and pointing it to the directory in which your tests reside. The runner will automatically find your test files, import them at runtime, instantiate each unit and run the tests within.

For the remainder of this section, it's assumed you'll be creating your tests inside ./tests in your working directory.

Creating a test unit

To create a test, create a new JavaScript file in your tests directory and define a class inside it. This class represents your test unit and stores all the test methods within the unit.

The class must extend Tramline's Unit class, exported by the main entrypoint.

import {Unit} from "tramline";

class MyTest extends Unit {

	MyTestMethod() {
		//Your test code here
	}

}

export default MyTest;

Your test file must export your test class definition as its default export. This will be instantiated by Tramline when your tests are run.

Test methods

All methods inside your test unit will be executed sequentially. Reserved/default methods (e.g. constructor, hasOwnProperty) are automatically blacklisted.

In addition, all test hooks are omitted from automatic testing.

You can manually define the tests to run by overriding the __tests() method and returning an array of method names to execute as tests.

Test methods are considered to have failed if they throw an uncaught error; in all other circumstances, the test method is deemed to have passed. All errors are automatically caught for logging and reporting as part of the test suite.

Test hooks

All test methods with names starting with __ are deemed to be test hooks. These are auxiliary tests relating to the operation of the test suite or unit.

Test hooks are invisible in the suite's log output and statistics, unless they fail.

Tramline defines the following built-in hooks:

• __init - Run before any tests in the unit
• __run - Run before every test in the unit
• __after - Run after every test in the unit
• __finally - Run after all tests in the unit have finished.

You can create your own hooks by defining methods prefixed with __; these will also be omitted from the log output in the same way as built-in test hooks, and will not be executed automatically like regular test methods.

Therefore these methods can be used to define "private" methods/reusable blocks common to multiple test cases.

Fatal test hooks

Some test hooks are fatal - at present, these are __init and __run, because they run before test methods, and are expected to be critical to their behaviour.

A failure in these hooks will cause the unit to be aborted, cancelling the execution of any outstanding tests in the unit.

Test method arguments

The arguments delivered to test methods are always converted to an array (if not already an array) and then unpacked for delivery as variadic arguments.

Test methods always receive the return value from the __run hook, or __init if the unit does not define __run. The return value of test methods is made available to __after.

The __run and __finally hooks always receive the return value of __init.

Test methods can also access the return values of previous methods with the results property of their unit. This stores the return value of all previously executed methods by name. Note this will be overridden by the next run for hooks that are executed repeatedly - e.g. __run/__after.

By default, tests should be saved as .test.mjs (only these files will be loaded by Tramline). This can be changed with the --tests configuration key.

Important: Your test files must be saved with the .mjs extension and follow the ES6 import standards; Tramline uses ES6 for all imports, and nodejs requires the use of .mjs for this purpose.

Running your tests

Tramline is installed to .bin in your node_modules.

To run your tests, run tramline, passing your test directory as the first argument:

tramline ./tests;

Since Tramline already defaults to your working directory, and only runs valid test files in it, just invoking tramline will also be sufficient in many cases.

Configuration

Configuration keys should be passed on the command line after specifying the directory to run tests from. They are passed in the format --key value, where key is the key name and value is your value.

• tests – Defines the filename format that identifies test files. Defaults to .test.mjs. Only files that end with this extension will be considered to be test files; others will not be loaded and will be ignored.
• abortFailure – If specified with a truthy value (e.g. --abortFailure true), Tramline will terminate immediately as soon as a single test case fails.

When using the built-in Tramline test runner command, a test suite summary screen will be logged to the console/stdout after the execution of all the tests completes.

The process will then terminate with a status code appropriate for the test status - if all tests passed, it will be 0; otherwise, if any test failed, it will be 1.

Thank you for using Tramline!

©James Walker 2018. Licensed under the MIT License.