ReScript Test Framework

8.0.0 · active · verified Tue Apr 21

rescript-test is a lightweight and performant test framework designed specifically for ReScript projects. Currently at version 8.0.0, it provides a native ReScript API for writing unit and integration tests, leveraging ReScript's type system for robust assertions. It integrates directly into the ReScript build pipeline, running compiled `.bs.js` files. The framework offers core testing primitives like `test`, `testAsync`, and flexible `assertion` functions, alongside utilities for setup/teardown and optional DOM simulation via JSDOM. It aims to provide a straightforward, type-safe testing experience tailored for the ReScript ecosystem, differentiating itself from general JavaScript test runners by its deep integration with ReScript's language features. It appears to be actively maintained, with updates typically correlating with ReScript compiler releases.

Common errors

```
Error: Cannot find module 'rescript-test/lib/js/src/Test.bs.js'
```
cause The ReScript compiler cannot locate the `rescript-test` module, likely due to incorrect `bsconfig.json` configuration or missing installation.

fix Ensure `rescript-test` is listed in your `bs-dev-dependencies` array within `bsconfig.json` and that `yarn add --dev rescript-test` has been run successfully.
```
retest: command not found
```
cause The `retest` executable is not in your system's PATH, or `rescript-test` is not installed.

fix Install `rescript-test` as a dev dependency (`yarn add --dev rescript-test`). If installed, try running with `npx retest ...` to execute the local package binary.
```
Type Error: The module 'test.bs.js' could not be loaded due to a type mismatch in ReScript
```
cause A mismatch between the expected types by `rescript-test` and the types provided in your ReScript test code, or using an assertion with incompatible types.

fix Review your ReScript test code for type errors highlighted by the ReScript compiler. Ensure arguments passed to assertions like `intEqual` or `stringEqual` match their defined types. Recompile your ReScript code (`npm run res:build` or `yarn res:build`) before running tests.
```
Assertion Failed: Char code should match
```
cause A custom assertion logic within your ReScript test file returned `false`, indicating an expected condition was not met.

fix Examine the test case where the failure occurred. Debug the values being compared against your assertion logic to understand why the condition `(a, b) => a === b` or your custom comparator returned `false`.

Warnings

breaking This package is a ReScript-native testing framework and requires the ReScript compiler (version ^12.0.1 or higher) as a peer dependency. Using it with significantly older ReScript versions will lead to compilation errors or unexpected runtime behavior.
Fix: Ensure your project's `rescript` dependency matches or exceeds `^12.0.1`. Update ReScript compiler version if necessary via `npm install rescript@latest`.
breaking The `retest` CLI requires Node.js version 20.0.0 or higher. Running it with older Node.js versions will result in execution failures.
Fix: Upgrade your Node.js runtime environment to version 20.0.0 or newer. Use a version manager like `nvm` to easily switch Node.js versions.
gotcha The `rescript-test` API (e.g., `test`, `assertion`) is designed for use within ReScript source files (`.res`). There are no direct JavaScript module exports for these testing utilities. Attempts to `import` or `require` them directly in JavaScript or TypeScript files will fail.
Fix: Write your tests in ReScript (`.res` files) and compile them to JavaScript. Then, use the `retest` CLI to run the compiled `.bs.js` test files.
gotcha To enable DOM testing functionality, the `--with-dom` flag must be explicitly passed to the `retest` CLI. This feature relies on `jsdom` which is an optional peer dependency; ensure it's installed if you intend to use DOM testing.
Fix: Install `jsdom` as a dev dependency (`yarn add --dev jsdom`) and execute tests with `npx retest --with-dom 'test/**/*.bs.js'`.

Install

npm install rescript-test npm
yarn add rescript-test yarn
pnpm add rescript-test pnpm

Imports

retest CLI
wrong:
```
import { retest } from 'rescript-test'; // CLI is not a JS module
```
correct:
```
npx retest 'test/**/*.bs.js'
```
The `retest` command-line interface (CLI) is the primary way to execute tests written with `rescript-test`. The actual testing API (`test`, `assertion`, etc.) is consumed directly within ReScript source files (`.res`) using `open Test` and does not expose direct JavaScript module imports for these functions. Attempting to import or require it in JavaScript code will result in module not found errors for the testing API itself.
Test module (ReScript)
wrong:
```
import { Test } from 'rescript-test'; // This is ReScript syntax, not JS.
```
correct:
```
open Test
```
Within ReScript source files, the `Test` module is made available via `open Test` at the top of your test file, similar to importing a namespace in other languages. This exposes functions like `test`, `assertion`, `throws`, etc., for use in your ReScript code.

Quickstart

Demonstrates how to install `rescript-test`, configure `bsconfig.json`, write a basic ReScript test file with custom assertions, and execute it using the `retest` CLI.

yarn add --dev rescript-test

# Add to bsconfig.json:
# {
#   "bs-dev-dependencies": [
#     "rescript-test"
#   ]
# }

# Create test/MyTest.res
// test/MyTest.res
open Test

let intEqual = (~message=?, a: int, b: int) =>
  assertion(~message?, ~operator="intEqual", (a, b) => a === b, a, b)

test("Basic integer equality", () => {
  let actual = 1 + 1
  let expected = 2
  intEqual(~message="1 + 1 should be 2", actual, expected)
})

test("Async operation test", () => {
  // In a real scenario, this would involve a Promise or callback
  // For simplicity, showing a synchronous pass.
  pass()
})

# Run the tests
npx retest 'test/**/*.bs.js'

view raw JSON →