正在加载

使用 Synthetics CLI

Elastic Stack Serverless

Elastic 使用 @elastic/synthetics Node.js 库来运行 synthetic 浏览器测试并报告测试结果。该库还提供一个 CLI，以帮助您搭建、在本地开发/运行测试以及将测试推送到 Kibana。

npx @elastic/synthetics [options] [files] [dir]

您将不需要使用大多数命令行标志。但是，有些您可能会发现有用

--match <string>
运行名称或标签与给定 glob 模式匹配的测试。
--tags Array<string>
运行具有与给定 glob 模式匹配的给定标签的测试。
--pattern <string>
用于匹配当前工作目录中的 journey 文件的 RegExp 模式。默认为 /*.journey.(ts|js)$/，它匹配以 .journey.ts 或 .journey.js 结尾的文件。
--params <jsonstring>

JSON 对象，用于定义您的测试需要的任何变量。有关更多信息，请阅读 使用参数和密钥。

传递的参数将与您的 synthetics.config.js 文件中定义的参数合并。通过 CLI 定义的参数优先。

--playwright-options <jsonstring>

JSON 对象，用于传入代理的自定义 Playwright 选项。有关相关 Playwright 选项的更多详细信息，请参阅 配置文档。

传递的选项将与您的 synthetics.config.js 文件中定义的 Playwright 选项合并。通过 CLI 定义的选项优先。

--screenshots <on|off|only-on-failure>

控制是否在每个步骤结束时捕获屏幕截图。选项包括 'on'、'off' 或 'only-on-failure'。

这也可以使用 monitor.screenshot 在配置文件中设置。通过 CLI 定义的值将优先。

-c, --config <string>
配置文件的路径。默认情况下，测试运行器在当前目录中查找 synthetics.config.(js|ts) 文件。 Synthetics 配置提供配置测试如何运行和推送到 Elastic 的选项。允许的选项在 配置文件中描述。
--reporter <json|junit|buildkite-cli|default>
json、junit、buildkite-cli 或 default 之一。使用 JUnit 或 Buildkite 报告器向 CI 系统提供易于解析的输出。
--inline
不从文件读取，而是 cat 内联脚本 journey 并通过 stdin 管道传输它们。例如，cat path/to/file.js | npx @elastic/synthetics --inline。
--no-throttling

不应用限制。

也可以使用 monitor.throttling 在配置文件中禁用限制。通过 CLI 定义的值将优先。

注意

基于浏览器的监控的网络限制已禁用。有关更多详细信息，请参阅此文档。

--no-headless

以 headful 模式运行浏览器。

这与通过运行 --playwright-options '{"headless": false}' 将 Playwright 的 headless 选项设置为 false 相同。

注意

Headful 模式应仅在本地使用，以查看浏览器并直接与 DOM 元素交互以进行测试。当通过 Elastic 的全局托管测试基础设施或私有位置运行时，请勿尝试以 headful 模式运行，因为不支持此模式。

-h, --help
显示 npx @elastic/synthetics 命令的帮助。
注意

用于筛选的 --pattern、--tags 和 --match 标志仅在本地运行 synthetic 测试或将它们推送到 Elastic 时受支持。在任何其他子命令（如 init 和 locations）中都不支持筛选。

注意

为了在本地调试 synthetic 测试，您可以设置一个环境变量 DEBUG=synthetics npx @elastic/synthetics 来捕获 Synthetics 代理日志。

使用 Elastic Synthetics 搭建一个新的 Synthetics 项目。

这将创建一个模板 Node.js 项目，其中包括 synthetics 代理、所需的依赖项、synthetics 配置文件以及示例浏览器和轻量级监控文件。可以编辑这些文件，然后将其推送到 Elastic 以创建监控。

npx @elastic/synthetics init <name-of-project>

有关模板 Synthetics 项目中包含的内容的更多信息，请阅读 创建 Synthetics 项目。

通过使用您的本地 journey 来创建监控。默认情况下，运行 push 命令将使用 synthetics.config.ts 文件中的 project 设置字段，该字段是使用 init 命令设置的。但是，您可以使用 CLI 标志覆盖这些设置。

SYNTHETICS_API_KEY=<api-key> npx @elastic/synthetics push --url <kibana-url> --id <id|name>
注意

push 命令包括交互式提示，以防止您意外删除或重复监控。您将在以下情况下看到提示

  • 您 push 一个 Synthetics 项目，该项目曾经包含一个或多个监控，但现在既不再包含先前运行的监控，也没有任何监控。选择 yes 以删除与正在推送的项目 ID 关联的监控。
  • 您 push 一个 Synthetics 项目，该项目已经使用一个 Synthetics 项目 ID 推送过，然后尝试使用不同的 ID push 它。选择 yes 以创建项目中所有监控的副本。您可以设置 DEBUG=synthetics 环境变量来捕获已删除的监控。
注意

如果 journey 包含 @elastic/synthetics 之外的外部 NPM 包，则在调用 push 命令时，这些包将与 journey 代码捆绑在一起。但是，使用外部包时存在一些限制

  • 压缩后的捆绑 journey 不应超过 1500 千字节。
  • 由于平台不一致，本机节点模块将无法按预期工作。
  • 不支持在 journey 脚本中上传文件（通过 locator.setInputFiles）。
--auth <string>

用于身份验证的 API 密钥。您还可以通过 SYNTHETICS_API_KEY 环境变量设置 API 密钥。

如果要推送到 私有位置，则必须使用在 8.4 或更高版本中生成的 API 密钥。

在 Elastic Stack 上，您必须以具有 Writer 角色中描述的权限的用户身份登录到 Kibana 才能创建 API 密钥。

在 Elastic Observability Serverless 上，您必须以具有 Editor 访问权限的用户身份登录才能创建 API 密钥。

--id <string>

与您的项目关联的唯一 ID。它将用于逻辑地对监控进行分组。

如果您使用 init 来创建一个项目，这就是您指定的 <name-of-project>。

这也可以使用 project.id 在配置文件中设置。通过 CLI 定义的值将优先。

--url <string>

您要将监控上传到的部署或 Observability Serverless 项目的 URL。

这也可以使用 project.url 在配置文件中设置。通过 CLI 定义的值将优先。

--space <string>

推送监控的目标 Kibana 空间的标识符。空间可帮助您组织推送的监控。如果未指定，则推送到“默认”空间。

这也可以使用 project.space 在配置文件中设置。通过 CLI 定义的值将优先。

--schedule <number>

监控器运行的间隔（分钟）。

也可以在配置文件中使用 monitor.schedule 进行设置。 通过 CLI 定义的值将优先。

--locations Array<SyntheticsLocationsType>

部署监控器的位置。监控器可以部署在多个位置，以便您可以检测这些位置的可用性和响应时间差异。

要列出可用位置，请参考 @elastic/synthetics locations。

也可以在配置文件中使用 配置文件中的 monitor.locations 进行设置。 通过 CLI 定义的值将优先。

--private-locations Array<string>

将监控器部署到的 私有位置。 这些私有位置是指由您托管和管理的位置，而 locations 由 Elastic 托管。 您可以使用位置的名称来指定私有位置。

要列出可用的私有位置，请参考 @elastic/synthetics locations。

也可以在配置文件中使用 配置文件中的 monitor.privateLocations 进行设置。 通过 CLI 定义的值将优先。

--fields <string>

将随每个监控器事件发送的键值对列表。 fields 将作为 labels 附加到 Elasticsearch 文档，这些标签显示在 Kibana 中 单个监控器的 概览 选项卡 中的监控器详情 面板。

示例：--fields '{ "foo": bar", "team": "synthetics" }'

也可以使用 monitor.fields 选项 在配置文件中进行设置。 通过 CLI 定义的值将优先。

--yes

push 命令包含交互式提示，以防止您意外删除或重复监控器。 如果以非交互方式运行 CLI，您可以使用 --yes 选项覆盖这些提示。 当 --yes 选项传递给 push 时

  • 如果您 push 一个以前包含一个或多个监控器但现在不再包含任何监控器的 Synthetics 项目，则将删除与正在推送的 Synthetics 项目 ID 关联的所有监控器。
  • 如果您使用一个 Synthetics 项目 ID 推送了一个 Synthetics 项目，然后尝试使用不同的 ID push 它，它将在 Synthetics 项目中创建所有监控器的副本。

Synthetics journey 可以使用一个或多个标签进行标记。 在本地运行测试或将其推送到 Elastic 时，使用标签来过滤 journey。

要向单个 journey 添加标签，请将 tags 参数添加到 journey 函数或使用 monitor.use 方法。

import {journey, monitor} from "@elastic/synthetics";

journey({name: "example journey", tags: ["env:qa"] }, ({ page }) => {
  monitor.use({
    tags: ["env:qa"]
  })
  // Add steps here
});

对于轻量级监控器，请使用 yaml 配置文件中的 tags 字段。

name: example monitor
tags:
  - env:qa

要将标签应用于所有浏览器和轻量级监控器，请使用 synthetics.config.ts 文件中的 monitor.tags 字段进行配置。

筛选监控项

运行 npx @elastic/synthetics push 命令时，您可以使用以下标志过滤推送到 Kibana 的监控器

--tags Array<string>
推送带有与 glob 模式匹配的给定标签的监控器。
--match <string>
推送名称或标签与 glob 模式匹配的监控器。
--pattern <string>
RegExp 模式，用于匹配当前工作目录中的 journey 文件。 对于浏览器监控器，默认为 /*.journey.(ts|js)$/，对于轻量级监控器，默认为 /.(yml|yaml)$/。

您可以结合使用这些技术，并使用多个配置文件，根据标签将监控器推送到不同的 Kibana 集群/空间。

npx @elastic/synthetics push --config synthetics.qa.config.ts --tags env:qa
npx @elastic/synthetics push --config synthetics.prod.config.ts --tags env:prod

列出所有可用于运行 synthetics 监控器的位置。

npx @elastic/synthetics locations --url <host> --auth <api-key>

运行 npx @elastic/synthetics locations 且不带标志，以列出 Elastic 管理的所有可用于运行 synthetics 监控器的可用全局位置。

要列出 Elastic 的全球托管基础设施和私有位置上的位置，请包括

--url <string>
Kibana 部署或 Observability Serverless 项目的 URL，用于从中获取所有可用的公共和私有位置。
--auth <string>
用于 身份验证 的 API 密钥。
注意

如果管理员禁用了您分配的角色中的 Elastic 管理位置，并且您*不*包含 --url 和 --auth，则将列出 Elastic 管理的所有全局位置。 但是，您将无法使用您的 API 密钥推送到这些位置，并且会看到错误：您没有使用 Elastic 管理的全局位置的权限。 有关更多详细信息，请参阅 故障排除文档。

在 Synthetics 中生成用于多因素身份验证 (MFA) 的基于时间的一次性密码 (TOTP)。

npx @elastic/synthetics totp <secret>
npx @elastic/synthetics totp <secret> --issuer <string> --label <string>

npx @elastic/synthetics totp <secret> --issuer <issuer> --label <label>
secret
用于生成 TOTP 的编码密钥。
--issuer <string>
与帐户关联的提供商或服务的名称。
--label <string>
帐户的标识符。 默认为 SyntheticsTOTP
© . All rights reserved.