在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

gatsbyjs/gatsby

菜单

端到端测试

相关源文件

Gatsby 中的端到端 (E2E) 测试从用户的角度验证 Gatsby 站点的完整功能，确保所有组件都能按预期协同工作。本文档将介绍 Gatsby 的 E2E 测试基础设施是如何组织的，测试如何执行，以及如何理解测试结果。

有关编写 Gatsby 组件单元测试的信息，请参阅 测试基础设施概述 或 CI/CD 管道，了解有关在持续集成环境中如何执行测试的详细信息。

Gatsby E2E 测试方法概述

Gatsby 采用全面的 E2E 测试策略，利用多种测试框架来验证跨不同环境和配置的功能。这些测试旨在模拟真实的用户交互，并验证 Gatsby 站点在开发和生产环境中的行为是否正确。

来源：e2e-tests/development-runtime/package.json54-58 e2e-tests/production-runtime/package.json47-54

测试框架架构

Gatsby 的 E2E 测试主要依赖两个测试框架

  1. Cypress - 用于所有测试场景的全面基于浏览器的测试
  2. Playwright - 在某些测试场景中与 Cypress 一起使用，以提供额外的覆盖

测试基础设施遵循一种模式：Gatsby 站点以开发模式构建或启动，启动一个测试服务器，然后针对正在运行的站点执行测试。

来源：e2e-tests/development-runtime/package.json32-58 e2e-tests/production-runtime/package.json29-54

测试目录组织

E2E 测试被组织到几个目录中，每个目录测试 Gatsby 的不同方面

测试目录目的环境关键测试功能
development-runtime在开发模式下测试 Gatsby开发热重载、按需查询、图像处理
production-runtime在生产模式下测试 Gatsby生产性能、离线功能、预取
mdx测试 MDX 集成两者MDX 渲染、组件导入
path-prefix测试路径前缀功能生产带路径前缀的路由、资源加载
contentful测试 Contentful 集成生产CMS 连接、图像处理
visual-regression测试视觉外观生产通过图像快照实现 UI 一致性
themes测试 Gatsby 主题两者主题组合、遮蔽
trailing-slash测试 URL 尾部斜杠选项两者不同配置下的 URL 格式行为

来源：每个测试目录的 package.json 文件

测试执行基础设施

E2E 测试使用 start-server-and-test 工具来协调测试执行。此工具确保在执行测试之前 Gatsby 服务器正在运行。

来源：e2e-tests/development-runtime/package.json42-58 e2e-tests/production-runtime/package.json41-54

常用测试命令

E2E 测试目录共享通用的 npm 脚本来运行测试

命令目的
npm test运行所有测试（如有必要则构建并执行测试）
npm run build使用测试标志构建 Gatsby 站点
npm run develop以开发模式启动 Gatsby 并启用测试标志
npm run serve服务生产构建
npm run cy:run无头模式下运行 Cypress 测试
npm run cy:open打开 Cypress UI 进行交互式测试
npm run playwright运行 Playwright 测试
npm run start-server-and-test协调服务器启动和测试执行

环境变量

有几个环境变量用于配置测试环境

  • CYPRESS_SUPPORT=y - 在 Gatsby 中启用 Cypress 支持
  • ENABLE_GATSBY_REFRESH_ENDPOINT=y - 为测试启用刷新端点
  • GATSBY_ENABLE_QUERY_ON_DEMAND_IN_CI=y - 在 CI 中启用按需查询
  • GATSBY_ENABLE_LAZY_IMAGES_IN_CI=y - 在 CI 中启用延迟图像加载
  • TEST_PLUGIN_OFFLINE=y - 测试离线插件功能

来源：e2e-tests/development-runtime/package.json32-45 e2e-tests/production-runtime/package.json29-34

使用不同配置进行测试

一些测试旨在测试带有不同配置选项的 Gatsby

尾部斜杠测试

尾部斜杠测试用于验证 Gatsby 的 URL 行为与不同的 trailingSlash 配置选项

  • always - 始终为 URL 添加尾部斜杠
  • never - 绝不为 URL 添加尾部斜杠
  • ignore - 保持 URL 原样

来源：e2e-tests/trailing-slash/package.json22-32

离线插件测试

production-runtime 测试包含用于离线插件功能的特定测试

来源：e2e-tests/production-runtime/package.json30-31 e2e-tests/production-runtime/package.json39

视觉回归测试

视觉回归测试可确保 Gatsby 站点的视觉外观保持一致。这些测试使用图像快照将当前外观与已知良好状态进行比较。

命令目的
cy:update-snapshots更新基线快照以进行视觉比较
cy:clean-snapshots删除现有快照以重新开始

视觉回归测试对于检测功能测试可能无法捕获的意外 UI 更改特别有用。

来源：e2e-tests/visual-regression/package.json30-31

测试基础设施依赖项

E2E 测试基础设施依赖于几个关键的依赖项

  1. 测试框架:

    • Cypress (cypress)
    • Playwright (@playwright/test)

  2. 实用工具:

    • start-server-and-test - 协调服务器启动和测试执行
    • cross-env - 跨平台设置环境变量
    • @simonsmith/cypress-image-snapshot - 视觉回归测试
    • gatsby-cypress - Gatsby 特定 Cypress 命令

  3. 开发服务器:

    • express - 用于在测试期间服务静态文件
    • fs-extra - 用于测试设置/拆卸的文件系统操作

来源：所有测试目录的 package.json 依赖项部分

本地运行 E2E 测试

开发人员可以在本地运行 E2E 测试，以在提交更改之前验证它们

  1. 用于交互式调试:

    这将打开 Cypress UI 进行交互式测试执行。

  2. 用于无头执行:

    这将以无头模式运行所有测试，类似于 CI 环境。

  3. 针对特定测试目录：导航到特定测试目录并运行适当的测试命令。

来源：e2e-tests/development-runtime/package.json51-52 e2e-tests/production-runtime/package.json42-43

E2E 测试目录结构

每个 E2E 测试目录通常包含

  1. cypress/ 目录，包含

    • integration/ 或 e2e/ - 测试文件
    • fixtures/ - 测试数据
    • support/ - 自定义命令和实用程序
    • plugins/ - Cypress 插件
    • configs/ - 测试配置

  2. src/ 目录，包含正在测试的 Gatsby 站点

  3. 配置文件:

    • package.json - 依赖项和测试脚本
    • gatsby-config.js - Gatsby 配置
    • gatsby-node.js - Gatsby 节点 API 实现
    • 在 scripts/ 目录中的各种实用脚本

来源：所有提供的 package.json 文件中的文件路径

结论

Gatsby 的 E2E 测试基础设施跨不同环境和配置提供了对 Gatsby 功能的全面验证。通过使用多种测试框架和各种测试场景，这些测试可确保 Gatsby 站点对最终用户正常运行。

了解此测试基础设施对于需要验证其更改不会破坏现有功能的 Gatsby 贡献者，以及希望在其项目中实施类似测试方法的 Gatsby 用户来说非常有价值。