Tests are grouped by runtime prerequisites, not just protocol. Cargo has autotests = false: register new test targets in Cargo.toml, and add new case modules to the appropriate target's .rs file. An unreferenced file under tests/cases/ is not compiled or run.

Local Checks

Run from the repository root. Limit Rust build concurrency on small machines:

export CARGO_BUILD_JOBS=1
cargo test --workspace --locked --lib --bins
cargo test -p shoes --locked --lib --features ffi -- --test-threads=1
cargo test -p shoes --locked --test process_contract -- --test-threads=1
cargo test -p shoes --locked --test rule_allocation
cargo fmt --check
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings

Library tests cover protocol parsers and adapters, authentication, routing and configuration, resource limits, deterministic backpressure, and rootless TUN and WireGuard paths. Binary and process-contract tests cover startup, validation, signals, reload rejection, listener replacement, and cleanup. The FFI feature enables host-side service and socket-protection tests; it does not simulate an Android or iOS VPN service.

Clippy's --all-features compiles optional tests but does not execute them. Likewise, a filtered cargo test command that matches zero tests succeeds; check the reported test count when renaming modules or changing CI filters.

Integration Targets

Target	Feature	Prerequisites and scope
`integration`	`integration-tests`	Local endpoints, Shoes subprocesses, and sing-box for peer cases. Includes TCP/UDP protocols, chaining, sniffing, Fake DNS, resource lifecycle, and userspace WireGuard.
`process_contract`	None	Shoes subprocesses; Unix-only cases exercise signals and filesystem reloads.
`rule_allocation`	None	Local rule compilation and allocation limits.
`optional_peer`	`optional-peer-tests`	sing-box, Mihomo, Xray, and Naive Caddy as required by each case. Includes carrier sharing and idle reuse.
`xhttp_interop`	`integration-tests`	Local-only filters or pinned Xray and Mihomo; see XHTTP.md.
`reality_interop`	`optional-peer-tests`	Pinned Xray and local TLS camouflage endpoints.
`vless_encryption_interop`	`optional-peer-tests`	Pinned Xray, Mihomo, and sing-box; see the fixture guide.
`external_network`	`external-network-tests`	Internet access and sing-box for DNS, external REALITY, and proxy cases.
`privileged`	`privileged-tests`	Select a case explicitly. Kernel TUN needs Linux, `/dev/net/tun`, `ip`, IPv6 loopback, and passwordless sudo. Kernel WireGuard also needs `wg` and namespace tools. Native Naive cases have separate binary, libcronet, and CA prerequisites.
`stress`	`stress-tests`	Sustained traffic and benchmarks; some cases are ignored and require explicit selection.

Examples:

# Local relay contract, without an external peer binary.
cargo test --locked --features integration-tests --test integration plain_tcp_relay:: -- --test-threads=1

# The full local-protocol suite also requires sing-box.
SHOES_TEST_SING_BOX_BIN=/absolute/path/to/sing-box \
  cargo test --locked --features integration-tests --test integration -- --test-threads=1

# Includes same-name device replacement and active-flow teardown.
cargo test --locked --features privileged-tests --test privileged tun_kernel:: -- --test-threads=1

Use absolute peer paths to avoid accidentally testing a different installed version. Most fixtures accept SHOES_TEST_SING_BOX_BIN, SHOES_TEST_MIHOMO_BIN, SHOES_TEST_XRAY_BIN, or SHOES_TEST_NAIVE_CADDY_BIN. The dedicated VLESS/REALITY fixtures additionally use XRAY_BINARY and MIHOMO_BINARY; their fixture guide and workflow specify the exact pins. Requested but unavailable peers should fail, not silently skip.

CI And Remaining Gaps

The workflows run Linux unit, process, FFI, local-protocol, external-network, kernel TUN/WireGuard, and pinned-peer suites. macOS runs rootless TUN, WireGuard, process-watcher unit tests, and selected FFI/process contracts. Android and iOS jobs cross-compile the native libraries but do not exercise device VPN lifecycles. Only selected bounded stress cases run in CI; long-duration and performance tests remain explicit opt-ins.

Retain the existing suite boundaries. Prefer deterministic in-process tests for fragmentation, cancellation, credit accounting, and parser rejection; use process/kernel tests for descriptor ownership, real routing, and reload behavior. Bound network waits, assert exact payloads and EOF/error outcomes, and propagate fixture-task failures rather than accepting a timeout as proof of rejection.

Important remaining limitations:

No measured whole-project line or branch coverage is maintained by these workflows; passing suites do not establish exhaustive coverage.
Android/iOS device execution and macOS Network Extension kernel-device behavior remain separate from host-side tests and cross-compilation.
Windows build entries are disabled; ARM and musl builds do not establish runtime coverage. macOS does not run the full Linux protocol and IP-stack suite.
Global resource-budget changes across rejected and accepted reload generations need a combined process contract; separate budget and reload tests do not cover their interaction.
Graceful message-stream EOF with a permanently pending shutdown needs an explicit shutdown policy and regression. Error-path cleanup already has a deadline; changing the graceful path is not merely a test improvement. The association idle timer also lacks deterministic paused-clock coverage.
Pre-auth ClientHello negative cases, credential rejection for VLESS fallback, Hysteria2 and TUIC, and broader WebSocket length/control-frame boundaries need focused tests. Multi-record ClientHello support and extension-length handling need separate protocol review.
The legacy privileged target's tun:: cases are not selected by CI; the tun_kernel:: cases are. Native Naive and most sustained multi-GiB stress tests remain manual. Several local ShadowTLS handshake cases still live in the Internet-dependent target.
Filtered CI invocations can still select zero tests after a rename. The resource-limit and raw-descriptor subprocess tests explicitly require one passed child test, but that guard is not applied to every workflow filter.
The historical Naive/sing-box idle timeout remains unattributed. Progress diagnostics and deterministic H2 credit tests do not prove its cause.
Mihomo and sing-box early-half-close limitations retain ignored strict tests. Their enabled reply-first cases still require exact payloads and clean TLS EOF. A passing non-injected run is not proof that the timing-sensitive Mihomo issue is fixed; see the fixture guide.
Internet-dependent failures and manual native Naive prerequisites require separate investigation; they are not covered by a local-only test run.