README.md

kuta

Experimental parallel test runner for node

npm install kuta

Introduction

This is an attempt at a parallel test runner for node. Parallellism is achieved by starting a number of processes and feeding them test-files. As soon as one process is done running a test file it will be given a new one.

Design goals

• Fast execution times by running tests in parallel
• Agnostic towards assertion libraries, as long as exceptions are thrown or promises returned.
• Small API, few features, little configuration

Trade-offs

• No TAP support(files are run one by one, so total number of tests are unknown)
• Processes are reused which means that test clean up has to be done for each test. If one test "leaks" into another it can be hard to debug since it is not deterministic which process will run which test.

Usage

Writing tests

import { test } from "kuta";

test.before(() => {
  // Some setup
});

test.after(() => {
  // Some tear down
});

test.beforeEach(() => {
  // Will run before each test
});

test.afterEach(() => {
  // Will run after each test
});

// Synchronous test
test("it should work", () => {
  assert(true);
});

// Asynchronous test (return a promise)
test("it should work", () => {
  return fetch("http://url.se").then((response) => {
    assert(response.ok);
  });
});

//  Grouped tests
test.group("a group", (t) => {
  t.before(() => {
    // Will run before tests in group
  });

  t.after(() => {
    // Will run after tests in group
  });

  t("a test in this group", () => {});
});

// Only running some tests
test.only("will only run this test", () => {});

test.only("and this since it also has only", () => {});

// Skipped tests
test.skip("this will not run", () => {});

test.group.skip("nor will this group", (t) => {
  t("or any tests withing it", () => {});
});

Running tests

Tests are run with the kuta command:

  Usage: kuta [options] testfiles

  Options:
   -r, --require            Files to require before running tests
   -p, --processes          Number of processes in the process pool
   -t, --timeout            Number of milliseconds before tests timeout
       --reporter           progress or spec(default)

Example:

kuta tests/**/*.js

Configuration

Kuta looks for a kuta-section in package.json where options can be defined. CLI arguments take precendence over package.json config.

Example package.json:

{
  "name": "my-app",
  "kuta": {
    "requires": ["testSetup.js", "babel-register"],
    "files": ["tests/*.js"],
    "processes": 8,
    "timeout": 1000
  }
}

Environment variables

You can also use the following environment variables to configure kuta

• KUTA_PROCESSES: Number of processes in the process pool
• KUTA_TIMEOUT: Number of milliseconds before tests timeout
• KUTA_REPORTER: Which reporter to run

If the same option is supplied from multiple sources the priority is

1. CLI argument
2. kuta-section in package.json
3. Environment variable

Babel

If you transpile with babel, use the babel-register hook:

kuta tests/**/*.js --require babel-register

Parallel processes

Since processes are run in parallel, test that spawn services on specific port will run into problems where two processes try to allocate the same port. To overcome this, kuta sends an environment variable with an index to each of the processs that can be used to generate unique ports for different processes.

The environment variable is KUTA_PROCESS_INDEX

Mocha compatibility

Kuta includes a mocha and mocha-cakes compatability layer:

import { describe, it } from "kuta/lib/mocha-compat";

describe("mocha style", () => {
  before(() => {});
  after(() => {});

  it("should work", () => {
    describe("inner group", () => {});
  });
});

Mocha cakes

import { Feature, Scenario, Given, When, Then, But } from "kuta/lib/mocha-compat";

Feature("Feature", () => {
  Scenario("", () => {
    Given("a given", () => {});

    When("something happens", () => {});

    Then("something is expected", () => {});

    And("another thing should be expected", () => {});

    But("not this thing", () => {});
  });
});

Licence

MIT Copyright Daniel Lundin