diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..7e18d22 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,163 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: ci-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: true + +env: + CI: 'true' + APP_ENV: test + MATCHING_AI_ENABLED: 'false' + +jobs: + frontend: + name: Frontend checks + runs-on: ubuntu-24.04 + timeout-minutes: 10 + defaults: + run: + working-directory: frontend + steps: + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 + - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6 + with: + node-version: '22' + cache: npm + cache-dependency-path: frontend/package-lock.json + - run: npm ci + - run: npm test -- --reporter=default --reporter=junit --outputFile=test-results/vitest.xml + - run: npm run type-check:e2e + - run: npm run build + - name: Upload frontend test results + if: ${{ !cancelled() }} + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: frontend-test-results + path: frontend/test-results/ + if-no-files-found: ignore + retention-days: 7 + + backend: + name: Backend checks + runs-on: ubuntu-24.04 + timeout-minutes: 10 + defaults: + run: + working-directory: backend + steps: + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 + - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0 + with: + version: '0.11.7' + python-version: '3.12' + enable-cache: true + cache-dependency-glob: backend/uv.lock + - run: uv sync --locked + - run: uv run --frozen ruff check . + - run: uv run --frozen pytest -m 'not mysql' --junitxml=test-results/pytest.xml + - name: Upload backend test results + if: ${{ !cancelled() }} + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: backend-test-results + path: backend/test-results/ + if-no-files-found: ignore + retention-days: 7 + + integration: + name: MySQL and browser tests + needs: [frontend, backend] + runs-on: ubuntu-24.04 + timeout-minutes: 20 + env: + DATABASE_URL: mysql+pymysql://lostlink_test:lostlink_test@127.0.0.1:3306/lostlink_test?charset=utf8mb4 + TEST_DATABASE_URL: mysql+pymysql://lostlink_test:lostlink_test@127.0.0.1:3306/lostlink_test?charset=utf8mb4 + E2E_DATABASE_URL: mysql+pymysql://lostlink_test:lostlink_test@127.0.0.1:3306/lostlink_test?charset=utf8mb4 + services: + mysql: + image: mysql:8.4 + env: + MYSQL_DATABASE: lostlink_test + MYSQL_USER: lostlink_test + MYSQL_PASSWORD: lostlink_test + MYSQL_ROOT_PASSWORD: lostlink_test_root + TZ: UTC + ports: + - 3306:3306 + options: >- + --health-cmd="mysqladmin ping -h 127.0.0.1 -ulostlink_test -plostlink_test --silent" + --health-interval=5s + --health-timeout=5s + --health-retries=30 + steps: + - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6 + - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6 + with: + node-version: '22' + cache: npm + cache-dependency-path: frontend/package-lock.json + - uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0 + with: + version: '0.11.7' + python-version: '3.12' + enable-cache: true + cache-dependency-glob: backend/uv.lock + - run: uv sync --locked + working-directory: backend + - name: Check migration upgrade and rollback on the disposable database + working-directory: backend + run: | + uv run --frozen alembic upgrade head + uv run --frozen alembic downgrade 20261006_0004 + uv run --frozen alembic upgrade head + uv run --frozen alembic downgrade 20260930_0001 + uv run --frozen alembic upgrade head + uv run --frozen alembic downgrade base + uv run --frozen alembic upgrade head + uv run --frozen python -m scripts.seed_items + - name: Run real MySQL integration tests + working-directory: backend + run: uv run --frozen pytest -m mysql --junitxml=test-results/mysql.xml + - run: npm ci + working-directory: frontend + - run: npx playwright install --with-deps chromium + working-directory: frontend + - run: npm run test:e2e + working-directory: frontend + - name: Upload integration and browser results + if: ${{ !cancelled() }} + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: integration-test-results + path: | + backend/test-results/ + frontend/playwright-report/ + frontend/test-results/ + if-no-files-found: ignore + retention-days: 7 + + required: + name: CI passed + if: ${{ always() }} + needs: [frontend, backend, integration] + runs-on: ubuntu-24.04 + timeout-minutes: 1 + steps: + - name: Require every test job to pass + env: + FRONTEND_RESULT: ${{ needs.frontend.result }} + BACKEND_RESULT: ${{ needs.backend.result }} + INTEGRATION_RESULT: ${{ needs.integration.result }} + run: | + test "$FRONTEND_RESULT" = success + test "$BACKEND_RESULT" = success + test "$INTEGRATION_RESULT" = success diff --git a/.gitignore b/.gitignore index 3fce5e3..2631cc7 100644 --- a/.gitignore +++ b/.gitignore @@ -20,6 +20,8 @@ node_modules/ dist/ coverage/ *.tsbuildinfo +playwright-report/ +test-results/ # Runtime data uploads/ @@ -27,6 +29,7 @@ logs/ *.log *.db *.sqlite3 +backend/var/e2e-uploads/ # IDE and OS .idea/ diff --git a/CHANGELOG.md b/CHANGELOG.md index e4646d0..906a23d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,8 @@ ### Added +- 2026-10-21 增加 GitHub Actions CI:Vitest、Ruff/pytest、MySQL 迁移与集成、Playwright 认证及失物/拾物核心流程;增加隔离测试数据库配置、报告上传和本地复现说明。 +- 2026-10-21 新增 `20261021_0005` 迁移,为历史 MySQL 回滚保留独立外键支撑索引,修复删除外键依赖索引时报错 1553;保留已发布迁移不变。 - 2026-10-07 增加可配置 DeepSeek 等 OpenAI 兼容图文匹配接口、规则与模型评分融合、批量候选及图片预算、异常降级和模拟供应商测试;真实模型调用待配置密钥后验证。 - 建立项目目录、协作模板和初始文档体系。 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 684d2fb..5058a5c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -53,7 +53,7 @@ docs(readme): add project structure guide - 业务功能与无关格式化修改应拆分提交。 - 接口或数据结构变化必须同步更新文档。 -仓库目前提供 Issue 和 Pull Request 模板,但尚未配置 `.github/workflows/` 自动检查。作者应在 Pull Request 中写明实际执行的命令、结果、未执行项及原因;不能把本地未运行的检查写成 CI 已通过。 +仓库通过 `.github/workflows/ci.yml` 自动检查前后端代码、MySQL 迁移与集成、Playwright 核心浏览器流程。PR 应等待 `CI passed` 成功;管理员可将它设为 `main` 的必需检查。作者仍应在 Pull Request 中写明实际执行的命令、结果、未执行项及原因;不能把本地验证写成 GitHub CI 已通过。配置与复现方法见[测试策略](docs/development/testing.md)。 ## 完成标准 diff --git a/README.md b/README.md index a7c72a7..9beccce 100644 --- a/README.md +++ b/README.md @@ -25,14 +25,15 @@ LostLink 是面向校园失物招领场景的软件工程课程项目。前端 - 使用 SQLAlchemy 查询 MySQL 的 `GET /api/v1/items` 筛选与分页接口。 - 后端账号注册、登录、注销和当前用户接口,以及 Bearer 会话、登录失败锁定和角色/归属权限守卫。 - 后端物品详情、发布、个人记录、编辑和状态更新接口,并记录不可变状态审计。 -- MySQL 8.4 本地容器配置和四份 Alembic migration。 +- MySQL 8.4 本地容器配置和五份 Alembic migration,支持一次性数据库中的升级与回滚验证。 - 前端接口、本地表单及状态存储单元测试,以及后端代码检查、接口测试和可选 MySQL 集成测试。 +- GitHub Actions 自动检查前后端、真实 MySQL 迁移与集成,以及 Playwright 核心用户流程。 后续范围: - 校园统一身份、密码找回和完整认领/归还身份核验流程。 - 对象存储、异步任务、站外通知以及基于真实标注样本的高级匹配训练。 -- 可重复执行的浏览器端自动化测试;当前完整认证、发布、编辑和退出流程已做人工浏览器联调。 +- 扩展图片、匹配和管理端的浏览器自动化覆盖,以及跨浏览器兼容性验证。 个人页和管理端均使用真实账号与服务端数据;所有管理写操作要求管理员角色并记录理由和审计日志。 @@ -54,7 +55,7 @@ LostLink 是面向校园失物招领场景的软件工程课程项目。前端 ## 快速开始 -全部真实业务流程都需要已启动的 FastAPI 和 MySQL。当前锁定的 Vite 6.4.3 要求 Node.js 18、20 或 22 及以上版本。启动前先按 [backend/README.md](backend/README.md) 启动数据库、执行迁移和演示数据脚本。 +全部真实业务流程都需要已启动的 FastAPI 和 MySQL。完整开发与测试环境建议使用 Node.js 22,与 CI 保持一致。启动前先按 [backend/README.md](backend/README.md) 启动数据库、执行迁移和演示数据脚本。 在仓库根目录使用 Windows PowerShell 执行: @@ -81,13 +82,15 @@ npm.cmd run build 2026-10-06 验证结果:6 个测试文件中的 17 个测试通过,类型检查、生产构建和真实浏览器联调通过;npm 生产依赖审计为 0 个已知漏洞。 +已增加 `.github/workflows/ci.yml`:在 PR 和推送到 `main` 时自动运行,统一结果为 `CI passed`。本地复现、隔离测试数据库与报告说明见[测试策略](docs/development/testing.md)。上述历史验证和依赖审计不代表最新运行结果,以本次 Actions 记录为准。 + 如果 PowerShell 提示禁止运行 `npm.ps1`,请使用上述 `npm.cmd` 命令,无需修改系统执行策略。 ## 目录说明 ```text LostLink/ -├─ .github/ # GitHub Issue 与 Pull Request 模板 +├─ .github/ # CI 工作流、Issue 与 Pull Request 模板 ├─ backend/ # 后端工程骨架 │ ├─ alembic/ # 数据库迁移目录 │ ├─ app/ # 后端应用分层目录 @@ -112,7 +115,7 @@ LostLink/ ## 后续开发顺序 1. 团队确认校园统一身份和认领核验的正式规则。 -2. 为完整用户流程补充可重复执行的浏览器自动化测试。 +2. 扩展图片、匹配与管理流程的浏览器自动化测试。 3. 评估对象存储、异步匹配和站外通知集成。 4. 完成部署、监控、备份和回滚演练。 @@ -131,4 +134,4 @@ LostLink/ 3. 按 [CONTRIBUTING.md](CONTRIBUTING.md) 创建分支并提交 Pull Request。 4. 功能、测试和相关文档在同一个 Pull Request 中交付。 -认证、物品、图片、举报、匹配和管理模块已经完成前后端与 MySQL 联调。下一阶段应优先补齐认领核验、浏览器自动化测试与部署准备。 +认证、物品、图片、举报、匹配和管理模块已经完成前后端与 MySQL 联调。下一阶段应优先补齐认领核验、扩展浏览器测试覆盖与部署准备。 diff --git a/backend/README.md b/backend/README.md index 678555a..62cb83c 100644 --- a/backend/README.md +++ b/backend/README.md @@ -2,7 +2,7 @@ > 状态:账号认证、物品与图片、举报、匹配通知、管理审计和校准接口均已实现;全部 migration 已在本地 MySQL 完成升级验证。 > -> 最后验证:2026-10-06;33 个默认测试和 3 个 MySQL 集成测试通过。 +> 本地验证:2026-10-21;95 个默认测试、3 个 MySQL 集成测试,以及迁移的部分/完整回滚再升级通过。 后端采用 Python 3.12、FastAPI、SQLAlchemy 和 MySQL,并按照“接口层 → 服务层 → 数据访问层 → 数据模型层”组织。`GET /api/v1/items` 通过 Repository 查询 MySQL;内存 Repository 只用于不依赖数据库的快速测试。 @@ -71,6 +71,8 @@ uv run alembic downgrade -1 已经合并或在共享环境执行过的 migration 不得修改;结构变化必须创建新的 migration。 +最新迁移为 `20261021_0005`,新增独立外键支撑索引,修复历史迁移回滚时 MySQL 报错 1553 的问题。降到 `0004` 时刻意保留兼容索引,继续回滚删除对应表/列时一并清除。完整回滚验证只允许在一次性测试库执行,步骤见[测试策略](../docs/development/testing.md)。 + ## 检查命令 ```bash @@ -85,8 +87,8 @@ $env:TEST_DATABASE_URL = $env:DATABASE_URL uv run pytest -m mysql ``` -代码检查和测试均应以退出码 `0` 结束。2026-10-06 的最近一次验证中,Ruff -检查通过,33 个默认测试及 3 个显式启用的 MySQL 集成测试通过。 +代码检查和测试均应以退出码 `0` 结束。2026-10-21 本地验证中,Ruff +检查通过,95 个默认测试及 3 个显式启用的 MySQL 集成测试通过。CI 统一检查名为 `CI passed`,本地复现步骤见[测试策略](../docs/development/testing.md)。 ## 当前接口 diff --git a/backend/alembic/versions/20261021_0005_preserve_foreign_key_indexes.py b/backend/alembic/versions/20261021_0005_preserve_foreign_key_indexes.py new file mode 100644 index 0000000..812fcfd --- /dev/null +++ b/backend/alembic/versions/20261021_0005_preserve_foreign_key_indexes.py @@ -0,0 +1,49 @@ +"""为历史迁移的 MySQL 回滚保留独立外键索引。 + +Revision ID: 20261021_0005 +Revises: 20261006_0004 +Create Date: 2026-10-21 + +历史迁移先删除业务索引再删除表;MySQL 可能已经用这些业务索引替换了 +自动生成的外键索引,导致 DROP INDEX 报错 1553。新增独立支撑索引, +无需改写已发布的迁移或关闭外键检查。 +""" + +from collections.abc import Sequence + +import sqlalchemy as sa + +from alembic import context, op + +revision: str = "20261021_0005" +down_revision: str | Sequence[str] | None = "20261006_0004" +branch_labels: str | Sequence[str] | None = None +depends_on: str | Sequence[str] | None = None + +SUPPORT_INDEXES = ( + ("stored_images", "ix_stored_images_owner_fk", ["owner_id"]), + ("stored_images", "ix_stored_images_item_fk", ["item_id", "id"]), + ("item_status_history", "ix_item_status_history_item_fk", ["item_id"]), + ("auth_sessions", "ix_auth_sessions_user_fk", ["user_id"]), + ("items", "ix_items_owner_fk", ["owner_id"]), +) + + +def upgrade() -> None: + """补足索引;从旧版本重新升级时复用已保留的同名索引。""" + + inspector = None if context.is_offline_mode() else sa.inspect(op.get_bind()) + for table, name, columns in SUPPORT_INDEXES: + existing = set() if inspector is None else { + index["name"] for index in inspector.get_indexes(table) + } + if name not in existing: + op.create_index(name, table, columns) + + +def downgrade() -> None: + """刻意保留兼容索引,供 0004、0003、0002 的回滚使用。 + + 降到 0004 时只额外保留索引,不改变数据或约束。继续回滚时,历史迁移 + 删除对应表会一并移除索引;再次升级由 upgrade 的存在性检查保证幂等。 + """ diff --git a/backend/app/models/feature.py b/backend/app/models/feature.py index 4784bde..fe5772b 100644 --- a/backend/app/models/feature.py +++ b/backend/app/models/feature.py @@ -36,6 +36,8 @@ class StoredImage(Base): __tablename__ = "stored_images" __table_args__ = ( Index("ix_stored_images_owner_created", "owner_id", "created_at"), + Index("ix_stored_images_owner_fk", "owner_id"), + Index("ix_stored_images_item_fk", "item_id", "id"), {"mysql_charset": "utf8mb4", "mysql_collate": "utf8mb4_0900_ai_ci"}, ) diff --git a/backend/app/models/item.py b/backend/app/models/item.py index 594377c..5c4b865 100644 --- a/backend/app/models/item.py +++ b/backend/app/models/item.py @@ -40,6 +40,7 @@ class Item(Base): Index("ix_items_type", "type"), Index("ix_items_category", "category"), Index("ix_items_campus_area", "campus", "area"), + Index("ix_items_owner_fk", "owner_id"), {"mysql_charset": "utf8mb4", "mysql_collate": "utf8mb4_0900_ai_ci"}, ) diff --git a/backend/app/models/item_status_history.py b/backend/app/models/item_status_history.py index c04fcb7..9bfa3cc 100644 --- a/backend/app/models/item_status_history.py +++ b/backend/app/models/item_status_history.py @@ -23,6 +23,7 @@ class ItemStatusHistory(Base): __tablename__ = "item_status_history" __table_args__ = ( Index("ix_item_status_history_item_created", "item_id", "created_at"), + Index("ix_item_status_history_item_fk", "item_id"), {"mysql_charset": "utf8mb4", "mysql_collate": "utf8mb4_0900_ai_ci"}, ) diff --git a/backend/app/models/user.py b/backend/app/models/user.py index d39bbdf..bf55c90 100644 --- a/backend/app/models/user.py +++ b/backend/app/models/user.py @@ -79,6 +79,7 @@ class AuthSession(Base): __tablename__ = "auth_sessions" __table_args__ = ( Index("ix_auth_sessions_user_expires", "user_id", "expires_at"), + Index("ix_auth_sessions_user_fk", "user_id"), {"mysql_charset": "utf8mb4", "mysql_collate": "utf8mb4_0900_ai_ci"}, ) diff --git a/backend/compose.test.yaml b/backend/compose.test.yaml new file mode 100644 index 0000000..c1a973e --- /dev/null +++ b/backend/compose.test.yaml @@ -0,0 +1,21 @@ +# 一次性测试数据库;与 compose.yaml 的开发数据库使用不同端口和项目名。 +name: lostlink-test + +services: + mysql: + image: mysql:8.4 + environment: + MYSQL_DATABASE: lostlink_test + MYSQL_USER: lostlink_test + MYSQL_PASSWORD: lostlink_test + MYSQL_ROOT_PASSWORD: lostlink_test_root + TZ: UTC + ports: + - "127.0.0.1:${MYSQL_TEST_PORT:-13306}:3306" + healthcheck: + test: [CMD-SHELL, "mysqladmin ping -h 127.0.0.1 -u$$MYSQL_USER -p$$MYSQL_PASSWORD --silent"] + interval: 5s + timeout: 5s + retries: 30 + start_period: 20s + # 不挂载开发数据库卷;结束后用 down -v 删除测试容器及其匿名卷。 diff --git a/docs/architecture/database.md b/docs/architecture/database.md index 57499fc..bb9d476 100644 --- a/docs/architecture/database.md +++ b/docs/architecture/database.md @@ -1,6 +1,6 @@ # 数据库与迁移 -> 状态:四份 migration 已演进出认证、物品、图片、举报、通知、审计和校准结构;最新版本 `20261006_0004` 已在本地 MySQL 完成升级。完整回滚仍只允许在一次性数据库验证。 +> 状态:五份 migration 已演进出认证、物品、图片、举报、通知、审计和校准结构;最新版本为 `20261021_0005`。CI 在一次性 MySQL 中验证部分回滚/再升级和完整回滚/再升级。 > > 最后验证记录:2026-10-06。 @@ -8,6 +8,8 @@ 数据库结构必须通过版本化 migration 演进,使开发、测试和部署环境可以从同一基线得到一致结构。已经合并或在共享环境执行过的 migration 不得直接改写;需要修正时创建新的 migration。 +`20261021_0005` 为图片、状态审计、认证会话和物品归属增加五个独立外键支撑索引,避免 MySQL 用业务索引支撑外键后,历史 `DROP INDEX` 回滚失败。该迁移降到 `0004` 时刻意保留这些兼容索引,不删除数据或外键;继续回滚对应表/列时索引随之清除。重新升级会复用已有索引。 + ## Migration 工作流 1. 在 Issue 或设计文档中说明数据变化及兼容性影响。 diff --git a/docs/development/testing.md b/docs/development/testing.md index 8b1be20..8b74135 100644 --- a/docs/development/testing.md +++ b/docs/development/testing.md @@ -1,11 +1,13 @@ # 测试策略 -> 状态:前端 Vitest 有 6 个测试文件、17 个测试;后端 pytest 当前 33 个默认测试及 3 个真实 MySQL 集成测试通过,覆盖健康检查、OpenAPI、认证、物品、图片、举报、匹配和管理流程。浏览器端自动化测试尚未配置。 +> 状态:已配置 GitHub Actions、Vitest、pytest、MySQL 集成测试和 Playwright Chromium 浏览器测试。前端现有 7 个文件、22 个测试,后端有 95 个默认测试、3 个 MySQL 集成测试;浏览器包含 3 条核心流程。 > > 前端、后端与 MySQL 集成测试最后验证:2026-10-06。 2026-10-07 图文匹配改动验证:后端 55 个测试通过、3 个 MySQL 测试未启用,Ruff 与前端类型检查/生产构建通过。新增供应商模拟测试覆盖图文请求、融合分数、候选上限、输出校验及失败降级;未调用真实模型。上述 2026-10-06 MySQL 和前端单元测试记录保留为上次验证结果。 +2026-10-21 CI 接入本地验证:前端 22 个测试、后端 95 个默认测试、3 个真实 MySQL 测试和 3 个 Chromium 流程通过;Ruff、浏览器测试类型检查、生产构建、actionlint 工作流检查及迁移的部分/完整回滚再升级通过。前端使用 `npm ci` 验证锁文件安装;本地 Node.js 为 25,CI 固定为 22。GitHub 上是否通过以对应提交的 Actions 记录为准。 + ## 测试目标 - 证明需求验收条件已经满足。 @@ -20,7 +22,90 @@ | 后端集成测试 | API、权限、Repository、数据库 migration | `backend/tests/` | | 前端单元测试 | 接口转换、举报/匹配 API、表单校验和通知状态 | `frontend/src/**/*.test.ts` | | 契约测试 | 请求、响应、状态码和错误格式与 OpenAPI 一致 | 前后端测试目录 | -| 端到端测试 | 发布、搜索、匹配反馈和关闭信息等核心流程 | 框架确定后指定目录 | +| 端到端测试 | 认证、失物/拾物发布、搜索、编辑和关闭流程 | `frontend/e2e/`(Playwright) | + +## CI 流水线 + +配置文件为 `.github/workflows/ci.yml`,在 PR、推送到 `main` 或手动运行时触发。使用 Node.js 22、Python 3.12、锁文件安装依赖,不需要配置生产密钥。 + +1. `Frontend checks`:Vitest、浏览器测试 TypeScript 检查、Vue 类型检查和生产构建。 +2. `Backend checks`:Ruff 与 `pytest -m 'not mysql'`,使用内存仓储。 +3. `MySQL and browser tests`:前两项成功后创建一次性 MySQL 8.4;验证迁移的部分回滚/再升级、完整回滚/再升级,导入演示数据,执行全部 MySQL 测试,再启动前后端运行 Playwright。 +4. `CI passed`:只有前三项全部成功才通过;失败、取消或被跳过都不能视为通过。 + +JUnit XML、Playwright HTML 报告和失败截图/视频/trace 作为 Actions artifacts 保留 7 天。报告可能包含测试会话信息,使用合成账号和测试数据,不上传 `.env` 或真实业务资料。可在本地执行 `npm run test:e2e:report` 打开浏览器报告。 + +管理员可在 GitHub `Settings → Rules → Rulesets` 或分支保护中,将 `CI passed` 设为 `main` 的必需检查并要求 PR 合并。工作流文件本身不会修改仓库保护规则;首次在 GitHub 运行成功后再选择检查项。修改代码后也需要重新通过 CI。 + +## 本地复现完整测试 + +默认单元与快速接口测试无需数据库: + +```bash +# 在 frontend/ 执行 +npm ci +npm test +npm run type-check:e2e +npm run build + +# 在 backend/ 执行 +uv sync --locked +uv run --frozen ruff check . +uv run --frozen pytest -m 'not mysql' +``` + +完整集成测试使用 `backend/compose.test.yaml`,项目名为 `lostlink-test`,默认端口 `13306`,不挂载开发数据库卷。可用 `MYSQL_TEST_PORT` 覆盖端口,并同步修改下方连接地址。以下迁移回滚命令仅允许用于该一次性测试库。 + +在 macOS/Linux 的 `backend/` 目录执行: + +```bash +docker compose -f compose.test.yaml up -d --wait +export DATABASE_URL='mysql+pymysql://lostlink_test:lostlink_test@127.0.0.1:13306/lostlink_test?charset=utf8mb4' +export TEST_DATABASE_URL="$DATABASE_URL" +export E2E_DATABASE_URL="$DATABASE_URL" +export APP_ENV=test +export MATCHING_AI_ENABLED=false +uv sync --locked +uv run --frozen alembic upgrade head +uv run --frozen alembic downgrade 20261006_0004 +uv run --frozen alembic upgrade head +uv run --frozen alembic downgrade 20260930_0001 +uv run --frozen alembic upgrade head +uv run --frozen alembic downgrade base +uv run --frozen alembic upgrade head +uv run --frozen python -m scripts.seed_items +uv run --frozen pytest -m mysql +``` + +Windows PowerShell 使用相同命令,但用下面方式设置环境变量: + +```powershell +$env:DATABASE_URL = 'mysql+pymysql://lostlink_test:lostlink_test@127.0.0.1:13306/lostlink_test?charset=utf8mb4' +$env:TEST_DATABASE_URL = $env:DATABASE_URL +$env:E2E_DATABASE_URL = $env:DATABASE_URL +$env:APP_ENV = 'test' +$env:MATCHING_AI_ENABLED = 'false' +``` + +然后在同一终端切换到 `frontend/`: + +```bash +npm ci +npx playwright install chromium +npm run test:e2e +``` + +PowerShell 使用 `npm.cmd`、`npx.cmd`,无需改变系统执行策略。Linux 若缺少浏览器系统依赖,使用 `npx playwright install --with-deps chromium`。 + +Playwright 强制要求 `E2E_DATABASE_URL` 指向本机 `lostlink_test`,不会复用开发服务。后端端口为 `18000`,生产构建预览端口为 `4173`;配置负责启动、等待就绪和停止这两个服务。外部 AI 调用关闭,上传目录单独使用 `backend/var/e2e-uploads/`。 + +每个浏览器用例使用随机的新账号和物品名称,不依赖其他用例的执行顺序。测试数据保留到容器销毁,以便排查失败;测试结束后在 `backend/` 执行以下命令清理容器和测试数据: + +```bash +docker compose -f compose.test.yaml down -v +``` + +浏览器用例覆盖未登录跳转、错误密码、注册登录,以及失物和拾物的发布、搜索、详情、编辑落库、关闭和退出。图片浏览器交互、匹配反馈、管理员 UI 和跨浏览器兼容性仍需后续补充;已有后端测试不能代替这些浏览器验收。 ## 当前前端测试 diff --git a/docs/development/workflow.md b/docs/development/workflow.md index 1e9a11c..a1c4335 100644 --- a/docs/development/workflow.md +++ b/docs/development/workflow.md @@ -36,7 +36,7 @@ ## 5. 合并 -Pull Request 通过评审并记录必要检查结果后再合并到 `main`。仓库当前没有 `.github/workflows/` 持续集成配置,不能把自动检查写成已运行的门槛;配置 CI 后再由团队确定强制检查项。合并后删除已经完成的短期分支。 +Pull Request 通过评审且 GitHub Actions 的 `CI passed` 成功后再合并到 `main`。流水线检查前后端、真实 MySQL 迁移与集成以及 Playwright 核心流程;管理员可将 `CI passed` 配置为必需检查,具体见[测试策略](testing.md)。合并后删除已经完成的短期分支。 ## 看板状态 diff --git a/frontend/README.md b/frontend/README.md index 3bb53aa..378bcfc 100644 --- a/frontend/README.md +++ b/frontend/README.md @@ -27,7 +27,7 @@ Bearer 请求头。 ## 环境要求 -- Node.js 18、20、22 或更高版本 +- Node.js 22(与 CI 一致;完整测试工具链需要受支持的 Node.js 版本) - npm - 真实业务流程需要先按 [后端开发说明](../backend/README.md) 启动 FastAPI 和 MySQL @@ -56,6 +56,7 @@ npm.cmd run dev ```bash npm run type-check +npm run type-check:e2e npm test npm run build npm audit --omit=dev @@ -64,6 +65,7 @@ npm audit --omit=dev - `type-check` 检查 TypeScript 和 Vue 组件类型。 - `test` 检查认证、物品、举报与匹配接口适配、数据转换、表单校验和草稿存储。 - `build` 生成 `dist/` 生产构建结果。 +- `type-check:e2e` 检查 Playwright 配置和浏览器测试类型;`test:e2e` 在隔离测试数据库上运行核心用户流程,环境准备和报告说明见[测试策略](../docs/development/testing.md)。 - 2026-10-06 验证结果:6 个测试文件、17 个测试通过,生产构建通过,依赖审计为 0 个已知漏洞。 @@ -76,6 +78,7 @@ npm audit --omit=dev - `src/stores/`:认证会话、导航缓存和举报 API 适配 - `src/types/`:认证、物品、举报和匹配模块共享类型 - `src/views/`:登录注册、查询、发布、个人管理、匹配通知和管理页面 +- `e2e/`:连接真实 FastAPI 和 MySQL 的 Playwright 浏览器测试 前端模块边界和数据流见 [前端架构](../docs/architecture/frontend.md),页面状态和视觉 规则见 [设计资料](../docs/design/README.md)。 diff --git a/frontend/e2e/user-flows.spec.ts b/frontend/e2e/user-flows.spec.ts new file mode 100644 index 0000000..7d74dfd --- /dev/null +++ b/frontend/e2e/user-flows.spec.ts @@ -0,0 +1,111 @@ +import { randomUUID } from 'node:crypto' +import { expect, test, type Page } from '@playwright/test' + +const apiUrl = 'http://127.0.0.1:18000/api/v1' +const password = 'LostLink-test-password-2026' + +async function registerAndLogin(page: Page) { + const account = `e2e-${randomUUID()}` + await page.goto('/register') + await page.getByLabel('校园账号', { exact: true }).fill(account) + await page.getByLabel('密码', { exact: true }).fill(password) + await page.getByLabel('确认密码', { exact: true }).fill(password) + await page.getByRole('button', { name: '注册账号', exact: true }).click() + await expect(page.getByRole('status')).toHaveText('账号注册成功,请使用新账号登录。') + await expect(page.getByLabel('校园账号', { exact: true })).toHaveValue(account) + await page.getByLabel('密码', { exact: true }).fill(password) + await page.getByRole('button', { name: '登录', exact: true }).click() + await expect(page).toHaveURL('/my') + await expect(page.getByRole('heading', { name: account, exact: true })).toBeVisible() + return account +} + +test('未登录不能发布,错误密码不能建立会话', async ({ page, request }) => { + const account = `e2e-${randomUUID()}` + const registration = await request.post(`${apiUrl}/auth/register`, { + data: { account, password }, + }) + expect(registration.status()).toBe(201) + + await page.goto('/publish/lost') + await expect(page).toHaveURL(/\/login\?.*redirect=/) + await page.getByLabel('校园账号', { exact: true }).fill(account) + await page.getByLabel('密码', { exact: true }).fill('incorrect-password') + await page.getByRole('button', { name: '登录', exact: true }).click() + await expect(page.getByRole('alert')).toHaveText('账号或密码错误,或账号暂时无法登录。') + await expect(page).toHaveURL(/\/login\?/) + const anonymous = await request.get(`${apiUrl}/users/me`) + expect(anonymous.status()).toBe(401) + + await page.getByLabel('密码', { exact: true }).fill(password) + await page.getByRole('button', { name: '登录', exact: true }).click() + await expect(page).toHaveURL('/publish/lost') + await expect(page.getByRole('heading', { name: '发布失物', exact: true })).toBeVisible() +}) + +for (const type of ['lost', 'found'] as const) { + test(`${type === 'lost' ? '失物' : '拾物'}:注册登录、发布、搜索、编辑、关闭与退出`, async ({ page }) => { + await registerAndLogin(page) + const title = `CI-${type}-${randomUUID().slice(0, 8)}` + await page.goto(`/publish/${type}`) + await page.getByLabel('物品名称').fill(title) + await page.getByLabel('物品类别').selectOption('数码') + await page.getByLabel('特征描述').fill('自动化测试专用物品,外壳有蓝色标记,不涉及真实个人信息。') + await page.getByLabel(type === 'lost' ? '丢失校区' : '拾获校区').selectOption('东丽校区') + await page.getByLabel('校区区域').selectOption('北区') + const location = page.getByLabel(type === 'lost' ? '具体丢失地点' : '具体拾获地点') + await expect(location).toBeEnabled() + await expect(location.locator('option')).not.toHaveCount(1) + await location.selectOption({ index: 1 }) + // 浏览器固定为上海时区,以同一时区生成过去时间,避免 CI 主机时区影响校验。 + const occurredAt = await page.evaluate(() => { + const date = new Date(Date.now() - 60 * 60_000) + const local = new Date(date.getTime() - date.getTimezoneOffset() * 60_000) + return local.toISOString().slice(0, 16) + }) + await page.getByLabel(type === 'lost' ? '丢失时间' : '拾获时间').fill(occurredAt) + await page.getByLabel('手机号或邮箱').fill('ci@example.invalid') + if (type === 'found') { + await page.getByLabel('保管方式').selectOption('self') + await page.getByLabel('暂存地点').selectOption({ index: 1 }) + await page.getByLabel('可联系时间或范围').fill('工作日中午') + } + await page.getByRole('button', { name: type === 'lost' ? '提交发布' : '提交登记' }).click() + await expect(page.getByRole('heading', { + name: type === 'lost' ? '失物发布成功' : '拾物登记成功', + })).toBeVisible() + + await page.getByRole('link', { name: '返回首页', exact: true }).click() + await page.getByLabel('搜索物品').fill(title) + await page.getByRole('button', { name: '搜索', exact: true }).click() + await page.getByRole('heading', { name: title, exact: true }).click() + await expect(page).toHaveURL(/\/items\/\d+$/) + await expect(page.getByRole('heading', { name: title, exact: true })).toBeVisible() + + await page.goto('/my') + if (type === 'found') await page.getByRole('button', { name: '我的拾物', exact: true }).click() + const record = page.locator('.profile-record').filter({ hasText: title }) + await record.getByRole('button', { name: '编辑', exact: true }).click() + const dialog = page.getByRole('dialog', { name: '编辑记录' }) + const editedTitle = `${title}-edited` + await dialog.getByLabel('名称', { exact: true }).fill(editedTitle) + await dialog.getByRole('button', { name: '保存', exact: true }).click() + await expect(dialog).not.toBeVisible() + const editedRecord = page.locator('.profile-record').filter({ hasText: editedTitle }) + await expect(editedRecord).toContainText('状态:进行中') + // 刷新后仍能读到修改,证明数据已经落库。 + await page.reload() + if (type === 'found') await page.getByRole('button', { name: '我的拾物', exact: true }).click() + await expect(editedRecord).toBeVisible() + // 关闭操作先确认,再填写处理说明;两次弹窗都需要回应。 + page.on('dialog', dialog => dialog.accept(dialog.type() === 'prompt' ? 'CI 测试关闭' : undefined)) + await editedRecord.getByRole('button', { name: '关闭记录', exact: true }).click() + await expect(editedRecord).toContainText('状态:已关闭') + await expect(editedRecord.getByRole('button', { name: '编辑', exact: true })).toHaveCount(0) + + await page.getByRole('button', { name: '退出登录', exact: true }).click() + await expect(page).toHaveURL('/') + await page.goto('/my') + await expect(page).toHaveURL(/\/login\?.*redirect=/) + }) +} diff --git a/frontend/package-lock.json b/frontend/package-lock.json index 288d994..f835ad6 100644 --- a/frontend/package-lock.json +++ b/frontend/package-lock.json @@ -12,6 +12,8 @@ "vue-router": "^4.5.1" }, "devDependencies": { + "@playwright/test": "1.64.1", + "@types/node": "22.20.5", "@vitejs/plugin-vue": "^5.2.1", "typescript": "~5.7.2", "vite": "^6.0.5", @@ -533,6 +535,22 @@ "node": "^22.20 || ^24.12 || >=25" } }, + "node_modules/@playwright/test": { + "version": "1.64.1", + "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.64.1.tgz", + "integrity": "sha512-IaYGml/nSOiZWROfPtuIL7neuu9qDOZ3TNvNljUIrhDMxiGTgPjzj/g9p9RxpS2tSepPDRY+UwAaEeiKtUvIAg==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "playwright": "1.64.1" + }, + "bin": { + "playwright": "cli.js" + }, + "engines": { + "node": ">=20" + } + }, "node_modules/@rollup/rollup-android-arm-eabi": { "version": "4.63.4", "resolved": "https://registry.npmjs.org/@rollup/rollup-android-arm-eabi/-/rollup-android-arm-eabi-4.63.4.tgz", @@ -954,6 +972,16 @@ "dev": true, "license": "MIT" }, + "node_modules/@types/node": { + "version": "22.20.5", + "resolved": "https://registry.npmjs.org/@types/node/-/node-22.20.5.tgz", + "integrity": "sha512-U2+DNr+wSjpsTS/wZGYHq7GcwfuSmKiKvoPvK22zwTlRhU91yOniN4qRR5KhIjvif7ysw/dz/hKmfDH0Ris4aA==", + "dev": true, + "license": "MIT", + "dependencies": { + "undici-types": "~6.21.0" + } + }, "node_modules/@vitejs/plugin-vue": { "version": "5.2.4", "resolved": "https://registry.npmjs.org/@vitejs/plugin-vue/-/plugin-vue-5.2.4.tgz", @@ -1541,6 +1569,35 @@ "url": "https://github.com/sponsors/jonschlinkert" } }, + "node_modules/playwright": { + "version": "1.64.1", + "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.64.1.tgz", + "integrity": "sha512-HCrVhHr5QQuwYoswEUGTb7gGp522yflbv/ST8nF4sFWGuLjQCt17Q/EubpGGSNKYn1tsTCPZxqHhHCfVURu7UA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "playwright-core": "1.64.1" + }, + "bin": { + "playwright": "cli.js" + }, + "engines": { + "node": ">=20" + } + }, + "node_modules/playwright-core": { + "version": "1.64.1", + "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.64.1.tgz", + "integrity": "sha512-BC4s8y6SEVA6Q1rSxZTto8hI1KUI3xXlHGZgvGqP4IqPdI/a6FX9H29IDNz7vKo9l21b6LfYosScPL6M3xxyDQ==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "playwright-core": "cli.js" + }, + "engines": { + "node": ">=20" + } + }, "node_modules/postcss": { "version": "8.5.28", "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.28.tgz", @@ -1703,6 +1760,13 @@ "node": ">=14.17" } }, + "node_modules/undici-types": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz", + "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==", + "dev": true, + "license": "MIT" + }, "node_modules/vite": { "version": "6.4.3", "resolved": "https://registry.npmjs.org/vite/-/vite-6.4.3.tgz", diff --git a/frontend/package.json b/frontend/package.json index 1844a79..38fd27e 100644 --- a/frontend/package.json +++ b/frontend/package.json @@ -8,13 +8,18 @@ "build": "vue-tsc -b && vite build", "preview": "vite preview", "test": "vitest run", - "type-check": "vue-tsc -b" + "type-check": "vue-tsc -b", + "type-check:e2e": "tsc --project tsconfig.e2e.json", + "test:e2e": "playwright test", + "test:e2e:report": "playwright show-report" }, "dependencies": { "vue": "^3.5.13", "vue-router": "^4.5.1" }, "devDependencies": { + "@playwright/test": "1.64.1", + "@types/node": "22.20.5", "@vitejs/plugin-vue": "^5.2.1", "typescript": "~5.7.2", "vite": "^6.0.5", diff --git a/frontend/playwright.config.ts b/frontend/playwright.config.ts new file mode 100644 index 0000000..ce65d4b --- /dev/null +++ b/frontend/playwright.config.ts @@ -0,0 +1,57 @@ +import { defineConfig, devices } from '@playwright/test' + +const databaseUrl = process.env.E2E_DATABASE_URL +if (!databaseUrl) { + throw new Error('请先启动隔离测试数据库并设置 E2E_DATABASE_URL,详见 docs/development/testing.md。') +} +const database = new URL(databaseUrl) +if (!['127.0.0.1', 'localhost'].includes(database.hostname) || database.pathname !== '/lostlink_test') { + throw new Error('浏览器测试只允许连接本机的 lostlink_test 数据库。') +} + +export default defineConfig({ + testDir: './e2e', + fullyParallel: false, + forbidOnly: Boolean(process.env.CI), + // 不用重试掩盖首轮失败,测试必须使用独立账号且可重复运行。 + retries: 0, + workers: 1, + timeout: 45_000, + globalTimeout: 10 * 60_000, + reporter: [ + ['list'], + ['html', { open: 'never' }], + ['junit', { outputFile: 'test-results/e2e.xml' }], + ], + use: { + baseURL: 'http://127.0.0.1:4173', + timezoneId: 'Asia/Shanghai', + trace: 'retain-on-failure', + screenshot: 'only-on-failure', + video: 'retain-on-failure', + }, + projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }], + webServer: [ + { + command: 'uv run --frozen uvicorn app.main:app --host 127.0.0.1 --port 18000', + cwd: '../backend', + url: 'http://127.0.0.1:18000/health', + env: { + DATABASE_URL: databaseUrl, + APP_ENV: 'test', + MATCHING_AI_ENABLED: 'false', + CORS_ORIGINS: '["http://127.0.0.1:4173"]', + UPLOAD_DIRECTORY: 'var/e2e-uploads', + }, + reuseExistingServer: false, + timeout: 60_000, + }, + { + command: 'npm run build && npm run preview -- --host 127.0.0.1 --port 4173 --strictPort', + url: 'http://127.0.0.1:4173', + env: { VITE_API_BASE_URL: 'http://127.0.0.1:18000' }, + reuseExistingServer: false, + timeout: 120_000, + }, + ], +}) diff --git a/frontend/tsconfig.e2e.json b/frontend/tsconfig.e2e.json new file mode 100644 index 0000000..fca3dfe --- /dev/null +++ b/frontend/tsconfig.e2e.json @@ -0,0 +1,7 @@ +{ + "extends": "./tsconfig.json", + "compilerOptions": { + "types": ["node"] + }, + "include": ["playwright.config.ts", "e2e/**/*.ts"] +} diff --git a/frontend/vitest.config.ts b/frontend/vitest.config.ts new file mode 100644 index 0000000..96ec066 --- /dev/null +++ b/frontend/vitest.config.ts @@ -0,0 +1,6 @@ +import { defineConfig } from 'vitest/config' + +export default defineConfig({ + // 浏览器用例由 Playwright 执行,避免 Vitest 把 e2e/*.spec.ts 当作单元测试。 + test: { include: ['src/**/*.test.ts'] }, +})