Skip to content

Development and Testing

develicit edited this page Nov 16, 2026 · 2 revisions

Development and Testing

Build and run

Rust 1.95 is the minimum supported version. The repository selects the stable toolchain, so the installed stable compiler must also meet that requirement. Run these commands from the repository root:

cargo build --workspace --locked
cargo run -p clipsync-cli -- --help
cargo run -p clipsync-desktop

Linux desktop and clipboard builds require GTK, Wayland, X11, and font development libraries. See the testing guide and CI configuration for package installation and headless execution.

Build native mobile applications in their separate repositories. UniFFI 0.32.2 generated bindings and native libraries must come from matching core sources. The mobile development guide describes the integration.

Local checks

cargo fmt --all -- --check
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo test --workspace --locked -- --test-threads=1
python3 -m unittest discover -s scripts/tests
python3 scripts/check-regressions.py --verify-tests

For headless Linux testing, install the required packages and prefix the Rust test command with xvfb-run -a. Ordinary local tests use private pasteboards or isolated adapters. CLIPSYNC_TEST_HOST_CLIPBOARD=1 and CLIPSYNC_TEST_DISPOSABLE_HOST=1 enable real host clipboard and foreground command paths for disposable CI sessions; do not set them as defaults in a personal workspace.

Use the following tool to reproduce concurrent pairing and relay E2E load. It runs three copies of the complete E2E test binary under one overall deadline and retains a report and logs:

python3 scripts/test-pairing-concurrency.py

Validation layers

Check Boundary exercised
Three-OS workspace CI Rust behavior active on each platform, including OS-specific service and clipboard paths
MSRV check Build compatibility with Rust 1.95
Contract and regression tests Serialization/cryptographic vectors, credential migrations, path and protocol errors
Product coverage Product-source line, region, and branch execution on Linux and macOS
Fuzzing and AddressSanitizer Malformed inputs and memory problems in reached protocol, AEAD, and native paths
Dependency checks Vulnerabilities and maintenance status, vendor provenance, patch scope, and upstream tests
Reproducible builds and release verification Build reconstruction, checksums, signatures, and provenance evidence
CodeQL and Scorecard Code analysis and repository supply-chain/operational settings

Successful compilation alone does not validate a real GUI or mobile device. Windows-specific paths, Swift/Kotlin apps, and OS/external native libraries are outside the Linux/macOS Rust coverage measurements.

Coverage requirements

Current CI requires at least 90% product line and region coverage and 85% branch coverage in each Linux and macOS measurement. All 12 product crates are included; desktop and mobile Rust sources remain in the denominator. Only inline test code is excluded during nightly measurement, while the tests themselves still run.

Measurement uses cargo-llvm-cov 0.9.1 and nightly-2026-11-11. Nightly supplies branch instrumentation and is separate from the minimum production toolchain. Exact reproduction commands are in the testing and coverage reference. Compare measurements with matching tools, operating systems, active cfg paths, and denominators.

The Actions artifacts workspace-coverage-linux and workspace-coverage-macos contain HTML reports, lcov.info, summary.json, and summary.txt. Inspect missed branches and failure points before adding tests that validate the actual behavior.

Regression checks and documentation updates

When fixing a defect, add a test that reproduces the original failure condition and update docs/regressions.json and the regression audit. Defect regression coverage and product-source coverage are different measures. At the baseline commit, the regression ledger records 61/107, or 57.01%; cases that cannot be demonstrated deterministically because of runtime or timing conditions are not counted as covered.

For protocol changes, review both clients and the relay. For key/token storage changes, review legacy migrations. For dependency changes, review the root, fuzz, and vendor graphs. Update docs/interfaces.md and the relevant wiki explanations when public interfaces change.

Sources: workflows, coverage configuration, regression audit, regression ledger, and concurrency validation tool.

Clone this wiki locally