加载中

系统测试指南

系统测试用于验证从您的集成服务到 Elasticsearch 的完整数据流，确保数据得到正确的采集、处理和索引。本指南介绍了如何使用 elastic-package 设置和运行系统测试。

有关系统测试的更多信息，请参阅 如何操作：为包编写系统测试

# Start the Elastic stack
elastic-package stack up -d

# Run system tests
cd packages/your-package
elastic-package test system

# Clean up
elastic-package stack down

系统测试验证：

  • 从您的服务到 Elastic Agent 的数据采集
  • 管道处理和字段映射
  • 文档索引到 Elasticsearch 数据流
  • 字段类型兼容性和映射验证
  • 集成配置和策略部署

测试框架自动执行：

  1. 部署您的集成服务 (Docker/Kubernetes/Terraform)
  2. 使用测试策略配置 Elastic Agent
  3. 收集并索引样本数据
  4. 验证文档
  5. 检查字段映射和数据类型兼容性
  6. 清理测试工件

系统测试需要两个主要组件

定义如何部署您的集成服务以进行测试。选择以下三种部署方式之一：

包级部署 (适用于所有数据流)

<package-root>/
  _dev/
    deploy/
      docker/
      k8s/
      tf/
  1. Docker Compose
  2. Kubernetes
  3. Terraform

数据流级部署 (特定于单个数据流)

<package-root>/
  data_stream/
    <data-stream>/
      _dev/
        deploy/
          docker/

通过服务部署器，您可以配置在测试期间向集成发送数据的服务。可以配置一个实时服务来运行并向集成发送数据，从而提供真实的完整系统测试。

由于通常无法运行实时服务，因此系统测试通常使用通过真实传输方式发送的模拟数据。例如，如果服务通过 UDP 提供 syslog 数据，则无需运行实时服务，而是可以通过设置一个将模拟 syslog 数据写入监听 UDP 套接字的部署来发送数据。elastic/stream 是一个可以与系统测试结合使用的工具，用于将模拟数据流式传输到多种类型的协议中。

为每个数据流定义测试场景

<package-root>/
  data_stream/
    <data-stream>/
      _dev/
        test/
          system/
            test-<scenario>-config.yml

测试用例配置定义了测试中使用的代理和集成配置，以及使用的服务部署器配置。

最常用于测试可以在容器中运行的服务。

文件结构

_dev/deploy/docker/
  docker-compose.yml
  Dockerfile (optional)
  config/ (optional)

示例 docker-compose.yml

version: '2.3'
services:
  apache:
    image: httpd:2.4
    ports:
      - "80"
    volumes:
      - ${SERVICE_LOGS_DIR}:/usr/local/apache2/logs
    environment:
      - APACHE_LOG_LEVEL=info

关键占位符

  • ${SERVICE_LOGS_DIR} - 映射到 Agent 可访问的日志目录
  • ${HOSTNAME} - 用于 Agent 配置的服务主机名

适用于测试 Kubernetes 原生集成或需要编排的情况。

先决条件

# Install kind and create cluster
wget -qO- https://raw.githubusercontent.com/elastic/elastic-package/main/scripts/kind-config.yaml | kind create cluster --config -

文件结构

_dev/deploy/k8s/
  deployment.yaml
  service.yaml
  .empty (if no YAML files needed)

示例部署

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:latest
        ports:
        - containerPort: 80

最适合云资源或复杂的基础设施测试。

文件结构

_dev/deploy/tf/
  main.tf
  variables.tf (optional)
  outputs.tf (optional)

示例 main.tf

variable "TEST_RUN_ID" {
  default = "detached"
}

provider "aws" {
  region = "us-west-2"
}

resource "aws_instance" "test_instance" {
  ami           = data.aws_ami.amazon_linux.id
  instance_type = "t3.micro"
  monitoring    = true

  tags = {
    Name = "elastic-package-test-${var.TEST_RUN_ID}"
  }
}

data "aws_ami" "amazon_linux" {
  most_recent = true
  owners      = ["amazon"]

  filter {
    name   = "name"
    values = ["amzn2-ami-hvm-*"]
  }
}

内置变量

  • TEST_RUN_ID - 用于并发测试隔离的唯一标识符

示例 test-default-config.yml

vars: ~
input: logfile
data_stream:
  vars:
    paths:
      - "{{SERVICE_LOGS_DIR}}/access.log*"
    exclude_files: [".gz$"]
  1. 使用包级默认值
  2. 如果存在多种输入类型，则进行选择

多种测试场景

# test-custom-config.yml
vars:
  username: testuser
  password: testpass
data_stream:
  vars:
    hosts: ["{{Hostname}}:{{Port}}"]
    ssl.enabled: true
    period: 30s

测试特定输入类型

# test-tcp-config.yml
input: tcp
data_stream:
  vars:
    listen_address: "0.0.0.0"
    listen_port: 8080

在测试配置中使用这些占位符

占位符 类型 描述
{{Hostname}} 字符串 服务主机名/IP
{{Port}} int 第一个暴露的端口
{{Ports}} []int 所有暴露的端口
{{SERVICE_LOGS_DIR}} 字符串 Agent 的日志目录路径
{{Logs.Folder.Agent}} 字符串 与 SERVICE_LOGS_DIR 相同

用法示例

data_stream:
  vars:
    hosts: ["{{Hostname}}:{{Port}}"]
    paths: ["{{SERVICE_LOGS_DIR}}/*.log"]
    url: "http://{{Hostname}}:{{Ports.0}}/metrics"

有关可用于定义测试用例行为的选项的完整列表，请参阅 测试用例定义。

# Start Elastic stack (one-time setup)
elastic-package stack up -d

# Verify stack is running
elastic-package stack status

运行所有数据流

cd packages/your-package
elastic-package test system

运行特定数据流

elastic-package test system --data-streams access,error

使用详细输出运行

elastic-package test system -v

在测试期间生成示例事件

elastic-package test system --generate

针对特定测试场景运行测试

elastic-package test system --data-streams access --test-config test-custom-config.yml

通常，在编写并测试通过其他类型的测试后再开发系统测试是最容易的，这样您可以将系统测试基础架构或配置可能导致的问题与集成其他部分导致的问题区分开来。

查看详细日志

elastic-package test system -v --report-format human

调试服务部署

# Check service logs
docker logs <service-container>

# For Kubernetes
kubectl logs deployment/nginx-test

# Check Agent status
elastic-package stack dump

保持服务运行 使用 --defer-cleanup 标志，可以在清理之前暂停测试用例执行，以便在测试运行后且数据从 Elasticsearch 中删除之前，检查堆栈的状态，例如索引中存在哪些数据。

elastic-package test system --defer-cleanup 10m

常见问题

  • 服务无法访问： 检查端口映射和网络配置
  • 无数据索引： 验证日志路径和文件权限
  • 字段映射错误： 检查管道配置中的字段类型
  • 测试超时： 增加等待时间或检查服务启动情况
# Clean up test artifacts
elastic-package clean

# Stop Elastic stack
elastic-package stack down
  1. 保持测试专注： 每个数据流测试对应一个服务
  2. 使用真实数据： 生成具有代表性的日志/指标样本
  3. 测试边缘情况： 包含错误条件和格式错误的数据
  4. 最小化资源使用： 使用轻量级服务镜像
  5. 记录依赖关系： 明确指定外部需求
  1. 使用描述性的测试名称： test-error-logs-config.yml 优于 test-config.yml
  2. 环境参数化： 为主机名/端口使用占位符
  3. 一切版本控制： 包含所有部署和测试文件
  4. 测试多种场景： 不同的输入类型、身份验证方法
  5. 保持配置最小化： 仅覆盖必要的变量
  1. 重用堆栈部署： 不要为每个测试重启
  2. 并行测试执行： 使用 --data-streams 测试子集

系统测试可以自动生成用于文档记录和验证的 sample_event.json 文件

# Generate samples during testing
elastic-package test system --generate

# Output location
packages/your-package/data_stream/your-stream/_dev/test/system/sample_event.json

这些文件对于以下方面很有用：

  • 文档和示例
  • 字段引用验证
  • 调试数据转换问题
  • 管道测试输入数据
© . This website operates independently and is not affiliated with or endorsed by Elasticsearch B.V. All brand names, logos, and trademarks are the property of their respective owners.