| name | signup-flow-driver |
| description | Use when an end-to-end signup, email-verification, or onboarding flow needs to be exercised in a real browser — verifying a new sign-up still works after a frontend/auth change, reproducing a "user stuck on onboarding" bug, checking the verification email actually arrives and its link lands the user in the right place, or wiring a smoke test for the account funnel into CI. |
Signup Flow Driver
Overview
Account funnels break in ways unit tests miss: a redirect fires before the
session cookie is set, the verification email link points at the wrong
environment, an onboarding step silently 500s for brand-new accounts. The only
way to know the funnel works is to walk it like a user — in a real browser,
against a real mailbox.
This skill drives signup → email verification → onboarding headlessly with
Playwright. It asserts observable state at every step (URL, cookie, DOM, mailbox
contents), captures a screenshot per step, and records a video plus a Playwright
trace so a failure is debuggable after the fact instead of "it was red on CI."
The discipline that makes this worth more than a hand-click: every step ends
with a programmatic assertion, not a sleep. If the assertion can't be made
true within its timeout, the run fails loudly at the step that broke.
When to Use
Reach for this when:
- A PR touches signup, auth, session handling, the verification email, or any
onboarding step, and you need proof the whole funnel still completes.
- Someone reports "I signed up but never got the email" or "onboarding won't let
me past step 2" — reproduce it deterministically here.
- You're adding a funnel smoke test to CI and need state assertions, not just a
200 from the signup endpoint.
- The verification link's target environment is suspect (link points at prod
from a staging signup, or vice versa).
Do NOT use this when:
- You only need to assert backend behavior with no UI — call the signup API and
inspect the DB directly; a browser is overhead.
- The mailbox you'd poll is a real human inbox. This needs a catch-all / test
mailbox API (Mailosaur, Mailpit, MailSlurp, or your internal test-mail
service). Never point it at a real user's email.
