zekr

A simple test framework for ReScript.

Installation

npm install zekr

Add to your rescript.json:

{
  "dev-dependencies": ["zekr"]
}

Usage

open Zekr

let myTests = suite("My Tests", [
  test("addition works", () => {
    assertEqual(1 + 1, 2)
  }),
  test("strings match", () => {
    assertEqual("hello", "hello")
  }),
  test("condition is true", () => {
    assertTrue(10 > 5)
  }),
])

runSuites([myTests])

API

Creating Tests

// Create a single test
let myTest = test("test name", () => {
  // return Pass or Fail(message)
  Pass
})

// Create a test suite
let mySuite = suite("Suite Name", [test1, test2, test3])

Setup/Teardown Hooks

Add lifecycle hooks directly to your test suites:

// Synchronous hooks
let mySuite = suite(
  "Database Tests",
  [test1, test2, test3],
  ~beforeAll=() => initializeDatabase(),
  ~afterAll=() => closeDatabase(),
  ~beforeEach=() => clearTables(),
  ~afterEach=() => resetState(),
)

// Async hooks
let myAsyncSuite = asyncSuite(
  "API Tests",
  [asyncTest1, asyncTest2],
  ~beforeAll=async () => await connectToServer(),
  ~afterAll=async () => await disconnectFromServer(),
  ~beforeEach=async () => await resetMocks(),
  ~afterEach=async () => await cleanup(),
)

All hooks are optional - you only need to provide the ones you need:

// Only beforeEach hook
let mySuite = suite(
  "My Tests",
  [test1, test2],
  ~beforeEach=() => resetState(),
)

Async Tests with Timeout

Async tests support an optional timeout parameter (in milliseconds). Tests that exceed the timeout will fail automatically. Uncaught exceptions in async tests are also caught and reported as failures.

let myAsyncTests = asyncSuite("API Tests", [
  // Test with 5 second timeout
  asyncTest("fetches data", async () => {
    let data = await fetchData()
    assertEqual(data.status, "ok")
  }, ~timeout=5000),

  // Test without timeout (runs until completion)
  asyncTest("processes data", async () => {
    let result = await processData()
    assertTrue(result.success)
  }),
])

Assertions

// Check equality
assertEqual(actual, expected)
assertEqual(actual, expected, ~message="custom message")

// Check inequality
assertNotEqual(actual, expected)

// Check boolean conditions
assertTrue(condition)
assertFalse(condition)

// Combine multiple results
combineResults([result1, result2, result3])

Snapshot Testing

Test complex data structures by comparing against stored snapshots:

let snapshotTests = suite("API Response", [
  test("user data matches snapshot", () => {
    let user = {"id": 1, "name": "Alice", "roles": ["admin", "user"]}
    assertMatchesSnapshot(user, ~name="user-data")
  }),
])

On first run, snapshots are created in __snapshots__/ directory. Subsequent runs compare against stored snapshots.

// Configure custom snapshot directory
setSnapshotDir("tests/__snapshots__")

// Update a snapshot programmatically
updateSnapshot(newValue, ~name="snapshot-name")

Test Filtering

Filter tests using environment variables:

# Run only tests matching "user"
ZEKR_FILTER="user" node tests/MyTests.js

# Skip tests matching "slow"
ZEKR_SKIP="slow" node tests/MyTests.js

# Combine filter and skip
ZEKR_FILTER="api" ZEKR_SKIP="integration" node tests/MyTests.js

Filtering is case-insensitive and matches against both suite and test names.

Watch Mode

Automatically re-run tests when files change:

// In a separate watch script (e.g., watch.res)
open Zekr

watchMode(
  ~testCommand="node tests/MyTests.js",
  ~watchPaths=["src", "tests"],
  ~buildCommand="npx rescript",
)

Run with: node watch.js

The watch mode will:

• Run an initial test pass
• Watch specified paths for file changes
• Re-build (if buildCommand provided) and re-run tests on changes
• Debounce rapid file changes

Running Tests

// Run a single suite
runSuite(mySuite)

// Run multiple suites
runSuites([suite1, suite2, suite3])

License

MIT