配置 Synthetics 项目

Elastic Stack Serverless

Synthetic 测试支持配置可用于 Synthetics 项目的动态参数。此外，Synthetics 代理是基于 Playwright 构建的，支持配置 Playwright 特定方法中可用的浏览器和上下文选项，例如 ignoreHTTPSErrors、extraHTTPHeaders 和 viewport。

在 Synthetics 项目的根目录中创建一个 synthetics.config.js 或 synthetics.config.ts 文件，并指定选项。例如：

Elastic Stack

		import type { SyntheticsConfig } from '@elastic/synthetics';

export default env => {
  const config: SyntheticsConfig = {
    params: {
      url: 'https://elastic.ac.cn',
    },
    playwrightOptions: {
      ignoreHTTPSErrors: false,
    },
    /**
     * Configure global monitor settings
     */
    monitor: {
      schedule: 10,
      locations: [ 'us_east' ],
    },
    /**
     * Project monitors settings
     */
    project: {
      id: 'my-project',
      url: 'https://abc123',
      space: 'custom-space',
    },
  };
  if (env !== 'development') {
    /**
     * Override configuration specific to environment
     * For example, config.params.url = ""
     */
  }
  return config;
};

	

Serverless

		import type { SyntheticsConfig } from '@elastic/synthetics';

export default env => {
  const config: SyntheticsConfig = {
    params: {
      url: 'https://elastic.ac.cn',
    },
    playwrightOptions: {
      ignoreHTTPSErrors: false,
    },
    /**
     * Configure global monitor settings
     */
    monitor: {
      schedule: 10,
      locations: [ 'us_east' ],
    },
    /**
     * Synthetic project monitors settings
     */
    project: {
      id: 'my-synthetics-project',
      url: 'https://abc123',
    },
  };
  if (env !== 'development') {
  /**
   * Override configuration specific to environment
   * For example, config.params.url = ""
   */
  }
  return config;
};

	

注意

上面示例中的 env 是您从中推送的环境，而不是监视器将运行的环境。换句话说，env 对应于配置的 NODE_ENV。

配置文件可以导出对象，也可以导出函数，调用该函数应返回生成的配置。要了解更多关于基于环境配置测试的信息，请查看动态配置文档。

`参数 (params)`

一个 JSON 对象，定义您的测试需要的任何变量。请阅读使用参数和密钥以获取更多信息。

`Playwright 选项 (playwrightOptions)`

对于所有可用选项，请参阅 Playwright 文档。

注意

当通过 Elastic 的全局托管测试基础设施或私有位置运行时，请勿尝试在 headful 模式下运行（使用 headless:false），因为不支持此模式。

以下是关于一些与 Elastic Synthetics 特别相关的 Playwright 选项的详细信息，包括 TLS 客户端身份验证、超时、时区和设备模拟。

TLS 客户端身份验证

要启用 TLS 客户端身份验证，请在配置文件中设置 clientCertificates 选项

注意

基于路径的选项 {certPath, keyPath, pfxPath} 仅在私有位置上受支持，在 Elastic 托管的位置上运行时，请改用内存中的替代方案 {cert, key, pfx}。

		playwrightOptions: {
  clientCertificates: [
    {
      origin: 'https://example.com',
      certPath: './cert.pem',
      keyPath: './key.pem',
      passphrase: 'mysecretpassword',
    },
    {
      origin: 'https://example.com',
      cert: Buffer.from("-----BEGIN CERTIFICATE-----\n..."),
      key: Buffer.from("-----BEGIN RSA PRIVATE KEY-----\n..."),
      passphrase: 'mysecretpassword',
    }
  ],
}

	

提示

当使用 Synthetics 监视器 UI 时，可以使用字符串文字简单地指定 cert、key 和 pfx

		clientCertificates: [
  {
    cert: "-----BEGIN CERTIFICATE-----\n...",
    // Not cert: Buffer.from("-----BEGIN CERTIFICATE-----\n..."),
  }
],

	

超时

Playwright 有两种类型的超时，用于 Elastic Synthetics：操作和导航超时。

Elastic Synthetics 使用默认的操作和导航超时时间为 50 秒。您可以使用 actionTimeout 和 navigationTimeout 在 playwrightOptions 中覆盖此默认值。

时区和区域设置

Elastic 全局托管测试基础设施当前未设置时区。对于私有位置，监视器将使用运行 Elastic Agent 的主机的时区。如果您想测试 Web 应用程序在不同时区中的行为，这并不总是理想的。要指定监视器运行时要使用的时区，您可以在每个监视器或全局范围内使用 playwrightOptions。

要为 Synthetics 项目中的所有监视器使用时区和/或区域设置，请在配置文件中设置 locale 和/或 timezoneId

		playwrightOptions: {
  locale: 'en-AU',
  timezoneId: 'Australia/Brisbane',
}

	

要为特定监视器使用时区和/或区域设置，请使用 monitor.use 将这些选项添加到旅程中。

设备模拟

用户可以使用配置文件来模拟移动设备。以下示例配置以 "Pixel 5" 模拟模式运行测试。

		import { SyntheticsConfig } from "@elastic/synthetics"
import { devices } from "playwright-chromium"

const config: SyntheticsConfig = {
  playwrightOptions: {
    ...devices['Pixel 5']
  }
}

export default config;

	

`项目 (project)`

关于 Synthetics 项目的信息。

id (string)

与您的 Synthetics 项目关联的唯一 ID。它将用于逻辑上对监视器进行分组。

如果您使用 init 来创建 Synthetics 项目，则这是您指定的 <synthetics-project-名称>。

url (string)

Serverless Observability 项目的 URL 或要将监视器上传到的部署的 Kibana URL。

space (string)

对于 9.0 或更高版本的 Kibana 部署，目标 Kibana 空间的标识符，用于推送的监视器。空间可帮助您组织推送的监视器。如果未指定，则推送到“default”空间。

`监视器 (monitor)`

在使用 @elastic/synthetics push 命令时，要应用于所有监视器的默认值。

id (string)

此监视器的唯一标识符。

name (string)

监视器的人工可读名称。

tags (Array<string>)

将与监视器事件一起发送的标签列表。标签显示在 Synthetics UI 中，允许您按标签搜索监视器。

schedule (number)

监视器应运行的间隔（以分钟为单位）。

enabled (boolean)

启用或禁用监视器的运行，而无需删除和重新创建它。

locations (Array<SyntheticsLocationsType>)

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

要列出可用位置，您可以

运行 elastic-synthetics locations 命令。
在全局搜索字段中找到 Synthetics，然后单击 创建监视器。位置将列在位置中。

privateLocations (Array<string>)

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

要列出可用的私有位置，您可以

运行 elastic-synthetics locations 命令，并提供 Observability 项目的 URL 或 Kibana URL，以便从中获取可用位置。
在全局搜索字段中找到 Synthetics，然后单击 创建监视器。私有位置将列在位置中。

throttling (boolean | ThrottlingOptions)

控制监视器的下载速度、上传速度和延迟，以模拟您的应用程序在较慢或较慢的网络上的行为。设置为 false 以完全禁用限制。

screenshot (ScreenshotOptions)

控制是否捕获屏幕截图。选项包括 'on'、'off' 或 'only-on-failure'。

alert.status.enabled (boolean)

启用或禁用监控状态警报。有关警报的更多信息，请参阅警报。

retestOnFailure (boolean)

启用或禁用监控失败时的重新测试。默认为true。

默认情况下，如果监控从“正常”变为“异常”，则会自动重新测试监控。如果重新测试的结果也为“异常”，将创建一个错误，并且如果已配置，则会发送警报。然后，监控将根据定义的计划恢复运行。

使用retestOnFailure可以减少与瞬时问题相关的噪音。

fields (object)

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

例如

		fields: {
  foo: 'bar',
  team: 'synthetics',
}

	

有关单独配置监控器的信息，请参阅

配置单个浏览器监控器，用于浏览器监控器
配置轻量级监控器，用于轻量级监控器