LoongCollector E2E 测试指南

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

目录

1. 概览
2. 设计测试用例
3. 编写测试用例
4. 本地运行（docker-compose）
5. 调试
6. 已知陷阱

---

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/... 恢复。