Testing.

How it works

The library is a thin, runner-agnostic toolkit over the genuine runtime. It deliberately mirrors how a user — or an LLM — actually runs your program, so a passing test means the real pipeline works:

• You test the program string, not internals. The unit of authorship in Aktion is a $app(...) program, so render(source) mounts a real <aktion-app> and exercises the genuine parse → plan → render → morph pipeline — real reactivity, real effects, real two-way binding, real router. No mocking of the framework.
• You query the rendered shadow DOM, not private state. Queries (getByRole, getByText, …) search the element’s shadow root for what the user can see. Prefer accessible queries (role / label / text) over implementation details, exactly as in Testing Library.
• Assertions target output, $state, and events. Read reactive atoms with screen.state.get("count") (backed by serializeState()), and capture assistant-message, route-change, error, and custom $emit(...) events with screen.emitted(...).
• Async is first-class. Aktion renders on the microtask queue, so interactions auto-flush and findBy* / waitFor retry until the next paint settles — no manual await Promise.resolve() plumbing.

Setup

The library works with any runner that provides a DOM (Vitest, Jest, Web Test Runner) — it has zero runner dependencies. The examples here use Vitest with happy-dom (jsdom works too). A custom-element + shadow-DOM-capable DOM is the only requirement.

npm i -D vitest happy-dom

// vitest.config.ts
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: { environment: "happy-dom" },   // or "jsdom"
});

Then import the helpers from aktion-runtime/test:

import { render, renderComponent, cleanup, flush, json } from "aktion-runtime/test";

render returns a Screen scoped to that instance’s shadow root (there is no single global screen — each mounted program owns its own, which keeps shadow roots isolated). Wire cleanup into your runner’s afterEach so each test starts clean:

import { afterEach } from "vitest";
import { cleanup } from "aktion-runtime/test";

afterEach(cleanup);   // unmounts every screen, restores mocked fetch + the route

Your first test

A complete test of a reactive counter — render, assert the initial UI, click, then assert both the reactive $state and the re-rendered DOM.

import { describe, it, expect, afterEach } from "vitest";
import { render, cleanup, flush } from "aktion-runtime/test";

afterEach(cleanup);

it("increments the counter", async () => {
  const screen = render(`
    $count = 0
    $app(Column([
      Text(\`Count: \${$count}\`),
      Button("Increment", { onClick: () => $count = $count + 1 })
    ]))
  `);
  await flush();                                  // settle the first paint

  expect(screen.getByText("Count: 0", { exact: false })).toBeTruthy();

  await screen.click("Increment");                // finds the button by text

  expect(screen.state.get("count")).toBe(1);      // reactive state updated
  expect(screen.getByText("Count: 1", { exact: false })).toBeTruthy();
});

render(...) is synchronous (like RTL), but the first paint lands on the next microtask — so await flush() once before synchronous getBy* assertions, or use await screen.findByText(...) which waits for you. Interactions (screen.click, screen.user.*) always auto-flush.

Testing a real app: renderCompiled

render(source) takes a program string, which cannot express a multi-file app: imports are resolved by the linker at build time, so the text of an entry module is not a runnable program on its own. Pass the compiled artefact instead — what aktion-runtime/vite turns your entry into.

import { renderCompiled, json } from "aktion-runtime/test";
import app from "../src/app.aktion";          // a CompiledProgram

it("shows the cluster list", async () => {
  const screen = renderCompiled(app, {
    route: "/clusters",
    fetch: () => json({ items: [] }),
  });
  await screen.findByText("No clusters yet");
});

Every RenderOptions field applies. Two are worth calling out for a real app: httpInterceptors installs the same registerHttpInterceptors(...) hooks your host page uses (so you can assert the auth header your program never sees), and state seeds $state before the first plan.

Outside a Vite build — a Node script, an SSR pass, a lint rule — aktion-runtime/vite exports the compiler directly:

import { compileAktionFile, compileAktionSource } from "aktion-runtime/vite";

const app = compileAktionFile("src/app.aktion", { root: "src" });

// An inline program whose imports resolve against the real filesystem: the way
// to unit-test a `.aktion` helper module without a fixture file per case.
const probe = compileAktionSource(
  `import { formatBytes } from "./src/lib/format.aktion"\n` +
  `$app(Text(formatBytes(2048)))`,
  "tests/probe.aktion",
  { root: process.cwd() },
);

Coverage

A .aktion file compiles to a module that does nothing but JSON.parse its own AST, so V8 and Istanbul report one executed line however much DSL sits behind it. Real coverage is a property of the interpreter: which AST nodes did the evaluator reach? Turn the recorder on and read it back.

import { beforeAll, afterAll } from "vitest";
import { coverage } from "aktion-runtime/test";

beforeAll(() => { coverage.start(); });

afterAll(() => {
  const report = coverage.report();
  console.log(coverage.formatSummary(report));
  writeFileSync("coverage/aktion.lcov", coverage.toLcov(report));
});

The report is per .aktion file, in the same terms lcov uses: lines (every line carrying a node the evaluator can reach), functions (each component / action / hook / effect / lambda, counted when its body actually runs — so a click handler that never fires shows up), and branches (both arms of every if and ternary, each short-circuiting &&/||/??, and each switch case). uncoveredLines per file is the actionable list.

Measurement accumulates across every render/renderCompiled in the file, so each test contributes. Because a runner isolates each test file in its own worker, a whole-suite number has to be assembled from shards: write coverage.report() per file, then coverage.merge(shards) in a global teardown.

What is not instrumented, stated plainly because a coverage number that hides its gaps is worse than none: blank lines, comments and closing braces are not executable and are absent from the report entirely (as in an instrumented JS file); Literal, Member, Object and Array nodes carry no source position, so a line holding only those is not counted; and a literal $x = 1 initialiser is attributed to its declaration rather than folded separately.

Queries

Queries search the shadow DOM for elements. As in Testing Library, prefer queries that resemble how a user finds things — by ARIA role and accessible name, then visible text, then label.

The matcher is a string (exact, normalised text by default; pass { exact: false } for a substring), a RegExp, or a predicate (text, el) => boolean.

Test ids: root elements and empty output

getByTestId only finds something once a component actually carries a matching data-testid — give it one with the testId prop (see the universal props). Two things to know before you rely on it:

• A test id marks the component’s root. On a labelled form field the root is the field wrapper, not the control inside it, so scope a second query to reach the control: within(getByTestId("email")).getByRole("textbox").
• No element, no attribute. A component that renders nothing — Show(false, [...]) with no fallback, for example — has no node to carry data-testid, so queryByTestId correctly returns null rather than finding a hidden placeholder.

Query variants

Every query comes in the familiar six flavours:

Use queryBy* to assert absence (expect(screen.queryByText("Error")).toBeNull()) and findBy* to assert something that appears after an effect, timer, or network request resolves.

Scoped queries with within

When a page has several similar regions (cards, rows, list items), scope a query to one subtree with within(node). It returns the same query suite, but rooted at node instead of the whole shadow tree.

import { render, within } from "aktion-runtime/test"

const { getByTestId } = render(program)
const row = getByTestId("row-7")
expect(within(row).getByRole("button", { name: "Delete" })).toBeTruthy()

Interactions

Interactions dispatch real DOM events — the same ones a browser fires — and then flush the reactive queue. Two-way binding, onClick handlers, and effects all run exactly as in production.

Two-way binding

Typing into a bound input writes straight through to the reactive atom — the genuine binding path, not a simulation.

it("binds an input to $state", async () => {
  const screen = render(`
    $name = ""
    $app(Column([
      Input("Name", { value: $name }),
      Text(\`Hi \${$name}\`)
    ]))
  `);
  await flush();

  await screen.type(screen.getByRole("textbox"), "Ada");

  expect(screen.state.get("name")).toBe("Ada");
  expect(screen.getByText("Hi Ada", { exact: false })).toBeTruthy();
});

Asserting on reactive state

screen.state reads the live reactive snapshot. It is the cleanest way to assert behaviour that isn’t (or isn’t only) visible in the DOM.

Names are the ones the author wrote. In a multi-file program the linker gives every non-entry module private scope by renaming its atoms — $count declared in lib/store.aktion is __a1_count in snapshot(), and the numeric part changes when an unrelated import is added. Every member above resolves that for you; hard-coding the mangled key is what breaks.

// Seed initial state, then assert a derived/computed atom.
const screen = render(`
  $price = 0
  $qty   = 0
  $total = $price * $qty
  $app(Text(\`Total: \${$total}\`))
`, { state: { price: 10, qty: 3 } });

await flush();
expect(screen.state.get("total")).toBe(30);

Async, effects & timers

Aktion schedules renders on the microtask queue. The library exposes three escalating tools:

For setInterval / "every(N)" / debounced effects, use your runner’s fake timers. flush() still works because microtasks are not faked.

import { vi } from "vitest";

it("ticks every second", async () => {
  vi.useFakeTimers();
  const screen = render(`
    $now = 0
    $effect(() => {
      let id = setInterval(() => { $now = $now + 1 }, 1000)
      cleanup(() => clearInterval(id))
    }, ["mount"])
    $app(Text(\`Ticks: \${$now}\`))
  `);
  await flush();

  await vi.advanceTimersByTimeAsync(3000);        // fire three intervals
  await flush();

  expect(screen.state.get("now")).toBe(3);
  vi.useRealTimers();
});

Testing a single component

renderComponent(expression, options) renders one component call in isolation — it wraps the expression in $app(...) and lets you prepend a setup block of helper DSL (component definitions, seed state).

import { renderComponent, flush } from "aktion-runtime/test";

it("colours a PriceTag by amount", async () => {
  const screen = renderComponent(`PriceTag(42)`, {
    setup: `
      function PriceTag(amount) {
        return Badge(\`$\${amount}\`, { tone: amount > 100 ? "danger" : "success" })
      }
    `,
  });
  await flush();
  expect(screen.getByText("$42", { exact: false })).toBeTruthy();
});

To assert that a callback prop fired, capture it the idiomatic Aktion way — write a $state flag (or $emit) from an inline handler, then read it back. This keeps the test in the language rather than reaching for host-side spies.

it("fires onClick", async () => {
  const screen = renderComponent(`Button("Save", { onClick: () => $saved = true })`);
  await flush();

  await screen.click("Save");

  expect(screen.state.get("saved")).toBe(true);
});

Testing events

An Aktion program talks to its host by dispatching DOM events. The Screen captures them so you can assert on the payloads. The three built-ins — assistant-message, route-change, and error — are always captured. For a custom $emit("name", ...) event, list its name in captureEvents (or call screen.listen("name")) before the trigger, since custom names aren’t known in advance.

it("emits a saved event with the new id", async () => {
  const screen = render(`
    function save() { $emit("saved", { id: 7 }) }
    $app(Button("Save", { onClick: save }))
  `, { captureEvents: ["saved"] });
  await flush();

  await screen.click("Save");

  expect(screen.emitted("saved")).toEqual([{ id: 7 }]);
  expect(screen.lastEvent("saved")).toEqual({ id: 7 });
});

Testing $http

Pass a fetch mock to render and it replaces the global fetch for the lifetime of the test (restored on cleanup). The handler receives the resolved URL and the request init; return a Response, a string, or a plain object — the json(data, status?) helper builds a JSON response for you.

import { render, json, flush } from "aktion-runtime/test";

it("loads and renders the user list", async () => {
  const screen = render(`
    $users = $http({ url: "https://api.example.com/users" })
    $app(Async($users, {
      loading: Text("Loading…"),
      data:    Text(\`\${$users.data.length} users\`)
    }))
  `, {
    fetch: (url, init) => json([{ id: 1 }, { id: 2 }]),
  });

  // findBy* waits for the request to resolve and the data slot to render.
  expect(await screen.findByText("2 users", { exact: false })).toBeTruthy();

  // Assert what was requested.
  expect(screen.requests[0].url).toContain("/users");
  expect(screen.requests[0].method).toBe("GET");
});

Branch on method / URL to drive writes, errors, and refetches:

const screen = render(programSource, {
  fetch: (url, init) => {
    if (init.method === "POST") return json({ id: 99 }, 201);
    if (url.includes("/fail")) return { status: 500, json: { message: "boom" } };
    return json([]);
  },
});

// later — assert the POST body the program sent
await screen.click("Create");
const post = screen.requests.find((r) => r.method === "POST");
expect(post.body).toEqual({ name: "New order" });

Testing routing

Set the initial hash route with the route option, then drive navigation with screen.navigate(...). The matching $router arm renders just like in the browser.

it("renders the matched route and follows navigation", async () => {
  const screen = render(`
    $app($router({
      "/":      Text("Home page"),
      "/about": Text("About page"),
      default:  Text("Not found")
    }))
  `, { route: "/about" });
  await flush();

  expect(screen.getByText("About page", { exact: false })).toBeTruthy();
  expect(screen.route).toBe("/about");

  await screen.navigate("/");
  expect(screen.getByText("Home page", { exact: false })).toBeTruthy();
});

Testing streaming

Aktion is streaming-first — an LLM emits the program token by token. screen.stream(chunks) appends each chunk (with streaming on, so transient mid-token parse errors are suppressed) and flushes, letting you assert the UI converges once the program completes. screen.appendChunk appends a single chunk for finer control.

it("renders progressively as chunks arrive", async () => {
  const screen = render("");                       // start empty

  await screen.stream([
    `$app(Column([`,
    `  Text("First"),`,
    `  Text("Second")`,
    `]))`,
  ]);

  expect(screen.getByText("First", { exact: false })).toBeTruthy();
  expect(screen.getByText("Second", { exact: false })).toBeTruthy();
});

Snapshots

Two snapshot surfaces — the rendered markup and the reactive state:

const screen = render(programSource);
await flush();

expect(screen.html()).toMatchSnapshot();              // rendered shadow DOM
expect(screen.state.snapshot()).toMatchSnapshot();    // every reactive atom

screen.debug() prints the current shadow-DOM markup to the console while you iterate — the equivalent of RTL’s screen.debug().

Custom (host-registered) components

If your app registers TypeScript ComponentSpecs via registerComponents(...), pass them to render through the components option so your program can call them.

import { render } from "aktion-runtime/test";
import { ProductCard } from "../src/components/product-card";

const screen = render(`$app(ProductCard("Widget", { price: 9.99 }))`, {
  components: [ProductCard],
});
await flush();
expect(screen.getByText("Widget", { exact: false })).toBeTruthy();

Accessibility audits with axe

Run a lightweight a11y audit on any rendered subtree with axe(node). It returns an array of violations — missing image alt text, buttons without an accessible name, inputs without a label, duplicate ids, and invalid tabindex — so you can fail a test the moment a regression slips in.

import { render, axe } from "aktion-runtime/test"

test("dashboard has no obvious a11y violations", () => {
  const { container } = render(program)
  expect(axe(container)).toHaveLength(0)
})

Testing SSR output

Assert on server‑rendered markup with renderToString from the runtime entry. It returns { html, state }; check that critical content is present in the string (no client mount required) and that the hydration state carries what the page needs.

import { renderToString } from "aktion-runtime"

test("renders the headline on the server", () => {
  const { html, state } = renderToString(program, { path: "/" })
  expect(html).toContain("Welcome back")
  expect(state.user).toBeDefined()
})

In Node, register a DOM shim (happy-dom / jsdom) on globalThis first — the same setup described in Setup.

API reference

render(program, options?) & renderComponent(expression, options?)

The Screen

Module functions

Coming from React Testing Library

The mental model transfers almost one-to-one:

Best practices

• Query by role / text, not by class. Tests that find a button by its label survive refactors; tests that query .rui-button break when internals change.
• Assert on what the user sees first. Reach for screen.state when the behaviour is genuinely invisible (a computed total, a flag), not as a shortcut around the DOM.
• Use findBy* for anything async. Never setTimeout in a test — findBy* / waitFor retry deterministically.
• One behaviour per test. Render, do one thing, assert the consequence — the counter test above is the shape to copy.
• Wire afterEach(cleanup) once per file so a leaked element, a mocked fetch or the route a test navigated to can’t bleed into the next one. location.hash is document state, not element state — without the restore, a later render() with no route starts wherever the previous test finished, and the suite’s result depends on its own ordering.
• Prefer real interactions to direct state writes. screen.click("Save") exercises the handler, the action, and the re-render; state.set(...) only seeds a value.

Next