[Deep Dive #18] Recipe Harnesses - discussion
We keep writing great docs and then failing to reproduce the bug the docs were describing a month later.
Do you build recipe harnesses as real routes in the app, or keep them as test fixtures? What makes a harness durable (deterministic inputs, render-visible signals, route posture keys, seeded data)? And how do you keep harnesses from becoming a pile of stale demos nobody maintains?
Comments (10)
Back to latestIs a harness basically a Storybook-ish thing, or is it more like a dedicated route that runs a recipe end-to-end?
I'm not sure where people put these in real apps.
More like dedicated routes for reproducible flows.
The point is you can share a URL that reproduces posture + data shape, and the app renders enough signals so the story is visible.
Ok, so it isn't a component playground, it's a route-flow playground.
Harnesses stayed alive for us once we treated them as contracts: deterministic inputs, stable signals, and route posture keys.
If a harness can't be reproduced from a URL + screenshot, it's not a harness.
Related: Testing and Debugging and Resilience Drills (Deep Dive #3).
A minimal harness route pattern we use (posture in route state, evidence in the shell):
tsx
export function HarnessRoute() {
const shell = useGlobalRoute('harness', { scenario: 'timeout', cacheLane: 'bypass' });
const scenario = shell.read('scenario');
return <Scenario scenario={scenario} data-scenario={scenario} data-cache={shell.read('cacheLane')} />;
}The important part is the harness doesn't hide its knobs. The knobs are the route contract.
Counterpoint: harness routes can become a security footgun if they ship accidentally.
We keep them behind a build-time flag and still render evidence so QA can use them, but end users can't discover them.
Yes. Also keep harness data fake. The goal is reproducible posture, not production content.
Treat harnesses like internal tools: stable, observable, and gated.
We made harnesses durable by deleting any harness that didn't have render-visible signals. If it couldn't explain itself, it rotted immediately.
We tied harnesses to incidents. When we fixed an incident, we added a harness scenario that reproduced it and rendered the missing evidence.
That was the only way it stayed funded.
A harness that doesn't pin inputs isn't reproducible. Seed data, route posture, and a stable contract version signal were our baseline.
The best harnesses are shareable. If a PM can paste a link and you can see signals that explain the behavior, debugging gets 10x faster.
We also used harnesses for perf. A stable scenario with signals is the only way to compare before/after without fooling yourself.
If harnesses aren't part of the release/migration story, they'll rot. Tie them to contracts and signals, not to nice-to-have demos.