测试 - BlockX 文档

BlockX 把测试按”保护哪一层真相”分开：core 单测保护状态机，adapter 测试保护协议映射，process E2E 保护单个进程的对外 contract，contract / system E2E 保护组件之间的边界，perf 单独保护吞吐与时延。这一页只讲怎么跑、在哪、要什么；环境搭建见本地开发环境。

测试分层总览

除 e2e/perf 外，所有层都被 go test ./... 覆盖；需要 Python executor 的层在 venv 缺失时会 t.Skip 而不是失败（internal/testutil/python.go 的 RequirePythonModules）。

层	位置	命令	耗时量级	前置条件	`-short`
Go 单元测试（core / adapter / app）	`internal/*/_test.go`（约 190 个文件）、`api/*/_test.go`	`go test ./internal/... ./api/...`	秒到分钟	无外部依赖	只有 `internal/sdk/noderpc`、`internal/obs` 各一处检查
Worker process E2E	`cmd/worker/worker_process_*_test.go`	`go test -v -timeout 300s ./cmd/worker/...`	CI 拆 8 个 shard，每个测试 90s	`uv sync --project python`；要求能 `import greenlet, blockx_sdk, blockx_executor, blockdb, blockx, leafage, chaintable`	只跳过 `TestWorkerProcess_ConcurrentWorkers_And_Executors` 与 task_finished 场景归档
Bundle worker 启动冒烟	`cmd/bundle_worker/bundle_worker_process_test.go`	`go test -v -timeout 120s ./cmd/bundle_worker/...`	分钟内	同上	不跳过
Coordinator process	`cmd/coordinator/coordinator_process_lifecycle_test.go`、`cmd/bundle_coordinator/bundle_coordinator_process_test.go`	`go test ./cmd/coordinator/... ./cmd/bundle_coordinator/...`	秒级	内嵌 etcd，不需要 Python	不跳过
Sync-invoker E2E	`cmd/syncinvoker/syncinvoker_process_test.go`（23 个 `TestSyncInvoker_E2E_*`）、`syncinvoker_perf_test.go`	`go test -v -timeout 300s ./cmd/syncinvoker/...`；`make test` 逐文件跑，每文件 `3m`	分钟级	venv（`greenlet, blockx_sdk, blockx_executor`）	不跳过；perf 用例由 `SYNC_PERF_N` 控制规模（默认 200）
Contract E2E	`e2e/contract/coordinator-etcd/`、`e2e/contract/coordinator-worker/`	`go test -v -timeout 300s ./e2e/contract/...`	分钟级	venv + 内嵌 etcd；CI 先 `go build ./cmd/worker ./cmd/coordinator` 暖缓存	不跳过
System E2E	`e2e/system/{smoke,routing,recovery,logical_type}/`	`go test -v -timeout 600s ./e2e/system/...`；快入口 `go test ./e2e/system/smoke/...`	分钟级	venv + 内嵌 etcd；`logical_type` 可用 `TEST_BLOCKDB_*_ADDR` 切到真实 BlockDB	不跳过
Perf	`e2e/perf/`、`cmd/perf`（打线上环境的 CLI）	`./test.sh` 或 `BLOCKX_RUN_PERF=1 go test -v -timeout 600s ./e2e/perf/...`	十分钟级	venv、`sudo`（cgroup）；见下文	`TestMain` 在 `-short` 下整包跳过，`BLOCKX_RUN_PERF_SHORT=1` 可覆盖
Python 单测	`python/tests/test_*.py`（43 个文件，无子目录）	`PYTHONPATH=python uv run --project python python -m unittest discover -s python/tests`	秒到分钟	`uv sync --project python`	不适用

几点补充：

make test 给所有包加了 -short，但除 perf 外没有一层因此被跳过，所以 make test 就是全量 E2E。
cmd/syncinvoker 被 Makefile 从 FAST_TEST_PACKAGES 中剔除后逐文件跑：每个测试都起独立进程 + Python executor，perf 用例又不受 -short 保护，整包一起跑会超出预算；逐文件跑让 SYNCINVOKER_TEST_TIMEOUT 成为每个文件的预算，并分别产出覆盖率再合并。
单个模块的 -run 过滤示例：go test ./internal/worker/core/ -run TestWorkerCore_RequestTaskSlot。
Python 单个模块：PYTHONPATH=python uv run --project python python -m unittest python.tests.test_executor_protocol_contract。

日常迭代
提交前
只跑某一层 E2E

go fmt ./... && go vet ./...
go test ./internal/... ./api/...
PYTHONPATH=python uv run --project python python -m unittest discover -s python/tests

uv sync --project python
make test                     # fmt + vet + 全量（含 E2E，syncinvoker 逐文件）

go test -v -timeout 300s ./cmd/worker/... -run TestWorkerProcess_RequestSlotAndSubmit
go test -v -timeout 300s ./e2e/contract/coordinator-worker/...
go test -v -timeout 600s ./e2e/system/smoke/...

测试组织约定

三份文件定义了怎么放、怎么命名：

blockx 仓库 docs/specs/worker-test-organization.md：适用于 internal/worker/** 与 cmd/worker/、cmd/bundle_worker/。三个层级：core unit（只测 Sans-IO 核心，禁止引入 HTTP、进程或 Python）、adapter integration（handler / subscriber / orchestrator / executor pool，允许 fake 与 stub）、process e2e（真实 cmd/worker 进程，只放在 cmd/<entrypoint>/）。文件名表达实现边界：worker_test.go、dispatcher_retry_test.go、handler_protocol_test.go、worker_process_<slice>_test.go；禁止 misc_test.go、e2e_test.go 这类弱语义名。顶层函数 Test<Boundary>_<Theme>，t.Run 名必须写”场景 + 预期结果”。拆分阈值：一个文件超过 3 个逻辑块、一个顶层测试超过 8 个 t.Run、一个 process E2E 文件超过 6 个独立 contract。
blockx 仓库 docs/specs/python-test-organization.md：python/tests/ 一个文件一个实现边界，test_<boundary>.py；TestCase 名 <Boundary><Theme>Test；方法名”场景 + 预期结果”，例如 test_deadline_after_resume_prevents_followup_waiting。
blockx 仓库 docs/specs/system-e2e-testing.md：contract 文件叫 contract_<behavior>_test.go、函数 TestContractE2E_<Boundary>_<Behavior>；system 文件叫 system_<behavior>_test.go、函数 TestSystemE2E_<Behavior>；一个 system 文件只放一个场景族。拿不准放哪层时默认放 contract 层。

AGENTS.md 的测试指南补充四条：Go 测试与实现放同目录的 *_test.go；状态机、协议映射、core/adapter 边界优先用表驱动；新行为要同时覆盖 happy path 与 spec 里的失败 / 超时路径；改了协议或生命周期语义就在同一个变更里更新对应 spec。

不同层断言不同真相：core 单测断状态迁移、幂等、命令输出、TTL 与结果收敛；adapter 测试断协议映射与错误翻译；process E2E 只断外部可观察行为（gRPC 返回、终态、日志字段）。不要在 E2E 里穷举 DispatcherCore 的 retry 矩阵，也不要用进程测试替代 handler 的错误映射断言。

测试工具与替身

位置	内容
`internal/testutil/etcd.go`	`StartEmbeddedEtcd` / `StartEmbeddedEtcdAt`：用 `go.etcd.io/etcd/server/v3/embed` 在测试进程内起 etcd，`t.Cleanup` 回收；`WaitForWorkerHeartbeat`、`WaitForWorkerHeartbeatGone` 观察注册
`internal/testutil/worker.go`、`coordinator.go`	`StartWorker` / `StartWorkerAt`、`StartCoordinator` / `StartBundleCoordinator`：编译并启动真实进程，注入最小环境变量，等 readiness。`BlockWorkerBlockDBEnv` 补 `BLOCKDB_BATCH_WRITE_ADDR` 与 `STUB_BLOCKDB_DELAY_MS=0`
`internal/testutil/process.go`	`Process`：停止、日志、`RSSKB` / `VmPeakKB`、`KillOneChildPython`（故障注入）
`internal/testutil/paths.go`	`BuildBinary`（每个测试进程只编译一次并缓存）、`FreeAddr`、`RunTestMain`（跑完清理二进制）、`pythonBin()` 探测 venv
`internal/testutil/python.go`	`RequirePythonModules`：探测失败 `t.Skip`，结果按解释器缓存
`internal/testutil/rpc.go`、`rpc_types.go`	`RequestTaskSlot`、`SubmitTask`、`PollUntilTerminal`、`GRPCCoordClient` / `GRPCWorkerClient`，以及 gRPC code 到业务错误码的反查
`internal/testutil/blockdb.go`	`StartMockFunctionBlockDB`：进程内 gRPC 假 BlockDB，只实现 `GetRow` / `BatchGetRows` / `FilterRows` / `Scan`，用于 function code 读取
`internal/testutil/sandbox_e2e.go`	`RequireExecutorSandboxE2E`：containerd 沙箱 E2E 的前置检查（`ctr`、镜像、snapshotter），不满足即跳过。相关测试带 `//go:build sandbox_e2e`，默认不编译
`internal/worker/devstub/`	dev / e2e 用的可插拔 stub：`StubBackendAdapter`、`DelayedBackendAdapter`（IO 后端）、`StaticCallBuilder` / `PayloadCallBuilder`（Builder）、`LogWriterPlugin` / `TestWriterPlugin`（Plugin）、`MemoryFunctionCodeStore`（function code）、`NoopEpochResolver` / `FailingEpochResolver`。只被 `cmd/worker` 与 `cmd/syncinvoker` 的 profile 注册，bundle 入口不注册
`cmd/blockdb_grpc_stub/`	独立的 BlockDB gRPC stub 进程（`-listen`、`-read-delay`、`-probe-address` 等 flag），benchmark 用；不含 Scan / Subscribe
`internal/sdk/localtestservice/`	示范能力后端：`Service` + `Adapter`，worker 默认注册；`LOCAL_TEST_SERVICE_DISABLED=true` 关闭。`cmd/worker/worker_process_localtestservice_test.go` 覆盖它
`examples/local_test_service/`	用 blockx-py 打本地 worker 的示例（`local_proxy.py` + `submit.py`），不是自动化测试

testutil 没有 fake clock。core 的方法显式接收 now（例如 WorkerCore.HandleRequestTaskSlot(taskID string, ttlMs int64, now int64)），core 单测直接传时间值即可。

CI

.github/workflows/test.yml 在 PR 到 dev、push 到 dev 与手动触发时运行；除 Deploy Script Tests 外的 job 都通过 GitHub App token 配置 github.com/Chaintable/* 私有模块访问：

Job	内容
`Deploy Script Tests`	`bash deploy/tests/*.sh`：worker / syncinvoker 的 entrypoint、profile、env resolver、reconcile、health、deploy bundle 脚本测试
`Go Tests`	`go test ./internal/... ./api/... ./cmd/...`。这个 job 不装 Python 依赖，`cmd/*` 下依赖 executor 的 process E2E 在 `RequirePythonModules` 探测失败时跳过；coordinator process 测试与各 `profile_test.go` 正常执行
`Python Tests`	`uv sync` 后 `uv run python -m unittest discover -s tests`（`working-directory: python`）
`Worker Process E2E (1/8 … 8/8)`	`bash .github/scripts/run-go-test-shard.sh ./cmd/worker <index> 8 90s`：编译测试二进制，按测试名 `cksum` 分 8 片，逐个测试跑，每个 90s
`Bundle Worker Process E2E`	`go test -v -timeout 120s ./cmd/bundle_worker/...`
`Contract E2E`	`go build ./cmd/worker ./cmd/coordinator && go test -v -timeout 300s ./e2e/contract/...`
`System E2E`	`go test -v -timeout 600s ./e2e/system/...`
`Perf E2E`	`go test -v -short -timeout 900s ./e2e/perf/...`，带 `PERF_N=8 PERF_C=2 PERF_EXECUTOR_COUNT=2 PERF_SLO_MULTIPLIER=5`

.github/workflows/build.yml 只在推 tag 时构建并推送镜像，不跑测试。

性能测试

e2e/perf 每个用例自起 etcd + coordinator + worker，用 PERF_* 环境变量控制规模，checkSLO 用 PERF_SLO_MULTIPLIER 放大后的阈值断言时延，阈值来源见 docs/specs/perf-methodology.md。整包由 e2e/perf/short_test.go 的 TestMain 门控：BLOCKX_RUN_PERF 不为 1 时直接返回，一个用例都不跑。

# 标准入口：在 cgroup（默认 CPUQuota=400%、MemoryMax=8G、禁 swap）内跑，需要 sudo
./test.sh
./test.sh -run TestPerf_SchedulerConcurrency
PERF_CPU=200% PERF_MEM=4G ./test.sh

# 不限资源直接跑（结果偏乐观）；必须显式打开门控
BLOCKX_RUN_PERF=1 go test -v -timeout 600s ./e2e/perf/...
BLOCKX_RUN_PERF=1 PERF_N=10 PERF_IO_READS=3 go test -v -timeout 300s -run TestPerf_CacheLocality ./e2e/perf/...

主要变量：PERF_N（每场景 task 数，默认 20）、PERF_C（并发，默认 4）、PERF_EXECUTOR_COUNT（默认 4）、PERF_IO_READS（默认 5）、PERF_SLO_MULTIPLIER（默认 1.0，CI 用 5）。test.sh 自身读 PERF_CPU、PERF_MEM、PERF_TIMEOUT，并透传 WORKER_CPU_PROFILE、WORKER_TRACE、COORDINATOR_CPU_PROFILE、COORDINATOR_TRACE。
文件按 docs/specs/perf-methodology.md §3 的 Stage 命名：s0_framework_*、s1_builder_*、s2_call_count_*、s3_cpu_*、s4_io_*、s5_plugin_*；phase_*、m3_stream_build_test.go、calibration_test.go 是规范之前的遗留文件。helpers_test.go 放 runScenario / startPerfInfra* / checkSLO 等脚手架。
产物落 e2e/perf/_artifacts/（已 gitignore）：<TestName>_<subtest>/spans.jsonl（with_trace 子测试的 OTel span，开关 BLOCKX_OTEL_SPAN_FILE + BLOCKX_OTEL_UDS_EVENTS=1）、<TestName>/*.pb.gz（pprof）、pyspy/。
离线分析 span：python3 analyze_spans.py e2e/perf/_artifacts/<TestName>_with_trace/spans.jsonl。脚本在仓库根，只接受一个位置参数，默认 /tmp/blockx_spans.jsonl。
报告：docs/specs/perf-test-report.md（v1 主报告）、perf-test-report-appendix.md（v1 附录）、perf-test-report-v2.md（当前唯一基线，cgroup 12 vCPU / 32G）、perf-capability-backend-report.md（能力后端框架税）。复现步骤在 docs/specs/perf-test-how-to-v2.md，方法论在 docs/specs/perf-methodology.md。
cmd/perf 是打已部署环境的负载 CLI（-coordinator、-n、-c、-mode），不属于 go test。cmd/bundle-loadgen 是 bundle 集群的负载生成器，自带纯单测。

开始使用

架构

组件

开发指南

测试

测试分层总览

测试组织约定

测试工具与替身

CI

性能测试

相关文档

​测试分层总览

​测试组织约定

​测试工具与替身

​CI

​性能测试

​相关文档

测试分层总览

测试组织约定

测试工具与替身

CI

性能测试

相关文档