Module: utils/disposableEmail

S3-08 — Disposable email support for auth flow testing.

Sentri can discover and crawl auth flows but cannot complete registration flows that require email verification. This module provides a DisposableEmail client backed by the temp-mail.io API, and a fillEmailVerificationFlow helper that stateExplorer.js calls when it encounters a signup form.

Flow

  1. createMailbox() — allocates a random disposable address.
  2. fillSignupForm(page, mailbox, fields) — fills the form with the temp address and any other generated test data.
  3. waitForOtp(mailbox) — polls the inbox until a message arrives, then extracts a numeric OTP or verification link.
  4. fillOtpFields(page, otp) — handles both single-input and split-digit OTP inputs, using clipboard paste for split fields.
  5. dispose(mailbox) — deletes the mailbox (best-effort cleanup).

Configuration

Env var Default Description
TEMP_MAIL_API_KEY — temp-mail.io API key
TEMP_MAIL_BASE_URL https://api.temp-mail.io/request API base URL
DISPOSABLE_EMAIL_TIMEOUT 60000 OTP poll timeout (ms)
DISPOSABLE_EMAIL_POLL_MS 3000 Poll interval (ms)

Exports

  • createMailbox — allocate a temp email address
  • waitForOtp — poll inbox and extract OTP/link
  • fillOtpFields — fill OTP into page (single or split)
  • fillEmailVerificationFlow — high-level helper for stateExplorer
  • dispose — delete mailbox (cleanup)
Source:

Members

(inner, constant) OTP_DIGIT_RE

Matches 4–8 digit numeric OTPs (most common format)

Source:

Matches verification/activation/confirm links

Source:

Methods

(static) createMailbox() → {Promise.<Mailbox>}

createMailbox() → Mailbox

Allocates a new disposable email address via the temp-mail.io API. The returned Mailbox object is passed to all other functions in this module.

Source:
Returns:
Type
Promise.<Mailbox>

(static) dispose(mailbox) → {Promise.<void>}

dispose(mailbox) → void

Deletes the mailbox. Best-effort — never throws.

Parameters:
Name Type Description
mailbox Mailbox
Source:
Returns:
Type
Promise.<void>

(static) extractOtpFromMessage(text) → {Object}

extractOtpFromMessage(message) → { otp: string|null, link: string|null }

Tries to extract a numeric OTP code or a verification URL from a raw email message body. Returns both in case the caller wants to try the link first.

Parameters:
Name Type Description
text string

Plain-text or HTML email body
Source:
Returns:
Type
Object

(static) fillEmailVerificationFlow(page, formFields, run) → {Promise.<{email: string, mailbox: object}>}

fillEmailVerificationFlow(page, formFields, run) → { email, mailbox, otpFilled, linkFollowed }

High-level helper called by stateExplorer.js when it encounters a signup/registration form. Orchestrates the full flow:

  1. Creates a disposable mailbox.
  2. Fills ALL form fields — email with the temp address, password and other required fields with generated test data.
  3. Returns the mailbox so the caller can submit the form first, then call waitForVerification to poll for OTP/link.

The caller is responsible for:

  • Submitting the form (clicking submit button) after this returns
  • Calling waitForVerification(page, mailbox) to poll for OTP/link
  • Calling dispose(mailbox) when done
Parameters:
Name Type Description
page Object

Playwright Page instance
formFields Array.<Object>

Field descriptors with selector, type, label, etc.
run object

Mutable run record for SSE logging
Source:
Returns:
Type
Promise.<{email: string, mailbox: object}>

(static) fillOtpFields(page, otp) → {Promise.<boolean>}

fillOtpFields(page, otp) → boolean

Fills an OTP code into the active page, handling both:

  • Single <input> fields (fills the whole string)
  • Split digit inputs (one <input maxlength="1"> per digit, pasted via clipboard so focus advances automatically)

Returns true if at least one input was filled successfully.

Parameters:
Name Type Description
page Object

Playwright Page instance
otp string
Source:
Returns:
Type
Promise.<boolean>

(static) waitForOtp(mailbox) → {Promise.<{otp: (string|null), link: (string|null)}>}

waitForOtp(mailbox) → { otp: string|null, link: string|null }

Polls the temp-mail.io inbox until a message arrives or the timeout is reached. On success, extracts an OTP code or verification link.

Parameters:
Name Type Description
mailbox Mailbox
Source:
Returns:
Type
Promise.<{otp: (string|null), link: (string|null)}>

(static) waitForVerification(page, mailbox) → {Promise.<{otpFilled: boolean, linkFollowed: boolean}>}

waitForVerification(page, mailbox) → { otpFilled, linkFollowed }

Polls the disposable mailbox for a verification OTP or link, then fills the OTP or follows the link on the page. Should be called AFTER the signup form has been submitted.

Parameters:
Name Type Description
page Object

Playwright Page instance
mailbox object

Mailbox object from fillEmailVerificationFlow
Source:
Returns:
Type
Promise.<{otpFilled: boolean, linkFollowed: boolean}>

(async, inner) apiFetch(url, optsopt) → {Promise.<unknown>}

Fetch a JSON endpoint, returning the parsed body or throwing on HTTP errors.

Parameters:
Name Type Attributes Description
url string
opts RequestInit <optional>
Source:
Returns:
Type
Promise.<unknown>

(inner) apiHeaders() → {Record.<string, string>}

Build common fetch headers, including the API key if configured.

Source:
Returns:
Type
Record.<string, string>

(async, inner) fillSignupFields(page, formFields, mailboxAddress)

fillSignupFields(page, formFields, mailboxAddress) → void

Fills all form fields for a signup form: the email field gets the disposable address, and other fields (password, name, etc.) get realistic test data via pickSignupFieldValue.

Parameters:
Name Type Description
page Object

Playwright Page instance
formFields Array.<Object>

Field descriptors with selector, type, label, etc.
mailboxAddress string

Disposable email address to use
Source:

(inner) pickSignupFieldValue()

Pick a test value for a non-email signup field based on its type and hints. Returns null if no match is found (field will be skipped).

Source:

Type Definitions

Mailbox

Type:
  • object
Properties:
Name Type Description
address string

The full email address (e.g. abc123@mailnull.com)
id string

Mailbox identifier used for subsequent API calls
_token string

Internal token for message retrieval
Source: