Test-at-work NPM

test-at-work

npm NPM

A browser test runner with focus on test isolation and performance

Why?

Because there seems to be no other test runner that is able to run test cases in parallel and in isolation at the same time without spinning up multiple browsers.

Status

This is an unreleased prototype.

Planned for v1

Full extensibility through plugins
Customizable test isolation and concurrency
Watch for changes in dev mode
Optional browser ui.
Builtin support for:
- Webpack (as the test environment bundler)
- Jasmine (as the actual test framework)
- Chrome, Firefox launchers
- Istanbul code coverage (+ reporter)
- VSTS reporter

Planned for v2

Move builtin plugins to individual packages.

Terminology

Environment - Provides the files wou want to test (usually bundled sources and tests)
Framework - The adapter for detecting and running your tests.
Launcher - Starts a client (usually a browser) which connects to the taw server.
Reporter - Processes test and coverage results.

Installation

npm i -D test-at-work

Configuration

The configuration is a regular node module that is executed:

// taw.js
const { taw } = require("test-at-work");

taw({
    // Path to the context directory (usually the package root):
    context: ".",

    // The list of plugins to use.
    // All other options are optional.
    use: [
        // Include one environment plugin and
        // at least one launcher and reporter.
    ],

    // If true, development mode is enabled.
    dev: false,

    // Specify, where the server is listening:
    port: 0, // = random port
    host: "127.0.0.1",

    // Specify how many suites can be executed concurrently (per browser):
    // Default is the number of cpus on this machine.
    concurrency: cpus().length,

    // An object with options that is passed to the framework.
    // The properties of this object depend on the framework and must be json serializable.
    frameworkOptions: { },

    // Optional filters a suite or spec must match to be executed if any filter is specified:
    suiteFilter: [
        "Full display name to match",
        /regex to match/,
        { uid: "uid to match" }
    ],
    specFilter: [
        // Same as suite filters.
    ],
});

# Run tests:
node taw.js

Environment & Frameworks

The environment is everything that you need to test. To get started, you can use the WebpackEnv plugins.

Make sure to include the taw client and the framework you want to use:

<!DOCTYPE html>
<html lang="en">
	<head>
		<meta charset="utf-8">
		<meta name="viewport" content="width=device-width, initial-scale=1.0">
		<title>Env</title>
		<script src="/_taw/client.js"></script>
		<script src="/_taw/frameworks/jasmine.js"></script>
	</head>
	<body></body>
</html>

Currently, jasmine is the only available framework. However you can use any framework by implementing this interface.

Plugins

`WebpackEnv`

Bundle your sources and spec files using webpack

// taw.js
const { WebpackEnv } = require("test-at-work/dist/plugins/webpack-env");
const HtmlPlugin = require("html-webpack-plugin");

use: [
    // You can pass a webpack configuration or a compiler instance as argument:
    new WebpackEnv({
        // Minimal webpack config:
        entry: "./env.js";
        plugins: [
            new HtmlPlugin({
                // Make sure to include the taw client and framework in env.html:
                template: "./env.html",
                inject: "body"
            })
        ],
        output: {
            path: `${__dirname}/dist/test`,
            publicPath: "/"
        }
    })
]

// Example env.js
const specs = require.context("./tests", true, /\.spec\.js$/);
specs.keys().map(specs);

<!-- Example minimum env.html -->
<script src="/_taw/client.js"></script>
<script src="/_taw/frameworks/jasmine.js"></script>

`TerminalReporter`

Log test results and exit with non-zero exit code if any test fails or no test passes.

const { TerminalReporter } = require("test-at-work/dist/plugins/terminal-reporter");

use: [
    new TerminalReporter()
]

`ChromeLauncher`, `FirefoxLauncher`

Launch chrome and firefox instances to test.

const { ChromeLauncher } = require("test-at-work/dist/plugins/chrome-launcher");
const { FirefoxLauncher } = require("test-at-work/dist/plugins/firefox-launcher");

use: [
    new ChromeLauncher(options),
    new FirefoxLauncher(options)
]

options <object> - An optional object with the following properties:
- headless <boolean> - Run the browser in headless mode. Default is false.
Autodetection of executables is supported on windows only.
If you need to run taw on mac or linux, specify the CHROME_BIN or FIREFOX_BIN environment variables.

`IstanbulReporter`

Generate istanbul coverage reports.

const { IstanbulReporter } = require("test-at-work/dist/plugins/istanbul-reporter");

use: [
    new IstanbulReporter({
        // Required. The list of reports to generate:
        reporters: ["text-summary"],

        // Optional additional configuration:
        dir: "./coverage",
        skipEmpty: false,
        skipFull: false,

        // A string or an array of gitignore like filters for files to ignore:
        // By default, all node_modules directories are ignored.
        ignore: "node_modules"
    }),

    // Note that you have to instruct your environment plugin to instrument your code:
    // With webpack, you can use the following loader:
    // - npm i -D istanbul-instrumenter-loader
    new WebpackEnv({
        module: {
            rules: [
                { test: /\.js$/, loader: "istanbul-instrumenter-loader", options: { esModules: true, produceSourceMap: true } }
            ]
        }
    })
]

All istanbul reporters are supported.

`VstsReporter` (experimental)

Generate VisualStudio TeamTest reports.

const { VstsReporter } = require("test-at-work/dist/plugins/vsts-reporter");

use: [
    new VstsReporter(options)
]

options <object> - An optional object with the following properties:
- filename <string> - The path for storing the report. Default is testresults/testresults.xml
- computerName <string> - The computer name to use. Default is the hostname.
- projectName <string> - The project name to use. Default is the taw context's name.