@mailagent/qa

Playwright / Cypress helpers for MailAgent test inboxes.

npm install @mailagent/qa

Playwright

import { createMailAgentQa, MailAgentQa } from "@mailagent/qa";

const mail = createMailAgentQa();
const inbox = await mail.createInbox({ label: MailAgentQa.ciLabel(), service: "auth0" });
const { otp } = await mail.waitForVerification(inbox.id, { subjectContains: "verify" });
// callback flow:
// const { verification } = await mail.waitForCallback(inbox.id, { since: new Date() });
await mail.cleanupRun(process.env.GITHUB_RUN_ID!);

Fixture: examples/playwright/mailagent.fixture.ts.

CI failure artifact

On timeout or failed email step, attach a safe JSON artifact and optionally write to $GITHUB_STEP_SUMMARY:

import {
  createMailAgentQa,
  formatFailureArtifactAttachment,
  writeFailureArtifact,
} from "@mailagent/qa";

const ctx = await mail.getDebugContext(inbox.id, { subjectContains: "verify" });
await testInfo.attach("mailagent-failure.json", {
  body: formatFailureArtifactAttachment(ctx).body,
  contentType: "application/json",
});
await writeFailureArtifact(ctx, { writeGitHubStepSummary: true });

The artifact includes failure summary, recommended action, retry payload, messages, callbacks, and debug UI URL. Full OTP values and magic links are redacted unless includeOtp / includeLinks is explicitly enabled.

Cypress

cypress.config.ts:

import { createMailAgentCypressTasks } from "@mailagent/qa/cypress";

export default defineConfig({
  e2e: {
    setupNodeEvents(on) {
      on("task", createMailAgentCypressTasks());
    },
  },
});

Spec: examples/cypress/signup-email.cy.example.ts.

Tasks: mailagentRunLabel, mailagentCreateInbox, mailagentWaitVerification, mailagentSimulateAndVerify, mailagentOpen, mailagentDeleteInbox, mailagentCleanupRun.

Docs

• QA guide
• Troubleshooting
• Local SMTP (Mailpit)
• Service presets
• Callback cookbook