Luna Flow
简体中文

cli 教程

本教程使用 mare-mark 命令把 JSONL 事件文件转换为 HTML 报告，并检查、然后重放一个记录下来的验证失败。命令在仓库的检出目录中运行；示例使用 testdata/ 中的测试数据。

快速上手

git clone https://github.com/Luna-Flow/mare_mark
cd mare_mark
moon run src/cli --target native -- report testdata/report/sample.jsonl report.html

输出：

report written: /path/to/mare_mark/report.html
events: 5
elapsed: 1333.542ms

在浏览器中打开 report.html。耗时值会有所不同；尽管标注为 ms，它的单位其实是微秒。

日常任务

使用管道

cat testdata/report/sample.jsonl \
  | moon run src/cli --target native -- report - - > report.html

以 - 作为输出时不会打印其他任何内容，因此 HTML 可以直接写入文件或传给另一个工具。

重放之前先检查失败

moon run src/cli --target native -- replay testdata/replay/sample.jsonl --dry-run
command: printf
arguments: [replayed]
timeout: 1000ms

阅读该命令。如果你信任它，就执行它：

moon run src/cli --target native -- replay testdata/replay/sample.jsonl --yes

该命令以记录的超时运行；其 stdout 会被打印出来，非零退出或超时会使 mare-mark 以 1 退出。

生成可重放的产物

运行器写出的 validation_failure 事件带有你的用例的 replay 函数返回的 ReplaySpec。请让该命令能独立复现失败，例如一个接收实现 id 和最小输入的小型工作程序。在导入了 "Luna-Flow/mare_mark/model" 的情况下：

test "a replayable failure description" {
  let replay = (input : Int, implementation : String) => {
    @model.ReplaySpec::new("my-worker", [implementation, input.to_string()], timeout_ms=2000)
  }
  let spec = replay(0, "off-by-one")
  debug_inspect(spec.arguments, content="[\"off-by-one\", \"0\"]")
}

runner 教程展示了一次产生此类事件的运行。

更进一步

  • 把报告步骤加入 CI：运行你的基准测试，写出 JSONL，然后执行 mare-mark report run.jsonl report.html 并上传这两个文件。
  • 在其他目标上，该命令只支持使用文件路径的 report。

常见陷阱

  • 从 stdin 重放。 不支持；请把产物保存到文件。
  • 忘记 --yes。 没有它（也没有 --dry-run）时，replay 以 2 退出且不运行任何东西。
  • 多余的参数。 第三个位置参数是用法错误。

后续步骤