Automating a signup flow that sends a verification email

A signup test is straightforward right up to the moment the product sends an email. The browser part is mechanical: open the page, fill three fields, submit. Then the flow leaves the browser. The next thing the test needs is a six-digit code sitting in a mailbox, and nothing on the page can reach it.

The short answer: drive the browser half in a real Chrome, read the verification message out of a real mailbox over IMAP, anchor the wait to a timestamp taken before you submit the form, and type the code back into the same session. The anchor is the part people skip, and it is the part that decides whether a passing run means anything. The rest of this page is why each of those four is load-bearing, and where the approach stops working.

That one gap is why so many signup flows are covered by a test that stops at "account created" and never touches the part users complain about: the code that arrives late, the second code that invalidates the first, the verify link pointing at the wrong host, the dashboard that loads empty behind the wall.

This page explains where a scripted browser test stops, what the three usual workarounds cost, and what DeckTest does instead — including which of those costs it still asks you to carry. If you have not set the app up yet, the quickstart covers installation first.

Where a scripted signup test stops

A browser test can assert only what the browser can reach. Verification mail is delivered out of band, to a mail server your test has no handle on. Three questions therefore fall outside the test entirely.

• Did the message arrive at all, to the address the form was given?
• Did it carry a usable code or link, not a template placeholder?
• Does that code still work when it is typed back into the form?

So the test is either cut short before the email, stubbed past it, or given a second system to talk to. Each of those has a price.

The three usual workarounds, and what each costs

A mail API. You sign the test up with an address at a service that exposes received mail over HTTP, then poll it for the message. It puts another vendor in the path of your signup mail, adds an account and a key to rotate, and gives your test an address that is not the kind your users have. Products that filter disposable domains will send your test down a branch real users never see.

A catch-all inbox you poll over IMAP. No third party, and the address looks like a real one. This is the right shape — it is the shape DeckTest uses — but a hand-rolled version has three details to get right before it is trustworthy. Plus-addressed mail is filed by some hosts into a subfolder rather than the inbox, so an INBOX-only search finds nothing. Verification mail lands in Junk often enough that the folder scan has to include it. And the mail credentials now live wherever your tests run, which is a decision to make on purpose rather than by accident.

A test-only bypass in the product. A flag that fixes the code to 000000, or auto-verifies the account, or exposes the code on a debug route. It is the cheapest to build and the most expensive to own, because the path you test is no longer the path you ship. Everything the email step can break — a template that renders the wrong variable, a provider that delays past expiry, a link built with the wrong base URL — is precisely what the bypass skips. A bypass also has a way of remaining reachable in production long after anyone remembers it exists.

What DeckTest does instead

DeckTest is a Mac app plus a small bridge extension you load once into your own Chrome. The app runs a local relay bound to 127.0.0.1, authenticated with a token header, and your Claude connects to it over MCP and drives that browser. It is your real Chrome — the profile you are already signed into — not a clean automation profile.

The browser half of the run happens there. The email half does not happen in the browser at all. DeckTest reads the message over IMAP from a mailbox you nominate, using credentials held in a config file on your Mac. No third-party inbox sits in the path, and nothing in the product is bypassed — the address is a real address, the message is the one your product sent, and the code is the one a user would type.

1. Fills and submits the signup form in your Chrome, using a fresh address.
2. Polls the nominated mailbox over IMAP for a message that arrived after a timestamp stamped before the submit.
3. Pulls the code, or the verification link, out of that message.
4. Types the code back into the field in the same browser and submits it.
5. Carries the session through to the logged-in state and keeps testing past it.

The repeatable form of this is a YAML scenario — ask Claude to save the run as one and you get a plain-text file you can re-run before every deploy. Its code and link steps scan INBOX, its plus-address subfolders and Junk, and wait for a message that arrived after that pre-submit timestamp, with a default budget of 180 seconds. A run that never receives the mail records a blocker-severity bug naming the address it waited on, rather than hanging.

Reading the code out of the message

Extraction is rule-based, and the rules are worth knowing because they tell you when it will miss. A labelled code wins first: words like code, OTP, one-time, verification, verify, passcode, PIN or token followed within a short span by four to eight digits. Failing that, any standalone run of four to eight digits is a candidate, six-digit runs are preferred, and four-digit years are discarded so a copyright line cannot be mistaken for a code.

For magic links, a URL whose host matches the site under test wins, and among those a path containing verify, confirm, magic, token, activate, signup, validate or auth wins again.

What it checks once it is through the wall

Getting past verification is not the finish. The step after the code is where the interesting failures live, and a screenshot alone will not show them. Three kinds of evidence are available, and they are not all automatic.

• Visually. A screenshot of the tab. In a scenario it is captured on every navigation and every assertion, on any step that fails, and on any step you mark for evidence — so a long run of passing clicks is not photographed end to end.
• In the UI. The page's real text, its HTML, and a structured scan of interactive elements with their roles and suggested selectors — so the assertion is against the element that exists, not pixels that happen to match.
• In the console and network. Captures of console output, exceptions and network requests — the failed request or thrown error behind a screen that looked fine. These run in a separate automation Chrome, so read the note below before you rely on them.

What the report contains

Every run writes a folder: a human-readable report.md, a machine-readable run.json, and a screenshots directory.

• A verdict line with the pass and fail counts and the number of bugs.
• A step table: each step, its status, its duration in milliseconds, a short detail, and a link to its screenshot where one was taken.
• Bugs sorted by severity from blocker down to cosmetic, each with expected, actual, dimension and evidence.
• A console and network anomalies section, capped at fifty entries.

Requirements, and what it will not do

• macOS 11 or newer. The build is universal, native on Apple Silicon and Intel. Windows is not shipped.
• Google Chrome installed. DeckTest drives real Chrome through its bridge extension, loaded once, unpacked.
• Your own Claude — a Claude Desktop login or Claude Code. DeckTest connects the Claude you already pay for; it does not include or resell AI access.
• A test mailbox with IMAP credentials, if your flow has an email step. You place them in a config file yourself; there is no settings screen for them yet.
• Your own sites and apps. Test what you own or are authorized to test.

Captchas are the honest edge. A readable image or text captcha is extracted from the page for your Claude to read, but only on hosts you have added to the auto-solve scope, which out of the box contains only localhost and 127.0.0.1 — so add your staging host before the first run. Behavioural challenges are never faked. They are flagged and escalated to you as a desktop notification so you can clear the challenge yourself and let the run continue.