Using a real Gmail account as the test inbox works at first. These are the ways it usually breaks.
Where it breaks
- Tokens lapse. An OAuth app whose consent screen is in Testing gets refresh tokens that expire after 7 days. The pipeline fails until someone signs in and copies a new token in.
- Restricted scopes. Reading mail needs one of Gmail’s restricted scopes. Moving the app out of Testing can mean Google’s verification and, for some uses, a security assessment, which is a lot for a test helper.
- One inbox for every run. Plus-addresses (
qa+run123@gmail.com) give each test its own address, but every email still lands in the same mailbox. Parallel runs read each other’s codes, and a retry can pick up the code from the previous attempt. - Fixed waits and fragile parsing. Scripts poll with
sleep, then pull the code out with a regular expression that breaks the day marketing changes the email template. - A person in the loop. When Google asks to confirm the sign-in, a test can’t answer. Someone with the phone has to.
One address per test instead
Proxy Mail QA gives each test its own address and inbox, then waits for the email that arrives after a given time:
import { ProxyMailQA } from 'proxymail-qa';
const qa = new ProxyMailQA(); // reads PROXYMAIL_QA_API_KEY
const { address } = await qa.createAddress({ label: 'sign-up test' });
const since = new Date();
// …fill in the sign-up form with `address` and submit…
const { value: code } = await qa.waitForCode(address, { since });
- No tokens to renew. An API key doesn’t expire after a week. Keep it in your CI secrets.
- No collisions. Each address belongs to one test, so parallel runs never see each other’s mail.
- No regular expressions. The code or link comes back on its own, with the time it arrived.
- No fixed sleeps. The wait returns as soon as the email arrives, and
sincemeans an older code can’t come back.
Moving over
- Swap the Gmail address in your sign-up step for a new address from
createAddress. - Replace the inbox polling and the regular expression with
waitForCodeorwaitForLink. - Remove the Gmail credentials from CI, and the job that renews the token.
The Playwright, Cypress and pytest guides show the same steps in each framework.