Cypress - GitHub

Cypress - GitHub 集成

将 Cypress 与 GitHub 集成可通过在你的拉取请求（Pull Request）中提供自动化检查和丰富的报告来增强你的开发工作流程。这主要通过 Cypress Dashboard 和 Cypress GitHub App 实现。

GitHub 集成的优势

**拉取请求状态检查：**为每个拉取请求自动运行 Cypress 测试，并在 GitHub 上直接查看通过/失败状态。
**测试结果摘要：**获取详细报告，包括截图和视频（如果启用），并从 PR 链接到这些报告。
**阻止合并不稳定或失败的测试：**强制执行要求测试通过才能合并代码的策略。
**改进协作：**开发人员和 QA 可以轻松查看测试结果并诊断失败。

设置集成

集成过程包括将你的 Cypress 项目（通过 Cypress Dashboard）连接到你的 GitHub 仓库。

步骤 1：在 Cypress Dashboard 中设置项目

如果你尚未完成，你需要先在 Cypress Dashboard 中设置你的项目：

登录 Cypress Dashboard。
创建或选择一个组织。
设置一个新项目，这将为你提供一个唯一的 projectId。
将此 projectId 添加到你的 cypress.config.js 或 cypress.config.ts 文件中。

// cypress.config.js
const { defineConfig } = require('cypress');

module.exports = defineConfig({
  projectId: 'your-project-id',
  e2e: {
    // ...
  },
});

步骤 2：安装 Cypress GitHub App

Cypress GitHub App 需要为你希望集成的 GitHub 组织或特定仓库安装和配置。

**从 Cypress Dashboard：**在 Cypress Dashboard 中导航到你的项目设置。查找 ‘集成’ 或 ‘GitHub 集成’ 部分。
点击安装或配置 GitHub App 的选项。这通常会重定向你到 GitHub。
**在 GitHub 上：**系统会提示你选择要在哪个 GitHub 账户或组织上安装该应用。
然后你可以选择授予访问所有仓库的权限，或仅选择特定仓库。
授权并安装该应用。

UI 标签和步骤可能略有不同，因为 Cypress Dashboard 和 GitHub 都在不断发展，因此请参考官方 Cypress 文档以获取最新的视觉指南。

步骤 3：在项目设置中配置 GitHub 集成

安装 App 后，你需要将你的 Cypress Dashboard 项目链接到特定的 GitHub 仓库：

在 Cypress Dashboard 中，进入你的项目设置并找到 GitHub 集成部分。
你应该能够选择要与此 Cypress 项目关联的 GitHub 仓库。
配置诸如 PR 状态检查和提交状态更新之类的选项。

使用 GitHub Actions 在 CI 中运行测试（示例）

要在拉取请求上触发 Cypress 测试，你通常会使用 CI/CD 提供商。GitHub Actions 是一个流行的选择。以下是一个基本的 GitHub Actions 工作流程文件 (.github/workflows/cypress-tests.yml) 示例：

name: Cypress 测试

on:
  pull_request:
    branches:
      - main # 或你的默认分支

jobs:
  cypress-run:
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v3

      - name: Cypress 运行
        uses: cypress-io/github-action@v6
        with:
          record: true # 启用记录到 Cypress Dashboard
          # browser: chrome # 可选指定浏览器
        env:
          CYPRESS_RECORD_KEY: ${{ secrets.CYPRESS_RECORD_KEY }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # 状态检查所需

重要提示：

你需要将你的 CYPRESS_RECORD_KEY（从 Cypress Dashboard 项目设置中获取）作为密文添加到 GitHub 仓库设置中（位于 ‘Secrets and variables’ > ‘Actions’ 下）。
GITHUB_TOKEN 通常默认可用，但为了某些权限显式传递它是一个好习惯。

故障排除

**缺少状态检查：**确保 Cypress GitHub App 对你的仓库具有必要的权限，并且在 Cypress Dashboard 中正确配置了集成。
**身份验证问题：**验证你的 CYPRESS_RECORD_KEY 是否正确并在你的 CI 环境中可访问。
**查阅官方文档：**Cypress 和 GitHub 都提供了详细文档。请查阅它们以获取具体的设置步骤和常见问题故障排除方法。

将 Cypress 与 GitHub 集成可以显著简化测试和审查过程，帮助团队保持更高代码质量。