webapp-testing - 本地 Web 应用自动化测试工具

技能概述

webapp-testing 是一个基于 Playwright 的 Python 工具包，专为测试本地 Web 应用设计，提供服务器管理、元素发现、UI 调试和浏览器日志捕获等完整自动化测试能力。

适用场景

1. 本地开发环境测试 - 需要启动并测试本地运行的前端应用、前后端分离项目，工具内置服务器生命周期管理，支持单服务器和多服务器环境

2. 前端功能验证与 UI 调试 - 验证页面交互逻辑是否正确、捕获浏览器截图排查 UI 问题、查看控制台日志定位前端错误，适合开发者的自测和 QA 的回归测试

3. 动态页面元素发现与自动化 - 对于需要等待 JavaScript 渲染的动态应用，提供侦察-后行动模式（Reconnaissance-Then-Action），先识别选择器再执行操作，避免因时序问题导致的不稳定测试

核心功能

1. 服务器生命周期自动化管理 - 通过 with_server.py 辅助脚本自动启动和停止测试所需的服务器进程，支持同时管理多个服务器（如前端开发服务器 + 后端 API 服务器），让开发者只需编写 Playwright 测试逻辑，无需手动处理环境搭建

2. Playwright Python 脚本编写 - 提供完整的同步 API 支持，包含页面导航、网络空闲等待、DOM 内容获取、元素选择器识别、截图和控制台日志捕获等功能，覆盖从静态 HTML 到复杂单页应用的测试需求

3. 侦察-后行动测试模式 - 针对动态 Web 应用，先等待 networkidle 确保 JS 执行完成，再通过截图和 DOM 检查识别目标元素的选择器，最后执行自动化操作，避免因页面未就绪导致的测试失败

常见问题

webapp-testing 支持哪些类型的 Web 应用？

支持静态 HTML 文件和需要 JavaScript 渲染的动态 Web 应用，包括单页应用（SPA）、前后端分离项目，以及任何可以通过 HTTP 访问的本地或远程 Web 页面。

如何测试需要启动服务器的本地应用？

使用工具提供的 with_server.py 辅助脚本，它会自动管理服务器进程。单服务器场景可运行 python scripts/with_server.py --server "npm run dev" --port 5173 -- python your_automation.py，多服务器（如前后端）可在命令中指定多个 --server 参数。

为什么必须在测试前等待 networkidle？

动态 Web 应用依赖 JavaScript 异步加载数据和渲染 DOM，如果过早检查页面元素会导致选择器找不到或状态不正确。page.wait_for_load_state('networkidle') 确保所有网络请求完成后才继续执行测试，是稳定测试的关键步骤。