Class NodeClient

Configures the Touca client. Must be called before declaring test cases and adding results to the client. Should be regarded as a potentially expensive operation. Should be called only from your test environment.

configure takes a variety of optional configuration parameters. Calling this function without any parameters is possible: the client can capture the behavior and performance data and store them on a local filesystem but it will not be able to post them to the Touca server.

In most cases, You will need to pass API Key and API URL during the configuration. The code below shows the common pattern in which API URL is given in long format (it includes the team slug and the suite slug) and API Key as well as the version of the code under test are specified as environment variables TOUCA_API_KEY and TOUCA_TEST_VERSION, respectively:

touca.configure({api_url: 'https://api.touca.io/@/acme/students'})

As long as the API Key and API URL to the Touca server are known to the client, it attempts to authenticate with the Touca server. You can explicitly disable this communication in rare cases by setting configuration option offline to false.

You can call configure any number of times. The client preserves the configuration parameters specified in previous calls to this function.

Declares name of the test case to which all subsequent results will be submitted until a new test case is declared.

If configuration parameter concurrency is set to "enabled", when a thread calls declare_testcase all other threads also have their most recent testcase changed to the newly declared one. Otherwise, each thread will submit to its own testcase.

Removes all logged information associated with a given test case.

This information is removed from memory, such that switching back to an already-declared or already-submitted test case would behave similar to when that test case was first declared. This information is removed, for all threads, regardless of the configuration option concurrency. Information already submitted to the server will not be removed from the server.

This operation is useful in long-running regression test frameworks, after submission of test case to the server, if memory consumed by the client library is a concern or if there is a risk that a future test case with a similar name may be executed.

Throws

when called with the name of a test case that was never declared

Captures the value of a given variable as a data point for the declared test case and associates it with the specified key.

Captures an external file as a data point for the declared test case and associates it with the specified key.

Logs a given value as an assertion for the declared test case and associates it with the specified key.

Adds a given value to a list of results for the declared test case which is associated with the specified key.

Could be considered as a helper utility function. This method is particularly helpful to log a list of items as they are found:

 for (const number of numbers) {
   if (is_prime(number)) {
     touca.add_array_element("prime numbers", number);
     touca.add_hit_count("number of primes");
   }
 }

This pattern can be considered as a syntactic sugar for the following alternative:

 const primes = [];
 for (const number of numbers) {
   if (is_prime(number)) {
     primes.push(number);
   }
 }
 if (primes.length !== 0) {
   touca.check("prime numbers", primes);
   touca.check("number of primes", primes.length);
 }

The items added to the list are not required to be of the same type. The following code is acceptable:

touca.check("prime numbers", 42);
touca.check("prime numbers", "forty three");

Throws

if specified key is already associated with a test result which was not iterable

See

check

Increments value of key every time it is executed. creates the key with initial value of one if it does not exist.

Could be considered as a helper utility function. This method is particularly helpful to track variables whose values are determined in loops with indeterminate execution cycles:

 for (const number of numbers) {
   if (is_prime(number)) {
     touca.add_array_element("prime numbers", number);
     touca.add_hit_count("number of primes");
   }
 }

This pattern can be considered as a syntactic sugar for the following alternative:

 const primes = []
 for (const number of numbers) {
   if (is_prime(number)) {
     primes.push(number);
   }
 }
 if (primes.length !== 0) {
   touca.check("prime numbers", primes);
   touca.check("number of primes", primes.length);
 }

Throws

if specified key is already associated with a test result which was not an integer

See

check

Adds an already obtained measurements to the list of captured performance benchmarks.

Useful for logging a metric that is measured without using this SDK.

Starts timing an event with the specified name.

Measurement of the event is only complete when function stop_timer is later called for the specified name.

Stops timing an event with the specified name.

Expects function stop_timer to have been called previously with the specified name.

Registers custom serialization logic for a given custom data type.

Calling this function is rarely needed. The library already handles all custom data types by serializing all their properties. Custom serializers allow you to exclude a subset of an object properties during serialization.

Stores test results and performance benchmarks in binary format in a file of specified path.

Touca binary files can be submitted at a later time to the Touca server.

We do not recommend as a general practice for regression test tools to locally store their test results. This feature may be helpful for special cases such as when regression test tools have to be run in environments that have no access to the Touca server (e.g. running with no network access).

Stores test results and performance benchmarks in JSON format in a file of specified path.

This feature may be helpful during development of regression tests tools for quick inspection of the test results and performance metrics being captured.

Submits all test results recorded so far to Touca server.

It is possible to call post multiple times during runtime of the regression test tool. Test cases already submitted to the server whose test results have not changed, will not be resubmitted. It is also possible to add test results to a testcase after it is submitted to the server. Any subsequent call to post will resubmit the modified test case.

Throws

if called before calling configure or when called on a client that is configured not to communicate with the Touca server or if operation fails for any reason.

Returns

a promise that is resolved when all test results are submitted.

Notifies the Touca server that all test cases were executed for this version and no further test result is expected to be submitted. Expected to be called by the test tool once all test cases are executed and all test results are posted.

Sealing the version is optional. The Touca server automatically performs this operation once a certain amount of time has passed since the last test case was submitted. This duration is configurable from the "Settings" tab in "Suite" Page.

Throws

if called before calling configure or when called on a client that is configured not to communicate with the Touca server or if operation fails for any reason.

Returns

a promise that is resolved when all test results are submitted.

High-level API designed to make writing regression test workflows easy and straightforward. It abstracts away many of the common expected features such as logging, error handling and progress reporting. The following example demonstrates how to use this API.

 import { touca } from '@touca/node';
 import { find_student, calculate_gpa } from  './code_under_test';

 touca.workflow('test_students', (testcase: string) => {
   const student = find_student(testcase);
   touca.assume('username', student.username);
   touca.check('fullname', student.fullname);
   touca.check('birth_date', student.dob);
   touca.check('gpa', calculate_gpa(student.courses));
 });

 touca.run();

Runs the registered workflows.