agentic_huge_data_base / wiki
页面 Open WebUI · 17.2 测试基础设施·DeepWiki 中文全文译文
DeepWiki 中文译文 / Open WebUI / 17.2

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

多模型对话工作台与知识应用入口 · 本章是 Open WebUI DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Open WebUI 章节17.2 状态全文译文 模块测试、发布与运维、界面与交互、检索、召回与知识系统、系统架构
项目要点页2.5 参考项目 项目章节目录Open WebUI DeepWiki 原始章节Testing Infrastructure 上一章17.1 下一章17.3
源码线索
  • .github/workflows/build-release.yml
  • .github/workflows/docker-build.yaml
  • .github/workflows/format-backend.yaml
  • .github/workflows/format-build-frontend.yaml
  • .github/workflows/release-pypi.yml
  • backend/open_webui/retrieval/web/firecrawl.py
  • backend/open_webui/retrieval/web/utils.py
  • backend/open_webui/storage/provider.py
  • backend/open_webui/test/apps/webui/storage/test_provider.py
  • docker-compose.playwright.yaml
模块标签
  • 测试、发布与运维
  • 界面与交互
  • 检索、召回与知识系统
  • 系统架构
  • 接口与服务契约

中文译文

测试基础设施（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/open-webui/open-webui/17.2-testing-infrastructure
翻译时间：2026-06-09T16:12:04.777Z
翻译模型：deepseek-chat
原文字符数：10289
项目：Open WebUI (open-webui)

---

测试基础设施

相关源文件

以下文件被用作生成此 wiki 页面的上下文：

  • .github/workflows/build-release.yml
  • .github/workflows/docker-build.yaml
  • .github/workflows/format-backend.yaml
  • .github/workflows/format-build-frontend.yaml
  • .github/workflows/integration-test.disabled
  • .github/workflows/lint-backend.disabled
  • .github/workflows/lint-frontend.disabled
  • .github/workflows/release-pypi.yml
  • backend/open_webui/retrieval/web/firecrawl.py
  • backend/open_webui/retrieval/web/utils.py
  • backend/open_webui/storage/provider.py
  • backend/open_webui/test/apps/webui/storage/test_provider.py
  • backend/requirements-min.txt
  • backend/requirements.txt
  • docker-compose.playwright.yaml
  • hatch_build.py
  • pyproject.toml
  • uv.lock
  • vite.config.ts

本文档描述 Open WebUI 的测试基础设施，包括单元测试、集成测试、端到端测试以及测试框架。内容涵盖测试组织方式、执行策略以及整个代码库中前后端组件所使用的模拟方法。

---

测试框架概述

Open WebUI 采用多层测试策略。pytest 是 Python 后端代码的主要测试框架，而 Cypress 和 Vitest 用于测试 SvelteKit 前端。该基础设施支持多种数据库后端（SQLite、PostgreSQL、MariaDB）和云存储提供商（S3、GCS、Azure Blob Storage）。

测试组件栈

标题：测试基础设施架构

graph TB
    subgraph "前端测试"
        cypress["Cypress E2E"]
        vitest["Vitest 单元测试"]
        sonner["Svelte Sonner（Toast 验证）"]
    end

    subgraph "后端测试"
        pytest["pytest"]
        pytest_docker["pytest-docker"]
        pytest_asyncio["pytest-asyncio"]
        moto["moto[s3]"]
        gcs_emulator["gcp-storage-emulator"]
    end

    subgraph "基础设施"
        playwright["Playwright（网页加载）"]
        docker_compose["Docker Compose 栈"]
        ollama_test["Ollama（模拟/测试模型）"]
    end

    subgraph "测试目标"
        chat_flow["Chat.svelte 流程"]
        storage_providers["StorageProvider 类"]
        migrations["Alembic/Peewee 迁移"]
        api_endpoints["FastAPI 路由"]
    end

    cypress --> chat_flow
    cypress --> api_endpoints
    vitest --> chat_flow
    pytest --> storage_providers
    pytest --> api_endpoints
    pytest_docker --> migrations
    playwright --> chat_flow
    ollama_test --> chat_flow

来源：

  • backend/requirements.txt:142-143（pytest 和 pytest-docker）
  • pyproject.toml:218（pytest-asyncio）
  • backend/requirements.txt:130（playwright）
  • .github/workflows/format-build-frontend.yaml:49-66
  • .github/workflows/integration-test.disabled:14-61

---

测试依赖

后端核心测试包

Open WebUI 的后端测试基础设施定义在 backend/requirements.txt 和 pyproject.toml 中，并通过 GitHub Actions 进行验证。

包名用途
pytest后端逻辑的主要测试框架 backend/requirements.txt:142。
pytest-asyncio为 FastAPI 和异步数据库驱动提供异步测试支持 pyproject.toml:218。
moto模拟 AWS 服务，特别是用于存储提供程序测试的 S3 backend/open_webui/test/apps/webui/storage/test_provider.py:6。
playwright浏览器自动化，用于网页内容加载和抓取验证 backend/requirements.txt:130。
ruffPython 代码的 linting 和格式化强制检查 pyproject.toml:219。
前端测试工具
包名用途
Cypress端到端测试和用户流程的浏览器自动化 .github/workflows/integration-test.disabled:53-61。
VitestSvelte 组件的前端单元测试 .github/workflows/format-build-frontend.yaml:65。
PrettierSvelte 和 TypeScript 文件的代码格式化 .github/workflows/format-build-frontend.yaml:38。

来源：

  • backend/requirements.txt:140-143
  • pyproject.toml:156-159
  • .github/workflows/format-backend.yaml:41-46
  • .github/workflows/format-build-frontend.yaml:38-66

---

存储提供程序测试

存储提供程序测试套件验证文件持久化的抽象层。测试位于 backend/open_webui/test/apps/webui/storage/test_provider.py，涵盖 LocalStorageProvider、S3StorageProvider、GCSStorageProvider 和 AzureStorageProvider。

测试实现细节

标题：存储提供程序测试逻辑

classDiagram
    class TestLocalStorageProvider {
        +test_upload_file()
        +test_get_file()
        +test_delete_file()
        +test_delete_all_files()
    }
    class TestS3StorageProvider {
        +s3_client: boto3.resource
        +test_upload_file()
        +test_delete_all_files()
    }
    class TestAzureStorageProvider {
        +setup_storage()
        +test_upload_file()
    }

    TestLocalStorageProvider ..> LocalStorageProvider : "测试 [backend/open_webui/storage/provider.py:58]"
    TestS3StorageProvider ..> S3StorageProvider : "测试 [backend/open_webui/storage/provider.py:101]"
    TestS3StorageProvider ..> mock_aws : "使用 [backend/open_webui/test/apps/webui/storage/test_provider.py:100]"

关键测试模式：

  • 模拟 AWS：使用 moto 的 @mock_aws 拦截 S3 操作的 boto3 调用 backend/open_webui/test/apps/webui/storage/test_provider.py:100-101。
  • 目录隔离：mock_upload_dir 辅助函数通过 monkey-patch 将 provider.UPLOAD_DIR 替换为临时路径，防止测试污染 backend/open_webui/test/apps/webui/storage/test_provider.py:14-19。
  • 提供程序发现：test_get_storage_provider 确保 get_storage_provider 工厂函数正确返回 LocalStorageProvider、S3StorageProvider 等实例 backend/open_webui/test/apps/webui/storage/test_provider.py:31-42。
  • 本地提供程序验证：TestLocalStorageProvider 直接在文件系统上验证文件的 CRUD 操作 backend/open_webui/test/apps/webui/storage/test_provider.py:59-98。

来源：

  • backend/open_webui/test/apps/webui/storage/test_provider.py:1-164
  • backend/open_webui/storage/provider.py:40-131

---

前端测试工作流

前端测试分为格式化检查、单元测试和 E2E 测试。

Vitest 单元测试

前端单元测试通过 npm run test:frontend 执行。该过程在 GitHub Actions 中使用 Node.js 22 自动运行 .github/workflows/format-build-frontend.yaml:49-66。

Cypress 端到端测试

Cypress 测试验证完整的应用栈，包括与本地 AI 提供程序（如 Ollama）的集成。

标题：CI/CD 集成测试流水线

graph LR
    subgraph "GitHub Action"
        checkout["检出代码"]
        compose["启动 Docker Compose"]
        wait_ollama["等待 Ollama"]
        pull_model["拉取测试模型<br/>(qwen:0.5b)"]
        run_cypress["运行 Cypress"]
    end

    subgraph "Docker 栈"
        webui_app["open-webui 容器"]
        ollama_svc["ollama 容器"]
        db_svc["postgres 容器"]
    end

    compose --> webui_app
    compose --> ollama_svc
    wait_ollama --> pull_model
    pull_model --> run_cypress
    run_cypress -.-> webui_app

来源：

  • .github/workflows/format-build-frontend.yaml:49-66
  • .github/workflows/integration-test.disabled:28-61

---

数据库迁移与重连测试

测试基础设施包括针对多种数据库引擎的数据库 schema 迁移和连接恢复能力的自动化验证。

迁移验证逻辑

集成工作流执行以下步骤：

  1. SQLite 测试：使用 uvicorn open_webui.main:app 启动服务器，并检查 /api/config 端点是否返回 200 OK 响应 .github/workflows/integration-test.disabled:155-173。
  2. Postgres 测试：使用 DATABASE_URL 环境变量，针对真实的 PostgreSQL 实例验证服务器 .github/workflows/integration-test.disabled:181-203。
  3. 重连检查：

    4. - 通过 /health/db 验证初始健康状态 .github/workflows/integration-test.disabled:212。 - 使用执行 pg_terminate_backend 的 Python 脚本强制终止所有 PostgreSQL 后端连接 .github/workflows/integration-test.disabled:219-222。 - 确认应用程序自动重连并返回健康状态 .github/workflows/integration-test.disabled:224-228。

来源：

  • .github/workflows/integration-test.disabled:105-228

---

测试执行摘要

测试类型工具命令
后端单元/存储测试pytestpytest backend/open_webui/test/
前端单元测试Vitestnpm run test:frontend .github/workflows/format-build-frontend.yaml:65
端到端测试Cypressnpx cypress run .github/workflows/integration-test.disabled:53
Linting（后端）Ruffruff format --check . .github/workflows/format-backend.yaml:46
Linting（前端）Prettiernpm run format .github/workflows/format-build-frontend.yaml:38

来源：

  • .github/workflows/format-backend.yaml:45-46
  • .github/workflows/format-build-frontend.yaml:38,65
  • .github/workflows/integration-test.disabled:53-61