feat(wrangler): dispatching email handlers with test harness

[edmundhung]

Fixes n/a.

This adds support for dispatching email handlers with createTestHarness

You can now call server.getWorker().email({ from, to, raw }) to dispatch directly to a Worker's email() handler and inspect its outcome, rejection reason, forwarded messages, and replies.

const result = await server.getWorker().email({
    from: "sender@example.com",
    to: "inbox@example.com",
    raw: [
        "From: Sender <sender@example.com>",
        "To: Inbox <inbox@example.com>",
        "Message-ID: <test@example.com>",
        "Subject: Test email",
        "",
        "Hello from the test harness",
    ].join("\r\n"),
});

expect(result).toMatchObject({
    outcome: "ok",
    forwards: [{ rcptTo: "archive@example.com" }],
    replies: [{ raw: expect.stringContaining("Thanks for your email") }],
});

---

• Tests
  • Tests included/updated
  • Automated tests not possible - manual testing has been completed as follows:
  • Additional testing not necessary because:
• Public documentation
  • Cloudflare docs PR(s): [Email Service, Workers] Document email handler testing cloudflare-docs#32362
  • Documentation not necessary because:

A picture of a cute animal (not mandatory, but encouraged)

[changeset-bot]

🦋 Changeset detected

Latest commit: 3c6167b

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

✅ All changesets look good

[pkg-pr-new]

@cloudflare/autoconfig

npm i https://pkg.pr.new/@cloudflare/autoconfig@14685

@cloudflare/config

npm i https://pkg.pr.new/@cloudflare/config@14685

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@14685

@cloudflare/deploy-helpers

npm i https://pkg.pr.new/@cloudflare/deploy-helpers@14685

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@14685

miniflare

npm i https://pkg.pr.new/miniflare@14685

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@14685

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@14685

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@14685

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@14685

@cloudflare/workers-auth

npm i https://pkg.pr.new/@cloudflare/workers-auth@14685

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@14685

@cloudflare/workers-utils

npm i https://pkg.pr.new/@cloudflare/workers-utils@14685

wrangler

npm i https://pkg.pr.new/wrangler@14685

commit: 3c6167b

[ask-bonk]

@edmundhung Bonk workflow was cancelled.

View workflow run · To retry, trigger Bonk again.

[workers-devprod]

Codeowners approval required for this PR:

• @cloudflare/wrangler

Show detailed file reviewers

• .changeset/calm-mails-report.md: [@cloudflare/wrangler]
• .changeset/tidy-pandas-email.md: [@cloudflare/wrangler]
• packages/miniflare/src/workers/core/email.ts: [@cloudflare/wrangler]
• packages/miniflare/test/index.spec.ts: [@cloudflare/wrangler]
• packages/wrangler/e2e/createTestHarness.test.ts: [@cloudflare/wrangler]
• packages/wrangler/src/api/test-harness.ts: [@cloudflare/wrangler]

[ask-bonk]

Review posted successfully to PR #14685.

I reviewed the PR and posted a batch review with two inline comments:

1. (High) test-harness.ts:999 — email() calls response.json() unconditionally. Server-side validation failures (missing Message-ID, missing from/to, empty/oversized body, parse errors) return plain-text 4xx responses that bypass the format=json branch, so callers get an opaque SyntaxError instead of the descriptive error. Provided a suggestion to check response.ok/content-type and throw the server message.

2. (Medium) email.ts:274 — the scheduler.wait(0) used to let an un-awaited setReject() cross JSRPC is a timing heuristic that could make rejectReason flaky; suggested a deterministic signal or at least a documented limitation.

github run

[tpmmorris]

Very useful change for improving Email service UX. Some of the response interfaces could be altered to provide better data to Local Explorer in the future.

[workers-devprod]

Codeowners approval required for this PR:

• ✅ @cloudflare/wrangler

Show detailed file reviewers

[workers-devprod]

Codeowners reviews satisfied