用途：为 Kafka 生产者与消费者编写生产级集成测试，使用 testcontainers 启动临时测试 broker，端到端验证生产/消费工作流、消息顺序保证、错误场景与投递语义，而不是 mock 外部服务。
主要能力：搭建隔离的 Kafka 容器；测试生产者发布与消费者接收的往返流程；验证同一分区键下消息顺序；测试畸形消息等错误场景；验证 exactly-once 语义；提供 pytest fixture 与异步测试模式。
使用方式：安装依赖 pip install testcontainers[kafka]>=4.0.0，并需要 confluent-kafka、msgspec、pytest、pytest-asyncio 及 Docker、Python 3.11+。用 KafkaContainer 作为 fixture 启动容器，通过 get_bootstrap_server() 获取 broker 地址，生产者发布后调用 flush()，消费者用 consume(timeout=5.0) 接收并断言。运行 pytest tests/integration/ -v，可加 --cov 统计覆盖率。
适用场景：测试 Kafka 生产/消费工作流、验证消息顺序、测试 Kafka 往返、验证 exactly-once 语义。不适用于 mock Kafka 的单元测试、生产者/消费者实现本身或 schema 校验。
限制与注意：需要 Docker 运行且资源充足；容器启动后建议等待约 2 秒让 broker 就绪；消费前必须 flush 生产者，否则可能挂起；每个测试使用唯一消费者组以保证隔离；用 try/finally 或 fixture 清理资源；consume 应设置超时避免测试卡死。常见问题包括容器启动失败、消费挂起、畸形消息异常、端口冲突与间歇性失败。详细示例与排错见 examples/examples.md 与 references/reference.md。