Overview

Miso.Test is a lightweight hspec-style testing framework for miso Component integration tests. It runs in the browser (or a JSDOM environment) via Playwright, giving each test full access to the live DOM.

Tests are written as StateT TestState IO, which means they can call any IO action — including miso DOM operations and FFI calls — directly. Each it block is timed and its result is printed with coloured output. After all tests run, runTests prints a summary and calls exitSuccess or exitFailure so the process exit code reflects the test outcome.

Quick start

import Miso.Test
import Miso.Runtime.Internal (components)
import Data.IORef (writeIORef)
import qualified Data.IntMap.Strict as IM

main :: IO ()
main = runTests $ do
  describe "Arithmetic" $ do
    it "2 + 2 = 4" $
      (2 + 2) `shouldBe` (4 :: Int)
    it "3 /= 4" $
      (3 :: Int) `shouldNotBe` 4

  describe "Component" $
    beforeEach (writeIORef components IM.empty) $ do
      it "mounts without error" $ do
        -- mount a component and assert on DOM state
        pure ()

Combinators

• describe — group related tests under a label.
• it — declare a single named test; times it and records pass/fail.
• beforeEach — run an IO action before every it in the wrapped block.
• afterEach — run an IO action after every it in the wrapped block.

Assertion primitives

• x `shouldBe` y — assert x == y; pretty-prints a diff on failure.
• x `shouldNotBe` y — assert x /= y.
• x `shouldSatisfy` p — assert that the predicate p x holds.
• expect f x y — assert f x y; the most general form.

Multiple assertions within a single it block are all evaluated; the block is marked as failed if any assertion fails.

Running tests

runTests :: Test a -> IO () is the entry point. It executes the test tree, prints per-test results and a final summary (pass count, fail count, total tests, total duration, and expect() call count), then exits:

• exitSuccess — all tests passed.
• exitFailure — one or more tests failed.

When compiled with -DJSDOM, runTests additionally calls globalThis.initJSDOM() before running any tests, enabling headless DOM testing outside a real browser.

Utilities

• choose min max — returns a uniformly random Int in [min, max) using the JS getRandomNumber global. Useful for property-style tests that need random inputs.

Types

• Test a = StateT TestState IO a — the test monad.
• TestState — internal state tracking per-test timing, pass/fail counts, before/after hooks, and error messages.

See also

• Miso.Runtime.Internal — components IORef for resetting state between tests
• Miso.Random — newStdGen, replicateRM for random values
• Miso — the component and effect API under test