What blocks a publish

Video is the reward for passing. A run that proves what it claimed gets the shareable artifact; a run that didn’t gets nothing to share.

You write that claim as expect steps, and every one has to hold before the mp4 leaves your machine. If a checkpoint fails, the demo is not published — you get the frame where it broke instead.

What an expect step can assert

Three kinds, and one is enough per checkpoint:

Field	Asserts	Example
text	The text becomes visible on screen	{ action: "expect", text: "Buy milk" }
urlIncludes	The current URL contains the substring	{ action: "expect", urlIncludes: "/library" }
selector	The element matching the CSS selector becomes visible	{ action: "expect", selector: "[data-testid=toast]" }

Each waits up to 8 seconds by default. Give a slow operation more with ms:

{ "action": "expect", "text": "Export complete", "ms": 30000 }

expect is a wait, not a snapshot: it polls until the condition holds or the timeout runs out. You don’t need a wait step before it.

What happens when a check fails

The recorder does not stop at the first failure. It finishes the run, so you get the whole picture instead of one error, then refuses to publish:

Tada did NOT publish this demo — 1 verification check(s) failed:
  ✗ expect "/library": expected URL to include "/library", but still at "/login"

The demo did not reach the state it claimed (e.g. a click that did nothing, a
page that never loaded). Fix the steps and record again. The local recording is
at: /tmp/tada-xxxx/demo.mp4

Two things worth knowing about that output:

• The failure names the actual state, not just the expectation. still at "/login" is usually the whole diagnosis.
• The local mp4 still exists, and the failed checkpoint is burned into it as an on-screen ⚠ check failed caption at the moment it happened. Watch the file to see what the browser actually saw.

Your agent gets this back as a tool error, which is what lets it fix the steps and re-record without you in the loop.

What blocks a publish, and what only warns

This is the distinction that matters, and it’s easy to assume it’s stricter than it is.

Blocks the publish:

• Any failed expect step.
• An awaitEmail step where no email arrived, or the email contained no link. A magic-link demo that never got its link didn’t demo anything.
• A failed first goto. There is no page to record, so the run aborts outright.

Does not block the publish:

• Any other step that throws: a click that found nothing, a fill on a field that isn’t there. These are recorded as skipped, captioned on screen as ⚠ step skipped, and the run continues so you still get an mp4. The tool output lists them.

• A demo with no expect steps at all. It publishes, and the result carries a warning:

  ⚠ No expect checkpoints — this demo was not verified.

That last one is the honest caveat: verification is something a demo opts into. Tada can’t block on a checkpoint you never wrote. A published Tada link is proof the feature works when the demo asserted that it does. The ✓ verified marker in the tool output tells you which kind you’re looking at.

Proving a fix, not just exercising it

For a demo that answers “does this bug still happen?”, one assertion proves it and doesn’t earn belief. The checkpoint that carries the weight is the one that would have been false before the fix and true after, so keep that one sacred.

Then tour the neighbours. If the bug was “overdue items still show when filtered by Sent”: assert the Sent-only result, then flip to Overdue (they’re still there), then All (both), then back to Sent. Every stop gets its own expect. That shows the fix holds across the space rather than at one point.

Two rules for the tour: stay on working states, since this is still the happy path, not error handling, and author the whole thing up front. An automated demo that improvises can wander into an unrelated bug on camera, and it records differently on every run.

What gets attested at publish time

When the checkpoints pass, the recorder sends the API the recorder version, the verified flag, and the list of checkpoints the demo asserted. The backend requires that attestation to publish.

That’s what makes a Tada link mean something: a video recorded somewhere else can’t be handed to the upload API and dressed up as a verified demo. There is deliberately no tada upload command.

Next: the verify_feature reference for every step type and option.