Cover the whole transport/codec matrix in the e2e tunnel test

AGENTS.md

@@ -16,7 +16,8 @@
 - `crates/`: the Rust workspace; the root `Cargo.toml` is a virtual manifest
   - `crates/pb-mapper-cli/src/bin/pb-mapper.rs`: unified CLI entry point
   - `crates/pb-mapper-{core,auth,protocol,server,client,cli}`
-  - `crates/pb-mapper-cli/tests/`: integration tests; loads env from `tests/.env`
+  - `crates/pb-mapper-testkit/`: test support only; nothing shipped depends on it
+  - `crates/pb-mapper-cli/tests/`: integration tests; no env setup required
   - `crates/pb-mapper-cli/examples/`: runnable examples
 - `ui/`: Flutter UI; Rust bridge under `ui/native/*`
 - `docker/`, `services/`, `scripts/`: container, systemd, build/release
@@ -41,10 +42,28 @@ Notes: CI builds release artifacts on tags `vX.Y.Z` (see `.github/workflows/rele
 - Naming: modules/functions `snake_case`, types/traits `PascalCase`, consts `SCREAMING_SNAKE_CASE`
 
 ## Testing Guidelines
-- Framework: `tokio` async + integration tests under `tests/`
-- Env vars (see `tests/.env`): `PB_MAPPER_TEST_SERVER`, `LOCAL_TEST_SERVER`, `ECHO_TEST_SERVER`, `SERVER_TEST_KEY`, `SERVER_TEST_TYPE` (`TCP`/`UDP`)
-- Run ignored tests: `cargo test -- --ignored`
-- Prefer new integration tests in `tests/` with reproducible env defaults
+- Framework: `tokio` async + integration tests in `crates/pb-mapper-cli/tests/`
+- No test needs environment setup. `pb-mapper-testkit` stands up a complete
+  tunnel (`server` + `register` + `connect`), so any test file can build one
+  rather than a single file owning the harness: `TunnelHarness::start(transport,
+  need_codec)` for the common case, or `Relay` + `TunnelSpec` when a case needs
+  to issue, renew, or revoke a credential first. `test_delay.rs` covers the
+  transport/codec matrix and `temporary_credential_e2e.rs` the credential
+  lifecycle; each case picks its own loopback ports and owns its auth state
+  directory, so cases run concurrently and never collide with a live relay.
+  Prefer binding a socket and keeping it over `reserve_addr`, which has to drop
+  the socket before the real bind and so cannot rule out a race.
+- Sequence components with a readiness probe, not a sleep: poll the relay's
+  `Keys` status for a registration, and round-trip a payload through the tunnel
+  for forwarding. `Tunnel::start` does both before it returns.
+- A framed driver (`run_echo_delay`) needs a byte-transparent echo server; a
+  tagged tunnel (`TunnelSpec::echo_tag`, which is how a namespace-isolation
+  assertion avoids passing on a leak) needs the raw drivers instead.
+- Anything that sets the process credential takes
+  `pb_mapper_core::test_support::PROCESS_CREDENTIAL_TEST_LOCK` first — it is
+  process-global, and that includes indirect writers such as building a
+  `PbMapperState`.
+- Prefer new integration tests that need no external setup
 
 ## Commit & Pull Request Guidelines
 - Commits: short, imperative (e.g., "Fix localhost resolution panic", "add network perms", "change to StreamBuilder")

CLAUDE.md

@@ -52,6 +52,7 @@ pb-mapper/
 │   ├── pb-mapper-protocol/ # Message framing, v2 secure sessions, forwarding
 │   ├── pb-mapper-server/   # Central relay server, plus the task manager
 │   ├── pb-mapper-client/   # Both tunnel ends: `register` and `connect`
+│   ├── pb-mapper-testkit/  # Test support: a complete e2e tunnel, for any test file
 │   └── pb-mapper-cli/      # The `pb-mapper` binary, integration tests, examples
 ├── ui/                    # Flutter UI, talking to Rust over dart:ffi
 │   ├── lib/               # Flutter application code
@@ -132,9 +133,23 @@ loader, two CMakeLists, four xcconfigs, and the release-ui hash checks expect.
   - `server/`: `register` — publishes a local service (`mod.rs`, `stream.rs`, `error.rs`)
   - `client/`: `connect` — subscribes and listens locally, plus `status.rs`
 
+- **`pb-mapper-testkit/`**: Test support only; nothing shipped depends on it
+  - `relay.rs`: `Relay` — a live server that retains its `AuthRuntime`, so a case
+    can issue, renew, and revoke credentials without the admin wire protocol
+  - `tunnel.rs`: `TunnelSpec` / `Tunnel` / `TunnelHarness` — echo server plus
+    `register` plus `connect`, each on reserved loopback ports
+  - `echo.rs`, `traffic.rs`: Echo servers and the framed and raw traffic drivers
+  - A crate rather than `tests/common/mod.rs`: that module is compiled separately
+    into every test binary, and whatever a binary does not use is reported as
+    dead code — fatal under `-D warnings`
+
 - **`pb-mapper-cli/`**: The binary, integration tests, and examples
   - `src/bin/pb-mapper.rs`: Argument parsing and the role commands
   - `src/bin/pb-mapper/admin.rs`: The `admin` subcommand
+  - `tests/test_delay.rs`: The transport/codec matrix over the whole tunnel
+  - `tests/temporary_credential_e2e.rs`: The credential lifecycle over the whole
+    tunnel — namespace isolation, renew, expiry, revoke
+  - `tests/regression.rs`: Protocol-level cases against hand-rolled frames
 
 #### Flutter UI (`ui/`)
 - **`lib/src/views/`**: One file per zone the shell can show
@@ -346,7 +361,9 @@ part of the landing page and the setup wizard.
 - **Toolchain**: rust-toolchain.toml for reproducible builds
 - **Testing**: Unit tests live beside the code; integration tests are in
   `crates/pb-mapper-cli/tests/`, which is the crate that depends on every layer
-  they exercise
+  they exercise. The e2e scaffolding is `pb-mapper-testkit`, so a new test file
+  stands up its own full `server` + `register` + `connect` flow instead of
+  everything accumulating in one file.
 
 ### UI Development Guidelines
 - **Framework**: Flutter 3.44.9, Material 3. CI pins the same version.
@@ -406,7 +423,8 @@ docker-compose -f docker/docker-compose.yml up
 
 - **Unit Tests**: `cargo test` for Rust components
 - **Widget Tests**: `flutter test` in ui/ directory
-- **Integration Tests**: `tests/` directory contains end-to-end tests
+- **Integration Tests**: `crates/pb-mapper-cli/tests/` — end-to-end tests built
+  on `pb-mapper-testkit`
 - **Examples**: `examples/` directory provides working usage examples
 
 ### Service Deployment

Cargo.toml

@@ -24,13 +24,14 @@ pb-mapper-client = { path = "crates/pb-mapper-client" }
 pb-mapper-core = { path = "crates/pb-mapper-core" }
 pb-mapper-protocol = { path = "crates/pb-mapper-protocol" }
 pb-mapper-server = { path = "crates/pb-mapper-server" }
+# Test support only; never a dependency of a shipped crate.
+pb-mapper-testkit = { path = "crates/pb-mapper-testkit" }
 
 base64 = "0.23.1"
 better_mimalloc_rs = { version = "0.1.2", features = ["config"] }
 bytes = "1.11"
 clap = { version = "4.5", features = ["derive"] }
 dirs = "6.0.0"
-dotenvy = "0.15.7"
 hashbrown = { version = "0.17.1" }
 hickory-resolver = { version = "0.26.1" }
 kanal = { git = "https://github.com/acking-you/kanal.git", branch = "dev/pb-mapper" }

README.md

@@ -122,7 +122,7 @@ Open `http://localhost:3000` in the coffee-shop browser — traffic flows throug
 
 ## Repository layout
 
-- `crates/` — the Rust workspace (six crates; the root manifest is virtual)
+- `crates/` — the Rust workspace (six shipped crates plus a test-support one; the root manifest is virtual)
 - `ui/` — Flutter UI + native bridge
 - `docs/` — documentation and assets
 - `docker/`, `services/`, `scripts/` — deployment and tooling

README.zh-CN.md

@@ -122,7 +122,7 @@ pb-mapper connect tcp --server <public-ip>:7666 --key web --addr 127.0.0.1:3000
 
 ## 仓库结构
 
-- `crates/` — Rust workspace（六个 crate，根清单为虚拟清单）
+- `crates/` — Rust workspace（六个发布 crate 加一个测试支撑 crate，根清单为虚拟清单）
 - `ui/` — Flutter UI + 原生桥接
 - `docs/` — 文档与素材
 - `docker/`、`services/`、`scripts/` — 部署与工具

crates/pb-mapper-cli/Cargo.toml

@@ -25,7 +25,8 @@ tracing.workspace = true
 uni-stream.workspace = true
 
 [dev-dependencies]
-dotenvy.workspace = true
+pb-mapper-testkit.workspace = true
+
 rand.workspace = true
 
 [features]