#MoonProbe

#一、项目基本信息

#二、项目简介

• 与 moon test 相比：moon test 验证的是链接进测试二进制的源码函数， 用例必须用 MoonBit 书写；MoonProbe 验证的是通过网络访问的远程服务， 用例用 .probe 文本描述，运行期与被测服务的实现语言完全解耦—— 被测服务用 Go、Rust、Java 还是 MoonBit 写的都无关紧要。
• 与各语言的单元测试框架相比：MoonProbe 不感知被测系统的内部结构， 只施加真实 HTTP 流量，属于黑盒契约验证。
• 与通用 API 调试工具相比：MoonProbe 的用例是版本化的静态文件， 可以随代码一起评审、一起提交，并直接产出 CI 可消费的测试报告。

#三、核心功能范围

• 声明式用例格式：.probe 文本格式，缩进敏感、类 YAML 风格； 单个文件可包含多个用例，按顺序串行执行。
• 注释：# 注释可以独占一行（可带任意缩进），也可以跟在任意一行代码末尾； 引号内的 # 与紧贴文本的 #（如 https://x/a#frag）不算注释。
• 套件级全局配置：文件顶部可用 config: 块声明 base_url（相对 URL 的基址）、 global_headers（每个用例都会带上的请求头）与 global_timeout（每个用例的默认超时）； 运行器在发请求前自动合并，用例自身的声明优先于全局配置。
• 请求定义：支持 GET / POST 等 HTTP 方法、URL、查询参数、请求头与请求体， 方法省略时默认 GET。
• 变量注入：{{var}} 引用用例上下文，${ENV_VAR} 引用宿主环境变量， ${ENV_VAR:-默认值} 给出兜底值；环境变量未设置又没有默认值时直接报错中止， 避免把空串悄悄发出去。两种写法可在同一段文本中混用。
• 状态码断言：对响应状态码做精确匹配。
• JSON 响应体断言（严格数值模式）：用点号路径校验嵌套字段（如 args.page、 data.user.id）。比较是类型感知的：数字按值精确比较（十进制规范化，19 位整数 不丢精度），999 永远不会被 7 满足；7 与 "7"、true 与 1 分属不同类型， 互不通过；7.0 / 1e3 这类写法按其数值是否为整数归入 Int，与 type: 的判定 规则完全一致。单个用例内的断言不短路，一次运行报出全部偏差。
• HTTP 协议合规性：http/ 包是一套自研的 HTTP/1.1 协议栈，不依赖任何外部 可执行文件。请求侧保留 URL fragment 但不写进请求行，按 UTF-8 字节数计算 Content-Length，请求体按原始字节发送（不会被重新解释为文件路径）；响应侧完整 支持 chunked（含扩展与 trailer）、Content-Length 与 EOF 三种分帧，跳过 100 Continue / 103 Early Hints 等中间响应，204 / 304 / HEAD 按规范不读 响应体，并兼容 obs-fold 续行。上述规则均可在 wasm-gc 上以脚本化字节流验证。
• 多族断言：除状态码与 JSON 路径外，还支持 contains / contains_ci（原始响应文本必须包含的子串，后者忽略大小写）、 length（JSON 数组长度）、type（JSON 类型，区分 int 与 number）、 schema（字段类型 + ! 必需标记 + 嵌套对象结构）、 duration_ms（耗时预算，支持 < / <= / > / >= 四种比较）。
• 变量提取与上下文串联：expect 块中的 set 指令可从三处取值—— 响应体 JSON 路径（set: token = data.access_token）、 响应头（set: trace = header.X-Trace-Id）、 Cookie（set: sid = cookie.session）；后续用例通过 {{var}} 引用， 整个测试集共享同一上下文，可完整走通"登录取 token → 携带 token 访问受保护资源"的链路。
• 超时控制：用例级 timeout: 与套件级 global_timeout 双层可配， 优先级为「用例 > 套件 > 运行器默认值」，避免单个用例挂死而拖住整轮运行。
• 智能重试：retry: 可在 config: 块（套件级）或 request: 块（用例级）声明， 取值是额外尝试次数，优先级「用例 > 套件 > 运行器默认 1 次」。只有可能自愈的失败 才重试——连接被拒、DNS 失败、超时这类根本没到达服务端的失败，以及服务端自认有责的 5xx；4xx 与其余状态码立即返回，不把真实故障拖成数倍耗时。取值范围 0–10（retry: 0 即 失败即止），超界或非数字在解析阶段就报错；响应会带上实际发出的尝试次数。
• 执行钩子：before_each: / after_each: 可写在文件顶部（套件级，环绕每一个用例）， 也可写进某个用例内部（用例级）。每个钩子步骤本身就是一条完整用例，可以发请求、做断言、 并用 set: 把 token 之类的前置数据留在共享上下文里供后续用例使用。执行顺序为 「套件 before_each → 用例 before_each → 用例体 → 用例 after_each → 套件 after_each」； before_each 失败会跳过用例体，after_each 则在任何路径上都会执行。
• 终端报告：逐用例输出 [PASS] / [FAIL] 与失败原因，并给出总用例数、 通过数、失败数与耗时汇总。
• JUnit XML 报告：生成符合 Jenkins / GitHub Actions 消费标准的 XML 报告， 供 CI 流水线展示每个用例的执行结果。
• 命令行入口：接收 .probe 文件路径一键运行整个测试集， 支持 --junit <path> 指定报告输出路径。
• 验收回归套件：tests/regression/ 针对 9 月验收暴露的失败点各设一条端到端用例， 从 .probe 源文件一路跑到断言结果，随 moon test 与 CI 一起执行，防止已修复的 问题重新出现。

#四、安装方式与快速开始

#4.1 前置要求

curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash
export PATH="$HOME/.moon/bin:$PATH"
moon version --all          # 应显示 moonc v0.10.14 或更高

若 cli.moonbitlang.com 不可达，可改用镜像 https://cli.moonbitlang.cn/install/unix.sh （CI 中即按此顺序回退重试）。Windows 安装包见 https://www.moonbitlang.com/download/。

#4.2 获取项目

git clone https://github.com/wuhaiting321/MoonProbe.git
cd MoonProbe

#4.3 最小可运行示例

moon run cli --target js -- examples/example_com.probe

[PASS] example.com answers with 200

Summary: 1 total, 1 passed, 0 failed in 3742 ms
Result: PASSED

运行 CLI 必须带 --target js，原因见 5.5 节。

#4.4 作为依赖安装

moon add wuhaiting321/moonprobe

#五、技术亮点与实现说明

#5.1 包结构与职责

#5.2 核心技术实现

1. 纯 MoonBit 实现，零第三方依赖。 解析器、执行器、HTTP 协议栈、断言引擎、 报告生成与 CLI 全部由 MoonBit 编写，仅依赖官方标准库 moonbitlang/core。 留给宿主的只有两类能力：读写成 .probe / 报告文件（cli/file_js.mbt）， 以及一条 TCP / TLS 字节管道（http/host_js.mbt）。后者只用 Node.js 内置的 net、tls 模块，经 process.execPath 启动，不查找也不调用任何外部可执行文件， 因此在 macOS、Linux 与 Windows 上行为一致。
2. 解析器与错误诊断（parser）。 手写词法分析器处理缩进、引号与注释——注释在 分行后立即被剥离（引号内的 # 与紧贴文本的 # 豁免），所以注释可以出现在任意 位置，且不会干扰每一行的缩进判定；递归下降解析器产出 AST（Config / Request / Expect / JsonCheck / SetSpec / LengthCheck / TypeCheck / SchemaField）。 config: 块被限定在文件的首个用例之前且只允许出现一次——全局默认值一旦被 解析，后续用例就只会读它读过的那一份。 错误诊断是解析器的技术细节，而不是独立的产品功能：缺失 URL、未知键、非法状态码、 非法缩进、非法配置块、非法的 set 取值来源都会显式报错并给出行号；运行阶段对 未定义的环境变量、未闭合的占位符、无法解析的相对 URL 同样给出可操作的错误信息， 让拼写错误暴露在第一次运行里，而不是变成一个安静发错的请求。json: 期望值的 引号状态也在这里保留（JsonCheck.expected_quoted），使 code: 7 与 code: "7" 在下游可以走不同的比较路径。
3. 自研 HTTP 栈（http）——从“调用工具”到“拥有协议”。 旧实现把整个网络层 交给 curl.exe：请求由命令行参数拼装、响应由 curl -i 的文本回传，于是产生了一串 无法从外部修正的问题——POST 的 100 Continue 头块混进正文、URL fragment 被当作 查询串、以 @ 开头的请求体被当成文件名、固定的 curl.exe 让 macOS / Linux 启动 即失败。现在协议由项目自己实现：
   • url.mbt 按 RFC 3986 解析 scheme / host / IPv6 / port / path / query / fragment； fragment 留在 Url 值里供用户回读，但 request_target() 只拼 path?query， 绝不把 fragment 写进请求行。
   • client.mbt 渲染请求行与头部，Host 必填（IPv6 加方括号、默认端口省略）， Content-Length 按 UTF-8 字节 计算而不是 UTF-16 code unit 数，请求体原样 发送——@handle 就是 7 个字节，不会被重新解释。
   • parser.mbt 解析响应：状态行 + 头部（obs-fold 续行、大小写折叠）+ 三种分帧 （chunked 含扩展与 trailer、Content-Length、连接关闭 EOF）；1xx 中间响应 （100 Continue、103 Early Hints）被跳过并单独计数，101 视为最终响应； 204 / 304 / HEAD 即使带了 Content-Length 也不读响应体。
   • stream.mbt 提供字节游标（按行、按长度、取剩余），所有解析都建立在这层之上， 因此协议栈可以在 wasm-gc 上被脚本化字节流完整驱动。
   • host_stub.mbt 让没有 socket 的后端返回明确错误，而不是静默失败； host_js.mbt 只负责把已渲染好的字节写进 socket 并读回原始字节（base64 穿越 字符串边界，二进制正文逐字节保真），HTTP 语义一律不越过这条边界。
4. 断言引擎（assert）。 状态码精确匹配；JSON 断言基于标准库 moonbitlang/core/json 解析响应体，按点号路径逐级下钻。数值比较采用严格模式： 期望值先按引号状态与字面量语法分类为 Int / Number / String / Bool / Null， 再与解码值按类型匹配；数字不做字符串拼接、也不经过 Double，而是归约为 「有效数字 + 指数」的十进制规范形式精确比较（1e3 与 1000.0 相等， 999 与 7 不等，19 位整数逐位保留）；7.0、1e3 这类数值为整数的写法与 type: 一样归为 Int。此外提供五族进阶断言：原始文本包含（contains / contains_ci）、数组长度（length）、JSON 类型（type）、对象结构（schema）、 耗时预算（duration_ms）。一个用例内的全部断言共享同一份响应，逐条判定、互不短路。
5. 报告器（reporter）。 控制台报告带 ANSI 色彩并保留 [PASS] / [FAIL] 文本标签，重定向到日志文件依然可读；JUnit XML 生成器完成 &、<、>、"、' 五类字符的 XML 转义，输出的 <testsuites> / <testsuite> / <testcase> / <failure> 结构可直接被 Jenkins 与 GitHub Actions 解析。
6. 配置合并与环境变量注入。 请求在发出前先与套件配置合并：相对 URL 拼到 base_url 上（两侧斜杠被规范化，绝对 URL 原样保留）、同名请求头由用例级声明 就地覆盖全局声明（其余保持全局顺序）、超时按「用例 > 套件 > 运行器默认值」取值。 占位符展开支持两个通道并可混用：{{var}} 取自用例上下文，${ENV} 与 ${ENV:-默认值} 取自宿主环境。整轮展开是一次从左到右的单遍扫描—— 被替换进来的值不会再被扫描一遍，因此响应里带回来的形如 ${...} 的 token 会原样发送；而未设置又无默认值的环境变量会让请求以可操作的错误信息中止， 而不是发出一个空串。
7. 变量提取与上下文传递。 运行器为整个测试集维护一个 Map[String, String] 上下文； set 指令在断言之后执行，可分别从响应体 JSON 路径、响应头（header. 前缀， 名称按 RFC 9110 折叠大小写）与 Cookie（cookie. 前缀，只读 Set-Cookie 的 name=value 部分、名称大小写敏感）取值。下一个用例发起请求前，对 URL、查询参数、 请求头与请求体统一插值；{{var}} 未被绑定时保留原文发送， 让错误暴露在请求内容上，而不是静默变成空串。
8. 多后端可移植。 平台相关代码用 #cfg(target="js") / #cfg(not(target="js")) 隔离，共享逻辑在 wasm-gc 与 js 上均可编译、可测试；环境变量查找与响应头 解析都做成可注入的纯函数，因此这两条路径在 wasm-gc 上也能被完整测到； CI 只跑 wasm-gc 即可覆盖纯逻辑，不受外部服务可用性影响。
9. 智能重试与执行钩子。 重试预算按「用例 retry: > 套件 retry: > 运行器默认 DEFAULT_RETRY_COUNT = 1」三级取值，语义是额外尝试次数而非总次数；解析阶段就把 负数与超过 MAX_RETRY_COUNT = 10 的取值挡在门外，因为重试是立即进行的、不插入退避 等待，一个荒唐的预算不会失败，只会把一次运行挂死。是否重试只看两件事：transport 根本没有完成（连接被拒、DNS 失败、超时），或服务端回了 5xx；4xx 与其余一切立刻返回。 每个响应都带着 attempts（实际发出的尝试次数），而耗时与尝试次数只描述产生该响应的 那一次调用，不把前面失败的尝试算进去。执行钩子复用了 case 语法——钩子步骤就是一条条 完整用例，能发请求、能断言、能 set: 变量，所以"先登录、留下 token"这类前置动作 不必另造一套语法。嵌套顺序为 suite before_each → case before_each → case → case after_each → suite after_each； before_each 失败会阻断用例体（真实原因被连锁失败淹没是最难查的故障），after_each 则在任何路径上都执行——用例出错时，恰恰是清理最要紧的时候。钩子的失败信息一律带 before_each "<步骤名>" 之类的前缀，以免被误读成用例本身的失败。

#5.2.1 HTTP 协议符合性矩阵与能力边界

#5.3 .probe 用例格式

# 套件级全局配置：对本文件的所有用例生效
config:
  base_url: "https://httpbin.org"          # 相对 url 的基址
  global_timeout: 8000                     # 每个用例的默认超时（毫秒）
  global_headers:                          # 每个用例都会带上的请求头
    Accept: "application/json"
    Authorization: "Bearer ${API_TOKEN}"   # 值里可以引用宿主环境变量

name: "1. read the token from the response"
request:
  method: GET
  url: "/response-headers"                 # 相对 url：拼接 config 里的 base_url
  query:
    # httpbin 会把查询参数原样变成响应头，方便演示三种取值来源
    echo: "demo-token-42"
    X-Trace-Id: "trace-7f3a"
    Set-Cookie: "session=abc123"
expect:
  status: 200
  json:
    echo: "demo-token-42"                  # 点号路径校验嵌套字段
  contains: "demo-token-42"                # 原始响应文本必须包含该子串
  type:
    echo: string                           # JSON 类型
  duration_ms <= 2000                      # 耗时预算
  set: token = echo                        # 从响应 JSON 取值
  set: trace = header.X-Trace-Id           # 从响应头取值
  set: sid = cookie.session                # 从 Cookie 取值

name: "2. send the extracted token back"
request:
  method: GET
  url: "/get"
  timeout: 3000                            # 用例级超时，优先于 global_timeout
  query:
    echo: "{{token}}"                      # 引用上一个用例提取的变量
  headers:
    Authorization: "Bearer {{token}}"
expect:
  status: 200
  json:
    args.echo: "demo-token-42"
  schema:
    args: object!                          # 必需字段用 `!` 标记
      echo: string!                        # object 下的缩进行是它的嵌套结构
    url: string!

# 注释既可独占一行（缩进随意），也可跟在任意一行末尾；两者都在词法阶段 被剥离，所以既不影响缩进判定，也不会混进值里。引号内的 # 不算注释，紧贴 文本的 # 也不算——url: https://x/a#frag 会保留 #frag。值本身要以 # 开头时必须加引号，例如 contains: "#tag"。

expect:
  json:
    code: 999          # 要求数字 999，7、7.0 之外的一切数值都不通过
    code: "999"        # 要求字符串 "999"，数字 999 不通过
    ratio: 7.5         # 非整数：按十进制规范形式精确比较
    ratio: 7.0         # 数值为整数，按 Int 比较，等价于 7
    active: true       # Bool 只匹配 true / false，不匹配 1 / 0
    extra: null        # Null 只匹配 JSON null
    name: alice        # 未加引号且不是数字/布尔/null，按字符串 alice 比较

#5.4 与现有方案的差异

#5.5 构建与运行

# 静态检查与单元测试（不依赖网络与 Node.js）
moon check --target wasm-gc
moon test  --target wasm-gc

# 只跑 9 月验收回归套件（它同样包含在上一条命令里）
moon test --target wasm-gc -p wuhaiting321/moonprobe/tests/regression

# 运行示例用例：CLI 必须显式指定 --target js
moon run cli --target js -- examples/httpbin.probe

# 生成 JUnit XML 报告
moon run cli --target js -- examples/auth_chain.probe --junit junit.xml

运行 CLI 必须使用 --target js。 CLI 依赖 JS 宿主读写 .probe 用例文件与报告 文件，并通过 Node.js 内置的 net / tls 建立 TCP 连接（见 http/host_js.mbt）； 用其他后端（如 native）运行会给出明确的“无网络传输”错误。模块的 preferred_target 也已设为 js。

bash check_验收.sh                                          # Linux / macOS
powershell -ExecutionPolicy Bypass -File .\check_验收.ps1   # Windows

#5.6 examples/ 目录的性质

• 它们不会被 moon test 执行，也不进入 CI（CI 只跑 wasm-gc 后端的单元测试）；
• 其中部分用例会真实访问外部站点（如 httpbin.org、example.com）， 运行结果取决于网络可达性，不适合作为构建门禁；
• 项目的自动化测试位于各包的 *_test.mbt 文件与 tests/regression/ 端到端套件， 由 moon test 执行。

#5.7 原创性与参考说明

#六、10 月黑客松新增工作

#七、验收对照（官方 9 条）

#7.1 验收演练记录

• 真实传输链路：js 宿主的 Node 桥接把已经 base64 编码的响应又编码了一次， 协议层拿到的是 base64 文本而不是响应字节，任何真实请求都会报 malformed status line。修复后 examples/example_com.probe 实测通过； CI 增加真实网络示例步骤，防止再次退化。
• 工具链新告警：当前 moonc 对黑盒测试中的非限定包名与 derive(Eq) 的隐式方法 提升给出告警。测试调用改为 @parser.parse / @http.parse_url 等显式形式， 并为 SetSource / JsonType 增加 pub extend ... with Eq::{not_equal, equal}， 使 moon check --deny-warn 在 wasm-gc 与 js 两个后端都真正零告警。

Total tests: 352, passed: 352, failed: 0.
[PASS] example.com answers with 200
Summary: 1 total, 1 passed, 0 failed in 2218 ms
Result: PASSED

#许可证