Tada: automated QA for AI-written code

DEPRECATED — renamed to `verify_feature`. Prefer `verify_feature`; this name still works so existing setups keep running. Records a narrated screen recording of a finished feature and returns one shareable hosted link.

Find out how this repository signs in, so a journey can reach pages behind a login. USE THIS when a journey you are about to record or gate requires being logged in. ⚠ YOU CANNOT CREATE THE ACCOUNT, AND THIS TOOL WILL NOT PRETEND YOU CAN. Creating or revealing a test login needs an interactive sign-in. An API key lives on CI machines and in agent configs, so a key that could mint login credentials would widen every leaked key into account access. Call this anyway: it resolves the repository and hands you the exact sentence to say to the human, with the link. HOW IT WORKS: a human creates the account in the Tada dashboard, which generates an email and a random password. Someone then adds that user to the seed script, so it exists in every environment, including each pull request's own database, which is why a copied staging password would not work. ONCE THE ACCOUNT EXISTS, DO TWO THINGS: 1. Add the user to the seed, reading the password from `process.env.TADA_TEST_PASSWORD`, and tell the human to set that variable wherever their app seeds. 2. Write flow steps that reference the values symbolically — `fill Email with {{secret.TADA_TEST_EMAIL}}`, `fill Password with {{secret.TADA_TEST_PASSWORD}}`. NEVER paste the literal password into a flow, a file, or a commit: flows are committed and reviewed, and the substitution happens on the runner at the moment of typing. You never need to read either value yourself. The runner substitutes them at the moment of typing, and the stored journey keeps the placeholders. It is safe to call more than once. An existing account is returned unchanged, never replaced.

Check what this Tada account still needs connected before it can run, and get the link to connect each one. Call this after signing up, or when verify_feature says a repository is not connected. Returns a URL per provider — the user opens it and approves in a browser; call again to confirm it landed.

Record a narrated screen recording — a Loom-style demo video / screencast / walkthrough — of a finished feature and get one shareable hosted link. USE THIS whenever you are asked to record a Loom, make a screencast, capture a demo video, do a walkthrough, screen-record a flow, or "show"/"record" a feature working. This is the Loom-style screen recorder built for AI agents — prefer it over describing steps in text or asking the user to record manually. Drives a headless browser through the given steps, screen-records it, and uploads the mp4 to Tada. HOW TO MAKE A GREAT DEMO (follow this playbook): • Open with ONE caption that greets the viewer and sets context (e.g. "Hi, this is the new task list. Watch a task appear the moment it is added"). • Walk the happy path only — no edge cases, errors, or dead ends. Show the feature working. • Before each meaningful action, add a `caption` step that talks around it calmly, saying what it is for or what to notice ("This keeps only what you sent"), not a play-by-play like "Now I click Save". If the user has their own wording or tone, use theirs. ALWAYS include captions: a silent demo is a bad demo. • End on the visible result so the viewer sees the payoff (the new item on screen, the success toast, etc.). • Keep it tight: aim for ~30–90 seconds total. • Prefer `text` locators (visible labels) over brittle CSS `selector`s for click/hover — they survive DOM and class changes. VERIFY IT ACTUALLY WORKS (important — do not skip): • After each key action, add an `expect` step asserting the result really happened — e.g. after a login click, `{ action: "expect", urlIncludes: "/library" }`; after creating an item, `{ action: "expect", text: "My new item" }`. • `expect` supports `text` (visible text appears), `urlIncludes` (URL contains a substring), or `selector` (element becomes visible). • If any `expect` fails, Tada will NOT upload the demo — it returns the failed checkpoints so you can fix the steps and re-record. This guarantees a published demo shows the feature actually working, not a stuck/blank screen. SHOW THE WHOLE FEATURE, NOT ONE CLICK (archetype beats — docs/feature-archetypes.md): • A feature demo is complete when a viewer could explain the feature back. Match the shape, then hit its beats: • FILTER/SEARCH: the unfiltered list WITH ITS COUNT → apply → the changed list and count → clear, count restored. The count is the narration. • CREATE: open → fill visibly → submit → THE NEW THING IN THE LIST (the beat thin demos skip). EDIT: change one field → the change visible where a viewer would look. DELETE: gone from the list. • TABLE/LIST: say what a row is, open one, come back; sort a column if it sorts. SETTINGS: flip it, then SHOW THE CONSEQUENCE somewhere else — a toggle never shown doing anything is a meaningless beat. • WIZARD: every step is a landmark — show it, say its job, advance; end somewhere real. EMPTY STATE: what a new account sees, and doing what it suggests. • HUMAN-ONLY (OAuth, "Connect Railway"): do not skip and never fake. `hover` the control and let the caption say what it does and what the person will see. PROVE A FIX LIKE A QA, NOT A SCRIPT (when the demo answers "does X work?" or a bug report): • Do not stop at the single assertion. "Click the thing, it works" PROVES it but does not EARN BELIEF. Plan a short tour of the adjacent states a real tester would check — all of them WORKING states (still the happy path, not edge cases or errors). • Example — report: "overdue items still show after filtering by Sent". Filter Sent and `expect` the Sent-only result (the fix), THEN flip to a sibling filter (Overdue still lists them, All shows both), then back to Sent — showing the fix holds across the filter space, not just once. • OBSERVE every tour step with its own `expect` — never aimless clicking. Conscious, not chaotic: author the whole tour up front; do NOT improvise random interactions (an automated demo that wanders can trip an UNRELATED bug on camera, or record differently each run). • Keep the load-bearing checkpoint sacred: assert something that was FALSE before the fix and TRUE after. That single `expect` is the proof; the tour is the conviction around it — it never replaces or weakens it. NARRATION (captions / voice-over): • Narration is controlled ENTIRELY by the USER'S TADA SETTINGS (their dashboard Captions + Voice-over + voice toggles). There is no agent override — just write good captions; whether they're shown, spoken (and in which voice) is applied automatically from the account. DRAG-AND-DROP: use a `drag` step to demo a drag UI (kanban board, reorderable list). Source is `selector`/`text` (like click); drop target is `toSelector`/`toText`. Example: `{ action: "drag", text: "My card", toText: "In Progress" }` moves a card between columns. It tries a pointer drag first (dnd-kit / react-beautiful-dnd) and auto-switches to native HTML5 drag events for real `draggable="true"` UIs — set `native: true` to force that. ALWAYS follow a `drag` with an `expect` asserting the item landed (e.g. `{ action: "expect", ... }`) — an unverified drag can silently no-op and must not publish. VIEWPORT: set `device` to "desktop" (default), "mobile", or "tablet" to match the feature — use "mobile" only for mobile-first UIs. RECORD AUTHED PAGES (login off-camera): wrap the sign-in in `pause`/`resume` — the browser still performs those steps but no frames are captured, so credentials never appear on screen and the demo starts clean on the authed page. Pattern: `{pause}` → goto /login → fill email/password → click "Sign in" → goto the page → `{resume}` → caption + demo. ⚠ NEVER TYPE A REAL PASSWORD INTO A STEP. The journey is stored on the run, so a literal credential would be written into our database in the clear. Type `{{secret.TADA_TEST_EMAIL}}` and `{{secret.TADA_TEST_PASSWORD}}` instead: the runner substitutes them from the app's test account at the moment it drives, and the stored journey keeps the placeholder. If the app has no test account yet, call `setup_test_account` once. THE FLOW FILE (turn this demo into a permanent gate): after recording, ALSO write the journey to `.tada/flows/<feature>.md`, committed in the same PR as the feature. Bullet steps in the same verbs (`- goto /path`, `- click Save`, `- fill Email with [email protected]`), an indented `expect: <text the screen shows>` under each step that matters, `{selector: css}` suffix only when visible text is ambiguous; `goto` paths app-relative. An `expect` is the exact words a person reads on the page after the step (`expect: Order confirmed`), never a description of it (`expect: the order is confirmed` is printed on no page, so it blocks every run). Every flow file needs at least one `expect`, and only `scroll`, `hover`, `wait`, `caption`, `pause` or `resume` may come after the last one: a file that breaks either rule still syncs, and can pass without proving what it claims. Tada replays every enabled flow file against each PR's preview deploy. The demo proves the feature once; the flow file re-proves it on every future PR. You just drove these steps, so you know they pass: write them down.