Skip to content

Unit Test Module

This page explains what the Unit Test module is and when to use it.

The Unit Test module is a testing framework for q code. It provides assertions, feature grouping, setup and teardown hooks, mocking, selective test execution, and JUnit XML output, so you can check that your q code works as expected and run the checks in a CI pipeline.

This module is implemented under the KDB-X module framework. After you install it, load it with use and assign it to any name:

t:use`kx.test

Features

  • Assertions – Check results with assertMatch, assertEqual, assertType, assertTrue, assertFalse, assertNull, and assertError. Each assertion accepts a lambda or a string.
  • Features – Group related tests with feature.
  • Setup and teardown – Create dependencies once with setup and before, or around every test with beforeEach and afterEach. Clean up with after and teardown.
  • Mocking – Replace variables for the duration of a test with mock, and restore them with unmock.
  • Selective execution – Use config to run or skip tests by feature, by name, or by regular expression. You can also mark individual tests to skip.
  • Debugging – Stop in the interactive debugger when a test errors or fails.
  • Metrics – Record the execution time and memory use of each test.
  • Repeat and parallel runs – Repeat a test, or run it under peach to find bugs that appear only in parallel evaluation.
  • Reproducible runs – Set the random seed with setSeed or setRandomSeed.
  • Reports – Read results from getReport, and convert them to JUnit XML with junitReport.

Example

Group assertions into a feature. Each assertion takes the code to test, the expected result, and an options dictionary. Pass :: to use the default options.

t:use`kx.test

t.feature`math
t.assertMatch[{1+1};2;([name:"one plus one"])]
t.assertType[{1i+1i};"i";::]
t.assertTrue[{2~1+1};::]
t.assertError[{1+`f};"type";([name:"type error is signaled"])]

Each assertion adds a row to the report. To view the results:

select feature,name,status from t.getReport[]

Use cases

The Unit Test module is most useful for:

  • Testing q libraries and modules – Verify the behavior of functions as you develop them.
  • Regression testing – Re-run a suite of tests after each change to catch unintended differences.
  • Continuous integration – Export results as JUnit XML so that CI systems can report passes and failures.
  • Isolated tests – Mock variables and set up data for each test without affecting other code.

Further information

Refer to the Unit Test GitHub documentation for: