winget install --id=lilinfangrelax.teshi-engine -e Teshi-engine is an NDJSON-driven multi-tech automation execution engine with self-healing capability. Core workflow: Record → Generate → Execute → Heal. Supports Playwright, Android, and API platforms.
测试自动化执行引擎 — 录制 → 生成 → 执行 → 自愈，通过 NDJSON 协议统一通信。
> 当前阶段：v0.4.0 — NDJSON 协议全面集成 + TUI 自动生成 PageObject/StepDef
>
> | 里程碑 | 目标 | 状态 |
> |--------|------|------|
> | v0.1 | 骨架搭建 — 基础 NDJSON 协议 + Playwright 执行 | ✅ |
> | v0.2 | 录制闭环 — 统一 Action 模型 + 录制归一化 | ✅ |
> | v0.3 | 自愈系统 — 规则回退 + SmartLocator 增强 + BDD + TUI | ✅ |
> | v0.4 | NDJSON 全面集成 — TUI 内录制/回放走 NDJSON + 自动生成 PO/StepDef | ✅ |
> | v1.0 | 多技术栈 — 至少一个额外适配器（Appium / WinUI3） | 🚧 |
# 1. 安装依赖
pip install -e .
# 2. 安装 Playwright 浏览器
playwright install chromium
# 3. 运行端到端验证（GitHub 主页场景）
cat scenarios/github_home.json | python -m engine run
你会看到 NDJSON 格式的 STEP_EXECUTED 和 SCENARIO_FINISHED 消息逐行输出到 stdout。
TUI 与录制数据相对于工作区根目录，而不是 engine 安装目录。首次启动会自动创建下列文件夹：
/
├── features/ # Gherkin .feature 文件
├── recordings/ # 录制会话
├── tests/page_objects/ # Gen 生成的 Page Object
├── tests/step_defs/ # Gen 生成的 step definitions
└── logs/ # TUI 日志
features/、recordings/、tests/page_objects/、tests/step_defs/ 已加入 .gitignore，请在各自工作区目录管理业务文件。
方式一：进入项目目录（推荐）
cd D:\Projects\my-automation
python -m engine tui
方式二：命令行参数
python -m engine tui --workspace D:\Projects\my-automation
python -m engine tui -w D:\Projects\my-automation
方式三：环境变量
# cmd
set TESHI_WORKSPACE=D:\Projects\my-automation
python -m engine tui
# PowerShell
$env:TESHI_WORKSPACE = "D:\Projects\my-automation"
python -m engine tui
优先级：--workspace / -w > TESHI_WORKSPACE > 当前工作目录。
-w 可写在子命令前或后，以下等价：
python -m engine tui -w D:\Projects\my-automation
python -m engine -w D:\Projects\my-automation tui
启动后日志面板会显示 Workspace: <路径>。record 模式同样支持 -w，录制写入该工作区的 recordings/。
run — 标准 NDJSON 服务模式从 stdin 读取 NDJSON 消息，处理后将结果写入 stdout。这是 teshi 启动引擎时的默认通信方式。
# 直接从 stdin 发送 RUN_SCENARIO
echo '{"type":"RUN_SCENARIO","scenario_id":"demo","steps":[{"id":"s1","action":"goto","url":"https://github.com"}]}' | python -m engine run
record — 录制模式打开一个可视化的 Playwright 浏览器，记录你的操作并输出 NDJSON 到 stdout。
python -m engine record --url https://github.com
选项：
| 选项 | 默认 | 说明 |
|---|---|---|
--browser | chromium | 浏览器引擎 (chromium, firefox, webkit) |
--headed | 无头 | 显示浏览器窗口 |
--url | https://github.com | 起始页面 |
--channel | chrome | 系统浏览器通道 (chrome, msedge, chrome-beta 等) |
--run | false | 录制停止后立即回放 |
--screenshot | false | 每个操作后截图 |
-w, --workspace | 当前目录 | 工作区根目录（见上文） |
tui — 图形界面模式启动 Textual TUI 界面，提供文件树浏览、Feature 编辑、录制控制、代码预览和实时执行反馈。
python -m engine tui
python -m engine tui -w D:\Projects\my-automation
界面布局：
┌─ Header ───────────────────────────────────────────────────┐
│ ┌─ Files ─┐ ┌─ Feature (Gherkin) ─┐ ┌─ Steps (code) ─────┐│
│ │📂 Scenarios│ │ Feature: GitHub │ │ Steps | PO | Defs ││
│ │📂 Features │ │ Scenario: ... │ │ [Record] [Stop] ││
│ │📂 Generated│ │ Given 打开... │ │ [Run] [Save] [Gen] ││
│ │ 📄 PO │ │ [editable] │ │ [Heals] [Trace] ││
│ │ 📄 Steps │ └──────────────────┘ │ ┌─ Code ──────────┐││
│ └────────────┘ ┌─ Steps Table ─────┐│ │ page.goto(...) │││
│ │ # │Action│Target│S││ │ page.click(...)│││
│ │ 1 │ click│ Sign │✓││ │ ... │││
│ │ 2 │ fill │ box │✗││ └────────────────┘││
│ └────────────────────┘└────────────────────┘│
├─ Log Panel ────────────────────────────────────────────────┤
├─ Status Bar Ready Steps: 7 ✓ 6 ✗ 1 File: — View: PO ─┤
└────────────────────────────────────────────────────────────┘
快捷键：
| 快捷键 | 功能 |
|---|---|
Ctrl+R | 开始录制 |
Ctrl+S | 停止录制 |
Ctrl+Enter | 回放录制的步骤 |
Ctrl+Shift+S | 保存场景 |
Ctrl+L | 清空日志 |
Ctrl+Q | 退出 |
F5 | 刷新文件树 |
录制：
Ctrl+R → 自动打开 Playwright 浏览器testid > role+aria-label > role+text > label > placeholder > text > cssRecordStep 消息传输回放：
Ctrl+Enter → 通过 ExecutionEngine 执行，走 NDJSON 协议✓ 5422ms / ✗ timeout / ⟐ 320ms（自愈）ScenarioTrace 自动存入 TraceView，点击 Trace 可查看完整执行轨迹HealDiff NDJSON 消息自动持久化到 HealStore自动生成：
录制停止后自动完成以下流程（也可手动点击 Generate）：
PageObjectGenerator → 生成 Playwright PageObject 类StepDefGenerator → 生成 behave 中文步骤定义tests/page_objects/ 和 tests/step_defs/ 目录page_objects + mappings 表）辅助视图：
| 按钮 | 功能 |
|---|---|
| Heals | 弹出自愈历史表格（策略、原始定位器、修复后的定位器、审批状态） |
| Trace | 弹出执行轨迹表格（每步状态、耗时、自愈标记、错误信息） |
| Generate | 手动触发 PageObject / StepDef 重新生成 |
支持 10 种操作动作：
| 动作 | 说明 |
|---|---|
goto | 导航到指定 URL |
click | 点击元素 |
fill | 输入文本 |
wait_for | 等待元素可见 |
screenshot | 全页截图 |
assert_visible | 断言元素可见 |
assert_text | 断言元素文本内容 |
hover | 悬停元素 |
press | 按键操作 |
select | 选择下拉选项 |
关键能力：
testid > role+aria-label > role+text > label > placeholder > text > css运行时定位器自动修复，支持 5 类可愈错误：
| 错误类型 | 说明 |
|---|---|
strict mode | 定位器匹配到多个元素 |
timeout | 元素超时未出现 |
no element | 元素不存在 |
target closed | 目标页面已关闭 |
detached | 元素已从 DOM 分离 |
5 级回退链：原始定位器(.first()) → 属性探测定位置换 → CSS 兜底 → 模糊 text 匹配 → CSS(.first()) 兜底
自愈结果通过协议透传（self_healed 计数 + 原始错误信息）。
集成 behave 框架，支持中文自然语言步骤。
内置步骤（tests/features/steps/web_steps.py）：
| 步骤模式 | 说明 |
|---|---|
Given 打开浏览器到 "{url}" | 导航到指定 URL |
When/Then 等待 "{spec}" 可见 | 等待元素可见 |
When/Then 点击 "{spec}" | 点击元素 |
When 输入 "{text}" 到 "{spec}" | 输入文本 |
Then "{spec}" 可见 | 断言元素可见 |
Then 按钮 "{name}" 可见 | 断言按钮可见 |
定位器支持智能解析：role:name、heading:text、button:name、testid:value、placeholder:text、label:text、CSS 选择器。
自动生成的步骤（通过 TUI 录制后产生在 tests/step_defs/）：
TUI 录制完成后自动生成对应录制操作的 PageObject 和 behave 步骤定义，步骤模式与 StepDefGenerator 一致：
| 来源 | Gherkin 模式 |
|---|---|
goto → navigate() | Given 打开 "{page}" 页面 |
click → click_{key}() | When 点击 "{key}" |
fill → fill_{key}() | When 输入 "{text}" 到 "{key}" |
hover → hover_{key}() | When 悬停 "{key}" |
select → select_{key}() | When 选择 "{value}" 从 "{key}" |
press → press_{key}() | When 按下 "{key}" 键 |
所有通信均使用 Newline-Delimited JSON，每行一条完整 JSON 消息。
引擎支持两种 Transport：
NdjsonTransport — 基于 stdin/stdout，用于 CLI 模式（teshi-engine run）QueueTransport — 基于 asyncio.Queue，用于 TUI 模式（teshi-engine tui），消息在进程内传递两种 Transport 使用完全相同的 Pydantic 消息模型，保证 CLI 和 TUI 行为一致。
| 类型 | 说明 |
|---|---|
RUN_SCENARIO | 启动一个测试场景 |
RECORD_START | 开始录制会话 |
RECORD_STOP | 停止录制 |
PING | 心跳探测 |
| 类型 | 说明 |
|---|---|
STEP_EXECUTED | 单步执行结果（含状态、耗时、截图路径、自愈标记） |
SCENARIO_FINISHED | 场景最终结果（含汇总统计、自愈计数） |
SCENARIO_TRACE | 完整执行轨迹（每步的原始/愈合定位器、BDD 步骤映射） |
RECORD_START | 录制会话开始 |
RECORD_STEP | 录制的单个操作 |
RECORD_STOPPED | 录制结束（含所有操作） |
PONG | 心跳应答 |
ERROR | 错误信息 |
HEAL_DIFF | 自愈差异记录（策略、原始/修复定位器） |
PAGE_OBJECT_GENERATED | PageObject 生成事件 |
MAPPING_UPDATED | 步骤-定位器映射更新事件 |
engine/
├── engine/ # Python 包
│ ├── cli.py # CLI 入口（run / record / tui / generate）
│ ├── protocol/
│ │ ├── messages.py # NDJSON 消息模型 (pydantic)
│ │ └── transport.py # NdjsonTransport + QueueTransport
│ ├── core/
│ │ ├── runner.py # TestRunner 抽象接口
│ │ ├── engine.py # 执行引擎（场景编排、重试、超时、NDJSON 输出）
│ │ ├── recorder.py # Recorder 抽象接口
│ │ ├── heal_store.py # SQLite 存储（自愈记录、PageObject、映射）
│ │ ├── mapper.py # StepMapper（步骤↔PageObject 映射）
│ │ └── trace.py # TraceCollector（执行轨迹收集）
│ ├── generators/
│ │ ├── page_object.py # PageObjectGenerator（PO 代码 + 映射生成）
│ │ └── step_defs.py # StepDefGenerator（behave 步骤定义生成）
│ ├── adapters/
│ │ └── playwright/
│ │ ├── runner.py # PlaywrightTestRunner（10 种动作执行）
│ │ ├── recorder.py # PlaywrightRecorder（JS 注入录制）
│ │ ├── enhancer.py # SmartLocatorEnhancer（定位器升级）
│ │ └── healer.py # SelfHealer（运行时自愈）
│ └── tui/
│ ├── app.py # TeshiApp — Textual TUI 界面
│ ├── heal_view.py # HealView — 自愈历史弹窗
│ └── trace_view.py # TraceView — 执行轨迹弹窗
├── scenarios/ # JSON 场景文件
│ └── github_home.json
├── tests/
│ ├── test_protocol.py # 消息模型序列化测试
│ ├── test_protocol_new.py # 扩展消息模型测试
│ ├── test_transport.py # NDJSON 收发单元测试
│ ├── test_recorder.py # 录制归一化测试
│ ├── test_heal_store.py # HealStore 存储测试
│ ├── test_trace.py # TraceCollector 测试
│ ├── test_page_object_generator.py # PageObject 生成器测试
│ ├── test_step_def_generator.py # StepDef 生成器测试
│ ├── page_objects/ # 自动生成的 PageObject（TUI 录制后产生）
│ ├── step_defs/ # 自动生成的 StepDefs（TUI 录制后产生）
│ └── features/ # behave BDD 特性
│ ├── environment.py # 浏览器生命周期钩子
│ ├── github_home.feature # GitHub 主页验证场景
│ └── steps/
│ └── web_steps.py # 中文步骤定义
├── logs/ # 运行日志
│ └── tui.log
├── pyproject.toml
├── behave.ini
└── README.md
# 安装开发依赖
pip install -e . pytest pytest-asyncio
# 运行测试
pytest
# 运行 BDD 测试
behave
# 添加新适配器
# 1. 实现 engine.core.runner.TestRunner 接口
# 2. 放到 engine/adapters//
# 3. 在 cli.py 中注册