STM32F4-Base/.opencode/command/test.md

description, agent

description	agent
Build → flash (download) → capture USART1 debug log → verify boot/test markers → iterate. The full automated test loop for the STM32F4-Base target.	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:

& '.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):

& "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/host/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:

& '.venv\Scripts\python.exe' test/host/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.