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.

2026-06-302.2k

e2e-manual

alibaba/loongcollector

E2E Testing Standards Guide. Use this rule when you need to write or execute E2E tests, including test naming conventions, test workflows, and test behavior templates. This rule should be used for end-to-end integration testing scenarios to ensure test standardization and maintainability. Example: When writing new E2E tests, use this rule to ensure proper test format and workflow compliance.

2026-06-302.2k

name	e2e
description	LoongCollector E2E 测试全流程指南：设计、编写、运行和调试。当需要编写新 E2E 测试、运行现有测试、或排查 E2E 测试失败时使用此 skill。

LoongCollector E2E 测试指南

步骤模板见 reference.md。手动清理可选 scripts/e2e-cleanup.sh。

1 概览

基于 BDD Godog，.feature 描述场景，test/engine/steps.go 为步骤权威来源。

test/e2e/test_cases/<case_name>/case.feature
test/engine/          # setup / control / verify / cleanup

环境 tag：@e2e + @docker-compose（或 @host / @k8s）

CI：.github/workflows/e2e.yaml — 矩阵 job 每个 TEST_CASE 单独跑；镜像由 Dockerfile_edge_linux 构建后 docker load；环境变量 DOCKER_BUILDKIT=0、COMPOSE_DOCKER_CLI_BUILD=0。

测试框架（test/engine/setup/dockercompose/）：compose 侧车构建禁用 BuildKit；场景结束后先校验 agent PID 再 cleanup.All()；失败时 TryCopyCoreLogs 导出到 test/e2e/report/<case>_log/。

2 设计测试用例

编写 feature 文件前，先确定测试矩阵。按以下维度逐项评估是否需要覆盖：

2.1 场景维度清单

维度	典型场景	何时需要
基础功能	单配置、单数据类型端到端	必须
多数据类型	logs / metrics / traces 分别验证	插件支持多类型时
多配置共存	同时加载多个 pipeline 配置	涉及端口/资源竞争时
配置热加载	运行中增/删/改配置	持续运行的 input 插件
配置类型变更	从 A 类型切换到 B 类型	插件支持多协议/格式时
反压与恢复	下游不可达 → 恢复后数据不丢	flusher 插件
外部依赖失效	依赖服务重启/不可达	有外部依赖时
大数据量	高吞吐压力下不 OOM/不丢数据	性能敏感路径

2.2 设计产出

确定要覆盖的场景后，明确每个 Scenario 的：

输入：什么数据、什么格式、多少条
流经路径：input → processor → flusher 的具体插件
预期输出：在哪里验证、验证什么
外部依赖：需要什么辅助服务（OTel Collector、Kafka 等）、docker-compose.yaml 侧车

3 编写测试用例

3.1 目录结构

test/e2e/test_cases/my_feature/
├── case.feature
├── docker-compose.yaml       # 外部依赖
└── otel-collector-config.yaml  # 若使用 OTel Collector

3.2 模板（节选）

  @e2e @docker-compose
  Scenario: TestMyFeatureBasic
    Given {docker-compose} environment
    Given subcribe data from {grpc} with config
    """
    """
    Given {my-case} local config as below
    """
    enable: true
    inputs:
      - Type: input_forward
        ...
    flushers:
      - Type: flusher_grpc
        Address: "host.docker.internal:9000"
    """
    When start docker-compose {my_feature}
    Then there is at least {1} logs

3.3 强制规则

配置含 enable: true
仅使用 test/engine/steps.go 已注册步骤
wait {N} seconds 为 Then，不是 When
Scenario 名：Test${功能名}${场景描述}
持续采集插件不要用 global.ExcutionTimeout（见 §6.1）
flusher_prometheus 的 Retry.*Delay 等为 duration 类型，YAML 里勿写 "1s" 字符串（会 JSON 反序列化失败）

3.4 v1 / v2 与 flusher

配置	说明
默认 v1 + `flusher_grpc` / `flusher_http`	C++ `ProcessPipelineEventGroup` → Go 转 `LogGroup` → `ReceiveLogGroup`
`StructureType: v2` + `flusher_prometheus`	Metric 走 `ReceivePipelineEventGroup`；不能 v2 + `flusher_grpc`（未实现 FlusherV2）

4 本地运行

4.1 镜像

与 CI 一致（完整构建，慢）：

make e2edocker    # 产出 aliyun/loongcollector:0.0.1

增量更新镜像（C++/Go 改过后常用）：

# 示例：仅替换二进制与 Go 插件（路径按本机 build 输出调整）
docker create --name tmp-lc aliyun/loongcollector:0.0.1
docker cp core/build/loongcollector tmp-lc:/usr/local/loongcollector/loongcollector
docker cp output/libGoPluginBase.so tmp-lc:/usr/local/loongcollector/libGoPluginBase.so
docker commit tmp-lc aliyun/loongcollector:0.0.1
docker rm tmp-lc

4.2 运行（与 GitHub matrix 一致）

仓库根目录：

export DOCKER_BUILDKIT=0
export COMPOSE_DOCKER_CLI_BUILD=0

# 单用例（推荐，与 CI 相同）
TEST_CASE=input_static_file ./scripts/e2e.sh e2e

或直接 go test（可自定义超时）：

cd test
export DOCKER_BUILDKIT=0 COMPOSE_DOCKER_CLI_BUILD=0
TEST_CASE=input_static_file go test -v -timeout 15m \
  -run '^TestE2EOnDockerCompose$' github.com/alibaba/ilogtail/test/e2e

# 单个 Scenario
TEST_CASE=flusher_http go test -v -timeout 15m \
  -run '^TestE2EOnDockerCompose/TestFlusherHTTP$' github.com/alibaba/ilogtail/test/e2e

全量 42 场景（本地串跑，非 CI 方式）：

cd test
go test -v -timeout 90m -run '^TestE2EOnDockerCompose$' github.com/alibaba/ilogtail/test/e2e

./scripts/e2e.sh e2e 未设 TEST_CASE 时会跑 test/e2e 下全部 feature，默认 30m 超时，全量可能不够。

make e2e 等价 clean e2edocker + ./scripts/e2e.sh e2e（会完整重建镜像，很慢）。

4.3 清理

正常退出：引擎 cleanup.All() + compose ShutDown 会 down 项目并清理残留 loongcollectorC。
异常退出或端口占用：可执行 skill 附带脚本（不会删除宿主机上无关容器）：

bash skills/e2e/scripts/e2e-cleanup.sh
bash skills/e2e/scripts/e2e-cleanup.sh input_static_file

勿将 test/e2e/test_cases/**/a.log、reader_log_rotate/volume/simple.log 等跑测产物提交进仓库。

5 调试

# 框架导出的日志（compose 启动失败或场景结束时会尝试复制）
ls test/e2e/report/<TEST_CASE>_log/

# 容器内实时查看
docker ps -a --filter name=loongcollectorC
docker exec <id> cat /usr/local/loongcollector/log/loongcollector.LOG
docker exec <id> cat /usr/local/loongcollector/log/go_plugin.LOG

# 配置是否加载
docker exec <id> ls /usr/local/loongcollector/conf/continuous_pipeline_config/local/

常见失败：

现象	方向
`agent crash` / `agent PID not found`	确认已合入 test/engine After 钩子与 PID 采集修复；compose 未启动时看 When 步骤原始错误
`compose exited abnormally` + buildx	确认 `DOCKER_BUILDKIT=0`；侧车 `FROM bash` 需能 `docker pull bash`
`plugin does not implement FlusherV2`	勿对 `flusher_grpc` 单独设 `StructureType: v2`
`cannot unmarshal string ... time.Duration`	检查 flusher HTTP/Prometheus 的 Retry/Timeout 配置格式
0 条日志	`go_plugin.LOG` 中 CONFIG_LOAD_ALARM；镜像是否含 `ProcessPipelineEventGroup`

6 已知陷阱

6.1 ExcutionTimeout

不要在 input_file、input_forward 等持续插件配置里写 global.ExcutionTimeout，否则被当作 onetime 配置，易出现 unsupported input plugin。详见 .cursor/rules/project-knowledge/config-pitfalls.mdc。

6.2 default_flusher.json

report/<case>default_flusher.json 须为文件；宿主机路径不存在时 Docker 可能建成目录。BootController.Start() 会尝试自动修复。

6.3 测试数据勿污染 git

跑测会改写 a.log、volume/simple.log 等；提交前 git checkout -- test/e2e/test_cases/... 恢复。