rustunnel/droid-wiki/how-to-contribute/testing.md

Testing

Test organization

All tests are inline #[cfg(test)] modules at the bottom of each source file. There are no standalone test files or integration test directories.

Running tests

cargo test --all-targets

This runs unit tests and doc tests across all modules.

Test patterns

Credential generation tests

Tests in src/generate.rs verify that generate() creates all expected files, that certificates contain valid PEM blocks, that private keys are detected as sensitive by the redaction module, and that config JSON is valid.

Framing tests

Tests in src/framing.rs cover:

• Frame roundtrips for all frame types (CONNECT, CONNECT_REPLY, DATA, CLOSE, ERROR)
• Partial read handling — buffers must not be consumed until a complete frame is available
• Multiple frames in one buffer
• Target address encoding/decoding for IPv4 and domain names

SOCKS5 tests

Tests in src/socks5.rs cover:

• Greeting parsing (no-auth, username/password, invalid versions)
• Auth request parsing (valid and empty credentials)
• CONNECT request parsing (IPv4, domain, unsupported commands)
• Reply building
• Target resolution (IPv4 direct, domain DNS lookup)
• Malformed input handling

TLS tests

Tests in src/tls.rs cover:

• Loading certificates and keys from files and PEM strings
• Building valid server and client configs
• Identity validation against SANs and CN
• Certificate fingerprinting
• Expiration checking
• Insecure config variants

Tunnel tests

Tests in src/tunnel.rs are the most extensive. They include:

• Auth tests: valid mTLS + auth, invalid token, missing client cert
• E2E tests: basic forwarding, server-side SOCKS5 reaching connector-side targets, concurrent stream isolation, target failure handling, listener-side target origin verification
• Operational tests: reconnect restoring traffic after tunnel drop, graceful shutdown of listener and connector, shutdown during active streams
• Log tests: verify effective config is logged with redacted tokens, verify auth failures don't leak token values in error messages

E2E test structure

Typical E2E tests follow this pattern:

1. Generate test credentials with generate_test_creds().
2. Pick a free port with get_free_port().
3. Spawn the listener as a tokio task.
4. Spawn the connector (and optionally a target server) as tokio tasks.
5. Sleep briefly to let services start.
6. Connect via SOCKS5, send data, verify response.
7. Abort all tasks in cleanup.

CI test matrix

Tests run on ubuntu-latest, windows-latest, and macos-latest.