# 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:
```q
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.
```q
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:
```q
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](https://github.com/KxSystems/unit-test){target=_blank} for:

- [Unit Test module reference](https://github.com/KxSystems/unit-test/blob/main/docs/reference.md){target=_blank}
- [Installation guide](https://github.com/KxSystems/unit-test/blob/main/docs/install.md){target=_blank}
- [Example tests](https://github.com/KxSystems/unit-test/tree/main/tests){target=_blank}