Universal Javascript Test Runner

Installation

$ npm install kinvey-universal-runner

Description

The goal of the runner is to provide an easy way to automate the testing in different javascript environments. Currently supported are:

• Web
• NativeScript
• Cordova
• ReactNative

Where is it used

• Kinvey HTML5 SDK
• Kinvey NativeScript SDK
• Kinvey Cordova SDK
• Kinvey Angular SDK
• Kinvey Angular 2 SDK

Structure

The runner is made out of two parts.

1. A nodejs library which makes it easy to automate serial tasks. Many of these tasks are especially usefull when managing test applications, collecting logs from these applications, file system interaction, shell commands, conditional tasks etc.
2. A library which is added in each test application. It includes a version of mocha and chai that supports all above mentioned environments, as well as helpers which help structure and run tests after the environment is ready.

Example

runner-config.js

const {
    Runner,
    tasks: {
        logServer,
        copy,
        runCommand
    },
    conditionals: {
        when
    }
} = require('kinvey-universal-runner');

const customTask = ['customTask', () => console.log('custom')];

const runner = new Runner({
    pipeline: [
        logServer(),
        runCommand({
            command: 'npm',
            args: ['run', 'build']
        }),
        customTask,
    ]
});

runner.run().then(() => console.log('done'));

Run it with node runner-config.js;

Tasks

Each task can be either:

• A function:

new Runner({
    pipeline: [
        function customTask(runner) {

        }
    ]
})

• An array:

new Runner({
    pipeline: [
        ['customTask', (arg, runner) => console.log('something' + arg), 5]
    ]
})

When tasks are specified as arrays they must have the following elements: The first one is the name of the task, the second one is the function to be executed and every next element is an argument that will be passed to the function.

Notes

• The instance of the runner will always be injected as a the argument
• Tasks can be asynchronous, as long as they return a promise
• The runner instance is an event emitter, it can be used for communication
• The runner can wait for an event to be emitted before exiting, by utilizing the waitForEvent(ev) method, usefull if you need to e.g. wait for the tests to end(built into logServer)

Built in Tasks

Import them as follows:

const {
    tasks: {
        logServer,
        copy,
        remove,
        copyTestRunner,
        runCommand,
        installPackages,
        processTemplateFile
    },
    conditionals: {
        when,
        ifThenElse
    }
} = require('kinvey-universal-runner');

logServer

Starts a log server on a random port. The logs send from the test application will be received and optionally logged to the console.

emits:

• log.start
• log.data
• log.end - the runner will not exit before log.end is fired

logServer(
    logToConsole = true //whether to log to the console
)

copy

Copies files or directories(recursively) from one location to another

copy(from, to)

remove

Removes files or directories(recursively)

remove(path)

copyTestRunner

Copies the test runner bundle that should be included in the test application to a specified directory

copyTestRunner(to)

runCommand

Runs a shell command

runCommand({ command, args, cwd })

installPackage

Installs npm packages

installPackages(packages)

processTemplateFile

Processes a handlebars template file with a context and creates a new file.

processTemplateFile(inputFile, contextObject, outputFile);

Conditionals

Conditionals can be used to execute tasks when given conditions are met. Conditional tasks can still return promises in the condition. The tasks to be executed can be the same format as all other tasks, making conditions chainable

when

Executes a task when a condition is met. The condition can be a simple expression or a function.

when(() => process.argv[3] === 'runLogServer', logServer())

ifThenElse

Executes a task if a condition is met, otherwise another task.

ifThenElse(() => new Promise(resolve => {
        let i = 0;
        const interval = setInterval(() => {
            i++;
            if (i === 5) {
                clearInterval(interal);
                resolve(true);
            }
        }, 1000);
    }),
    () => console.log('5 seconds passed'), 
    () => console.log('5 seconds didn\'t pass for some reason')
);

Contributing

When making changes to the test runner inside injectables make sure to run npm run build-deps to rebuild the bundle.