{"id":15375,"library":"rescript-test","title":"ReScript Test Framework","description":"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.","status":"active","version":"8.0.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","BuckleScript","ReScript","Test"],"install":[{"cmd":"npm install rescript-test","lang":"bash","label":"npm"},{"cmd":"yarn add rescript-test","lang":"bash","label":"yarn"},{"cmd":"pnpm add rescript-test","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for the ReScript compiler, essential for compiling and running tests.","package":"rescript","optional":false},{"reason":"Engine requirement for running the CLI and compiled tests.","package":"node","optional":false},{"reason":"Optional dependency used for simulating a browser DOM environment when running tests with the `--with-dom` flag.","package":"jsdom","optional":true}],"imports":[{"note":"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.","wrong":"import { retest } from 'rescript-test'; // CLI is not a JS module","symbol":"retest CLI","correct":"npx retest 'test/**/*.bs.js'"},{"note":"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.","wrong":"import { Test } from 'rescript-test'; // This is ReScript syntax, not JS.","symbol":"Test module (ReScript)","correct":"open Test"}],"quickstart":{"code":"yarn add --dev rescript-test\n\n# Add to bsconfig.json:\n# {\n#   \"bs-dev-dependencies\": [\n#     \"rescript-test\"\n#   ]\n# }\n\n# Create test/MyTest.res\n// test/MyTest.res\nopen Test\n\nlet intEqual = (~message=?, a: int, b: int) =>\n  assertion(~message?, ~operator=\"intEqual\", (a, b) => a === b, a, b)\n\ntest(\"Basic integer equality\", () => {\n  let actual = 1 + 1\n  let expected = 2\n  intEqual(~message=\"1 + 1 should be 2\", actual, expected)\n})\n\ntest(\"Async operation test\", () => {\n  // In a real scenario, this would involve a Promise or callback\n  // For simplicity, showing a synchronous pass.\n  pass()\n})\n\n# Run the tests\nnpx retest 'test/**/*.bs.js'","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure your project's `rescript` dependency matches or exceeds `^12.0.1`. Update ReScript compiler version if necessary via `npm install rescript@latest`.","message":"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.","severity":"breaking","affected_versions":"<8.0.0"},{"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.","message":"The `retest` CLI requires Node.js version 20.0.0 or higher. Running it with older Node.js versions will result in execution failures.","severity":"breaking","affected_versions":"<8.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Install `jsdom` as a dev dependency (`yarn add --dev jsdom`) and execute tests with `npx retest --with-dom 'test/**/*.bs.js'`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The ReScript compiler cannot locate the `rescript-test` module, likely due to incorrect `bsconfig.json` configuration or missing installation.","error":"Error: Cannot find module 'rescript-test/lib/js/src/Test.bs.js'"},{"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.","cause":"The `retest` executable is not in your system's PATH, or `rescript-test` is not installed.","error":"retest: command not found"},{"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.","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.","error":"Type Error: The module 'test.bs.js' could not be loaded due to a type mismatch in ReScript"},{"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`.","cause":"A custom assertion logic within your ReScript test file returned `false`, indicating an expected condition was not met.","error":"Assertion Failed: Char code should match"}],"ecosystem":"npm"}