On this pageStory and Scene
Testing
Story and Scene test two parts of a Foldkit application. Story calls update directly. Scene enters through the rendered view. Neither test runs a browser or executes the Effects inside Commands, so both stay deterministic and fast.
| Story | Scene | |
|---|---|---|
| Enters through | A Message | An interaction or lifecycle result |
| Observes | Model changes, Commands, and OutMessages | Rendered output, Commands, Mounts, and OutMessages |
| Best suited to | Update logic, edge cases, and Command wiring | User flows, view behavior, and accessibility |
Use both. Story proves the state machine behaves correctly. Scene proves that a person can reach that behavior through the view.
Name each file for the boundary it tests:
story.test.tsdrives update.scene.test.tsdrives the rendered view.When one folder has several tests of the same kind, prefix the subject:
login.story.test.ts.Keep root-level Scene tests for flows that cross pages. Colocate page and Block tests with the code they exercise.
The names stay accurate whether update and view live together or in separate files. See Project Organization for the full layout.
story starts from a Model, sends Messages through update, and keeps Commands as data until the test supplies their result Messages. See the Story page for the full API.
Story can test a root update or a child update in isolation. The update function is the contract at either level.
scene renders the view after every step. Locators find elements by role, label, placeholder, and visible text. Interactions invoke the view's event handlers, while cause-named steps supply Subscription, ManagedResource, and CustomElement results. Scene also tracks pending Commands and Mounts. See the Scene page for the full API.
Scene can also start at the root or at a child Block. withViewInputs adapts a Block view that needs ViewInputs, and expectOutMessage checks a child's OutMessage directly.
Choose the level by ownership. Test a Block's rendering, interactions, Commands, and OutMessages at the Block. Test parent folding, lifted Commands, route changes, and parent-computed ViewInputs at the root. Those behaviors cross the boundary and cannot be observed from the child.
To test a Command's work, execute its Effect with the application's real handler Layer and controlled service providers. The Commands guide shows an HTTP test that runs the real request, decoding, and result Message mapping.
Choose the lowest service boundary whose behavior the test needs to exercise. If an API service contains authentication or retry policy, retain that service and replace its transport. The same principle applies to Subscription Streams, Mount integrations, and ManagedResource acquisition and cleanup. Testing through service boundaries explains how to compose these providers at the application root.
Replacing an entire handler tests a narrower orchestration path and excludes the replaced implementation. Story and Scene already supply results explicitly; execution tests use Effect and Layer composition to run the application's handlers.
The Blocks preview changes where tests get identity, generated delivery, and lifecycle declarations. Keep tests at the same Story or Scene boundary, then replace hand-written observations with the declarations carried by the composed application.
A bound child Command has a placement-qualified display name such as Application/Pins/ReadPins. Do not compare that string, or compare command.name with Definition.name. Story and Scene match the original Definition by its source identity, so the same matcher keeps working after the Command is registered below a Binding. Pass an instance for exact args; a bound instance also selects its composition path.
When the Command belongs to a child Block, supply its raw child result Message. The pending Command retains the generated delivery chain and Story or Scene replays it before calling the parent update.
The parent Message union no longer declares GotPinsMessage. Composition owns generated child envelopes, and tests do not fabricate their placement or occurrence fields.
Subscription.emit identifies both the registered source and its raw Message. Build the Scene registry from the Application Composition, pass it in the Scene config, and select the entry that declared the Message. For a child entry, pass the child's Message; Scene derives every generated parent delivery from the registry.
// ❌ Emit a Message without identifying its registered Subscription.
import { Scene } from 'foldkit'
import { model, update, view } from './application'
import { Message } from './application/message'
Scene.scene(
{ update, view },
Scene.given(model),
Scene.Subscription.emit(Message.ObservedPins({ count: 3 })),
)The scaffolded tsconfig.json includes src/**/*, which keeps *.test.ts files in the project typecheck. Preserve that coverage when customizing TypeScript project references or include patterns, so a changed Story or Scene signature fails during typecheck instead of waiting for the test runner.
Stateful UI components expose their Model, Message, init, operations, and OutMessage through a completed Block. Read the Model type as typeof FooBlock.Model.Type. Let the parent Binding and Composition initialize the child so its startup Commands are retained.
Command and Mount Definitions intended for Story and Scene live under the component's test namespace. Resolve the original public Definition with a result Message from the completed Block.
The Block guide covers connected Steps, owner-specific builder aliases, and child initialization. The Mount guide covers reusable mounted view helpers. Component pages document helpers that drain a component's whole pending lifecycle when one public operation is clearer than several individual resolvers.