---
title: 测试文档
order: 4
category: pro
---

﻿# PisellEmail 组件测试用例文档

## 1 测试概述

### 1.1 测试目标

确保 PisellEmail 组件的功能完整性、稳定性和用户体验，特别是邮箱特有功能（格式校验、域名补全、mailto 发送、域名脱敏）。

### 1.2 测试范围

- 三种状态模式（只读、编辑、禁用）
- 邮箱格式校验（标准/严格 RFC 5322）
- 域名白名单/黑名单限制
- 域名智能补全（AutoComplete）
- mailto 邮件发送（只读态）
- 域名隐藏/脱敏
- 受控/非受控模式

### 1.3 测试方法

- 使用 Storybook 进行可视化测试
- 人工测试：UI 交互、域名补全、格式校验、mailto 功能验证

## 2 核心功能测试点

### 2.1 基础功能测试

#### 测试点 1：组件正常渲染

- **测试描述**：组件应该能够正常渲染
- **预期结果**：组件渲染成功，无报错
- **测试状态**：待测试 ⏳

#### 测试点 2：默认为编辑态

- **测试描述**：不传 mode 时，默认应为编辑态
- **预期结果**：渲染带邮件图标前缀的输入框
- **测试状态**：待测试 ⏳

### 2.2 邮箱格式校验测试（核心）

#### 测试点 3：标准格式校验（有效邮箱）

- **测试步骤**：
  1. 输入 "user@example.com"
  2. 失焦
- **预期结果**：
  - 无错误提示
  - 输入框无红色边框
- **测试状态**：待测试 ⏳

#### 测试点 4：标准格式校验（无效邮箱）

- **测试步骤**：
  1. 输入 "invalid-email"（无 @）
  2. 失焦
- **预期结果**：
  - 显示 "邮箱地址格式不正确"
  - 输入框显示红色边框
- **测试状态**：待测试 ⏳

#### 测试点 5：严格格式校验

- **测试步骤**：
  1. 设置 strictValidation=true
  2. 输入复杂邮箱格式（如带引号的本地部分）
- **预期结果**：
  - 符合 RFC 5322 标准的邮箱通过校验
- **测试状态**：待测试 ⏳

#### 测试点 6：缺少 @ 符号

- **测试步骤**：
  1. 输入 "userexample.com"
- **预期结果**：
  - 显示 "邮箱地址格式不正确"
- **测试状态**：待测试 ⏳

#### 测试点 7：@ 前为空

- **测试步骤**：
  1. 输入 "@example.com"
- **预期结果**：
  - 显示 "邮箱地址格式不正确"
- **测试状态**：待测试 ⏳

#### 测试点 8：@ 后为空

- **测试步骤**：
  1. 输入 "user@"
- **预期结果**：
  - 显示 "邮箱地址格式不正确"
- **测试状态**：待测试 ⏳

#### 测试点 9：域名无顶级域

- **测试步骤**：
  1. 输入 "user@example"
- **预期结果**：
  - 显示 "邮箱地址格式不正确"
- **测试状态**：待测试 ⏳

#### 测试点 10：必填校验

- **测试步骤**：
  1. 设置 required=true
  2. 输入框为空时失焦
- **预期结果**：
  - 显示 "请输入邮箱地址"
- **测试状态**：待测试 ⏳

### 2.3 域名白名单/黑名单测试

#### 测试点 11：白名单域名校验

- **测试步骤**：
  1. 设置 allowedDomains={['company.com', 'partner.com']}
  2. 输入 "user@gmail.com"
- **预期结果**：
  - 显示 "只允许以下域名：company.com, partner.com"
- **测试状态**：待测试 ⏳

#### 测试点 12：白名单域名通过

- **测试步骤**：
  1. 设置 allowedDomains={['company.com']}
  2. 输入 "user@company.com"
- **预期结果**：
  - 校验通过，无错误提示
- **测试状态**：待测试 ⏳

#### 测试点 13：黑名单域名校验

- **测试步骤**：
  1. 设置 blockedDomains={['tempmail.com', '10minutemail.com']}
  2. 输入 "user@tempmail.com"
- **预期结果**：
  - 显示 "该邮箱域名不可用"
- **测试状态**：待测试 ⏳

#### 测试点 14：黑名单域名通过

- **测试步骤**：
  1. 设置 blockedDomains={['tempmail.com']}
  2. 输入 "user@gmail.com"
- **预期结果**：
  - 校验通过，无错误提示
- **测试状态**：待测试 ⏳

### 2.4 域名智能补全测试（核心）

#### 测试点 15：域名补全触发

- **测试步骤**：
  1. 输入 "user@"
  2. 观察下拉框
- **预期结果**：
  - 显示所有常用域名建议（gmail.com、qq.com、163.com 等）
- **测试状态**：待测试 ⏳

#### 测试点 16：域名补全过滤

- **测试步骤**：
  1. 输入 "user@g"
- **预期结果**：
  - 只显示以 "g" 开头的域名（gmail.com）
- **测试状态**：待测试 ⏳

#### 测试点 17：域名补全选择

- **测试步骤**：
  1. 输入 "user@"
  2. 键盘下键选择 "gmail.com"
  3. 回车确认
- **预期结果**：
  - 输入框显示 "user@gmail.com"
  - 触发 onSelect 回调
- **测试状态**：待测试 ⏳

#### 测试点 18：自定义补全域名

- **测试步骤**：
  1. 设置 autoCompleteDomains={['company.com', 'custom.com']}
  2. 输入 "user@"
- **预期结果**：
  - 只显示自定义的域名列表
- **测试状态**：待测试 ⏳

#### 测试点 19：关闭域名补全

- **测试步骤**：
  1. 设置 enableAutoComplete=false
  2. 输入 "user@"
- **预期结果**：
  - 不显示下拉框
  - 无任何建议
- **测试状态**：待测试 ⏳

#### 测试点 20：@ 前为空不补全

- **测试步骤**：
  1. 输入 "@gmail"
- **预期结果**：
  - 不显示补全建议
- **测试状态**：待测试 ⏳

### 2.5 mailto 邮件发送测试（核心）

#### 测试点 21：只读态点击发邮件

- **测试步骤**：
  1. mode="read", value="support@example.com"
  2. 点击邮箱地址
- **预期结果**：
  - 邮箱显示为紫色链接（#7F56DA）
  - 点击后唤起邮件客户端
  - URL 为 "mailto:support@example.com"
- **测试状态**：待测试 ⏳

#### 测试点 22：mailto 带参数

- **测试步骤**：
  1. 设置 mailtoOptions={{subject: '产品咨询', body: '您好'}}
  2. 点击邮箱
- **预期结果**：
  - URL 为 "mailto:support@example.com?subject=产品咨询&body=您好"
  - 邮件客户端预填主题和正文
- **测试状态**：待测试 ⏳

#### 测试点 23：邮件图标显示

- **测试步骤**：
  1. mode="read"
  2. showEmailIcon=true
- **预期结果**：
  - 邮箱地址右侧显示邮件图标
  - 点击图标可发邮件
- **测试状态**：待测试 ⏳

#### 测试点 24：关闭 mailto 功能

- **测试步骤**：
  1. mode="read"
  2. enableMailto=false
- **预期结果**：
  - 邮箱显示为普通文本，无链接样式
  - 点击无反应
- **测试状态**：待测试 ⏳

#### 测试点 25：关闭链接样式

- **测试步骤**：
  1. mode="read"
  2. displayAsLink=false
- **预期结果**：
  - 邮箱显示为普通文本颜色（#101828）
  - 但点击仍可发邮件（如果 enableMailto=true）
- **测试状态**：待测试 ⏳

#### 测试点 26：mailto 回调触发

- **测试步骤**：
  1. 设置 onMailto 回调
  2. 点击邮箱
- **预期结果**：
  - 触发 onMailto 回调，参数为邮箱地址
- **测试状态**：待测试 ⏳

### 2.6 域名隐藏/脱敏测试

#### 测试点 27：部分隐藏（partial 模式）

- **测试步骤**：
  1. mode="read"
  2. value="user@gmail.com"
  3. hideDomain=true, maskPattern="partial"
- **预期结果**：
  - 显示 "u***@gmail.com"
- **测试状态**：待测试 ⏳

#### 测试点 28：完全隐藏（full 模式）

- **测试步骤**：
  1. maskPattern="full"
- **预期结果**：
  - 显示 "user@***"
- **测试状态**：待测试 ⏳

#### 测试点 29：脱敏后仍可发邮件

- **测试步骤**：
  1. hideDomain=true
  2. enableMailto=true
  3. 点击脱敏后的邮箱
- **预期结果**：
  - 仍可正常唤起邮件客户端
  - 使用原始邮箱地址
- **测试状态**：待测试 ⏳

### 2.7 编辑态功能测试

#### 测试点 30：最大长度限制

- **测试步骤**：
  1. 设置 maxLength=20
  2. 尝试输入超过20个字符
- **预期结果**：
  - 自动截断，不允许超出
- **测试状态**：待测试 ⏳

#### 测试点 31：清空按钮

- **测试步骤**：
  1. 设置 allowClear=true
  2. 输入邮箱后观察
- **预期结果**：
  - 输入框右侧显示清空按钮
  - 点击清空内容
- **测试状态**：待测试 ⏳

#### 测试点 32：自动聚焦

- **测试步骤**：
  1. 设置 autoFocus=true
  2. 渲染组件
- **预期结果**：
  - 输入框自动获得焦点
- **测试状态**：待测试 ⏳

#### 测试点 33：占位文本

- **测试步骤**：
  1. 设置 placeholder="请输入工作邮箱"
- **预期结果**：
  - 空输入框显示自定义占位文本
- **测试状态**：待测试 ⏳

### 2.8 校验触发时机测试

#### 测试点 34：onChange 校验

- **测试步骤**：
  1. 设置 validateTrigger="onChange"
  2. 输入无效邮箱
- **预期结果**：
  - 实时显示错误提示
- **测试状态**：待测试 ⏳

#### 测试点 35：onBlur 校验

- **测试步骤**：
  1. 设置 validateTrigger="onBlur"
  2. 输入无效邮箱但不失焦
- **预期结果**：
  - 无错误提示
  - 失焦后才显示错误
- **测试状态**：待测试 ⏳

#### 测试点 36：both 校验

- **测试步骤**：
  1. 设置 validateTrigger="both"
  2. 输入无效邮箱
- **预期结果**：
  - 输入时和失焦时都会校验
- **测试状态**：待测试 ⏳

### 2.9 自定义校验测试

#### 测试点 37：自定义校验函数

- **测试步骤**：
  1. 设置 customValidator={(email) => email.endsWith('@company.com') || '必须使用公司邮箱'}
  2. 输入 "user@gmail.com"
- **预期结果**：
  - 显示 "必须使用公司邮箱"
- **测试状态**：待测试 ⏳

#### 测试点 38：自定义错误提示

- **测试步骤**：
  1. 设置 errorMessage="邮箱格式有误，请检查"
  2. 输入无效邮箱
- **预期结果**：
  - 显示自定义错误提示
- **测试状态**：待测试 ⏳

### 2.10 只读态展示测试

#### 测试点 39：字体样式配置

- **测试步骤**：
  1. mode="read"
  2. fontSize=18, fontWeight=600, color="#FF0000"
- **预期结果**：
  - 邮箱显示为18px、粗体、红色
- **测试状态**：待测试 ⏳

#### 测试点 40：链接颜色配置

- **测试步骤**：
  1. mode="read", displayAsLink=true
  2. linkColor="#FF5722"
- **预期结果**：
  - 链接显示为自定义颜色
- **测试状态**：待测试 ⏳

### 2.11 禁用态测试

#### 测试点 41：编辑态禁用

- **测试步骤**：
  1. mode="edit", disabled=true
- **预期结果**：
  - 输入框不可输入
  - 透明度 40%
  - 无法获取焦点
- **测试状态**：待测试 ⏳

#### 测试点 42：只读态禁用

- **测试步骤**：
  1. mode="read", disabled=true
- **预期结果**：
  - 邮箱地址显示，透明度 40%
  - 不可点击发邮件
- **测试状态**：待测试 ⏳

### 2.12 受控/非受控模式测试

#### 测试点 43：受控模式

- **测试步骤**：
  1. 传入 value 和 onChange
  2. 输入内容
- **预期结果**：
  - value 由外部控制
  - onChange 被触发
- **测试状态**：待测试 ⏳

#### 测试点 44：非受控模式

- **测试步骤**：
  1. 只传入 defaultValue
  2. 输入内容
- **预期结果**：
  - 组件内部管理状态
  - 可正常输入
- **测试状态**：待测试 ⏳

### 2.13 边界情况测试

#### 测试点 45：空值处理

- **测试步骤**：
  1. value="" 或 undefined
- **预期结果**：
  - 不报错，显示为空
- **测试状态**：待测试 ⏳

#### 测试点 46：特殊字符邮箱

- **测试步骤**：
  1. 输入 "user+tag@example.com"
- **预期结果**：
  - 标准校验通过
- **测试状态**：待测试 ⏳

#### 测试点 47：大写邮箱

- **测试步骤**：
  1. 输入 "USER@EXAMPLE.COM"
- **预期结果**：
  - 校验通过
  - （可选）自动转小写
- **测试状态**：待测试 ⏳

#### 测试点 48：多个 @ 符号

- **测试步骤**：
  1. 输入 "user@@example.com"
- **预期结果**：
  - 显示 "邮箱地址格式不正确"
- **测试状态**：待测试 ⏳

#### 测试点 49：首尾空格

- **测试步骤**：
  1. 输入 " user@example.com "
- **预期结果**：
  - 自动去除首尾空格
  - 校验通过
- **测试状态**：待测试 ⏳

#### 测试点 50：超长邮箱

- **测试步骤**：
  1. 输入超过254字符的邮箱
- **预期结果**：
  - 自动截断在254字符
- **测试状态**：待测试 ⏳

## 3 事件回调测试

#### 测试点 51：onChange 回调

- **测试步骤**：
  1. 输入邮箱
  2. 观察回调
- **预期结果**：
  - 每次输入都触发 onChange
  - 参数为当前值
- **测试状态**：待测试 ⏳

#### 测试点 52：onBlur 回调

- **测试步骤**：
  1. 输入后失焦
- **预期结果**：
  - 触发 onBlur，参数为当前值
- **测试状态**：待测试 ⏳

#### 测试点 53：onFocus 回调

- **测试步骤**：
  1. 点击输入框
- **预期结果**：
  - 触发 onFocus
- **测试状态**：待测试 ⏳

#### 测试点 54：onSelect 回调

- **测试步骤**：
  1. 选择域名补全建议
- **预期结果**：
  - 触发 onSelect，参数为选中的邮箱
- **测试状态**：待测试 ⏳

#### 测试点 55：onValidate 回调

- **测试步骤**：
  1. 输入无效邮箱后触发校验
- **预期结果**：
  - 触发 onValidate
  - 参数包含 isValid=false 和 errors 数组
- **测试状态**：待测试 ⏳

## 4 性能测试

#### 测试点 56：域名补全响应性能

- **测试方法**：输入 @ 后立即显示建议
- **性能指标**：响应时间 < 5ms
- **测试状态**：待测试 ⏳

#### 测试点 57：大量组件渲染

- **测试方法**：渲染50个组件
- **性能指标**：正常渲染，不卡顿
- **测试状态**：待测试 ⏳

#### 测试点 58：频繁输入性能

- **测试方法**：快速连续输入字符
- **性能指标**：输入流畅，无延迟
- **测试状态**：待测试 ⏳

## 5 兼容性测试

#### 测试点 59：浏览器兼容性

- **测试浏览器**：Chrome、Firefox、Safari、Edge
- **预期结果**：所有功能正常
- **测试状态**：待测试 ⏳

#### 测试点 60：移动端兼容性

- **测试设备**：iOS、Android
- **预期结果**：触摸交互正常，mailto 功能正常
- **测试状态**：待测试 ⏳

#### 测试点 61：邮件客户端兼容性

- **测试客户端**：Outlook、Gmail、Apple Mail、Thunderbird
- **预期结果**：mailto 链接正常唤起邮件客户端
- **测试状态**：待测试 ⏳

## 6 测试覆盖率要求

### 6.1 功能覆盖率

- **状态模式**：100%（3/3）
- **邮箱校验**：100%（标准/严格/分部/域名）
- **域名补全**：100%（显示/过滤/选择/自定义）
- **mailto 功能**：100%（基础/带参数/回调）
- **域名脱敏**：100%（partial/full）
- **白名单/黑名单**：100%

### 6.2 重点测试项

1. ✅ **邮箱格式校验**：PisellEmail 的核心特性，包括标准和严格校验
2. ✅ **域名智能补全**：基于 AutoComplete 的域名提示功能
3. ✅ **mailto 邮件发送**：只读态一键唤起邮件客户端
4. ✅ **域名隐藏/脱敏**：隐私保护功能
5. ✅ **域名白名单/黑名单**：企业邮箱限制等场景

---

## 7 Bug 汇总模块

### 已发现的 Bug 列表

> 暂无 Bug

### 已修复的 Bug 列表

> 暂无已修复 Bug

---

**说明**：

- 人工测试时发现的 Bug 请记录在此模块
- Bug 修复后请更新状态和修复时间
- Bug 格式：【Bug ID】【严重程度】【Bug 描述】【复现步骤】【修复状态】【修复时间】
