Mesop 测试指南基于 Bazel 单元测试与 Playwright 端到端测试的完整实践【免费下载链接】mesopRapidly build AI apps in Python项目地址: https://gitcode.com/GitHub_Trending/me/mesopMesop 是一个用 Python 快速构建 AI 应用界面的 UI 框架其工程质量依赖一套双轨并行的测试体系单元测试走 Bazel 构建系统覆盖 Python 侧的状态管理、组件与运行时逻辑端到端E2E测试则使用 Playwright 驱动真实浏览器验证页面渲染与用户交互。本文基于仓库内 docs/internal/testing.md 展开并结合 playwright.config.ts、mesop/tests/e2e 等源码给出可直接运行的命令、配置解读与仓库内真实用例帮助你快速掌握 Mesop 的测试环境搭建、用例组织与调试方法。测试体系总览Mesop 的测试分为两层对应不同的测试目标与运行方式测试类型框架运行命令覆盖范围单元测试Bazelpytest 规则封装bazel test //mesop/...Python 状态、事件、运行时、工具函数端到端测试Playwrightyarn playwright test真实浏览器中的页面渲染与交互单元测试不依赖浏览器直接由 Bazel 调度 Python 测试目标端到端测试则启动一个真实的 Mesop 应用服务默认端口http://127.0.0.1:32123/由 Playwright 驱动 Chromium 访问页面并断言 DOM 状态。两条链路互补前者保证框架内部逻辑正确后者保证用户实际看到、操作到的界面行为符合预期。单元测试Bazel 一键执行运行全部单元测试仓库的单元测试通过 Bazel 统一管理运行以下命令即可执行mesop/目录下的全部 Python 测试目标bazel test //mesop/...该命令会递归发现并执行所有 Bazel 测试目标。以 mesop/tests/BUILD 为例其中定义了名为simple_test的py_test目标通过glob([*.py])收集目录下全部 Python 测试文件并依赖THIRD_PARTY_PY_PYTEST提供 pytest 运行时。这意味着你新写的*_test.py文件只要放进对应目录并保证构建图可见就能被bazel test自动纳入测试集。单元测试覆盖的典型模块从仓库布局可以直观看到单元测试的覆盖范围每个核心模块旁都带有对应测试文件状态与会话mesop/server/state_session_test.py、mesop/runtime/node_tree_state_test.py数据类与序列化mesop/dataclass_utils/dataclass_utils_test.py、mesop/dataclass_utils/diff_state_test.py组件差异计算mesop/component_helpers/diff_component_test.py、mesop/component_helpers/helper_test.py服务端工具mesop/server/server_utils_test.py、mesop/server/static_file_serving_test.py、mesop/server/config_test.py命令与特性mesop/commands/cookie_class_test.py、mesop/commands/set_cookie_test.py、mesop/features/query_params_test.py安全策略mesop/security/security_policy_test.pyCLI 执行mesop/cli/execute_module_test.py这些测试验证了状态会话的存取、组件树的差异计算、Cookie 的读写、CSP 安全策略等框架核心行为是bazel test //mesop/...实际覆盖的典型对象。运行单个测试目标如果你只想运行某一个模块的测试可以精确指定 Bazel 目标例如bazel test //mesop/server:state_session_test结合 docs/internal/development.md 中的说明开发环境建议通过 bazelisk 管理 Bazel 版本以保证与项目WORKSPACE声明的版本一致如果构建因 npm 相关错误莫名失败可尝试bazel clean --expunge并清理node_modules后重试Bazel 与 Yarn 在升级 npm 模块时存在缓存 bug。端到端测试Playwright 驱动真实浏览器运行全部 E2E 测试E2E 测试未纳入 Bazel 体系仓库注释明确表示未来希望将这部分 Bazel 化而是直接使用 Playwright 运行yarn playwright test执行前需要先安装项目依赖yarn install以及 Playwright 的 Chromium 浏览器。该命令会依据 playwright.config.ts 自动完成「启动本地服务 → 运行用例 → 生成报告」的完整流程。调试测试当某个 E2E 用例失败且原因不明时可以进入 Playwright 的交互式调试模式逐步回放每个操作步骤yarn playwright test --debug该模式会打开 Playwright Inspector让你以单步方式观察页面状态、检查选择器命中情况是排查交互类问题最直接的手段。用例组织与存放位置E2E 测试按功能域分散在两类目录中框架级用例集中在 mesop/tests/e2e例如buttons_test.ts、navigation_test.ts、state_test.ts、query_params_test.ts、web_security_test.ts以及web_components/子目录下的组件集成用例slot_test.ts、quickstart_test.ts、csp_violations_test.ts等组件级用例位于各组件自己的e2e/子目录例如mesop/components/button/e2e/、mesop/components/input/e2e/。以 mesop/tests/e2e/buttons_test.ts 为例一个典型的 E2E 用例会先page.goto(/buttons)打开页面再通过getByText/getByRole定位元素最后用expect断言交互结果import {test, expect} from playwright/test; test(buttons, async ({page}) { await page.goto(/buttons); expect(await page.getByText(0 clicks).textContent()).toEqual(0 clicks); await page.getByRole(button, {name: primary color button}).click(); expect(await page.getByText(1 clicks).textContent()).toEqual(1 clicks); });测试目标应用example_indexE2E 用例访问的页面路由如/buttons、/navigation来自 mesop/example_index.py该文件集中导入mesop/examples下各示例页面以及每个组件的e2e模块如mesop.components.text.e2e、mesop.components.button.e2e作为所有 E2E 用例的公共应用入口。新增组件时脚手架 scripts/scaffold_component.py 会自动把新组件的 e2e 导入插入该文件并在mesop/BUILD的example_index目标中注册对应依赖。深入 Playwright 配置端口、环境变量与服务启动E2E 测试的可复现性高度依赖 playwright.config.ts 中的关键配置理解这些参数有助于你自定义本地运行方式基础运行参数export default defineConfig({ timeout: process.env.CI ? 75_000 : 40_000, // CI 环境放宽超时 testDir: ., testMatch: [e2e/**/*_test.ts, demo/screenshot.ts], testIgnore: scripts/**, fullyParallel: true, forbidOnly: !!process.env.CI, // CI 中禁止遗留 test.only reporter: html, // 输出 HTML 测试报告 use: { baseURL: http://127.0.0.1:32123/, trace: retain-on-failure, // 失败时保留 trace screenshot: on, // 失败时自动截图 video: retain-on-failure, // 失败时保留视频 }, projects: [{name: chromium, use: {...devices[Desktop Chrome]}}], });要点解读baseURL所有用例中的page.goto(/buttons)等相对路径都会拼接为该地址因此必须与下方webServer启动的服务端口一致快照路径模板项目自定义了snapshotPathTemplate将快照存放到各用例同级目录下的snapshots/文件夹如mesop/tests/e2e/snapshots/web_security_test.ts_csp.txt且明确不做平台相关的截图对比仅做文本 diff保证跨平台可复现失败诊断开启trace、screenshot、video三种留存机制任何用例失败都会留下可回放现场。本地服务自动启动webServer配置会在测试前自动启动一个 Mesop 生产模式服务webServer: { command: MESOP_COOKIE_SECRET_KEY${process.env.MESOP_COOKIE_SECRET_KEY || playwright-test-secret-key} MESOP_STATE_SESSION_BACKEND${process.env.MESOP_STATE_SESSION_BACKEND || none} MESOP_STATIC_FOLDER${process.env.MESOP_STATIC_FOLDER || } bazel run //mesop/cli -- --pathmesop/mesop/example_index.py --prod${process.env.MESOP_DEBUG_MODE true ? false : true}, url: http://127.0.0.1:32123/, reuseExistingServer: !process.env.CI, }可以看出仓库通过环境变量控制测试运行模式环境变量默认值作用MESOP_COOKIE_SECRET_KEYplaywright-test-secret-key为测试服务提供 Cookie 签名密钥MESOP_STATE_SESSION_BACKENDnone关闭状态会话后端使每个请求独立、便于断言MESOP_STATIC_FOLDER空字符串指定静态资源目录默认使用内置静态资源MESOP_DEBUG_MODE未设置设为true时以非生产模式启动服务对应--prodfalse并会跳过部分仅在生产模式有效的用例服务入口是bazel run //mesop/cli以--pathmesop/mesop/example_index.py启动的示例应用reuseExistingServer: !process.env.CI意味着本地已有一个服务在32123端口时会被复用加快迭代速度。按运行模式跳过用例mesop/tests/e2e/e2e_helpers.ts 提供了两组可复用的用例扩展用于按运行模式控制用例是否执行testInProdOnly当MESOP_DEBUG_MODE为true调试/开发模式时跳过用例testInWebSocketsEnabledOnly当MESOP_WEBSOCKETS_ENABLED不为true时跳过用例专门服务于 WebSocket 并发更新场景参考mesop/tests/e2e/concurrent_updates_websockets_test.ts。如果你的自定义用例依赖生产模式或 WebSocket 特性可以从e2e_helpers.ts导入对应的test别名来替代 Playwright 默认的test无需手写条件跳过逻辑。测试用例快照与文本 diff仓库的 E2E 测试不依赖像素级截图对比而是将关键页面状态以文本快照形式固化。快照文件存放在各用例目录下的snapshots/子目录例如 mesop/tests/e2e/snapshots 中的web_security_test.ts_csp.txt、web_security_test.ts_csp-trusted-types.txt分别记录了 CSP 响应头、Trusted Types 策略等安全相关的文本输出。当页面行为发生变化时Playwright 会报告快照 diff帮助你精确定位是预期变更还是回归。与 CI 的衔接仓库的持续集成在 docs/internal/ci.md 中说明使用 GitHub Actions。结合 playwright.config.ts 可以推断CI 环境下 Playwright 会使用更宽的超时75 秒 vs 本地 40 秒因为 CI 机器运行更慢启用forbidOnly防止test.only被误提交关闭reuseExistingServer保证每次从零启动干净的服务。本地开发时则建议先用yarn playwright test快速验证全部用例失败后再用yarn playwright test --debug单步定位问题。常见问题与排查建议端口被占用baseURL与服务启动端口必须一致默认http://127.0.0.1:32123/。若本地已有残留服务Playwright 会尝试复用如遇异常可先停止占用该端口的进程。浏览器未安装首次运行报找不到 Chromium 时执行yarn playwright install chromium安装对应浏览器。用例仅在特定模式有效确认用例是否导入了testInProdOnly/testInWebSocketsEnabledOnly并检查对应的MESOP_DEBUG_MODE、MESOP_WEBSOCKETS_ENABLED环境变量是否符合预期。快照 diff 不明确文本快照在mesop/tests/e2e/snapshots/下直接查看 diff 内容判断是功能变更还是回归。单元测试构建异常参考 docs/internal/development.md必要时执行bazel clean --expunge并清理node_modules。小结Mesop 的测试体系思路清晰Bazel 负责快速、轻量的 Python 单元测试Playwright 负责贴近真实用户的端到端验证。单元测试命令bazel test //mesop/...覆盖状态、事件、运行时与安全策略等框架内核E2E 命令yarn playwright test与yarn playwright test --debug则通过 playwright.config.ts 自动拉起示例应用、驱动 Chromium 完成交互断言。理解了配置中端口、环境变量与快照机制的设计意图你既能快速跑通整套测试也能按需扩展属于自己的 E2E 用例为 Mesop 框架或基于 Mesop 的应用开发建立可靠的回归防线。【免费下载链接】mesopRapidly build AI apps in Python项目地址: https://gitcode.com/GitHub_Trending/me/mesop创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
