豫言 / 全树测试 @ 0.1.0

发现并运行全仓测试：原生单元测试、黄金样例、宿主测试的类型检查与 JS 测试，可分片并行。

# 全树测试

发现并运行整个仓库的测试，按统一规则判定结果，可按分片并行；CI 的「全树测试」矩阵作业逐片调用本工具。

## 用法

在仓库根目录运行（需先有 `yy豫构.wasm` 与其旁的 `yy4_bs.wasm`）：

```sh
node 豫言操作系统/宿主/节点/宿主.cjs yy豫构.wasm 构建 全树测试 --输出 yy全树测试.wasm -j 24
node 豫言操作系统/宿主/节点/宿主.cjs yy全树测试.wasm                      # 运行全部
node 豫言操作系统/宿主/节点/宿主.cjs yy全树测试.wasm --列出               # 只列出将运行的测试
node 豫言操作系统/宿主/节点/宿主.cjs yy全树测试.wasm --分片 3/16          # 运行第 3 片（共 16 片）
node 豫言操作系统/宿主/节点/宿主.cjs yy全树测试.wasm --只 库/标准库/      # 只运行路径以此开头的测试
```

`--分片` 与 `--只` 都可再加 `--列出`。有意外失败时退出码为 1，否则为 0。

## 测试的种类与判定

测试清单来自 `git ls-files`，忽略 `_v0` 目录：

- **单元测试**（`X。测试。豫`）：用 `node 豫言操作系统/宿主/节点/宿主.cjs yy豫构.wasm 文件 <路径> --输出 …` 构建后运行。退出码非零，或输出里出现非零的“当前失败数：N”（单元测试库每次断言都会打印），即判为失败。
- **只检查**：规则表里标为 `只检查` 的单元测试（云工宿主、浏览器宿主须在对应宿主里运行）只做类型检查，即 `node 豫言操作系统/宿主/节点/宿主.cjs yy豫构.wasm 文件 <路径> -- --type-check-only`。
- **黄金样例**（`名-N。豫` 配 `名。成功` 或 `名。失败`）：同组里没被其他文件以“名-N之书”导入的每一份，以及 `名-1`，各自作为独立用例：
  - `。成功`：必须构建、运行成功；标记文件非空时，去掉首尾空白后的标准输出须与它相同。
  - `。失败`：构建或运行必须失败；标记文件非空时，输出须包含它的文字。
- **JS 测试**（`.test.mjs`、`.test.cjs`、`。测试.mjs`、`。测试.cjs`、`.e2e.mjs`）：`node --test --test-timeout=180000 <路径>`。
- **测试页**（`。测试页.html`）暂不自动运行，报告为跳过。

每个测试的运行时限为 3 分钟：有 `timeout` 命令时以它强制，并按用时判定超时；构建不限时。构建产物放在 `dist/全树测试/`，运行后即删除。

## 规则表

`测试规则.tsv` 每行三栏，以制表符分隔：类别、路径、说明。路径以 `/` 结尾时按前缀匹配。空行和以 `#` 开头的行忽略。类别有：

- `跳过`：不运行，说明写原因（如需要云仓、miniflare、QEMU）。
- `只检查`：单元测试只做类型检查。
- `参数`：运行单元测试时追加的参数，以空格分隔（相对仓库根目录）。
- `已知失败`：已登记的失败。失败时报告为“已知失败”，不使 CI 失败；若已通过则报告“意外通过”，提醒把它移出规则表。

## 分片

`--分片 序/总` 按路径顺序把测试切成连续的若干段，同一片内的测试多属同一包，可以共用编译缓存；各片合起来不重不漏。

## 维护

新增测试无需登记，会被自动发现；只有需要跳过、只检查、附加参数或暂列已知失败时才改规则表。修改判定规则时同步更新本说明与文言版。

# 全树测试

遍求全仓之试而行之，以一律断其成败，可分片并行；CI 之「全树测试」矩阵，逐片召此器。

## 用法

于仓根行之（先备 `yy豫构.wasm` 及其旁之 `yy4_bs.wasm`）：

```sh
node 豫言操作系统/宿主/节点/宿主.cjs yy豫构.wasm 构建 全树测试 --输出 yy全树测试.wasm -j 24
node 豫言操作系统/宿主/节点/宿主.cjs yy全树测试.wasm                      # 尽行之
node 豫言操作系统/宿主/节点/宿主.cjs yy全树测试.wasm --列出               # 但列将行者
node 豫言操作系统/宿主/节点/宿主.cjs yy全树测试.wasm --分片 3/16          # 行第三片（凡十六片）
node 豫言操作系统/宿主/节点/宿主.cjs yy全树测试.wasm --只 库/标准库/      # 但行径首合此者
```

`--分片` 与 `--只` 皆可更加 `--列出`。有不虞之败则退码一，否则零。

## 试之类与其断

试之清单出于 `git ls-files`，略 `_v0` 之目：

- **单元之试**（`X。测试。豫`）：以 `node 豫言操作系统/宿主/节点/宿主.cjs yy豫构.wasm 文件 <径> --输出 …` 构而行之。退码非零，或所出有非零之“当前失败数：N”（单元测试之库每断必书），则为败。
- **但检**：规则表记为 `只检查` 之单元试（云工宿主、浏览器宿主须于其宿主行之），唯核其型，即 `node 豫言操作系统/宿主/节点/宿主.cjs yy豫构.wasm 文件 <径> -- --type-check-only`。
- **金样**（`名-N。豫` 配 `名。成功` 或 `名。失败`）：同组之中，不为他篇以“名-N之书”所引者，及 `名-1`，各为一试：
  - `。成功`：须构成、行成；标记非空，则常出去首尾之空后须与之同。
  - `。失败`：构或行须败；标记非空，则所出须含其文。
- **JS 之试**（`.test.mjs`、`.test.cjs`、`。测试.mjs`、`。测试.cjs`、`.e2e.mjs`）：`node --test --test-timeout=180000 <径>`。
- **试页**（`。测试页.html`）今不自行，报为略。

每试行时以三分为限：有 `timeout` 令则以之强制，并以所用之时断其逾限；构不限时。构成之物置 `dist/全树测试/`，行毕即删。

## 规则表

`测试规则.tsv` 每行三栏，以制表为界：类、径、注。径以 `/` 终者为前缀。空行及 `#` 起首者略之。其类：

- `跳过`：不行，注书其故（如须云仓、miniflare、QEMU）。
- `只检查`：单元试唯核其型。
- `参数`：行单元试时所加之参，以空格为界（相对仓根）。
- `已知失败`：已登之败。败则报“已知失败”，不令 CI 败；若已成则报“意外通过”，促其出表。

## 分片

`--分片 序/总` 依径序切为相连之段，同片之试多属一包，可共编译之缓存；诸片合之无重无漏。

## 维护

新增之试无须登记，自能寻得；唯须略、但检、加参或暂列已知之败，乃改规则表。改断之律，则同改此文与汉语之篇。