@touca/node

Touca JavaScript SDK

Write regression tests, the easy way.

import { touca } from '@touca/node';
import { important_workflow } from './code_under_test';

touca.workflow('test_important_workflow', (testcase: string) => {
  const number = Number.parseInt(testcase);
  touca.check('output', important_workflow(number));
});

touca.run();

Table of Contents

• Touca JavaScript SDK
  • Table of Contents
  • Requirements
  • Install
  • Usage
  • Documentation
  • Community
  • Contributing
  • License

Requirements

• Node 12 or newer

Install

You can install Touca with npm:

npm install --save-dev @touca/node

Usage

Suppose we want to test a software that checks whether a given number is prime.

export function is_prime(input: number): boolean {
  for (let i = 2; i < input; i++) {
    if (input % i === 0) {
      return false;
    }
  }
  return 1 < input;
}

We can use unit testing in which we verify that the actual output of our function matches our expected output, for a small set of possible inputs.

import { is_prime } from './is_prime';

test('is_prime_test', () => {
  expect(is_prime(2)).toEqual(true);
  expect(is_prime(4)).toEqual(false);
});

Touca is different from unit testing:

• Touca tests do not hard-code input values.
• Touca tests do not hard-code expected outcome.

import { touca } from '@touca/node';
import { is_prime } from './is_prime';

touca.workflow('is_prime_test', (testcase: string) => {
  const number = Number.parseInt(testcase);
  touca.check('output', is_prime(number));
});

touca.run();

With Touca, instead of verifying that the actual behavior of our software matches our expected behavior, we compare it against the actual behavior of a previous baseline version. This approach has two benefits:

• We can test our software with a much larger set of possible inputs.
• We won't need to change our test code when the expected behavior of our software changes.

Touca allows capturing values of any number of variables and runtime of any number of functions to describe the actual behavior and performance of our software.

This approach is similar to snapshot testing where, for each test case, we store the actual output of our software in a snapshot file, to compare outputs of future versions against them. But unlike snapshot tests, Touca tests submit our captured data to a remote server that automatically compares it against our baseline and visualizes any differences.

We can run Touca tests with any number of inputs from the command line:

export TOUCA_API_KEY=<TOUCA_API_KEY>
export TOUCA_API_URL=<TOUCA_API_URL>
node dist/is_prime_test.js --testcase 19 51 97

Where API Key and URL can be obtained from app.touca.io or your self-hosted server. This command produces the following output:

Now if we make changes to our workflow under test, we can rerun this test and rely on Touca to check if our changes affected the behavior or performance of our software.

Unlike integration tests, we are not bound to the output of our workflow. We can capture any number of data points and from anywhere within our code. This is specially useful if our workflow has multiple stages. We can capture the output of each stage without publicly exposing its API. When any stage changes behavior in a future version of our software, our captured data points will help find the root cause more easily.

Documentation

• Documentation Website: If you are new to Touca, this is the best place to start.
• JavaScript SDK API Reference: Auto-generated source code documentation for Touca JavaScript SDK with explanation about individual API functions.
• JavaScript Examples: Sample JavaScript projects that show how to use Touca in various real-world use-cases.

Community

We hang on Discord. Come say hi! We love making new friends. If you need help, have any questions, or like to contribute or provide feedback, that's the best place to be.

Contributing

We welcome contributions of all forms, from adding new features to improving documentation and sharing feedback.

• Code of Conduct
• Contributing Guide
• Good First Issues

License

This repository is released under the Apache-2.0 License. See LICENSE.