集成测试Integration test

用容器启动 Kafka、创建全新主题，再驱动真实的命令行程序走完「发送消息 → 消费消息」 的完整链路。

Starts Kafka in a container, creates fresh topics, then drives the real command-line program through a full produce → consume round trip.

为什么不在 moon test 里Why it is not part of moon test

它需要容器运行时和一个真实 broker，因此不属于 moon test， 只在被显式调用时运行，入口是 make itest。

It needs a container runtime and a live broker, so it is deliberately not part of moon test and only runs when asked for — through make itest.

不过 harness 里那些纯函数（命令渲染、输出解析、运行时候选列表等）有自己的白盒测试， 它们是 moon test 的一部分。所以 make ci 覆盖的是 解析逻辑，端到端链路则由 make itest 覆盖，两者互补。

The harness's pure helpers — command rendering, output parsing, the runtime candidate list — do have white-box tests, and those are part of moon test. So make ci covers the parsing logic while make itest covers the end-to-end path; the two are complementary.

运行Running it

make itest

make itest 先构建 CLI，再启动测试。想先看它到底会执行哪些命令，用 make itest-plan（等价于 --dry-run）——它不启动任何东西， 也不会碰你的容器。

make itest builds the CLI and then runs the test. To see exactly which commands it would execute, use make itest-plan (the same as --dry-run): it starts nothing and touches no container.

make itest-plan

也可以绕开 Makefile 直接运行，所有选项照常可用：

You can also bypass the Makefile; every option still applies:

moon run --target native tests/itest -- --target native --runtime docker

测试流程What a run does

按顺序执行下面这些步骤：

In order:

1. 先构建 CLI。harness 执行的是构建产物，所以先编译一次——编译错误在这里暴露，后面的计时阶段也不必为构建买单。
2. 挑一个能用的容器运行时。
3. 启动 Kafka，然后轮询 broker 直到它接受管理命令。
4. 创建两个全新主题，并等待每个分区都选出 leader。
5. 阶段一：发送一条消息，再从 earliest 读回。
6. 阶段二：让 consumer 先开始轮询，之后再发送消息。
7. 收尾：默认停止 Kafka（--keep 可保留）。
8. 打印 checks=… failures=…；有失败则以非零退出码结束。

1. Build the CLI first. The harness executes the built artifact, so it compiles once up front: a compile error surfaces here, and no timed phase then pays for a build.
2. Pick a working container runtime.
3. Start Kafka, then poll the broker until it answers admin commands.
4. Create two fresh topics and wait for every partition to elect a leader.
5. Phase 1: produce a message, then read it back from earliest.
6. Phase 2: let a consumer start polling, then produce to it.
7. Tear down: Kafka is stopped unless --keep is given.
8. Print checks=… failures=…; a non-zero exit code follows any failure.

每次运行都使用唯一的主题名与唯一的消息内容（以 @async.now() 打时间戳）， 因此上一次运行的残留数据不可能满足这一次的断言。

Every run uses unique topic names and unique payloads, stamped with @async.now(), so nothing a previous run left behind can satisfy an assertion.

两个阶段The two phases

阶段一：先发送，再从头读回Phase 1: produce, then read back from the start

这一阶段不依赖任何时序：消息先落盘，之后才去读。断言包括：

Nothing here depends on timing: the message lands first and is read afterwards. The assertions:

阶段二：消费的同时发送Phase 2: consuming while it is produced to

第二个主题在开始时是空的。consumer 先启动并开始轮询，--live-delay-ms （默认 2000 毫秒）之后再发送消息。断言是：生产者退出码 0、消费者退出码 0，并且 消费者确实收到了这条记录。

The second topic is empty when the run starts. The consumer is started first and begins polling; the message is produced after --live-delay-ms (2000 ms by default). The assertions: the producer exits 0, the consumer exits 0, and the consumer did receive that record.

因为主题是空的，赢得竞态的 consumer 会在下一次 poll 读到它，输掉竞态的会在第一次 fetch 读到它——两种顺序都满足断言。--live-delay-ms 只是让常见路径成为 真正的「实时投递」，而不是一场竞态。

Since the topic is empty, a consumer that wins the race reads the record on its next poll and one that loses it reads it on its first fetch — both orderings satisfy the assertions. --live-delay-ms merely makes the common case a genuinely live delivery rather than a race.

容器运行时怎么选How the container runtime is chosen

默认（--runtime auto）按 podman、docker 的顺序逐个探测，用 <engine> version 确认它真的能用， 而不只是装了。这样就不会选中一个装了但没跑起来的引擎，然后在后面报一个莫名其妙的错。

By default (--runtime auto) it probes podman then docker, using <engine> version to confirm the engine actually works rather than merely being installed — so it never picks an installed-but-dead engine and fails later with a confusing error.

锁定引擎后，再看它有没有 compose provider：

Once an engine is locked in, it looks for a compose provider:

1. <engine> compose version（插件形式，如 docker compose）；
2. <engine>-compose version（独立二进制，如 docker-compose）。

1. <engine> compose version — the plugin form, e.g. docker compose;
2. <engine>-compose version — the standalone binary, e.g. docker-compose.

--compose-bin 可以指定一个二进制并跳过这两个探测。两条路径分别是：

--compose-bin names a binary explicitly and skips both probes. The two paths are:

直接 run 那条路径下，镜像标签从 compose 文件里读出来（也可以用 --image 覆盖），因此两条路径不会各写一份镜像版本。启动前会先 inspect 同名容器：已经在跑就直接复用，否则先 rm -f 清掉残留 再起。

On the direct run path the image tag is read out of the compose file (--image overrides it), so the two paths cannot drift on the image version. Before starting, the container is inspected: if it is already running it is reused, otherwise a stale one is rm -fed first.

选项Options

开关Flags

取值选项Value options

默认要驱动的 CLI 二进制是 _build/native/debug/build/cmd/main/main.exe（随 --target 变化）。文件不存在时会明确报告「CLI 二进制缺失」，而不是抛出一个莫名的启动失败。

The default CLI binary is _build/native/debug/build/cmd/main/main.exe (following --target). When it is missing you get an explicit "the CLI binary is missing" failure rather than a mysterious spawn error.

常用组合Common invocations

make itest ITEST_FLAGS="--keep"       # 保留容器，便于排查
make itest ITEST_FLAGS="--dry-run"    # 只打印将要执行的命令
make itest-plan                       # 同上
make itest ITEST_RUNTIME=podman       # 改用 podman（默认 docker）

跑在已有的 Kafka 上Against a Kafka you already run

--no-container 跳过容器生命周期与建主题，因此必须自己指定一个已存在且为空 的主题：测试不会替你创建它，也不会替你清空它。这种情况下阶段二会被跳过——它需要一个空主题， 而 harness 不负责准备。

--no-container skips the container lifecycle and topic creation, so you must name an existing, empty topic: the test will not create it and will not clear it. Phase 2 is skipped in this mode — it needs an empty topic, and the harness is not the one that prepares it.

moon run --target native tests/itest -- --no-container --topic <an-existing-empty-topic>

日志怎么读Reading the log

日志把每条命令、退出码与耗时都逐条打印出来：

Every command, exit code and duration is logged as it happens:

第一次 produce 被拒是正常的The first produce being refused is normal

刚起来的 broker 会先接受管理命令、也接受建主题，但在能处理 produce 之前还有一小段窗口。 落在这个窗口里的第一次 produce 会被立即拒绝，报 moonkafka 的 ProtocolError，第二次就成功了。

A broker that has just started answers admin commands and accepts topic creation well before it can serve a produce. A produce that lands in that window fails fast with moonkafka's ProtocolError; the next one succeeds.

harness 因此对 produce 做有界重试（最多 5 次，每次间隔 1 秒），并把每一次尝试都如实 打印出来。这样启动竞态不会污染断言，同时日志里仍然看得到它发生过。

The harness therefore retries the produce a bounded number of times (5 attempts, one second apart) and logs every attempt. The startup race stays out of the assertions while remaining visible in the log.

  # moonkafka cli
  $ _build/native/debug/build/cmd/main/main.exe produce \
      itest-1757923200 itest-value-a-1757923200 itest-key-1757923200 127.0.0.1 9092
  ... exit=1 after 61ms
  ! ProtocolError: ...
  ... retrying (2/5): the previous attempt was refused
  # moonkafka cli
  $ _build/native/debug/build/cmd/main/main.exe produce \
      itest-1757923200 itest-value-a-1757923200 itest-key-1757923200 127.0.0.1 9092
  ... exit=0 in 74ms

与此同时，harness 在建完主题之后会轮询 kafka-topics.sh --describe， 直到没有分区停留在 Leader: -1，用这个把大部分竞态直接消掉，而不是靠 一段固定 sleep。

In parallel, after creating a topic the harness polls kafka-topics.sh --describe until no partition still reports Leader: -1 — removing most of that race without an arbitrary sleep.

就绪等待Readiness waits