---
description: Build → flash (download) → capture USART1 debug log → verify boot/test markers → iterate. The full automated test loop for the STM32F4-Base target.
agent: build
---

Run the full automated test loop: **build → download → capture serial debug → verify markers → report/iterate**.

Prerequisites (checked in step 0):
- Repo `.venv` exists with `pyserial` installed (rebuild per AGENTS.md "Python 环境" if missing).
- ST-Link probe connected; target powered. The USB-serial (CH340) may stay idle while flashing — ST-Link download does not conflict with the serial port.

## Procedure

### Step 0 — Pre-flight: serial assistant + port

Verify the serial assistant works and the target port exists:

```powershell
& '.venv\Scripts\python.exe' 'tools/serial_tool/serial_tool.py' selftest   # SELFTEST PASS
& '.venv\Scripts\python.exe' 'tools/serial_tool/serial_tool.py' ports        # JSON: 端口列表 + configured 标注
```

Read `.opencode/serial_config.json` for the authoritative `portName` (COM6) and confirm it appears in the `ports` output. If the port is missing, the CH340 driver or the cable is the problem — do not continue.

### Step 1 — Build verify

Run the build script (repo-relative; the repo root is the working directory):

```powershell
& "MDK-ARM\build.bat"
```

Interpretation (per AGENTS.md): exit code 0 = PASS (0 errors, 0 warnings). 1/2+ = FAIL. If it fails, read `MDK-ARM/build_log.txt`, fix, and rerun `@build` until exit code 0 **before** touching the hardware.

### Step 2 — Flash + capture boot log (one orchestrated call)

Use `test/run_boot_test.py` (pure-stdlib Python, 2026-09-20 起替代 PowerShell 版) which opens the port + clears the log (arming),
flashes, waits for RX silence, extracts the boot log and verifies — all in one
call. The serial daemon buffers the full stream in `tools/serial_tool/state/serial.log`,
so nothing can be lost between steps:

```powershell
& '.venv\Scripts\python.exe' test/run_boot_test.py `
  --settle-ms 8000 --max-wait-ms 30000 `
  --flash-cmd "MDK-ARM\download.bat" `
  --required "App init OK;Network Init;net init: OK" `
  --forbidden "FAIL;ERROR;HardFault"
```

`--port` defaults to `.opencode/serial_config.json`; override only if needed.
Exit codes: **0 = PASS**, 1 = FAIL (marker miss / forbidden hit), 2 = capture/flash error, 3 = preflight/usage error.

### Step 3 — Iterate

- **PASS** → report the verdict and which markers matched; done.
- **FAIL** → the `[MISS]`/`[HIT]` lines + the log tail show what went wrong. Fix the code, then loop again from **Step 1**. Do not skip the build step.

## Alternative: interactive serial debug

For interactive command/response (not boot-log capture), drive the serial assistant directly:

1. `ports` → confirm the target port.
2. `open --port COM6 --baud 115200` (idempotent; auto-starts the daemon).
3. `send "text"` / `send --hex 0D0A` to transmit; `log --tail 20` (or Read the log file directly) to see RX history.
4. `close` when done (the daemon itself keeps running; `stop` only if the port must be freed for another tool).

## Notes

- **串口端口**：以 `.opencode/serial_config.json` 为准（本机为 COM6）。每次连接前先读它。
- **全量历史 = 日志文件**：daemon 把 RX/TX/SYS 持续写入 `tools/serial_tool/state/serial.log`，直接 Read/Grep 即可，无需采集窗口仪式。
- **⚠️ 静默判据**：boot 任务间有 ~3-4s 自然静默间隙，`--settle-ms` 必须 ≥ 8000（默认已如此），否则日志截断。
- **daemon 生命周期**：任何命令自动拉起 daemon（无需显式 start）；`restart` 保证加载最新代码；强杀 daemon 后下条命令自动恢复（串口需重新 `open`）。
- UI (LVGL) task `ui_task` 已有 `UI port init: OK` / `UI menu init: OK` 打印，可用 `--required "UI port init: OK;UI menu init: OK"` 自动回归 UI 初始化。
- Full command contract / daemon behavior / known traps: `docs/测试说明/串口助手设计说明.md` and `docs/测试说明/自动化测试流程.md`.