CI/CD Integration

The core CI/CD pattern: create an ephemeral alias per test run, send email to it, extract the OTP, let the alias expire automatically. No teardown code. No shared state between parallel runs.

The Recommended Pattern

One alias per run

ci+run-{uuid}@qa.acme.mailfork.dev

Never share a single inbox address across parallel runs — emails bleed across runs. Create a unique alias per run using a UUID or timestamp. The alias auto-expires with onExpire: 'delete', so no afterAll or teardown is needed.

GitHub Actions

Add your API key to the repository's secrets as MF_API_KEY: Settings → Secrets and variables → Actions → New repository secret.

Workflow file:

.github/workflows/e2e.yml

name: E2E Tests
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - name: Run e2e tests
        env:
          MF_API_KEY: ${{ secrets.MF_API_KEY }}
        run: npx playwright test

TypeScript Test Example

A complete Playwright test that creates an alias, triggers a signup flow, and extracts the OTP — all in one test body.

TypeScript

import { MailForkClient } from '@mailfork/sdk';

const mf = new MailForkClient({ apiKey: process.env.MF_API_KEY });

test('signup OTP flow', async ({ page }) => {
  // 1. Create a unique alias for this run
  const alias = await mf.inboxes.createAlias({
    inbox: 'ci@qa.acme.mailfork.dev',
    tag: 'run-' + crypto.randomUUID(),
    ttlHours: 1,
    onExpire: 'delete',
  });

  // 2. Trigger the signup flow using the alias address
  await page.goto('/signup?email=' + alias.address);
  await page.click('[data-testid="submit"]');

  // 3. Extract the OTP — SDK polls until it arrives
  const otp = await mf.emails.extractOtp({
    inbox: 'ci@qa.acme.mailfork.dev',
    aliasTag: alias.tag,
    waitTimeoutMs: 20000,
  });

  // 4. Enter the OTP and verify
  await page.fill('[data-testid="otp-input"]', otp);
  await page.click('[data-testid="verify"]');
  await expect(page).toHaveURL('/dashboard');

  // No teardown needed — alias expires automatically after 1 hour
});

GitLab CI

Add MF_API_KEY as a CI/CD variable in your GitLab project: Settings → CI/CD → Variables → Add variable. Mark it as masked and protected.

.gitlab-ci.yml

e2e-tests:
  image: node:20
  stage: test
  variables:
    MF_API_KEY: $MF_API_KEY
  script:
    - npm ci
    - npx playwright test
  only:
    - merge_requests
    - main

The alias auto-expires after 1 hour — no after_script teardown needed. Even if the test job fails or is cancelled, the alias will expire and its emails will be purged automatically.

What's next?

Working with Aliases →

Deep dive into alias creation, TTL, and onExpire behaviors.

OTP Extraction →

Custom patterns, confidence scores, and timeout handling.