实现无UI交互Gmail API读写及Cypress自动化测试自动认证

问题背景 #

• 希望无需浏览器/UI交互，通过Postman调用Gmail API实现邮件读写
• 在Cypress测试用例中调用Gmail API读写邮件时遇到问题，现有代码需手动刷新令牌，寻求基于JavaScript的自动化方案，自动生成Gmail API运行所需的全部必要认证内容

现有Cypress代码：

import { google } from "googleapis";

Cypress.Commands.add("getLatestEmail", () => {
  // Authenticate with Gmail API
  const auth = new google.auth.GoogleAuth({
  keyFile: "path/to/your/credentials.json",
  scopes: ["https://www.googleapis.com/auth/gmail.readonly"],
});
const gmail = google.gmail({ version: "v1", auth });

// Fetch list of emails
return gmail.users.messages
.list({
  userId: "me",
  q: "is:inbox", // Filter by inbox
})
.then((response) => {
  // Get the latest email
  const latestEmailId = response.data.messages[0].id;

  // Fetch the latest email
  return gmail.users.messages.get({
    userId: "me",
    id: latestEmailId,
  });
})
.then((email) => {
  // Return email data
  return email.data;
});
});

解决方案 #

Postman无UI调用Gmail API配置 #

使用服务账号密钥实现无UI自动认证，无需手动刷新令牌：

• 第一步：在Google Cloud控制台创建服务账号，下载JSON格式的密钥文件
• 第二步：在Postman中配置OAuth2.0认证，选择JWT Bearer Token类型
• 第三步：填写JWT参数：
  • 上传下载的JSON密钥文件
  • 受众：https://www.googleapis.com/oauth2/v4/token
  • 作用域：根据需求选择，如只读https://www.googleapis.com/auth/gmail.readonly或读写https://www.googleapis.com/auth/gmail.modify
  • 颁发者：服务账号的邮箱地址
• 第四步：点击「获取访问令牌」，Postman会自动生成并定期刷新令牌
• 第五步：调用Gmail API接口时，将令牌放在Authorization请求头中（格式：Bearer <token>）

Cypress中自动认证调用Gmail API优化方案 #

基于google-auth-library实现令牌自动刷新，优化后的代码如下：

import { google } from "googleapis";

Cypress.Commands.add("getLatestEmail", async () => {
  // 初始化认证，自动处理令牌缓存与刷新
  const auth = new google.auth.GoogleAuth({
    keyFile: "cypress/fixtures/credentials.json", // 建议将密钥放在fixtures目录
    scopes: ["https://www.googleapis.com/auth/gmail.readonly"],
    // 若访问指定用户邮箱（如测试邮箱），需开启域范围委派并设置subject
    // subject: "test-user@your-domain.com"
  });

  // 显式获取认证客户端，确保令牌自动刷新逻辑生效
  const authClient = await auth.getClient();
  const gmail = google.gmail({ version: "v1", auth: authClient });

  try {
    // 仅获取最新1封邮件，减少请求量
    const messagesResponse = await gmail.users.messages.list({
      userId: "me", // 域范围委派启用后可用，否则需指定具体邮箱地址
      q: "is:inbox",
      maxResults: 1
    });

    if (!messagesResponse.data.messages?.length) {
      throw new Error("收件箱无可用邮件");
    }

    const latestEmailId = messagesResponse.data.messages[0].id;
    // 获取完整邮件内容（含正文）
    const emailResponse = await gmail.users.messages.get({
      userId: "me",
      id: latestEmailId,
      format: "full"
    });

    return emailResponse.data;
  } catch (error) {
    Cypress.log({
      name: "GMAIL_API_ERROR",
      message: error.message
    });
    throw error;
  }
});

关键注意事项 #

• 域范围委派：若需访问特定用户的Gmail（如测试邮箱），需在Google Cloud控制台为服务账号启用域范围委派，并在G Suite/Workspace admin控制台授权相应API作用域
• 令牌自动刷新：google-auth-library会自动缓存访问令牌，当令牌过期时自动刷新，无需手动干预
• 敏感信息管理：建议将密钥文件路径、目标邮箱等配置放在Cypress环境变量中（如cypress.env.json），避免硬编码敏感内容

内容的提问来源于stack exchange，提问作者Bilal Hussain