开始 appmap-agent-js

appmap-agent-js 是 JavaScript 记录代理 应用程序 框架.

导言

appmap-agent-js 运行时从 Node.js 进程记录 AppMaps 。 记录 AppMaps 有几种策略:

1. 记录测试案例。 目前,我们支持 欢笑 财务报告和审定财务报表 摩卡岛。 。 。 .
2. 通过 http 调用网络端点来记录使用起/止控的Node.js进程. 这些由AppMap代理执行,让用户远程控制录音.
3. 记录从开始到完成的节点.js进程.

安装和设置

所需资源

支持的平台 :

• 主流 os: Linux distros, macOS, and Windows. 星洲网.
• 节点(Node.js):任何没有被淘汰的更新的主要版本 -- -- 即:16,18,和19.
• 快报.js: 4.
• git是极好的建议.
• 需要mocha QQ 8.0.0从测试案例录入 AppMaps(早期版本不支持所需的根钩).
• jest qq 25,更旧的版本也可能有用,但还没有经过测试.

请 打开新的 GitHub 票 如果您的申请不符合标准,或与代理人有任何问题.

安装

在您的 Node.js 工程文件夹中运行此命令( 在哪里) package.json 地点:

npx @appland/appmap install

您将遵循一系列安装和配置代理的步骤.

或者,可以将代理设备作为普通设备直接安装 npm 软件包数字 :

npm install --save-dev @appland/appmap-agent-js

为了使用远程录音,并查看和与录制的 AppMaps 交互,我们建议为流行代码编辑器安装 AppMap 扩展:

• VS 代码中的 AppMap 市场
• JetBrains市场中的 AppMap

配置

代理从命名的文件读取配置选项 appmap.yml。如果此文件不存在,将创建默认文件。 注意 install 命令创建合适的 appmap.yml 通过扫描工程目录来创建文件。 我们建议你们审查任何产生 appmap.yml 文档并确认您的应用程序名称和将记录的目录列表.

用于 JavaScript 源地图的项目: 向要记录的源添加路径。 例如:

name: MyApp
packages:
  - path: src/server/controllers
  - path: src/server/data
  - path: src/server/lib
  - path: src/server/models
  - path: src/server/routes

没有 JavaScript 源地图的项目: 包括构建文件夹。 例如:

name: MyApp
packages:
  - path: dist/controllers
  - path: dist/data
  - path: dist/lib
  - path: dist/models
  - path: dist/routes

如果您不确定要选择哪个选项, 请从源头开始, 并创建文件夹并优化 appmap.yml 稍后存档.

记录 AppMaps 中

一次 appmap.yml 已配置到您的项目, 您已准备好录制 AppMps .

记录测试案例 :

1. 验证测试是否在 AppMaps 记录前运行 .
2. 测试命令的前缀 npx appmap-agent-js -- 例如:

npx appmap-agent-js -- mocha 'test/**/*.ts'

npm run test 目前只支持直接引用测试框架 3个. appmap-agent-js 将运行测试。 测试完成后, AppMaps 将被存储在默认输出目录中 tmp/appmap/(mocha|jest)。 。 。 .

用远程记录记录节点.js进程:

1. 将节点命令前缀为 npx appmap-agent-js --recorder=remote --。例如:

npx appmap-agent-js --recorder=remote -- node app/main.js --param1 hello --param2=world

2. appmap-agent-js 将启动应用程序并输入其 http 堆栈。 它会听 远程记录请求 在应用程序的所有 http 端口上.
3. 启动远程记录 :
   • 在VS代码中
   • 在 JetBrains IDES 中
   • 带卷曲
4. 与您的应用程序或服务进行交互,以练习包含的代码 appmap.yml
5. 停止录音,将新的 AppMap 保存到磁盘中.

从开始到完成记录节点.js进程

1. 将节点命令前缀为 npx appmap-agent-js --recorder=process --。例如:

npx appmap-agent-js --recorder=process -- node app/main.js --arg1 val1 --arg2=val2

2. 当节点进程退出时,将存储一个 AppMap tmp/appmap/process。 。 。 .

正在查看 AppMaps

已录制的 AppMap 保存为 .appmap.json 项目文件夹中的文件(默认位置 : tmp/appmap) (中文(简体) ).

跟踪您的 IDE 文档打开记录 .appmap.json 文件 :

• 在VS代码中
• 在 JetBrains IDES 中

常用参数

使用次数最多的 appmap-agent-js 参数为:

• --recorder=[mocha|jest|remote|process]: 进程记录器
  • 从起始命令推断出默认记录器 :
    • mocha 如果命令包含 mocha
    • jest 如果命令包含 jest
    • process 在所有其他情况下
  • mocha 财务报告和审定财务报表 jest 记录器将 AppMaps 从测试大小写自动记录
  • remote 记录器必须用 http 请求手动启动并停止
  • process 从头到尾自动记录整个进程
    • 警告: AppMaps 记录在 process 录音机可能过于庞大和吵闹.
• --command="_start command_": 指定应用程序启动命令或测试启动命令的替代方法,用引号包起来
• --log-level=[debug|info|warning|error]: 默认为 info
• --log-file=_file_: 日志文件的位置, 默认为 stderr
• --appmap-dir=_directory_: 记录的 AppMap 文件的位置,默认为 tmp/appmap。 。 。 .

示例

npx appmap-agent-js --recorder=mocha --command='mocha "test/**/*.ts"' --log-level=error

今后的步骤

• appmap-agent-js 参考文件