| name | e2e-develop-guide |
| description | LoongCollector E2E Testing Framework Development Guide. Use this rule when you need to understand E2E testing framework architecture, develop new test behavior functions, or extend testing capabilities. Contains detailed BDD testing framework usage, test behavior function development and registration workflows, and comprehensive reference of existing testing capabilities. Example: When adding custom test behaviors for new plugins, use this rule to understand how to write and register new test functions. Example: When developing E2E tests, use this rule to understand the e2e framework. |
LoongCollector E2E 本地开发手册
背景
E2E测试采用行为驱动开发（Behavior-Driven Development）的设计思路，通过定义一系列测试行为，并通过配置文件的方式来描述测试场景，从而实现对插件的集成测试。测试引擎会根据配置文件中的内容，正则匹配对应的函数，并解析配置文件中的参数，传递给对应的函数。从而完成自动创建测试环境、启动iLogtail、触发日志生成、验证日志内容等一系列操作，最终输出测试报告。
开发（编写配置文件）
对于每一个新的功能，您都需要在 test 不同目录下创建一个新的目录，其中包含了 feature 格式的配置文件。每个配置文件中可以包含多个测试场景，每个测试场景由一个或多个步骤组成。
-
e2e/test_cases：开源 Go 插件测试（Docker Compose 环境运行）
-
e2e_enterprise/test_cases：商业版测试（主机+K8s 环境运行，静态，不涉及环境变化）
-
e2e_enterprise/regression：商业版测试（主机+K8s 环境运行，动态，涉及环境变化）
test
e2e
...
e2e_enterprise
test_cases
input_file
case.feature
regression
test_cases
...
配置文件的基本框架如下所示：
@input
Feature: input file
Test input file
@e2e @host
Scenario: TestInputFileWithRegexSingle
Given {host} environment
Given subcribe data from {sls} with config
"""
"""
Given {regex_single} local config as below
"""
enable: true
inputs:
- Type: input_file
FilePaths:
- /tmp/ilogtail/**/regex_single.log*
processors:
- Type: processor_parse_regex_native
SourceKey: content
Regex: (\S+)\s(\w+):(\d+)\s(\S+)\s-\s\[([^]]+)]\s"(\w+)\s(\S+)\s([^"]+)"\s(\d+)\s(\d+)\s"([^"]+)"\s(.*)
Keys:
- mark
- file
- logNo
- ip
- time
- method
- url
- http
- status
- size
- userAgent
- msg
"""
When generate {100} regex logs to file {/tmp/ilogtail/regex_single.log}, with interval {100}ms
Then there is {100} logs
Then the log fields match regex single
-
Feature定义了一个测试功能，下面为这个功能的描述信息。在Feature下可以定义多个测试场景。
-
Scenario定义了一个测试场景。在Scenario下可以定义多个行为。
-
行为定义分为三类：
-
@表示一个tag，在运行测试时，会根据tag的不同，分别运行。除了自定义的tag外，测试框架定义了一些默认的tag：
现有的测试能力可以参考附录中的表格。如果现有的行为不能满足需求，可以参考后续的"如何添加新的测试行为"添加自己需要的函数。
如何添加新的测试行为
在某些情况下，需要对engine中的测试行为进行拓展，可以参考下面的添加指南。
1. 编写行为函数
如果您需要添加新的行为函数，可以在engine目录下添加一个Go函数。不同目录下的行为函数的职责有所不同：
-
cleanup：清理测试环境，其中的测试函数会默认在测试结束后执行。无需在配置文件中显式声明使用。
-
control：管控相关的行为函数，如初始化环境、添加配置等。
-
setup：初始化测试环境，并提供远程调用的相关功能。
-
trigger：数据生成相关的行为函数，如生成日志等。
-
verify：验证相关的行为函数，如验证日志数量、验证日志内容等。
每个行为函数的接口定义如下所示：
func LogCount(ctx context.Context, expect int) (context.Context, error) {
}
函数的第一个参数必须为context.Context。除此之外，后续可添加任意多个参数。函数的返回值为context.Context和error，其中context.Context为传递给下一个行为函数的参数，error为错误信息。一些需要在多个行为函数之间传递的参数，可以通过context.Context来传递。
return context.WithValue(ctx, key, value), nil
2. 注册行为函数
在test/e2e_enterprise/main_test.go中，您需要注册您的行为函数。注册函数的格式如下所示：
func scenarioInitializer(ctx *godog.ScenarioContext) {
ctx.Then(`^there is \{(\d+)\} logs$`, verify.LogCount)
}
您需要根据行为的类型，将行为函数注册到对应的位置。在Given中注册setup中的行为函数，在When中注册trigger中的行为函数，在Then中注册verify中的行为函数。control中的行为函数比较灵活，根据函数职责不同，注册到不同的类型中。
在注册时，您需要定义一个正则表达式，用于匹配配置文件中的行为。在正则表达式中，您可以使用`{}`来标识参数，这些参数将会传递给行为函数。例如：
ctx.Then(`^there is \{(\d+)\} logs$`, verify.LogCount)
能够从配置文件中匹配到there is {100} logs这样的行为，并将100作为参数传递给LogCount函数。
3. 在配置文件中使用
在 feature 配置文件中，您可以直接使用您定义的行为函数。例如：
Then there is {100} logs
在运行测试时，测试框架会根据配置文件中的行为，调用对应的行为函数，并传递参数。
附录
现有测试行为（部分）。可以参考 test/engine/steps.go 中的定义，目前支持的测试行为如下：
| 行为类型 | 模板 | 参数 | 说明 |
|---|
| Given | ^{(\S+)} environment$ | 环境类型 | 初始化远程测试环境 |
| Given | ^{(.*)} local config as below | 1. 配置名 2. 配置文件内容 | 添加本地配置 |
| Given | ^subcribe data from {(\S+)} with config | 1. 数据源 2. 配置文件内容 | 订阅数据源 |
| When | ^begin trigger | 无 | 触发日志采集，记录开始时间 |
| When | ^generate {(\d+)} regex logs, with interval {(\d+)}ms$ | 1. 生成日志数量 2. 生成日志间隔 | 生成正则文本日志（路径为/tmp/ilogtail/regex_single.log） |
| When | ^generate {(\d+)} http logs, with interval {(\d+)}ms, url: {(.)}, method: {(.)}, body: | 1. 生成日志数量 2. 生成日志间隔 3. url 4. method 5. body | 生成http日志，发送到LoongCollector input_http_server |
| Then | ^there is {(\d+)} logs$ | 日志数量 | 验证日志数量 |
| Then | ^there is at least {(\d+)} logs$ | 日志数量 | 验证日志数量 |
| Then | wait {(\d+)} seconds | 等待时间 | 等待时间 |
| When | ^execute {(\d+)} commands {(.*)} in sequence | 1.执行次数 2.执行命令 | 在数据来源机器上，执行指定次数的命令 |
| When | ^create the shell script file {(\S+)} with the following content | 1.shell文件名称（会自动添加.sh后缀）2.shell文件内容 | 创建shell文件，并赋权可执行 |
| When | delete the shell script file {(\S+)} | shell文件名称 | 删除shell文件 |
| When | execute {(\d+)} the shell script file {(\S+)} in parallel | 1.执行次数 2.执行的shell文件名称 | 执行shell脚本 |
⚠️注意：
（1）日志数量验证
对于日志数量的验证，最高为100。
| Then | ^there is {(\d+)} logs$ | 日志数量 | 验证日志数量 |
|---|
如果超过100，请用以下行为函数：
在查询的时候用count(1)，然后在结果验证的时候Then the log fields match kv。
When query through {* | select count(1) as cnt from e2e where call_name = 'execve' and arguments = 'loongcollector-e2e-test' and binary = '/usr/bin/grep'}
Then wait {10} seconds
Then there is {1} logs
Then the log fields match kv
"""
cnt: "1000"
"""
