---
name: email-template-compatibility-test
description: Use when a user wants to batch-send local HTML email templates through a web mail-testing form to multiple test inboxes, use filenames as subjects, verify accepted sends, or compare rendering compatibility across email providers.
license: MIT
---

# 邮件模板兼容性测试

## 概述

将本地 `.html` 邮件模板逐份发送到指定测试邮箱，并用可审计清单区分“服务器已接受”与“收件箱已送达/渲染正常”。默认适配 `https://email-sent-chi.vercel.app/`，也可使用用户指定的同类页面。

**REQUIRED SUB-SKILL:** 使用 `browser:control-in-app-browser` 完成网页操作。

**浏览器选择是固定约束：直接使用应用内置浏览器（IAB）。** 初始化浏览器运行时后，显式调用 `agent.browsers.get("iab")`；不要调用 `getForUrl()`、`getDefault()`，也不要先尝试 Chrome。若 IAB 不可用，停止并报告，不要自行切换到 Chrome。

## 工作流

1. 盘点文件
   - 用 `rg --files -g '*.html' -g '*.htm'` 枚举用户指定目录；默认不递归目录外部。
   - 记录稳定排序后的完整文件名、绝对路径和大小。
   - 对照页面限制校验扩展名与大小；异常文件先报告，不擅自修改模板。

2. 明确发送口径
   - 收件人使用用户明确提供的测试邮箱，并去重。
   - 每个模板上传一次，收件人字段同时填写全部测试邮箱。
   - 邮件标题使用完整文件名，包括 `.html` 后缀，除非用户另有要求。
   - 预计投递数 = 模板数 × 收件人数。

3. 准备浏览器
   - 显式选择 IAB：`browser = await agent.browsers.get("iab")`，完整读取其 `documentation()` 后再操作。
   - 打开目标页面，读取 DOM 快照，确认上传、收件人、标题和发送控件。
   - 文件上传属于用户初始请求明确授权的范围时，无需重复确认。
   - 在点击“发送邮件”前，按浏览器确认策略进行一次批次级最终确认，列出模板数、收件人和预计投递数。

4. 逐份上传与发送
   - 先监听 `filechooser`，再点击可见的 `label[for="html-file"]` 或页面标注的可见上传区域，然后用绝对路径设置文件。
   - 不要优先点击带 `sr-only` 的隐藏 `input[type="file"]`；它可能无法触发文件选择事件。
   - 上传后从页面确认显示的文件名，再填写同名标题。
   - 点击发送一次，等待按钮恢复并读取明确结果；不要因超时直接重复点击。
   - 只有页面出现“邮件服务器已接受 N 封邮件”且 `N` 等于收件人数，才把该模板记为“服务器已接受”。

5. 失败恢复
   - IAB 无法捕获文件选择器时，读取页面快照并检查可见上传标签；不要切换到 Chrome。
   - IAB 本身不可用或连接失败时，停止并向用户报告当前阻塞。
   - 结果不明确时标记“待核实”，先检查页面状态；未证明失败前不得重发，以免重复邮件。
   - 明确失败只重试当前模板；保留已成功集合，从未成功项继续。
   - CAPTCHA、登录或权限阻塞时按浏览器规则暂停并交接给用户。

6. 验收
   - 核对成功集合与原文件清单，确保遗漏为零且没有重复。
   - 报告模板数、收件人数、预计投递数、服务器接受数、失败数和待核实数。
   - 不把“服务器已接受”等同于“已送达”。若用户要求兼容性结论，再检查各测试邮箱中的送达、布局、字体、图片、链接、深色模式与移动端表现。

## 快速检查

| 检查项 | 通过条件 |
|---|---|
| 文件 | 扩展名和大小符合页面限制 |
| 标题 | 等于当前完整文件名 |
| 收件人 | 与确认清单完全一致 |
| 单模板结果 | 页面接受数等于收件人数 |
| 批次结果 | 成功 + 失败 + 待核实 = 模板总数 |
| 最终清单 | 无遗漏、无未说明重复 |

## 常见错误

- 通过 `getForUrl()` 或 `getDefault()` 选中 Chrome：必须显式使用 `agent.browsers.get("iab")`。
- 点击隐藏文件输入框后反复重试：改点可见 label，并在点击前监听 `filechooser`。
- 用固定等待时间判断成功：轮询按钮恢复与明确成功提示。
- 把一次页面成功提示当成整个批次成功：逐模板记录结果。
- 网络超时后立即重发：先标记待核实，避免重复发送。
- 只验证 SMTP 接受就声称兼容：兼容性必须以各邮箱实际渲染为准。