btleplug

On Android, all 28 integration tests share a single process. A Rust panic! calls abort(), which kills the entire process and stops all subsequent tests.

To prevent this, wrap JNI test functions in std::panic::catch_unwind() within tests/android/rust/src/lib.rs. This allows panics to be caught and converted into JNI java/lang/AssertionError exceptions, which the Android test runner treats as individual JUnit failures rather than process-ending crashes.

Implementation pattern:

fn run_test(env: &JNIEnv, f: impl std::future::Future<Output = ()>) {
    let result = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| {
        runtime().block_on(f);
    }));
    if let Err(panic) = result {
        let msg = if let Some(s) = panic.downcast_ref::<&str>() {
            s.to_string()
        } else if let Some(s) = panic.downcast_ref::<String>() {
            s.clone()
        } else {
            "test panicked".to_string()
        };
        env.throw_new("java/lang/AssertionError", &msg).ok();
    }
}

The btleplug integration test system validates the library's API by interacting with a real or simulated BLE peripheral. The system consists of three components:

1. Rust Integration Tests: Located in the tests/ directory, these use the btleplug API to perform scanning, connecting, and GATT operations.
2. Test Peripheral: A GATT server that implements a specific test profile. This can be:
   • Hardware: An nRF52840 DK running Zephyr firmware.
   • Software: A Python Bumble implementation running on the host OS.
3. BLE Radio: The communication medium (either physical hardware or the host's BLE stack).

The Rust tests are identical regardless of whether you use hardware or Bumble. The tests discover the peripheral by looking for the advertised device name "btleplug-test".

┌─────────────────────────┐     BLE Radio     ┌─────────────────────────┐
│  Rust Integration Tests │ ◄──────────────► │  nRF52840 DK (Zephyr)   │
│  (tests/*.rs)           │                   │  GATT Test Server       │
│                         │                   │  (test-peripheral/      │
│                         │                   │   zephyr/)              │
└─────────────────────────┘                   └─────────────────────────┘

         OR (no hardware)

┌─────────────────────────┐   Host BLE Stack  ┌─────────────────────────┐
│  Rust Integration Tests │ ◄──────────────► │  Python Bumble           │
│  (same tests)           │                   │  GATT Test Server       │
│                         │                   │  (test-peripheral/      │
│                         │                   │   bumble/)              │
└─────────────────────────┘                   └─────────────────────────┘

Key terms used within the integration test system:

• GATT: Generic Attribute Profile; the protocol used to expose structured data via services and characteristics.
• Central: The BLE client role (played by btleplug). It scans, connects, and communicates.
• Peripheral: The BLE server role (the test device). It advertises and hosts GATT services.
• Characteristic: A GATT data endpoint with a UUID, properties (read/write/notify/indicate), and a value.
• Descriptor: Metadata attached to a characteristic (e.g., CCCD for enabling notifications).
• Notification/Indication: Server-initiated updates. Notifications are unacknowledged; indications require acknowledgement.
• MTU: Maximum Transmission Unit; the negotiated maximum payload size for an ATT packet.
• RSSI: Received Signal Strength Indicator; signal power in dBm.
• Zephyr: The RTOS used for the nRF52840 DK firmware.
• Bumble: A pure-Python BLE stack used for the virtual peripheral.

Integration tests are located in the tests/ directory and are gated with #[ignore] by default because they require an external peripheral.

To run tests, you must have either the Zephyr firmware running on an nRF52 DK or the Python Bumble server running.

Run all integration tests:

# Note: must include --ignored to run the gated tests
cargo test --test '*' -- --ignored

Run a specific test file:

cargo test --test test_read_write

Run only unit tests (skipping integration tests):

cargo test --lib

Customizing Peripheral Discovery: You can override the default device name ("btleplug-test") by setting the BTLEPLUG_TEST_PERIPHERAL environment variable. This is useful if you have multiple test boards.

# With hardware peripheral (nRF52 DK running, or Bumble started):
cargo test --test test_read_write

# All integration tests:
cargo test --test '*'

# Skip integration tests (unit tests only):
cargo test --lib

# To actually run the ignored integration tests:
cargo test --test '*' -- --ignored