# @bhavinkumarvegad/playwright-email-utils 中文文档

规范地址：https://npmcn.com/package/%40bhavinkumarvegad/playwright-email-utils/

版本：1\.1\.0
npm 元数据更新时间：2025-06-03T03:18:21.070Z
中文译文更新时间：2026-11-08T01:13:01.928Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40bhavinkumarvegad/playwright-email-utils
原文对照：https://npmcn.com/package/%40bhavinkumarvegad/playwright-email-utils/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：57.3 kB，31 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2025-05-26T06:52:44.200Z
- 最新版本发布：2025-06-03T03:18:20.902Z
- 近 30 天下载量：4022（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 0 个）

## 中文简介

在来自Yopmail,Gmail和其他供应商的 Playwright 测试中处理邮件的可重用功能.

## 安装

```sh
npm install @bhavinkumarvegad/playwright-email-utils
```

也可以使用：`pnpm add @bhavinkumarvegad/playwright-email-utils`、`yarn add @bhavinkumarvegad/playwright-email-utils`、`bun add @bhavinkumarvegad/playwright-email-utils`

## README

# Playwright 电子邮件 Utils

用 Playwright 从一次性电子邮件服务(例如 Yopmail) 和 Gmail 中提取和交互邮件的功能包 .

## 特征

-   支持多个电子邮件提供者 :
    -   Gmail( 通过 Gmail API)
    -   Yopmail( 通过网络界面)
-   提取内容、 点击链接或动态获取属性
-   为延迟发送电子邮件而建的投票
-   有多个策略的高级电子邮件内容提取
-   可选自动删除支持
-   方便其他提供者扩展

## 安装

```bash
npm install @bhavinkumarvegad/playwright-email-utils
```

## Gmail 设置

### 1\. 设置 Gmail API 证书

1.  转到 [谷歌云控台](https://console.cloud.google.com/)
2.  创建新工程或选择现有工程
3.  为您的工程启用 Gmail API
4.  创建 OAuth 2. 0 证书( 身份识别和客户端保密)
5.  将 http://localhost 添加到授权重定向的 URI

### 2\. 刷新托肯语Name

1.  首先创建一个 `.env` 在工程根中带有证书的文件 :

```env
GMAIL_CLIENT_ID=your-client-id
GMAIL_CLIENT_SECRET=your-client-secret
```

2.  配置环境变量 :

```bash
npm install dotenv
```

更新您的 `playwright.config.ts`数字 :

```typescript
import 'dotenv/config';

export default defineConfig({
  // ... rest of your config
});
```

3.  生成刷新符号 :

```bash
npx get-gmail-token
```

4.  跟随提示:
    -   访问授权 URL
    -   允许访问您的 Gmail 账户
    -   从重定向 URL 复制代码
    -   把它粘入终端
    -   将提供的配置添加到您的.env 文件

## 用法实例

### Gmail 整合

#### 基本电子邮件搜索

```typescript
import { emailUtils } from '@bhavinkumarvegad/playwright-email-utils';
import 'dotenv/config';

test('Read email from Gmail', async () => {
  const config = {
    clientId: process.env.GMAIL_CLIENT_ID!,
    clientSecret: process.env.GMAIL_CLIENT_SECRET!,
    refreshToken: process.env.GMAIL_REFRESH_TOKEN!
  };

  const email = await emailUtils.getEmail.fromGmail(config, {
    subject: 'New release on live - 1.1.0',
    from: 'sender@example.com',
    to: 'recipient@example.com',
    afterTime: '2025-06-01 00:00:00',
    beforeTime: '2025-06-01 23:59:59'
  });

  if (email) {
    console.log('Subject:', email.subject);
    console.log('From:', email.from);
    console.log('Body:', email.body);
  }
});
```

#### 高级内容提取

```typescript
const extractionRules = [
  {
    field: 'releaseNotes',
    type: 'between-markers',
    startMarker: 'Release Notes:',
    endMarker: 'End of Release Notes'
  },
  {
    field: 'deploymentUrl',
    type: 'regex',
    regex: /https?:\/\/[^\s<]+/
  },
  {
    field: 'fullContent',
    type: 'full-text'
  }
];

const result = await emailUtils.getEmail.fromGmailWithDetails(
  config,
  { subject: 'New Release' },
  extractionRules
);

if (result.email) {
  console.log('Release Notes:', result.extractedDetails.releaseNotes);
  console.log('URL:', result.extractedDetails.deploymentUrl);
}
```

### Yopmail 整合

#### 获取链接

```typescript
const result = await emailUtils.getEmail.fromYopmail(page, 'demoInbox', 'Welcome Email', [
  {
    selector: { type: 'text', value: 'Click here' },
    action: 'getAttribute',
    attributeName: 'href',
    description: 'Reset Link'
  }
]);
```

#### 多个动作

```typescript
const results = await emailUtils.getEmail.fromYopmail(page, 'testInbox', 'Order Confirmation', [
  // Extract text content
  {
    selector: { type: 'text', value: 'Order ID:' },
    action: 'textContent',
    description: 'Order Number'
  },
  // Click a button
  {
    selector: { type: 'role', value: { role: 'button', name: 'Track Order' }},
    action: 'click',
    description: 'Track Order Button'
  },
  // Get attribute using custom locator
  {
    selector: { type: 'locator', value: '.verification-code' },
    action: 'textContent',
    description: 'Verification Code'
  }
]);
```

#### 自动删除示例

```typescript
const result = await emailUtils.getEmail.fromYopmail(
  page,
  'inbox123',
  'Password Reset',
  [
    {
      selector: { type: 'text', value: 'verification code is:' },
      action: 'textContent',
      description: 'Reset Code'
    }
  ],
  true // Enable auto-delete
);
```

## 采掘业战略

### Gmail 内容提取

在与Gmail合作时,您有三种复杂的提取策略:

1.  **在标记之间** (单位:千美元)`type: 'between-markers'`(中文(简体) )
    
    -   提取电子邮件正文中特定标记之间的内容
    -   对结构化内容的理想,如发布说明或核查代码
    -   示例
    
    ```typescript
    {
      field: 'releaseNotes',
      type: 'between-markers',
      startMarker: 'Release Notes:',
      endMarker: 'End of Release Notes'
    }
    ```
    
2.  **正则表达式** (单位:千美元)`type: 'regex'`(中文(简体) )
    
    -   使用正则图案提取内容
    -   适合URL,版本编号,代码等.
    -   示例
    
    ```typescript
    {
      field: 'confirmationUrl',
      type: 'regex',
      regex: /https:\/\/confirm\.example\.com\/[a-zA-Z0-9-]+/
    }
    ```
    
3.  **全文** (单位:千美元)`type: 'full-text'`(中文(简体) )
    
    -   获取完整的电子邮件正文
    -   需要全部内容时有用
    -   示例
    
    ```typescript
    {
      field: 'completeEmail',
      type: 'full-text'
    }
    ```
    

Gmail 提取规则结构 :

```typescript
interface EmailExtractionRule {
  field: string;              // Name for the extracted content
  type: 'between-markers' | 'regex' | 'full-text';
  startMarker?: string;       // Required for 'between-markers'
  endMarker?: string;        // Required for 'between-markers'
  regex?: RegExp;            // Required for 'regex'
}
```

### Yopmail 内容提取

对于Yopmail,您有基于UI相互作用的不同提取方法:

1.  **文本内容** (单位:千美元)`action: 'textContent'`(中文(简体) )
    
    -   从元素中提取文本内容
    -   示例
    
    ```typescript
    {
      selector: { type: 'text', value: 'Order ID:' },
      action: 'textContent',
      description: 'Order Number'
    }
    ```
    
2.  **属性值** (单位:千美元)`action: 'getAttribute'`(中文(简体) )
    
    -   提取特定属性( 如 href, 值)
    -   示例
    
    ```typescript
    {
      selector: { type: 'text', value: 'Reset Password' },
      action: 'getAttribute',
      attributeName: 'href',
      description: 'Reset Link'
    }
    ```
    
3.  **单击并提取** (单位:千美元)`action: 'click'`(中文(简体) )
    
    -   点击元素并可以与其他动作结合
    -   示例
    
    ```typescript
    {
      selector: { type: 'role', value: { role: 'button', name: 'View Details' }},
      action: 'click',
      description: 'Open Details'
    }
    ```
    

Yopmail 提取规则结构 :

```typescript
interface EmailAction {
  selector: {
    type: 'text' | 'role' | 'locator';
    value: string | { role: string; name?: string };
  };
  action: 'click' | 'textContent' | 'getAttribute';
  attributeName?: string;     // Required for getAttribute
  description: string;
}
```

## 解决问题

1.  环境变量
    
    -   保证之后没有空格 `=` 在.env文件中
    -   校验 `dotenv` 安装和配置
    -   检查环境变量已装入
2.  认证问题
    
    -   使用 `npx get-gmail-token`
    -   确保给予所有必要的许可
3.  电子邮件搜索问题
    
    -   校验搜索参数
    -   检查账户中存在的电子邮件
    -   对延迟的邮件使用重试机制

## 许可证

麻省理工学院

## 常见问题

### @bhavinkumarvegad/playwright-email-utils 是什么？

在来自Yopmail,Gmail和其他供应商的 Playwright 测试中处理邮件的可重用功能\.

### 如何安装 @bhavinkumarvegad/playwright-email-utils？

在项目目录运行 npm install @bhavinkumarvegad/playwright-email-utils，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 get-gmail-token，可以用 npx get-gmail-token 直接运行。

### @bhavinkumarvegad/playwright-email-utils 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @bhavinkumarvegad/playwright-email-utils 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @bhavinkumarvegad/playwright-email-utils 可以商用吗？

@bhavinkumarvegad/playwright-email-utils 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bhavinkumarvegad/playwright-email-utils 的下载量有多少？

根据 npm 官方下载统计，@bhavinkumarvegad/playwright-email-utils 在 2026/10/08 – 2026/11/06 这 30 天内被下载 4,022 次，日均约 134 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @bhavinkumarvegad/playwright-email-utils 还在维护吗？

最新版本 1\.1\.0 发布于 2025/06/03（1\.4 年前）；至今共发布 3 个版本，其中过去 12 个月发布了 0 个；首次发布于 2025/05/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。