测试与 CI

测试与 CI

CI 由 GitHub Actions 运行，主要包含静态检查、类型检查、测试、构建、自动格式修复和文档部署。仓库本地自动化以 Taskfile.yml 为主入口。

Taskfile 主入口

task check
task test
task build
task ci

task check 覆盖 Ruff、Ruff format check、Markdown lint、Turbo lint、Pyright、ty 和 Turbo type check。task test 覆盖 Python pytest 和 docs Vitest。task ci 会按顺序运行 check、test 和 build。

Python / code 聚焦检查

uv run -m ruff check . --output-format=github
uv run -m ruff format --check .
uv run -m pyright .
uv run -m ty check --output-format github
uv run -m pytest

如果只改了某个模块，可以先跑相关测试文件，再按需要扩大范围。

数据库测试

项目通过 SQLALCHEMY_DATABASE_URL 环境变量支持 6 个数据库后端测试，遵循 NoneBot 数据库测试最佳实践。

本地多数据库测试

默认使用 SQLite 进行测试。要在 PostgreSQL / MySQL / MariaDB / Oracle / SQL Server 上本地测试：

1. 安装数据库驱动（已在 test 依赖组中）：

uv sync --all-groups

2. 启动数据库服务器（通过 Docker 或本地安装）。

3. 设置 SQLALCHEMY_DATABASE_URL 环境变量并运行测试：

# PostgreSQL
export SQLALCHEMY_DATABASE_URL="postgresql+psycopg://postgres:postgres@localhost:5432/postgres"
uv run -m pytest

# MySQL
export SQLALCHEMY_DATABASE_URL="mysql+aiomysql://mysql:mysql@localhost:3306/mymysql"
uv run -m pytest

# MariaDB（使用 mysql+aiomysql，SQLAlchemy 通过 VERSION() 自动检测 MariaDB）
export SQLALCHEMY_DATABASE_URL="mysql+aiomysql://mariadb:mariadb@localhost:3306/mymariadb"
uv run -m pytest

# Oracle（oracledb 2.0+ 默认 Thin 模式，无需 Oracle Client）
export SQLALCHEMY_DATABASE_URL="oracle+oracledb://system:oracle@localhost:1521/?service_name=FREEPDB1"
uv run -m pytest

# SQL Server（需要 aioodbc + pyodbc + 系统 ODBC Driver 18）
export SQLALCHEMY_DATABASE_URL="mssql+aioodbc://sa:Password!1@localhost:1433/master?driver=ODBC+Driver+18+for+SQL+Server&TrustServerCertificate=yes"
uv run -m pytest

4. 测试前运行迁移：

uv run nb orm upgrade

系统依赖说明

• Oracle：使用 ghcr.io/gvenzl/oracle-free:23-slim 镜像（GitHub Container Registry，避免 Docker Hub 速率限制）；需要 Oracle 12.2+（128-char 标识符 + MERGE INTO）。
• SQL Server：Linux 环境需要 msodbcsql18 系统包（ACCEPT_EULA=Y apt-get install -y msodbcsql18 mssql-tools18 unixodbc-dev）；macOS 同名 brew 包；Windows 自带。

CI 多数据库矩阵

CI 跨 6 个数据库引擎跑 10 个任务，覆盖 LTS 与最新版：

• SQLite（默认，无需额外服务；版本由 Python sqlite3/aiosqlite 决定）
• PostgreSQL 16（postgres:16-alpine，支持至 2028-11）与 PostgreSQL 18（postgres:18-alpine，最新版）
• MySQL 8.4 LTS（mysql:8.4，支持至约 2032）与 MySQL 9.7 LTS（mysql:9.7，支持至约 2034）
• MariaDB 11.4 LTS（mariadb:11.4，支持至 2029-05）与 MariaDB 11.8 LTS（mariadb:11.8，支持至 2028-06）
• Oracle 23ai（ghcr.io/gvenzl/oracle-free:23-slim，来自 GitHub Container Registry；唯一免费版本，无 LTS 拆分）
• SQL Server 2022 与 SQL Server 2025（mcr.microsoft.com/mssql/server:2022-latest / 2025-latest + apt 安装 msodbcsql18；已从废弃的 azure-sql-edge 镜像迁移）

每个矩阵条目携带 engine + image 字段；服务容器通过 ${{ matrix.db.engine == '<engine>' && matrix.db.image || '' }} 选择镜像，使同一引擎的多个版本可在一个矩阵中共存。fail-fast: false 策略确保即使一个数据库失败，所有数据库仍会被测试。Oracle / SQL Server 启动较慢（health-start-period 90-180s），单次全跑约 8-15 分钟。

Docs / frontend 聚焦检查

文档站使用 pnpm、Vitest、Playwright、ESLint、Fumadocs 和 Turbo：

pnpm --filter docs lint
pnpm --filter docs test
pnpm --filter docs run test:e2e:hook
pnpm --filter docs run test:e2e
pnpm --filter docs run lint:links
pnpm turbo run check-types --filter=docs
pnpm turbo run build --filter=docs

Vitest 覆盖 apps/docs/src/__tests__ 下的组件和库行为。Playwright 测试放在 apps/docs/e2e，覆盖浏览器级文档导航。本地 hook 在 docs 变更时运行 Chromium 冒烟命令（test:e2e:hook）；CI 运行全部配置的 Playwright 浏览器项目，并上传 HTML report 与 trace 产物。

编写 Playwright 测试时优先使用 role/text locator 和 toBeVisible()、toHaveAttribute() 等 web-first assertion。除非变更明确需要，否则不要使用 sleep、截图断言或宽泛的视觉检查。

Markdown 检查

pnpm exec markdownlint-cli2

glob 与 ignore 列表由仓库根目录的 .markdownlint-cli2.jsonc 统一配置，无需传入路径参数。

国际化检查

修改可翻译字符串后运行：

task i18n

如果只修改文档中的 i18n 说明，不需要重新生成 gettext catalog。

CI 工作流

• 🧪 Python CI：共享的 detect-changes 复合 action（.github/actions/detect-changes）按文件类型输出布尔标志（python/markdown/frontend/frontend-code/frontend-style/frontend-content/frontend-tsx），然后条件触发 Static Analysis（Python 或 markdown 变更时，通过 task ci:static）和 Tests & Type Check（Python 变更时，跨多数据库矩阵）。Auto Fix & Format 在 main/dev push 时运行。条件与 pre-commit v3 的 NEEDS_LINT/NEEDS_TYPE_CHECK/NEEDS_DOCS_TEST 对齐。
• 🧪 Frontend CI：使用同一个 detect-changes action，然后条件触发 Docs Check — ESLint 在代码/样式变更时，check-types 在任意前端变更时，link validation 在内容变更时，Vitest 在代码/内容变更时。
• 🎭 Playwright：针对 apps/docs 和 packages 变更运行 docs E2E 测试，安装浏览器依赖，并上传 Playwright report 产物。
• 👷 CI-builds：运行 task ci:build；在 main、dev、releases/** 的 push 上还会 bump dev version、写回 core_version、构建、归档产物、生成 provenance 并提交 tag。
• 📚 Docs Deploy：docs 相关路径 push 到 main 或 dev 时，运行 pnpm/turbo lint、docs test 和 docs build，然后部署 GitHub Pages。

CI 失败处理

打开失败 job 日志，定位命令、规则和行号。修复时只改导致失败的最小范围，并重新运行对应本地命令。