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 type | Support | Input/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 callf(getDataframe()) |
column_list | * | Requires a dataframe parameterf(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: