snapshot-checker 0.2.2 → 0.3.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +103 -343
- package/dist/commands/forkall.d.ts +4 -12
- package/dist/commands/forkall.d.ts.map +1 -1
- package/dist/commands/forkall.js +46 -23
- package/dist/commands/forkall.js.map +1 -1
- package/dist/commands/report.d.ts +7 -0
- package/dist/commands/report.d.ts.map +1 -1
- package/dist/commands/report.js +133 -32
- package/dist/commands/report.js.map +1 -1
- package/dist/demos/context-demo.d.ts +10 -0
- package/dist/demos/context-demo.d.ts.map +1 -0
- package/dist/{commands/context_demo.js → demos/context-demo.js} +15 -18
- package/dist/demos/context-demo.js.map +1 -0
- package/dist/{commands → demos}/mac-example.d.ts +1 -3
- package/dist/demos/mac-example.d.ts.map +1 -0
- package/dist/{commands → demos}/mac-example.js +2 -4
- package/dist/demos/mac-example.js.map +1 -0
- package/dist/{commands/timeout_demo.d.ts → demos/timeout-demo.d.ts} +2 -2
- package/dist/demos/timeout-demo.d.ts.map +1 -0
- package/dist/demos/timeout-demo.js +35 -0
- package/dist/demos/timeout-demo.js.map +1 -0
- package/dist/src/cli.js +209 -169
- package/dist/src/cli.js.map +1 -1
- package/dist/src/executor.d.ts +1 -3
- package/dist/src/executor.d.ts.map +1 -1
- package/dist/src/executor.js +1 -3
- package/dist/src/executor.js.map +1 -1
- package/dist/src/groupSpecs.d.ts +1 -4
- package/dist/src/groupSpecs.d.ts.map +1 -1
- package/dist/src/groupSpecs.js.map +1 -1
- package/dist/src/index.d.ts +1 -1
- package/dist/src/index.d.ts.map +1 -1
- package/dist/src/index.js +1 -1
- package/dist/src/index.js.map +1 -1
- package/dist/src/lib/{common_groups.d.ts → presets.d.ts} +13 -2
- package/dist/src/lib/presets.d.ts.map +1 -0
- package/dist/src/lib/{common_groups.js → presets.js} +66 -24
- package/dist/src/lib/presets.js.map +1 -0
- package/dist/src/lib/{programmatic.d.ts → scenario.d.ts} +9 -11
- package/dist/src/lib/scenario.d.ts.map +1 -0
- package/dist/src/lib/{programmatic.js → scenario.js} +6 -10
- package/dist/src/lib/scenario.js.map +1 -0
- package/dist/src/logger.d.ts +23 -0
- package/dist/src/logger.d.ts.map +1 -0
- package/dist/src/logger.js +92 -0
- package/dist/src/logger.js.map +1 -0
- package/dist/src/runCommand.d.ts +27 -35
- package/dist/src/runCommand.d.ts.map +1 -1
- package/dist/src/runCommand.js +81 -70
- package/dist/src/runCommand.js.map +1 -1
- package/dist/src/runGroups.d.ts +6 -12
- package/dist/src/runGroups.d.ts.map +1 -1
- package/dist/src/runGroups.js +14 -19
- package/dist/src/runGroups.js.map +1 -1
- package/dist/src/runners/builtinFunctionRunner.d.ts +1 -0
- package/dist/src/runners/builtinFunctionRunner.d.ts.map +1 -1
- package/dist/src/runners/builtinFunctionRunner.js +5 -12
- package/dist/src/runners/builtinFunctionRunner.js.map +1 -1
- package/dist/src/runners/embedRunner.d.ts +1 -0
- package/dist/src/runners/embedRunner.d.ts.map +1 -1
- package/dist/src/runners/embedRunner.js +5 -1
- package/dist/src/runners/embedRunner.js.map +1 -1
- package/dist/src/runners/shellRunner.d.ts +1 -0
- package/dist/src/runners/shellRunner.d.ts.map +1 -1
- package/dist/src/runners/shellRunner.js +40 -8
- package/dist/src/runners/shellRunner.js.map +1 -1
- package/dist/src/runners/types.d.ts +9 -0
- package/dist/src/runners/types.d.ts.map +1 -1
- package/dist/src/types.d.ts +47 -77
- package/dist/src/types.d.ts.map +1 -1
- package/dist/src/types.js +37 -10
- package/dist/src/types.js.map +1 -1
- package/package.json +10 -3
- package/dist/commands/context_demo.d.ts +0 -18
- package/dist/commands/context_demo.d.ts.map +0 -1
- package/dist/commands/context_demo.js.map +0 -1
- package/dist/commands/mac-example.d.ts.map +0 -1
- package/dist/commands/mac-example.js.map +0 -1
- package/dist/commands/timeout_demo.d.ts.map +0 -1
- package/dist/commands/timeout_demo.js +0 -48
- package/dist/commands/timeout_demo.js.map +0 -1
- package/dist/src/lib/common_groups.d.ts.map +0 -1
- package/dist/src/lib/common_groups.js.map +0 -1
- package/dist/src/lib/foo.d.ts +0 -3
- package/dist/src/lib/foo.d.ts.map +0 -1
- package/dist/src/lib/foo.js +0 -7
- package/dist/src/lib/foo.js.map +0 -1
- package/dist/src/lib/programmatic.d.ts.map +0 -1
- package/dist/src/lib/programmatic.js.map +0 -1
- package/dist/src/lib/trace_formatter.d.ts +0 -9
- package/dist/src/lib/trace_formatter.d.ts.map +0 -1
- package/dist/src/lib/trace_formatter.js +0 -148
- package/dist/src/lib/trace_formatter.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,307 +1,118 @@
|
|
|
1
1
|
# snapshot-checker
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
面向 **Harmony/OpenHarmony 设备联调** 的采集与分析 CLI:通过 `hdc` 在设备上配置 trace 权限、后台拉取日志、并行执行 `hitrace` / `hiperf` 采样,并在本机对 perf 文本做解析、去重与调用栈输出。仓库内两条主场景为 **`forkall`**(可按需走「改机后重启」流程)与 **`report`**(多类风险目标、可选 hstack 与 sourcemap 解析)。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
---
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
| ------------------ | ---------------------------------- | ------------ |
|
|
9
|
-
| `windows` | Windows 下执行命令 | 仅 Windows |
|
|
10
|
-
| `mac` | 面向 macOS 的命令 | 仅 macOS |
|
|
11
|
-
| `linux` | 面向 Linux 的命令 | 仅 Linux |
|
|
12
|
-
| `embed` | 内置指令(如 `sleep` / `timeout`) | 全平台 |
|
|
13
|
-
| `builtin-function` | 内置函数命令(JS/TS 函数) | 全平台 |
|
|
7
|
+
## `forkall` 场景
|
|
14
8
|
|
|
15
|
-
|
|
9
|
+
针对**单一自定义 trace 事件路径**(`--event-path`)做监控或「改配置后重启再采」模式。命令由 `applyOptions` 根据 CLI 注入,实际流水线见 `commands/forkall.ts` 与 `src/lib/presets.ts`。
|
|
16
10
|
|
|
17
|
-
|
|
18
|
-
npm install
|
|
19
|
-
npm run build
|
|
20
|
-
npm start -- foo # 或: node dist/cli.js foo
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
开发时可直接用 tsx 跑(无需 build):
|
|
24
|
-
|
|
25
|
-
```bash
|
|
26
|
-
npm run dev -- run
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
## 测试
|
|
30
|
-
|
|
31
|
-
项目使用 `node:test` + `tsx` 运行测试,测试文件位于 `tests/*.test.ts`。
|
|
32
|
-
|
|
33
|
-
```bash
|
|
34
|
-
npm test
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
当前已覆盖的核心模块(`src/`):
|
|
38
|
-
|
|
39
|
-
- `src/groupSpecs.ts`:组参数解析(默认展开、`name:repeat`、非法 repeat 回退)
|
|
40
|
-
- `src/lib/programmatic.ts`:场景解析、group 参数规范化、按组执行的 stopOnError 行为
|
|
41
|
-
- `src/runGroups.ts`(通过 programmatic 入口间接覆盖):跨组共享命令上下文
|
|
42
|
-
- `src/lib/trace_formatter.ts`:profile 列表、未知 profile 回退、`dev` 配置映射
|
|
43
|
-
|
|
44
|
-
## 配置命令与组(commands 目录)
|
|
11
|
+
**典型阶段(`defaultGroupOrder` 由 `--mode` 决定)**
|
|
45
12
|
|
|
46
|
-
|
|
13
|
+
- **`reboot`**(仅 `reboot-monitor`):上传 `hitrace_utils` / `hiperf`、写入事件占位、重启设备,并用内置 `timeout` 等待重启(可按键跳过)。
|
|
14
|
+
- **`init`**:remount、清理设备与本地残留日志、停后台 hitrace、强停应用、销毁镜像、检查事件列表、配置 checkpoint 开关、为 `--event-path` 对应节点配置权限。
|
|
15
|
+
- **`monitor`**:后台 `hilog` 追加到本地 `snapshot_log.txt`;取 `apppool` pid 注入 `monitor_target`;组合 `hitrace custom_event` + `hiperf record`(事件名为路径中 `/` 替换为 `:`)与 `--app` 触发的 launcher 脚本等。
|
|
16
|
+
- **`collect`**:拉取 `/data/local/tmp` 下的 perf、hitrace 等到 `--output-dir`。
|
|
17
|
+
- **`analysis`**(阶段名:**风险调用栈数据分析**):可选 Python 系统栈解栈;内置步骤按应用进程过滤 tg id、解码 perf、`dedupePerfData`,输出 `dump_stack.txt` / `dump_stack.json`。
|
|
47
18
|
|
|
48
|
-
|
|
19
|
+
**模式**
|
|
49
20
|
|
|
50
|
-
|
|
21
|
+
| `--mode` | 说明 |
|
|
22
|
+
| ---------------- | ---- |
|
|
23
|
+
| `monitor` | 顺序:`init` → `monitor` → `collect` → `analysis`(默认) |
|
|
24
|
+
| `reboot-monitor` | 在首部增加 `reboot` 组,再执行同上 |
|
|
51
25
|
|
|
52
|
-
|
|
53
|
-
export const groups: Groups = {
|
|
54
|
-
env: [
|
|
55
|
-
{ kind: "shell", description: "打印当前目录", run: "pwd" },
|
|
56
|
-
{ kind: "shell", description: "Node 版本", run: "node -v" },
|
|
57
|
-
],
|
|
58
|
-
list: [{ kind: "shell", description: "列出文件", run: "ls -la" }],
|
|
59
|
-
};
|
|
60
|
-
|
|
61
|
-
export const defaultGroupOrder: string[] = ["env", "list"];
|
|
62
|
-
```
|
|
63
|
-
|
|
64
|
-
- 不指定 `--group` 时:按 `defaultGroupOrder` 依次执行各组,且**只执行当前系统支持**的命令(shell 全平台;bat 仅 Windows;mac 仅 macOS)。
|
|
65
|
-
- 指定 `--group env list` 时:按给定顺序执行这些组内、且当前系统支持的命令。
|
|
66
|
-
|
|
67
|
-
每条命令可加 `cwd` 指定工作目录。
|
|
26
|
+
**主要 CLI(场景专有,运行于 `snapshot-checker forkall`)**
|
|
68
27
|
|
|
69
|
-
|
|
28
|
+
| 选项 | 说明 |
|
|
29
|
+
| ------ | ------ |
|
|
30
|
+
| `--event-path <path>` | 内核 tracing 事件路径片段(脚本内会转成 `:` 分隔的 hiperf 事件名) |
|
|
31
|
+
| `--app <app>` | 应用包名;空则跳过通过 hidumper 创建实例等步骤 |
|
|
32
|
+
| `--system-symbol-file-path <path>` | 若提供:对导出 perf 文本做系统栈解析(Python) |
|
|
33
|
+
| `--log-key <key>` | `hilog` 过滤关键字,默认 `pid` |
|
|
34
|
+
| `--duration <seconds>` | 采样时长(秒),默认 `70` |
|
|
35
|
+
| `--default-timeout <seconds>` | `reboot-monitor` 下等待设备就绪,默认 `90` |
|
|
36
|
+
| `--buffer-size <bytes>` | hitrace/hiperf 缓冲,默认 `512000` |
|
|
37
|
+
| `--mode <mode>` | `monitor` 或 `reboot-monitor` |
|
|
38
|
+
| `--output-dir <path>` | 本地输出目录,默认 `.\output` |
|
|
39
|
+
| `--trace-format-profile <name>` | trace 解码 profile,默认 `default` |
|
|
40
|
+
| `--skip-perf-dedupe` | 解码后跳过 `dedupePerfData` |
|
|
70
41
|
|
|
71
|
-
|
|
42
|
+
此外还有与子命令通用的选项(见下文「次要:CLI 场景框架」中的通用标志)。
|
|
72
43
|
|
|
73
|
-
|
|
44
|
+
**示例**
|
|
74
45
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
#### `timeout <seconds>`(兼容 `timieout <seconds>`)
|
|
82
|
-
|
|
83
|
-
最多等待指定秒数,并实时显示剩余时间;在可交互终端下,用户按任意键可立即结束等待。
|
|
84
|
-
|
|
85
|
-
示例:
|
|
86
|
-
|
|
87
|
-
```ts
|
|
88
|
-
{
|
|
89
|
-
kind: 'embed',
|
|
90
|
-
run: 'timeout 30',
|
|
91
|
-
description: '最多等待 30 秒,按任意键跳过',
|
|
92
|
-
}
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
行为说明:
|
|
96
|
-
|
|
97
|
-
- 使用同一行原地刷新倒计时(`[timeout] 剩余 Ns...`)。
|
|
98
|
-
- 到达超时时间后自动继续后续命令。
|
|
99
|
-
- 若检测到键盘输入则立即结束等待并继续。
|
|
100
|
-
- 在非 TTY 环境(如某些 CI)中会退化为仅按时间等待,不监听按键。
|
|
101
|
-
|
|
102
|
-
仓库内完整示例见 `commands/timeout_demo.ts`(`npm run dev -- timeout_demo` 或 `node dist/cli.js timeout_demo`)。
|
|
103
|
-
|
|
104
|
-
### 通用 lib 工具函数
|
|
105
|
-
|
|
106
|
-
推荐将通用逻辑放在 `src/lib/` 下(例如 `src/lib/foo.ts`),在场景文件中直接调用这些函数:
|
|
107
|
-
|
|
108
|
-
```ts
|
|
109
|
-
import { buildTag, buildUserGreeting } from '../src/lib/foo.js';
|
|
110
|
-
|
|
111
|
-
{
|
|
112
|
-
kind: CommandKind.BuiltinFunction,
|
|
113
|
-
description: '调用 lib/foo 的工具函数写入变量',
|
|
114
|
-
func: (ctx) => {
|
|
115
|
-
const user = ctx.user ?? 'unknown';
|
|
116
|
-
ctx.builtinTag = buildTag('context_demo');
|
|
117
|
-
ctx.fromFoo = buildUserGreeting(user);
|
|
118
|
-
},
|
|
119
|
-
}
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
仓库内完整示例见 `commands/context_demo.ts`。
|
|
123
|
-
|
|
124
|
-
### 命令之间传递变量(上下文)
|
|
125
|
-
|
|
126
|
-
命令执行器内置了一个**简单的上下文对象**,允许前一条命令将自己的输出写入变量,后续命令通过模板占位符引用这些变量。通过 CLI 跑场景时,该上下文在**整个场景执行期间**(含不同 `group`、不同块之间)**同一份共享**,因此可以把变量从 `getUser` 组传到 `greet` 组。仓库内示例见 `commands/context_demo.ts`。
|
|
127
|
-
|
|
128
|
-
- **写入变量:**在命令上增加 `captureToVar` 元数据
|
|
129
|
-
- **读取变量:**在 `run` / `file` / `args` / `cwd` / `description` 中使用 `{{varName}}` 占位符
|
|
130
|
-
|
|
131
|
-
示例:
|
|
132
|
-
|
|
133
|
-
```ts
|
|
134
|
-
// commands/example.ts
|
|
135
|
-
import type { Groups } from "../src/types.js";
|
|
136
|
-
|
|
137
|
-
export const groups: Groups = {
|
|
138
|
-
env: [
|
|
139
|
-
{
|
|
140
|
-
kind: "shell",
|
|
141
|
-
description: "获取当前用户名",
|
|
142
|
-
run: "whoami",
|
|
143
|
-
// 将整段 stdout 写入变量 user
|
|
144
|
-
// (比如 "alice"),供后续命令使用
|
|
145
|
-
// @ts-expect-error: 由执行器在运行时识别的扩展字段
|
|
146
|
-
captureToVar: {
|
|
147
|
-
name: "user",
|
|
148
|
-
},
|
|
149
|
-
},
|
|
150
|
-
],
|
|
151
|
-
greet: [
|
|
152
|
-
{
|
|
153
|
-
kind: "shell",
|
|
154
|
-
description: "使用上一条命令得到的用户名",
|
|
155
|
-
run: 'echo "hello, {{user}}"',
|
|
156
|
-
},
|
|
157
|
-
],
|
|
158
|
-
};
|
|
159
|
-
|
|
160
|
-
export const defaultGroupOrder = ["env", "greet"];
|
|
46
|
+
```bash
|
|
47
|
+
npm run build
|
|
48
|
+
npm start -- forkall --help
|
|
49
|
+
node dist/src/cli.js forkall --mode monitor --event-path snapshot/hmb_forkall_report_image_failure --app com.example.app
|
|
161
50
|
```
|
|
162
51
|
|
|
163
|
-
|
|
52
|
+
---
|
|
164
53
|
|
|
165
|
-
|
|
54
|
+
## `report` 场景
|
|
166
55
|
|
|
167
|
-
|
|
168
|
-
{
|
|
169
|
-
kind: 'shell',
|
|
170
|
-
description: '获取某个进程 pid',
|
|
171
|
-
run: 'pidof my-app',
|
|
172
|
-
// @ts-expect-error: 由执行器在运行时识别的扩展字段
|
|
173
|
-
captureToVar: {
|
|
174
|
-
name: 'pid',
|
|
175
|
-
pattern: '^(\\d+)', // 匹配第一行的数字
|
|
176
|
-
groupIndex: 1, // 取第 1 个捕获组
|
|
177
|
-
},
|
|
178
|
-
},
|
|
179
|
-
{
|
|
180
|
-
kind: 'shell',
|
|
181
|
-
description: '用 pid 做点事',
|
|
182
|
-
run: 'echo "pid is {{pid}}"',
|
|
183
|
-
}
|
|
184
|
-
```
|
|
56
|
+
面向 **镜像失效等风险** 的专项采集与分析:可多选内核侧风险类型,拉取 ipc / 文件访问相关 tap;分析阶段可选用 **hstack** 解析 perf 文本与 **sourcemap** 符号化,或通过内置步骤在多个候选文件中挑选可用 perf 输入再解码。
|
|
185
57
|
|
|
186
|
-
|
|
58
|
+
**典型阶段**
|
|
187
59
|
|
|
188
|
-
-
|
|
189
|
-
-
|
|
190
|
-
-
|
|
191
|
-
-
|
|
60
|
+
- **`init`**:与 forkall 共用的初始化(权限命令按所选风险类型生成)。
|
|
61
|
+
- **`monitor`**:多标签 `hitrace` + 多事件 `hiperf record`(由 `--risk-targets` 推导)。
|
|
62
|
+
- **`collect`**:同 forkall。
|
|
63
|
+
- **`analysis`**(阶段名:**镜像失效风险栈分析**):会先写回溯栈再做过滤/解码路径;配置了 hstack 时先跑外部工具再在 `_snapshot_perf.data.txt` 与原始快照间选输入。
|
|
192
64
|
|
|
193
|
-
|
|
65
|
+
**风险目标 `--risk-targets`**
|
|
194
66
|
|
|
195
|
-
|
|
196
|
-
- 在 `commands/foo.ts` 中定义 `foo` 场景:
|
|
67
|
+
逗号分隔,可选:`all`、`ipc`、`file`(语义见运行时日志中的中文展示名:**文件访问** 与 **IPC 调用** 两类链路)。未知值会报错。
|
|
197
68
|
|
|
198
|
-
|
|
199
|
-
// commands/foo.ts
|
|
200
|
-
export const groups: Groups = {
|
|
201
|
-
env: [
|
|
202
|
-
{ kind: "shell", description: "[foo] 打印当前目录", run: "pwd" },
|
|
203
|
-
{ kind: "shell", description: "[foo] 显示 Node 版本", run: "node -v" },
|
|
204
|
-
],
|
|
205
|
-
list: [{ kind: "shell", description: "[foo] 列出当前目录", run: "ls -la" }],
|
|
206
|
-
};
|
|
69
|
+
**主要 CLI**
|
|
207
70
|
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
-
|
|
71
|
+
| 选项 | 说明 |
|
|
72
|
+
| ------ | ------ |
|
|
73
|
+
| `--app <app>` | 应用包名 |
|
|
74
|
+
| `--hstack-tool-path <path>` | hstack 可执行文件;不配置则跳过该步并仅用原始 perf |
|
|
75
|
+
| `--sourcemap-dir <path>` | 传给 hstack 的 `-s` |
|
|
76
|
+
| `--log-key`、`--duration`、`--buffer-size` | 同 forkall |
|
|
77
|
+
| `--output-dir` | 默认 `.\output`;perf 文本子目录为 `perf_txt/` |
|
|
78
|
+
| `--trace-format-profile` | 同 forkall |
|
|
79
|
+
| `--risk-targets <targets>` | 默认 `all` |
|
|
80
|
+
| `--skip-perf-dedupe` | 同 forkall |
|
|
212
81
|
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
export const groups: Groups = {
|
|
216
|
-
env: [
|
|
217
|
-
{ kind: "shell", description: "[bar] 打印当前目录", run: "pwd" },
|
|
218
|
-
{ kind: "shell", description: "[bar] 显示 Node 版本", run: "node -v" },
|
|
219
|
-
],
|
|
220
|
-
list: [{ kind: "shell", description: "[bar] 列出当前目录", run: "ls -la" }],
|
|
221
|
-
extra: [
|
|
222
|
-
{
|
|
223
|
-
kind: "shell",
|
|
224
|
-
description: "[bar] 额外命令示例",
|
|
225
|
-
run: "echo extra from bar",
|
|
226
|
-
},
|
|
227
|
-
],
|
|
228
|
-
};
|
|
229
|
-
|
|
230
|
-
export const defaultGroupOrder: string[] = ["env", "extra", "list"];
|
|
82
|
+
```bash
|
|
83
|
+
node dist/src/cli.js report --app com.example.app --risk-targets ipc,file
|
|
231
84
|
```
|
|
232
85
|
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
- `commands/foo.ts` → `snapshot-checker foo`
|
|
236
|
-
- `commands/bar.ts` → `snapshot-checker bar`
|
|
237
|
-
|
|
238
|
-
## CLI 选项
|
|
239
|
-
|
|
240
|
-
- `--wait`:所有**前台**命令跑完后,继续等待**后台**命令(`background: true`)自然退出再结束进程;不加则前台全部结束后会**优雅结束**这些后台子进程并立即退出 CLI。
|
|
241
|
-
- `snapshot-checker <scene>` — 使用 `commands/<scene>.ts` 中的配置执行命令,例如:
|
|
242
|
-
- `snapshot-checker foo` 使用 `commands/foo.ts` 的 `groups` 与 `defaultGroupOrder`
|
|
243
|
-
- `snapshot-checker bar` 使用 `commands/bar.ts` 的 `groups` 与 `defaultGroupOrder`
|
|
244
|
-
- `snapshot-checker foo --list` 仅列出 `foo` 场景中的命令,不执行
|
|
245
|
-
- `snapshot-checker bar --list` 仅列出 `bar` 场景中的命令,不执行
|
|
86
|
+
---
|
|
246
87
|
|
|
247
|
-
##
|
|
88
|
+
## 安装与本地开发
|
|
248
89
|
|
|
249
90
|
```bash
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
# 仅查看 foo 场景中的命令(不执行)
|
|
254
|
-
node dist/cli.js foo --list
|
|
255
|
-
|
|
256
|
-
# 使用 bar 场景(commands/bar.ts)执行命令
|
|
257
|
-
node dist/cli.js bar --group env,extra
|
|
258
|
-
|
|
259
|
-
# 仅查看 bar 场景中的命令(不执行)
|
|
260
|
-
node dist/cli.js bar --list
|
|
261
|
-
```
|
|
262
|
-
|
|
263
|
-
## 项目结构
|
|
264
|
-
|
|
265
|
-
```
|
|
266
|
-
src/
|
|
267
|
-
cli.ts # CLI 入口,负责解析参数并调用执行逻辑
|
|
268
|
-
runCommand.ts # 单条/多条命令执行(无 group 概念)
|
|
269
|
-
runGroups.ts # 组规格解析、分块、按组执行(含组间间隔)
|
|
270
|
-
executor.ts # 统一导出 runCommand + runGroups
|
|
271
|
-
types.ts # 类型定义
|
|
272
|
-
index.ts # 库导出(从 commands/config.ts 导出默认 groups)
|
|
273
|
-
|
|
274
|
-
commands/
|
|
275
|
-
foo.ts # foo 场景示例:自定义 groups/defaultGroupOrder
|
|
276
|
-
bar.ts # bar 场景示例:自定义 groups/defaultGroupOrder
|
|
277
|
-
|
|
278
|
-
demos/
|
|
279
|
-
consumer-app/ # 独立示例:npm install snapshot-checker 后的调用方式
|
|
91
|
+
npm install
|
|
92
|
+
npm run build
|
|
93
|
+
npm start -- --help # 或: node dist/src/cli.js --help
|
|
280
94
|
```
|
|
281
95
|
|
|
282
|
-
|
|
96
|
+
开发时可直接用源码跑(无需 build):
|
|
283
97
|
|
|
284
98
|
```bash
|
|
285
|
-
npm
|
|
286
|
-
npm run build # prepublishOnly 也会在 publish 时执行
|
|
287
|
-
npm publish
|
|
99
|
+
npm run dev -- forkall --list
|
|
288
100
|
```
|
|
289
101
|
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
## 作为库使用(npm install 之后)
|
|
102
|
+
## 测试
|
|
293
103
|
|
|
294
|
-
|
|
104
|
+
使用 `node:test` + `tsx`,文件位于 `tests/*.test.ts`。
|
|
295
105
|
|
|
296
106
|
```bash
|
|
297
|
-
npm
|
|
107
|
+
npm test
|
|
298
108
|
```
|
|
299
109
|
|
|
300
|
-
|
|
110
|
+
## 作为库使用
|
|
111
|
+
|
|
112
|
+
安装后可通过 `resolveScenario` + `runScenarioGroups` 注入场景 CLI 等价参数:
|
|
301
113
|
|
|
302
114
|
```ts
|
|
303
115
|
import { resolveScenario, runScenarioGroups } from "snapshot-checker";
|
|
304
|
-
import * as contextDemo from "snapshot-checker/commands/context_demo";
|
|
305
116
|
import * as forkall from "snapshot-checker/commands/forkall";
|
|
306
117
|
|
|
307
118
|
const { groups, defaultGroupOrder } = resolveScenario(forkall, {
|
|
@@ -313,108 +124,57 @@ const { groups, defaultGroupOrder } = resolveScenario(forkall, {
|
|
|
313
124
|
await runScenarioGroups({ groups, defaultGroupOrder, stopOnError: true });
|
|
314
125
|
```
|
|
315
126
|
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
独立 Node 示例工程(依赖 registry 上的本包):见 `demos/consumer-app/README.md`。
|
|
319
|
-
|
|
320
|
-
在该示例目录中可直接运行:
|
|
321
|
-
|
|
322
|
-
```bash
|
|
323
|
-
cd demos/consumer-app
|
|
324
|
-
npm install
|
|
325
|
-
npm run context
|
|
326
|
-
npm run forkall
|
|
327
|
-
```
|
|
328
|
-
|
|
329
|
-
## 包安装、更新与卸载
|
|
330
|
-
|
|
331
|
-
### 在业务项目中安装(推荐)
|
|
332
|
-
|
|
333
|
-
```bash
|
|
334
|
-
npm install snapshot-checker
|
|
335
|
-
```
|
|
336
|
-
|
|
337
|
-
使用方式:
|
|
338
|
-
|
|
339
|
-
```bash
|
|
340
|
-
npx snapshot-checker --help
|
|
341
|
-
```
|
|
342
|
-
|
|
343
|
-
卸载:
|
|
344
|
-
|
|
345
|
-
```bash
|
|
346
|
-
npm uninstall snapshot-checker
|
|
347
|
-
```
|
|
348
|
-
|
|
349
|
-
更新到最新版本:
|
|
350
|
-
|
|
351
|
-
```bash
|
|
352
|
-
npm install snapshot-checker@latest
|
|
353
|
-
# 或更新已安装版本
|
|
354
|
-
npm update snapshot-checker
|
|
355
|
-
```
|
|
356
|
-
|
|
357
|
-
### 全局安装(命令行直接可用)
|
|
127
|
+
独立示例工程:`demos/consumer-app`(内含 `README` 与子命令演示)。
|
|
358
128
|
|
|
359
|
-
|
|
360
|
-
npm install -g snapshot-checker
|
|
361
|
-
snapshot-checker --help
|
|
362
|
-
```
|
|
129
|
+
---
|
|
363
130
|
|
|
364
|
-
|
|
131
|
+
## 次要:`snapshot-checker` CLI 场景框架与其它能力
|
|
365
132
|
|
|
366
|
-
|
|
367
|
-
npm uninstall -g snapshot-checker
|
|
368
|
-
npm install -g snapshot-checker@latest
|
|
369
|
-
```
|
|
133
|
+
本工具本质是 **按命名场景(`commands/*.ts`、`demos/*.ts`)注册子命令**:每个文件导出 **`groups`**、**`defaultGroupOrder`**,可选 **`options`** 与 **`applyOptions(opts)`**——在运行时根据 Commander 解析结果重写命令表(`forkall` / `report` 即用此机制)。
|
|
370
134
|
|
|
371
|
-
###
|
|
135
|
+
### 命令类型与环境
|
|
372
136
|
|
|
373
|
-
|
|
137
|
+
默认只执行「当前操作系统支持」的条目:`windows` / `mac` / `linux` / `shell`;另有 **`embed`**(内置_sleep、timeout 等)与 **`builtin-function`**(TypeScript 函数)。不指定 `-g,--group` 时按 **`defaultGroupOrder`** 遍历各组。
|
|
374
138
|
|
|
375
|
-
|
|
376
|
-
npm run build
|
|
377
|
-
npm pack
|
|
378
|
-
```
|
|
139
|
+
### `commands/` 最小场景
|
|
379
140
|
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
141
|
+
```ts
|
|
142
|
+
export const groups: Groups = {
|
|
143
|
+
env: [
|
|
144
|
+
{ kind: "shell", description: "当前目录", run: "pwd" },
|
|
145
|
+
],
|
|
146
|
+
};
|
|
147
|
+
export const defaultGroupOrder: string[] = ["env"];
|
|
384
148
|
```
|
|
385
149
|
|
|
386
|
-
|
|
150
|
+
子命令:`snapshot-checker <场景名>` 对应文件名(跳过 `config.*`)。
|
|
387
151
|
|
|
388
|
-
|
|
389
|
-
npm uninstall snapshot-checker
|
|
390
|
-
```
|
|
152
|
+
### 内置 `embed`
|
|
391
153
|
|
|
392
|
-
|
|
154
|
+
- **`sleep <seconds>`** — 休眠。
|
|
155
|
+
- **`timeout <seconds>`** — 倒计时等待,TTY 下可按键跳过;CI 中非 TTY 时仅延时。详见 `demos/timeout-demo.ts`。
|
|
393
156
|
|
|
394
|
-
|
|
157
|
+
### 命令上下文(`captureToVar`)
|
|
395
158
|
|
|
396
|
-
|
|
397
|
-
npm link
|
|
398
|
-
```
|
|
159
|
+
前序命令可把 stdout/stderr(或正则捕获组)写入变量,后续在 `run` / `cwd` 等处用 **`{{变量名}}`** 展开。示例见 `demos/context-demo.ts`。
|
|
399
160
|
|
|
400
|
-
|
|
161
|
+
### 其它 CLI 开关(作用于各场景子命令)
|
|
401
162
|
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
163
|
+
- **`--wait`** — 前台结束后仍等待后台命令自然退出;默认会结束后台进程后退出进程。
|
|
164
|
+
- **`--list`** — 只列出将要执行的命令。
|
|
165
|
+
- **`--dry-run`** — 打印序列但不执行。
|
|
166
|
+
- **`--stop-on-error`** — 遇错中止。
|
|
167
|
+
- **`-g,--group`** — 限定或重复某一组:`env:10,list` 等。
|
|
168
|
+
- **`--silent`**、`--interval`**、`--ignore-platform`、`--log-level`** 等 — 见 `snapshot-checker <scene> --help`。
|
|
405
169
|
|
|
406
|
-
|
|
170
|
+
### `foo` / `bar` 与多场景
|
|
407
171
|
|
|
408
|
-
|
|
409
|
-
npm unlink snapshot-checker
|
|
410
|
-
```
|
|
172
|
+
仓库保留 `commands/foo.ts`、`commands/bar.ts` 等用于演示多套 `groups`;默认「运行」场景的入口仍可指向 `commands/config.ts`(若项目中使用 `run` 子命令时需与当前 `cli` 实现对齐)。
|
|
411
173
|
|
|
412
|
-
|
|
174
|
+
### 发布与日常命令
|
|
413
175
|
|
|
414
|
-
|
|
415
|
-
npm unlink -g snapshot-checker
|
|
416
|
-
```
|
|
176
|
+
构建发布、全局/本地安装、`npm pack`、`npm link` 等与常规 Node 包相同;全局安装后:`snapshot-checker`。若远程包名不可用,可使用作用域名发布并相应调整 `package.json`。
|
|
417
177
|
|
|
418
|
-
|
|
178
|
+
### License
|
|
419
179
|
|
|
420
180
|
MIT
|
|
@@ -1,13 +1,4 @@
|
|
|
1
1
|
import type { Groups } from "../src/types.js";
|
|
2
|
-
/**
|
|
3
|
-
* forkall 场景的基础占位配置。
|
|
4
|
-
* 实际要执行的命令会在 applyOptions 中,根据 CLI 传入的参数(eventPath/app 等)动态生成。
|
|
5
|
-
*
|
|
6
|
-
* 作为 npm 包被外部项目引用时:
|
|
7
|
-
* import * as forkall from 'snapshot-checker/commands/forkall';
|
|
8
|
-
* resolveScenario(forkall, { app, eventPath, ... })
|
|
9
|
-
* 完整示例见 demos/consumer-app。
|
|
10
|
-
*/
|
|
11
2
|
export declare const groups: Groups;
|
|
12
3
|
export declare const defaultGroupOrder: string[];
|
|
13
4
|
export declare const options: ({
|
|
@@ -30,10 +21,11 @@ interface ForkallOptions {
|
|
|
30
21
|
mode?: string;
|
|
31
22
|
outputDir?: string;
|
|
32
23
|
traceFormatProfile?: string;
|
|
24
|
+
skipPerfDedupe?: boolean;
|
|
25
|
+
dropFailedSamples?: boolean;
|
|
26
|
+
dryRun?: boolean;
|
|
33
27
|
}
|
|
34
|
-
/**
|
|
35
|
-
* 将 CLI 解析出来的参数应用到 forkall 场景,动态生成各阶段命令。
|
|
36
|
-
*/
|
|
28
|
+
/** 按 CLI 结果生成 reboot/monitor/collect/analysis 各阶段命令表 */
|
|
37
29
|
export declare function applyOptions(ctx: {
|
|
38
30
|
groups: Groups;
|
|
39
31
|
defaultGroupOrder: string[];
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"forkall.d.ts","sourceRoot":"","sources":["../../commands/forkall.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA8B,MAAM,EAAE,MAAM,iBAAiB,CAAC;
|
|
1
|
+
{"version":3,"file":"forkall.d.ts","sourceRoot":"","sources":["../../commands/forkall.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAA8B,MAAM,EAAE,MAAM,iBAAiB,CAAC;AAkB1E,eAAO,MAAM,MAAM,EAAE,MAAW,CAAC;AAEjC,eAAO,MAAM,iBAAiB,EAAE,MAAM,EAKrC,CAAC;AAEF,eAAO,MAAM,OAAO;;;;;;;;IAmDnB,CAAC;AAEF,UAAU,cAAc;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAkJD,wDAAwD;AACxD,wBAAgB,YAAY,CAAC,GAAG,EAAE;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,OAAO,EAAE,cAAc,CAAC;CACzB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,EAAE,CAAA;CAAE,CAqHlD"}
|