Usage

Command Line Interface

Test-a-BLE provides a command-line interface for running tests:

# Run all tests in the current directory with interactive device discovery (default)
test-a-ble

# Connect to a device by address and run all tests in the current directory
test-a-ble --address 00:11:22:33:44:55

# Connect to a device by name and run a specific test module or function
test-a-ble --name "My Device" test_module.test_function

# Run tests from a specific file path
test-a-ble path/to/test_file.py

# Run all tests in a specific directory
test-a-ble path/to/test_directory

# Run tests in a directory specified with dot notation (converts to path)
test-a-ble package.module.submodule

Writing Tests

Test-a-BLE supports both function-based and class-based tests.

Function-based Tests

from test-a-ble import test

@test
def test_device_connection(ctx):
    """Test that we can connect to the device."""
    # ctx is a TestContext object that provides access to the device
    ctx.log.info("Connected to device")
    assert ctx.device is not None

Class-based Tests

from test-a-ble import TestCase

class MyDeviceTests(TestCase):
    def test_read_characteristic(self):
        """Test that we can read a characteristic."""
        value = self.read_characteristic("00002a00-0000-1000-8000-00805f9b34fb")
        self.log.info(f"Read value: {value}")
        assert value is not None

    def test_write_characteristic(self):
        """Test that we can write to a characteristic."""
        self.write_characteristic("00002a00-0000-1000-8000-00805f9b34fb", b"test")
        self.log.info("Wrote to characteristic")

Common Testing Patterns

Write to device and expect a response:

@test
def test_write_and_response(ctx):
    ctx.write_characteristic("00002a00-0000-1000-8000-00805f9b34fb", b"test")
    response = ctx.read_characteristic("00002a00-0000-1000-8000-00805f9b34fb")
    assert response == b"expected_response"

Write to device, prompt user for interaction, then expect a response:

@test
def test_user_interaction(ctx):
    ctx.write_characteristic("00002a00-0000-1000-8000-00805f9b34fb", b"test")
    ctx.prompt_user("Please press the button on the device")
    response = ctx.read_characteristic("00002a00-0000-1000-8000-00805f9b34fb")
    assert response == b"button_pressed"

Prompt user for interaction and expect a notification:

@test
def test_notification(ctx):
    ctx.subscribe_to_characteristic("00002a00-0000-1000-8000-00805f9b34fb")
    ctx.prompt_user("Please press the button on the device")
    notification = ctx.wait_for_notification("00002a00-0000-1000-8000-00805f9b34fb", timeout=5)
    assert notification == b"button_pressed"