agentic_huge_data_base / wiki
页面 Onyx · 11.4 测试基础设施·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 11.4

11.4 · 测试基础设施（Testing Infrastructure）

企业连接器与统一搜索 · 聚焦本章的模块关系、源码依据与实现要点。

项目Onyx 章节11.4 状态全文译文 模块测试、发布与运维、安装与启动、界面与交互、文档对象与元数据
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节Testing Infrastructure 上一章11.3 下一章11.5
源码线索
  • .cursor/skills/playwright/SKILL.md
  • .github/actions/slack-notify/action.yml
  • .github/actions/slack-notify/user-mappings.json
  • .github/dependabot.yml
  • .github/workflows/deployment.yml
  • .github/workflows/docker-tag-beta.yml
  • .github/workflows/docker-tag-latest.yml
  • .github/workflows/helm-chart-releases.yml
  • .github/workflows/post-merge-beta-cherry-pick.yml
  • .github/workflows/pr-database-tests.yml
模块标签
  • 测试、发布与运维
  • 安装与启动
  • 界面与交互
  • 文档对象与元数据
  • 智能体运行时

章节正文

测试基础设施

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/11.4-testing-infrastructure

测试基础设施

相关源文件

本章引用的主要源码文件：

  • .cursor/skills/playwright/SKILL.md
  • .github/actions/slack-notify/action.yml
  • .github/actions/slack-notify/user-mappings.json
  • .github/dependabot.yml
  • .github/workflows/deployment.yml
  • .github/workflows/docker-tag-beta.yml
  • .github/workflows/docker-tag-latest.yml
  • .github/workflows/helm-chart-releases.yml
  • .github/workflows/post-merge-beta-cherry-pick.yml
  • .github/workflows/pr-database-tests.yml
  • .github/workflows/pr-external-dependency-unit-tests.yml
  • .github/workflows/pr-helm-chart-testing.yml
  • .github/workflows/pr-integration-tests.yml
  • .github/workflows/pr-jest-tests.yml
  • .github/workflows/pr-playwright-tests.yml
  • .github/workflows/pr-python-checks.yml
  • .github/workflows/pr-python-connector-tests.yml
  • .github/workflows/pr-python-model-tests.yml
  • .github/workflows/pr-python-tests.yml
  • .github/workflows/pr-quality-checks.yml
  • .github/workflows/release-cli.yml
  • .github/workflows/release-devtools.yml
  • .github/workflows/sandbox-deployment.yml
  • .github/workflows/zizmor.yml
  • backend/alembic/versions/ca04500b9ee8_add_cascade_deletes_to_agent_tables.py
  • backend/alembic/versions/f39c5794c10a_add_background_errors_table.py
  • backend/onyx/background/error_logging.py
  • backend/onyx/db/background_error.py
  • backend/tests/external_dependency_unit/answer/conftest.py
  • backend/tests/integration/common_utils/managers/document.py
  • backend/tests/integration/common_utils/managers/file.py
  • backend/tests/integration/common_utils/managers/index_attempt.py
  • backend/tests/integration/common_utils/managers/llm_provider.py
  • backend/tests/integration/common_utils/managers/query_history.py
  • backend/tests/integration/common_utils/managers/settings.py
  • backend/tests/integration/common_utils/managers/user.py
  • backend/tests/integration/common_utils/reset.py
  • backend/tests/integration/common_utils/test_files/Sample.pdf
  • backend/tests/integration/conftest.py
  • backend/tests/integration/tests/index_attempt/test_index_attempt_pagination.py
  • backend/tests/integration/tests/ingestion/test_ingestion_api.py
  • backend/tests/integration/tests/query_history/test_query_history.py
  • backend/tests/integration/tests/query_history/test_query_history_pagination.py
  • backend/tests/integration/tests/query_history/utils.py
  • backend/tests/integration/tests/users/test_user_pagination.py
  • web/.gitignore
  • web/playwright.config.ts
  • web/src/app/admin/token-rate-limits/TokenRateLimitTables.tsx
  • web/src/app/ee/admin/theme/AppearanceThemeSettings.tsx
  • web/src/lib/admin-routes.ts
  • web/src/refresh-components/SimpleTabs.tsx
  • web/tests/e2e/admin/admin_pages.spec.ts
  • web/tests/e2e/admin/image-generation/image-generation-content.spec.ts
  • web/tests/e2e/admin/llm_provider_setup.spec.ts
  • web/tests/e2e/admin/theme/appearance_theme_settings.spec.ts
  • web/tests/e2e/auth/login.spec.ts
  • web/tests/e2e/chat/chat-search-command-menu.spec.ts
  • web/tests/e2e/chat/llm_ordering.spec.ts
  • web/tests/e2e/chat/llm_runtime_selection.spec.ts
  • web/tests/e2e/chat/message_edit_regenerate.spec.ts
  • web/tests/e2e/chat/welcome_page.spec.ts
  • web/tests/e2e/constants.ts
  • web/tests/e2e/global-setup.ts
  • web/tests/e2e/mcp/mcp_oauth_flow.spec.ts
  • web/tests/e2e/utils/auth.ts
  • web/tests/e2e/utils/chatActions.ts
  • web/tests/e2e/utils/visualRegression.ts

本文档描述了 Onyx 代码库中使用的全面测试基础设施，包括单元测试、集成测试、端到端测试、视觉回归测试以及编排这些测试的持续集成/持续部署（CI/CD）工作流。

概述

Onyx 采用多层测试策略，涵盖后端 Python 测试、前端 JavaScript 测试、全栈集成测试和视觉回归测试。所有测试均通过 GitHub Actions 在拉取请求、合并组和发布标签上自动执行。

测试金字塔结构：

Onyx · 概述 · 图 1
Onyx · 概述 · 图 1

来源：.github/workflows/pr-playwright-tests.yml:1-64，.github/workflows/pr-integration-tests.yml:1-42，.github/workflows/pr-python-tests.yml:1-18

后端测试基础设施

Python 单元测试

快速、隔离的测试，不需要外部依赖。这些测试通过 pytest 运行，可在开发过程中提供快速反馈。

测试位置： backend/tests/unit/

执行方式： 由 .github/workflows/pr-python-tests.yml:1-53 触发。

配置：

  • 使用 pytest，输出格式为 xunit2 .github/workflows/pr-python-tests.yml:53-53。
  • 使用 --ff（失败优先）标志运行，以加快迭代速度 .github/workflows/pr-python-tests.yml:53-53。
  • 设置环境变量 DISABLE_TELEMETRY=true 以避免分析 .github/workflows/pr-python-tests.yml:29-29。
  • 设置 LICENSE_ENFORCEMENT_ENABLED=false，适用于外部许可服务不可用的单元测试环境 .github/workflows/pr-python-tests.yml:32-32。

来源：.github/workflows/pr-python-tests.yml:26-53

集成测试 v2

全栈集成测试，针对使用 Docker Compose 的完整 Onyx 部署运行。这些测试验证端到端工作流，包括文档索引、聊天交互和多租户隔离。

测试发现与矩阵执行：

Onyx · 集成测试 v2 · 图 2
Onyx · 集成测试 v2 · 图 2

工作流配置：

集成测试工作流 .github/workflows/pr-integration-tests.yml 遵循以下模式：

  1. 构建阶段：并行构建系统组件的镜像：
    • build-backend-image：后端 API 服务器 .github/workflows/pr-integration-tests.yml:88-147。
    • build-model-server-image：嵌入向量和推理模型服务器 .github/workflows/pr-integration-tests.yml:148-206。
    • build-integration-image：包含 pytest 及其依赖的测试运行器 .github/workflows/pr-integration-tests.yml:207-264。
  1. 测试阶段：矩阵执行涵盖：
    • 通过 find 命令动态发现的测试目录 .github/workflows/pr-integration-tests.yml:61-76。
    • 版本：ee（企业版）和 mit（MIT 许可证）。在拉取请求上，仅运行 ee；在合并/标签上，两者都运行 .github/workflows/pr-integration-tests.yml:78-86。

集成测试的 Docker Compose 堆栈： 工作流从 deployment/docker_compose/docker-compose.yml 和 docker-compose.dev.yml 启动服务 .github/workflows/pr-integration-tests.yml:342-354：

  • relational_db：PostgreSQL 数据库。
  • index：Vespa 搜索引擎。
  • cache：Redis。
  • minio：兼容 S3 的文件存储。
  • api_server：FastAPI 后端。
  • inference_model_server：实时嵌入向量生成。
  • indexing_model_server：批量嵌入向量生成。
  • background：Celery 工作节点。

来源：.github/workflows/pr-integration-tests.yml:45-450

连接器测试

定期执行的测试，用于验证与外部服务（Slack、Confluence、Jira、GitHub 等）的集成。这些测试需要真实的 API 凭证。

测试位置： backend/tests/daily/connectors/

执行方式： .github/workflows/pr-python-connector-tests.yml。

条件执行： 该工作流使用 dorny/paths-filter 检测特定连接器目录（例如 hubspot、salesforce、github）的更改，并触发相应的测试 .github/workflows/pr-python-connector-tests.yml:78-98。

凭证管理： 外部源的凭证通过 GitHub Secrets 和环境变量（如 CONFLUENCE_ACCESS_TOKEN、SF_USERNAME 和 SHAREPOINT_CLIENT_ID）进行管理 .github/workflows/pr-python-connector-tests.yml:32-45。

来源：.github/workflows/pr-python-connector-tests.yml:1-160

外部依赖单元测试

需要外部服务（Vespa、Redis、PostgreSQL、MinIO、OpenSearch）但不需要完整应用堆栈的测试。

测试位置： backend/tests/external_dependency_unit/

服务堆栈： 使用 docker compose 启动最小服务集：minio、relational_db、cache、index、opensearch 和 code-interpreter .github/workflows/pr-external-dependency-unit-tests.yml:133-145。

迁移执行： 该工作流在启动测试前运行 Alembic 迁移（alembic upgrade head），以确保模式是最新的 .github/workflows/pr-external-dependency-unit-tests.yml:147-152。

来源：.github/workflows/pr-external-dependency-unit-tests.yml:59-165

静态分析与类型检查
  • Python 检查：使用 ty（一个基于 astral-sh Rust 类型检查器 mypy 的封装）执行静态类型检查 .github/workflows/pr-python-checks.yml:49-52。
  • 质量检查：通过 j178/prek-action 运行一套全面的检查，包括代码风格检查和安全性扫描 .github/workflows/pr-quality-checks.yml:41-46。
  • 工作流审计：使用 zizmor 审计 GitHub Actions 工作流，以发现安全漏洞和过度权限 .github/workflows/zizmor.yml:32-36。

来源：.github/workflows/pr-python-checks.yml:19-53，.github/workflows/pr-quality-checks.yml:19-52，.github/workflows/zizmor.yml:1-42

前端测试基础设施

Jest 单元测试

使用 jest 对 React 组件和工具函数进行 JavaScript/TypeScript 单元测试。

执行方式：由 .github/workflows/pr-jest-tests.yml 触发。

  • 使用 npm ci 进行干净的依赖安装 .github/workflows/pr-jest-tests.yml:39-40。
  • 使用 --coverage 运行以生成质量报告 .github/workflows/pr-jest-tests.yml:43-43。

来源：.github/workflows/pr-jest-tests.yml:20-52

Playwright 端到端测试

基于浏览器的测试，模拟用户在完整应用堆栈上的真实交互。

测试位置： web/tests/e2e/

测试基础设施流程：

Onyx · Playwright 端到端测试 · 图 3
Onyx · Playwright 端到端测试 · 图 3

服务就绪检查： 该工作流为 API 服务器 .github/workflows/pr-playwright-tests.yml:333-365、各种模拟服务器（Slack、MCP）.github/workflows/pr-playwright-tests.yml:367-411 以及 Next.js Web 服务器 .github/workflows/pr-playwright-tests.yml:413-436 实现了健壮的健康检查。

OnyxApiClient 工具： 端到端测试使用专门的 OnyxApiClient 以编程方式设置状态。它包含以下方法：

  • createFileConnector：为本地文件创建连接器 web/tests/e2e/utils/onyxApiClient.ts:213-213。
  • ensurePublicProvider：设置大语言模型（LLM）提供商 web/tests/e2e/utils/onyxApiClient.ts:316-316。
  • createChatSession：初始化对话 web/tests/e2e/utils/onyxApiClient.ts:501-501。

来源：.github/workflows/pr-playwright-tests.yml:1-787，web/tests/e2e/utils/onyxApiClient.ts:81-510

视觉回归测试

自动化的截图比较系统，用于检测非预期的 UI 更改。

截图比较： 该工作流使用 ods screenshot-diff compare 运行比较 .github/workflows/pr-playwright-tests.yml:500-509。它从 S3 存储桶（onyx-playwright-artifacts）下载基线截图，与当前截图进行比较，并生成 HTML 差异报告。

基线更新： 当测试在受保护的分支（main、release/*）或版本标签上通过时，基线会自动更新 .github/workflows/pr-playwright-tests.yml:551-576。

来源：.github/workflows/pr-playwright-tests.yml:61-63，.github/workflows/pr-playwright-tests.yml:462-576

Helm Chart 测试

使用 helm chart-testing（ct）和 kind（Docker 中的 Kubernetes）进行 Kubernetes 部署验证。

执行方式： .github/workflows/pr-helm-chart-testing.yml。

流程：

  1. 变更检测：使用 ct list-changed 检测 deployment/helm/charts 中 chart 的修改 .github/workflows/pr-helm-chart-testing.yml:49-59。
  2. 集群设置：创建一个 kind 集群 .github/workflows/pr-helm-chart-testing.yml:72-74，并预拉取 cloudnative-pg 和 redis 等镜像 .github/workflows/pr-helm-chart-testing.yml:105-125。
  3. 安装：运行 ct install，超时时间为 25 分钟，并监控集群状态和事件以发现失败 .github/workflows/pr-helm-chart-testing.yml:138-168。

来源：.github/workflows/pr-helm-chart-testing.yml:1-220

构建与部署工作流

Onyx 使用由 Git 标签触发的复杂 Docker 构建系统。

确定构建任务： deployment.yml 中的 determine-builds 任务解析 Git 标签，以决定构建哪些镜像（例如 build-web、build-backend、build-desktop）.github/workflows/deployment.yml:20-154。

  • 稳定标签：（例如 v1.2.3）触发完整的生产构建，包括桌面应用 .github/workflows/deployment.yml:90-106。
  • 云标签：触发专门的 web-cloud 构建 .github/workflows/deployment.yml:98-99。
  • 最新标签：只有最高的语义化版本稳定标签会获得 latest Docker 标签，通过 ods latest-stable-tag 确定 .github/workflows/deployment.yml:115-123。

来源：.github/workflows/deployment.yml:1-155