For agents: start with the agent guide. Every page is Markdown by default; add Accept: text/html for HTML.

UI behaviour is a scene

A Foldkit¹⁶ program has a Model, Messages, an update function, and a view. A Command is a named side effect. Its result comes back as a Message. A Scene runs update, the view, and subscriptions together, without a browser.¶

Input and time are data

A Scene starts from a Model with given. Input is a step such as pointerDown, click, or Subscription.emit. A timer is a Command, so the test finishes it with Command.resolve.¶

The test does not use fake timers, a clock, or a DOM. Each step runs in order, and the result is the same on every run.¶

The Toast example

Devin Jameson shared a Scene test for the Foldkit UI Toast. The test name is “returns a short swipe to zero while settling”.¶

1. A pointer goes down on the toast.¶
2. The pointer moves 30 pixels and releases.¶
3. The swipe is too short, so the toast settles back. It does not dismiss.¶
4. The test resolves the settle wait.¶
5. The test resolves an old dismissal timer with a stale version.¶
6. The toast still exists.¶

This paraphrase keeps the steps and drops the setup:¶

scene(
  { update: Toast.update, view },
  given(withEntry()),
  pointerDown(toast, { clientX: 100 }),
  Subscription.emit(MovedSwipePointer({ pointerId, clientX: 130 })),
  Subscription.emit(ReleasedSwipePointer({ pointerId, clientX: 130 })),
  expect(toast).toHaveAttr("data-swipe", "settling"),
  expect(toast).not.toHaveAttr("data-leave"),
  Command.resolve(
    WaitForSwipeSettled,
    CompletedWaitForSwipeSettled({ entryId, version: settlingVersion })
  ),
  expect(toast).not.toHaveAttr("data-swipe"),
  Command.resolve(
    WaitBeforeDismissal,
    CompletedWaitBeforeDismissal({ entryId, version: staleVersion })
  ),
  expect(toast).toExist()
);

Read the full test in the Foldkit source.¶

A race is a plain assertion

A race happens when an old result arrives after the state has moved on. In a Scene, the test resolves the old Command late. Then it asserts that nothing broke. The stale dismissal step above is that race.¶

Assert on what the view shows

Find elements by role, text, or data attribute. Do not assert on Model fields. A Model field can change name while the behaviour stays the same. A person and an agent can read the steps without the implementation.¶

The rat-stack reader uses the same shape for its copy button. The test clicks copy, resolves the copy, and checks the status text. Then it resolves the reset wait and checks that the label returns:¶

it("a copy confirms with text the reader can see and hear, then resets after the wait", () => {
  scene(
    { update, view },
    given(clipboardReady),
    click(copyButton),
    Command.expectExact(CopyReaderText({ id, text: promptText })),
    Command.resolve(CopyReaderText, Message.SucceededCopyReaderText({ id })),
    expect(role("status")).toHaveText("Copied ✓"),
    expect(copyButton).toContainText("Copied ✓"),
    Command.expectExact(WaitBeforeCopyReset({ id })),
    Command.resolve(
      WaitBeforeCopyReset,
      Message.CompletedWaitBeforeCopyReset({ id })
    ),
    expect(role("status")).toHaveText(""),
    expect(copyButton).toContainText(label),
    Command.expectNone()
  );
});

Plant a bug first

Break the rule the Scene protects. For the Toast, let a stale timer dismiss the entry. The Scene must fail. Restore the code and watch it pass.¶

See also: tests that earn their place²², model-based testing¹⁴, and the test-behaviour skill.¶

Last changed 2026-10-09 in 3107109. Source on GitHub. Change log.