Testing & validation

Run the current suites

All tests run inside the disposable QEMU VM through tools/vm/vm.sh. Never execute psh test binaries, account tests, or listeners on the host.

tools/vm/vm.sh start
tools/vm/vm.sh wait
tools/vm/vm.sh sync
tools/vm/vm.sh run 'make -j2 all && make test'
tools/vm/vm.sh run 'make test-sanitize'

run starts in guest /work/psh and sets PSH_TEST_VM=1. Test guards also require the disposable-guest marker and actual QEMU/KVM detection. Integration tests create temporary Linux accounts and UDP listeners inside the guest. See the VM guide for lifecycle and source-sync details.

Choose a focused check

Pass these Make targets to tools/vm/vm.sh run 'make TARGET':

Target	Coverage
`test`	Complete normal suite, including unit and integration checks
`test-unit`	Wire format, reliability, config, keys, signing, DTLS, channels, trust, sessions, broker, and sandbox
`test-install`	Staged layout, manual pages, directory overrides, permissions, and preservation of administrator state
`test-authentication`	Paired host/user authentication and adversarial real-client cases
`test-post-quantum`	Mandatory hybrid exchange, transport faults, and admission bounds
`test-terminal-flags`	Terminal modes and restoration
`test-client-standard-fds`	Missing or closed standard descriptors
`test-remote-stdin-close`	Input credit, blocked controls, stdin closure, and PTY output drainage
`test-wildcard-listeners`	IPv4/IPv6 reply sources and endpoint binding
`test-trust-concurrency`	Concurrent trust prompts, pins, and atomic updates
`test-deps`	Vendored dependency inventory and verification regressions
`test-vm-sync`	Safe source/state exclusions and preservation of guest builds
`test-sanitize`	AddressSanitizer/UndefinedBehaviorSanitizer unit suites and deterministic parser mutations

The full integration runner also covers account switching, command and PTY semantics, binary streams, exit status, migration, revocation, and reloads. The UDP proxy’s separate smoke check is available with:

tools/vm/vm.sh run 'python3 tests/integration/test_udp_proxy.py'

Preview manual pages

The pages are plain roff using standard man macros; no generation step or additional build dependency is needed. Where the guest has man, preview with:

tools/vm/vm.sh run 'man -l docs/man/psh.1'
tools/vm/vm.sh run 'man -l docs/man/pshd.8'
tools/vm/vm.sh run 'man -l docs/man/psh_config.5'

After installation, use man psh, man pshd, and man psh_config.

Evidence and limits

Keep logs in guest /work/results and copy review artifacts through the VM helper as described in the VM guide . Record the source revision, commands, environment, and limitations alongside results. A dated result applies to its identified candidate, not automatically to a later tree.

The November 2026 records retain prior results, review findings, manifests, latency/CPU/RSS measurements, and reproduction notes. They include historical psh/2 checks as well as paired psh/3 authentication. The design paper explains how those measurements were interpreted.

Sanitizers instrument project-owned C, not the vendored static crypto/YAML libraries. Unit sanitizer runs enable leak detection. Credential-dropping application sanitizer runs need leak tracing disabled because it cannot trace those processes. The deterministic mutation harness is a bounded smoke test, not a long-running coverage-guided fuzzing campaign. Guest loopback measurements provide no production performance guarantee. These checks and internal reviews do not constitute an external security audit or establish production readiness.