Cypress: wait for an email without cy.wait
Cypress runs your test in the browser, which raises two problems for reading an email: the API key must not be there, and the network call depends on the origin of the page under test. A Node task solves both.
The configuration, then the test: the key stays in Node
The task lives in the Cypress process, where the key can stay. The test only sees a command.
// The key stays here, out of the browser.
import { defineConfig } from 'cypress';
export default defineConfig({
e2e: {
setupNodeEvents(on) {
on('task', {
async waitForEmail({ sentTo, since }) {
const search = new URLSearchParams({ inbox: 'j3k9x2mq', sentTo, since });
// Searches every second, thirty seconds at most.
for (let attempt = 0; attempt < 30; attempt++) {
const response = await fetch('https://api.facteur.eu/messages?' + search, {
headers: { authorization: 'Bearer ' + process.env.FACTEUR_API_KEY },
});
const { messages } = await response.json();
if (messages?.[0]) return messages[0];
await new Promise((resolve) => setTimeout(resolve, 1000));
}
return null;
},
});
},
},
});
// The attempt number tells a retry from the previous attempt.
it('the code arrives by email', () => {
const tag = 'signup-a' + (Cypress.currentRetry ?? 0) + '-' + Date.now();
const since = new Date().toISOString(); // only an email that arrives after it counts
cy.visit('/signup');
cy.get('[name=email]').type(tag + '@j3k9x2mq.inbox.facteur.eu');
cy.contains('button', 'Create my account').click();
cy.task('waitForEmail', { sentTo: tag + '@', since }, { timeout: 40000 }).should((message) => {
expect(message, 'an email arrived').to.not.be.null;
expect(message.otp).to.have.length(6);
});
});
- The key stays on the Node side
- Your spec is served to a page: a key written in it would be a key in a page's JavaScript. The task keeps it on the other side.
- cy.task yields a value, so the chain goes on
- The message comes back in the usual command chain, and .should() behaves as it does on a cy.get(). The timeout of cy.task stays above the wait sent to the API.
- The attempt number is in the address
- Without it, a retried test reads the email of its first attempt and passes for the wrong reason, precisely when something is already flaky.
Why there is no cy.wait
The task searches every second
It returns the message as soon as it arrives, thirty seconds at most. A fixed cy.wait is either too short on a busy machine, or time lost on every run.
The code is already extracted
The message arrives with its one-time code in the otp field.
One inbox is enough for the whole suite
Each test receives at its own address in the same inbox, with nothing to create. On a plan that includes a single inbox, that is the difference between a suite that runs and a suite that hits a ceiling.
Install the Cypress plugin from npm
cypress-facteur gives one address per test and a command that waits for the message, with the key kept in Node. It installs with npm i -D cypress-facteur. The configuration above remains the one that needs nothing installed, in some thirty lines you keep.
Write this test today
An inbox and a read-only key are enough. The free plan asks for no credit card.