Skip to main content

Add package tests

Packages developed for the platform should be tested. Datagrok supports several mechanisms for testing purposes. This article provides instructions for utilizing these mechanisms in the package code.

Adding unit tests​

We use a custom test framework that is similar to Jest, and it supports Datagrok API. To learn more about that, see our guide for packages.

To add tests for local testing, run the following command:

grok create <package-name> --test

If you need to add tests support to an existing package, run this command instead:

cd <package-name>
grok add tests

Once you get package dependencies (npm install), you can start writing tests. First, create a folder for your test files:

cd <package-name>/src
mkdir tests

Each file typically includes tests for one category. Here is an example:

import { category, expect, test } from '@datagrok-libraries/utils/src/test';


category('Examples', () => {
  test('Success', async () => {
    expect(1, 1);
  });

  test('Fail', () => {
    throw 'Exception';
  });
});

Next, make sure to import your test files in src/package-test.ts. After that, build and publish your package. There are several options to runs the tests: locally using datagrok-tools, via DG console, and via Test manager. All public packages in the repository are tested using GitHub Actions on every commit. There is an option to trigger GitHub Actions manually, if something goes wrong during the auto-check.

For some real-life examples, please refer to the Chem package, which has everything properly configured and all tests written properly.

Skipping tests​

If a test fails for some reason, you can skip it using the skipReason parameter (specify a reason for skipping the test, for example, the associated Jira issue key or GitHub issue number):

test('Skipped', async () => {
  expect(1, 11);
}, {skipReason: 'GROK-99999'});

Testing functions​

Every package utilizes the concept of functions. Tests cases can be added directly to a function's annotation. Afterwards, the metadata is used to test package functions automatically. Use the test parameter to add test cases. A test is essentially any grok script expression that will be evaluated to a boolean value. Here are some examples:

//name: square
//input: int x
//output: int y
//test: square(1) == 1
//test: square(2) == 4
//test: square(3) == 9
export function square(x: number): number {
  return x ** 2;
}

Functions with the following input/output parameter types can be tested using the test annotation:

Parameter typeSupportInput/output example
int✓test: f(123) == 246
double✓test: 10 < f(12.5) && f(12.5) < 20
bool✓test: f(true),
test: returnsBool()
string✓test: f("a") == "b" (use "" for strings)
datetime✓test: f("1/1/2020") == Date(2020, 1, 1),
test: DateDiff(DateTime(2020, 1, 1, 3, 0, 0, 0), "2020-01-01") == 10800000
map✓f({"a": 10, "b": "c"}),
test: f("abc").testparam == "abc"
dataframe*Works via an additional function call
f(getDataframe())
column_list*Requires a dataframe parameter
f(getDataframe(), ["colname1", "colname2"])
column*Works via an additional function call
file*Works via an additional function call
blob*Works via an additional function call

See also: