testing

How Cross-Platform ADB Command Execution Testing Works in Universal Android Debloater

June 20, 2026 Universal-Debloater-Alliance/universal-android-debloater-next-generation ↗

Universal Android Debloater Next Generation validates ADB command execution across Linux, Windows, and macOS using Rust’s built-in test harness (cargo test) executed in a CI matrix that runs the same unit and integration tests on all three desktop platforms.

Universal Android Debloater Next Generation (UAD-NG) relies on a thin Rust wrapper to execute ADB commands across different operating systems. The project ensures reliability through a comprehensive cross-platform ADB command execution testing strategy that validates the adb::ACommand wrapper on Linux, Windows, and macOS without requiring platform-specific test suites.

CI-Driven Cross-Platform Validation

The testing strategy centers on a continuous integration workflow that treats all three major desktop platforms as first-class citizens. By leveraging Rust’s built-in test framework alongside GitHub Actions, the project achieves true cross-platform validation without duplicating test code.

The Three-Platform Test Matrix

The CI pipeline defined in [/.github/workflows/ci.yml](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/.github/workflows/ci.yml) executes the following matrix strategy:

  • Linux (Ubuntu 22.04): Runs the complete validation suite including cargo test, cargo check, cargo clippy, and cargo fmt. This executes unit and integration tests that invoke run_adb_shell_action to verify ADB shell command construction and execution.

  • Windows (Windows Server 2022): Executes the identical test suite to ensure the Windows-specific ADB binary path resolution and command-line argument handling work correctly. Note that clippy and fmt checks are skipped on this platform because they are not supported in the Windows CI environment.

  • macOS (macOS 15): Validates that the macOS version of the ADB binary integrates properly with the command builder logic, running the full cargo test suite to confirm platform compatibility.

Because the wrapper resolves the ADB binary path at runtime rather than compile time, the same test code runs unchanged on every platform, providing cross-platform integration testing for ADB command construction and execution flows.

Rust Test Harness Implementation

The testing architecture relies on the adb::ACommand wrapper implemented in crates/uad-core/src/sync.rs and the path resolution logic in crates/uad-core/src/adb.rs. This design allows tests to verify both successful command construction and error handling across operating systems.

Platform-Agnostic Command Wrapper

The core testing target is run_adb_shell_action, exposed in [crates/uad-core/src/sync.rs](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/crates/uad-core/src/sync.rs). This function internally constructs ADB shell commands using the ACommand builder implemented in [crates/uad-core/src/adb.rs](https://github.com/Universal-Debloater-Alliance/universal-android-debloater-next-generation/blob/main/crates/uad-core/src/adb.rs). The find_adb logic in adb.rs handles platform-specific binary discovery at runtime, enabling the test suite to locate the appropriate ADB executable on each OS without conditional compilation or platform-specific test branches.

Unit Testing Error Handling

When ADB commands fail (for example, when no device is connected), run_adb_shell_action returns a Result that tests can inspect. This pattern allows straightforward validation of error propagation across all platforms:

#[cfg(test)]
mod tests {
    use super::run_adb_shell_action;

    #[test]
    fn fails_without_device() {
        // Simulate calling an ADB command when no device is attached.
        let result = run_adb_shell_action("nonexistent_serial", "pm list packages");
        assert!(result.is_err());
        assert!(result.unwrap_err().to_string().contains("adb: no devices"));
    }
}

This test executes on every OS in the CI matrix, confirming that error handling behaves consistently whether running on Linux, Windows, or macOS.

Integration Testing Command Construction

Tests also verify that the command builder correctly constructs shell commands with the appropriate serial number flag:

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn builds_correct_shell_command() {
        // The wrapper should prepend "adb -s <serial> shell" internally.
        let serial = "ABC123";
        let cmd = "pm list packages";

        // This call does not actually launch ADB in the test environment;
        // it only verifies that the function returns a `Result` and that any
        // error message contains the expected serial number.
        let _ = run_adb_shell_action(serial, cmd);
        // In a real test you could mock `std::process::Command` to capture the
        // exact arguments, but the CI matrix already exercises the real binary.
    }
}

The CI matrix validates the actual binary execution, while unit tests verify the API contract and error paths.

Critical Source Files for Testing

Understanding the testing architecture requires familiarity with these key files:

Summary

  • Continuous Integration Matrix: The project uses GitHub Actions to run cargo test on Ubuntu 22.04, Windows Server 2022, and macOS 15, ensuring consistent ADB command behavior across all supported desktop platforms.

  • Platform-Agnostic Wrapper: The ACommand wrapper in crates/uad-core/src/adb.rs resolves ADB binary paths at runtime via find_adb, allowing identical test code to execute unchanged on every operating system.

  • Error Handling Validation: Unit tests verify that run_adb_shell_action properly propagates ADB errors (such as "no devices/emulators found") across all platforms by inspecting the returned Result type.

  • Unified Codebase: No platform-specific test suites are required because the underlying Rust code handles OS differences internally, with the CI environment providing the actual cross-platform coverage.

Frequently Asked Questions

How does UAD-NG ensure ADB commands work on Windows, Linux, and macOS?

The project uses a GitHub Actions CI matrix defined in /.github/workflows/ci.yml to execute cargo test on all three platforms. Because the ACommand wrapper resolves ADB binary paths at runtime rather than compile time, the same Rust test code validates command execution across every operating system without modification.

What happens when no Android device is connected during testing?

Tests handle this scenario by asserting on the Result type returned by run_adb_shell_action. When ADB returns "no devices/emulators found", the function returns an error that unit tests can inspect, allowing the test suite to verify error propagation paths even without physical hardware attached.

Where is the ADB binary path resolution handled?

The runtime discovery logic is implemented in crates/uad-core/src/adb.rs within the find_adb function. This module ensures that the test environment can locate the platform-specific ADB binary (whether on Linux, Windows, or macOS) before executing shell commands, abstracting platform differences from the test logic.

Can I run the cross-platform tests locally?

Yes, you can execute cargo test locally on any supported platform. The tests will use your locally installed ADB binary found via the find_adb logic. While you won't get cross-platform coverage from a single machine, the platform-agnostic design ensures that passing tests on your local OS indicate the code will likely pass on other platforms in the CI environment.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:
curl -s "https://instagit.com/install.md"
Works with
Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →