Python Requests Playwright MCP Promptfoo

本地测试自动化堆栈

自动化工作区，用于配置Conduit RealWorld演示应用程序，填充确定性数据，并在本地基础设施上完全运行API、UI和LLM提示验证。

特点/特性

• 打包了RealWorld的前端+后端，因此设置过程完全离线进行（无需额外的git克隆）。
• 确定性的种子数据通过公共API创建了五个用户和十条文章。
• 在 pytest 执行之前，健康护栏（或称为健康检查机制）会验证前端、后端和数据库的准备情况。
• Pytest测试套件涵盖了REST CRUD操作、身份验证、分页功能，以及支持多上下文（桌面+移动）的Playwright UI流程。
• 每次运行都会内置Allure报告，并附带API响应、Playwright追踪和LLM输出的附件。
• 基于Ollama + Promptfoo构建的用于小型本地模型的提示评估工具gemma3:4b， deepseek-r1:8b) 并通过（某种方式）进行判断验证 gpt-oss:20b）。
• GitHub Actions CI 管道验证 API、UI 和 LLM 套件，并为每次推送/拉取请求存档 Allure 包。
• 可选的Playwright MCP服务器集成，用于交互式定位器捕获（参见 docs/playwright-mcp-notes.md）。

项目布局

.
├── config/               # Environment, seed, and promptfoo configs
├── demo-app/             # Vendored RealWorld example app sources
├── docs/                 # MCP and workflow notes
├── scripts/              # Bootstrap, seeding, and health utilities
├── src/                  # Shared helpers (API client, health, ollama)
├── tests/
│   ├── api/              # Requests-based API coverage
│   ├── ui/               # Playwright MCP multi-context UI coverage
│   ├── llm/              # Promptfoo + Ollama integration tests
│   └── smoke/            # 60-second smoke checks
├── promptfoo/            # Offline prompt suites and shared templates
├── docker-compose.yml    # Optional container stack for postgres/backend/frontend
├── Makefile              # Friendly entry points
├── pyproject.toml        # Python dependencies + pytest config
└── package.json          # Node dependencies for promptfoo / MCP

先决条件

• Python 3.10+ 及以上版本 pip 以及虚拟环境支持（python3-venv 在Debian/Ubuntu上。
• Node.js 18+（演示应用和Promptfoo CLI所需）。
• Docker + Docker Compose（可选；本地运行时默认使用 SQLite，PostgreSQL 仍然可用）。
• Allure 命令行（brew install allure， scoop install allure（或从 JetBrains 下载）。
• 带有Gemma 3 4B、DeepSeek R1 8B和GPT-OSS 20B模型的Ollama二进制文件已本地拉取（测试默认假设为真实推理；如需切换 USE_FAKE_OLLAMA=1 （仅用于快速存根）。

  ollama pull gemma3:4b
  ollama pull deepseek-r1:8b
  ollama pull gpt-oss:20b

测试默认假设进行真实推理；切换 USE_FAKE_OLLAMA=1 仅适用于快速桩（或快速接口）。 - 在CI（持续集成）管道中，您可以设置 CI=true （或者 USE_FAKE_OLLAMA=1) 自动回退到轻量级存根。

快速入门

1. 安装Python依赖项

   python3 -m venv .venv
   source .venv/bin/activate
   pip install --upgrade pip
   pip install -r requirements.txt

1. 安装Node依赖项

   npm install

1. 提供RealWorld演示应用程序

   make demo:setup        # Installs workspace deps, writes backend .env (sqlite by default), runs migrations
   make demo:seed         # Populates five users + ten articles through the public API

> 需要一张白纸吗？ make demo:lite 移除工作区的 node_modules 并以 sqlite 模式重建所有内容。

1. 启动堆栈

- Docker Compose（PostgreSQL）

     docker compose up postgres -d
     docker compose up demo-backend demo-frontend

- 手册（SQLite，默认）

     (cd demo-app/src && npm run dev)  # backend on 3001, frontend on 3000

1. 运行就绪性检查

   make check:health

> 第一次之后 pip/npm 安装时，无需额外克隆GitHub仓库——RealWorld应用和提示套件已完全集成到此仓库中，因此整个测试栈可以在离线状态下运行。

1. 可选快速烧烤

   make test:smoke

测试套件与命令

make promptfoo
# or watch mode
make promptfoo-watch

可用套房：

• articles – 结构化文章撰写，附带评分标准执行。
• is_nlq_agent_prompt – 对自然语言问答（NLQ）进行JSON评分。
• is_nlq_minimal_agent_prompt – 轻量级的“是/否”验证。
• nlq_to_sql – 带聚合查询的SQL合成。
• nlq_to_sql_experiment – 以JOIN为中心的SQL提示。
• try_this_nlq_agent_prompt – 带有行数限制的自然语言问题生成。

你可以单独运行一个测试套件，使用 npx promptfoo eval --config promptfoo/suites//promptfooconfig.yaml。

Pytest + Ollama

tests/llm/test_article_generation.py 从（指定位置）渲染模板 promptfoo/prompts/articles.yaml 并且使用 OllamaRunner 收件人：

1. 生成内容（默认为真实模型，启用存根则 USE_FAKE_OLLAMA=1）。
2. 确保字符长度符合要求。
3. 询问 gpt-oss:20b （或简短说明）用于判断连贯性和主题准确性。

输出、提示和裁判决定均附加在Allure上，以便进行追溯。

剧作家MCP（可选）

在RealWorld前端运行时，启动MCP助手以捕获DOM片段和选择器：

npm run mcp -- --url http://localhost:3000/#/

见 docs/playwright-mcp-notes.md 以了解详细的使用模式。

故障排除

• 缺少Python包 – 创建一个虚拟环境（python3 -m venv .venv) 在安装之前 requirements.txt。
• ollama 错误 – 确认守护进程正在运行（ollama serve）。 为了更快地进行确定性运行，您可以设置 USE_FAKE_OLLAMA=1 使用存根（或桩模块）。
• 未找到 Promptfoo CLI – 跑 npm install 放置 promptfoo 在 node_modules/.bin或者通过调用 npx promptfoo。
• Playwright 浏览器缺失 – 之后 pip install，跑 python -m playwright install --with-deps chromium。
• Allure CLI 不可用 – 全局安装或使用 Docker（docker run -p 4040:4040 -v $PWD/allure-results:/app/results frankescobar/allure-docker-service）。
• GitHub Actions 失败 – 复习/回顾 .github/workflows/ci.yml 重新播放 npm install， python scripts/health_check.py， python scripts/seed_demo_data.py，和 python -m pytest 在本地，然后检查工作流运行中上传的所有 Allure 艺术制品。

已知的差距与未来的改进方向

• 真实的Ollama模型提供更高保真度的结果；可选的存根（或模拟接口）仍然可通过 USE_FAKE_OLLAMA=1 当不需要端到端（E2E）覆盖时。
• SQLite 保持设置轻量；仍可通过 Docker 打包 PostgreSQL 版本以进行兼容性测试。
• UI测试依赖于真实浏览器；除了主页外引入视觉回归快照或进行自动化无障碍性检查将扩大测试覆盖范围。

______________________________________________________________________

有关MCP的使用技巧，请参阅 docs/playwright-mcp-notes.md。