Mobly Test Framework

Instead of duplicating test logic for different parameters, you can use Mobly's Generated tests feature. This allows you to run the same logic multiple times with different argument sets.

1. Implement pre_run: In this method, define the list of arguments (arg_sets) and call self.generate_tests.
2. Define test_logic: A function containing the actual test steps that accepts the arguments from arg_sets.
3. Define name_func: A function that returns a unique string for each generated test case, using the same signature as test_logic.

Example Implementation:

from mobly import base_test
from mobly import test_runner
from mobly.controllers import android_device

class ManyGreetingsTest(base_test.BaseTestClass):

    def pre_run(self):
        # List of (greeting, name) tuples
        messages = [('Hello', 'World'), ('Aloha', 'Obama'), ('konichiwa', 'Satoshi')]
        
        self.generate_tests(
            test_logic=self.make_toast_logic,
            name_func=self.make_toast_name_function,
            arg_sets=messages)

    def setup_class(self):
        self.ads = self.register_controller(android_device)
        self.dut = self.ads[0]
        self.dut.load_snippet('mbs', android_device.MBS_PACKAGE)

    def make_toast_logic(self, greeting, name):
        self.dut.mbs.makeToast('%s, %s!' % (greeting, name))

    def make_toast_name_function(self, greeting, name):
        return 'test_greeting_say_%s_to_%s' % (greeting, name)

if __name__ == '__main__':
  test_runner.main()

To control custom hardware (like smart lights or switches), you must create a controller module that implements a specific interface. This module allows Mobly to manage the lifecycle of your custom devices.

Required Functions

Your module must provide these top-level functions:

• create(configs): Receives a list of configuration dictionaries and returns a list of instantiated device objects.
• destroy(objects): Receives the list of device objects and performs cleanup (e.g., closing connections, powering off devices).

Optional Functions

• get_info(objects): Receives the list of device objects and returns a list of dictionaries containing metadata. This information is included in the Mobly test report.

def create(configs: List[Dict[str, Any]]) -> List[Any]:
    # Instantiate devices from configs
    return [Device(**cfg) for cfg in configs]

def destroy(objects: List[Any]) -> None:
    # Cleanup devices
    for obj in objects:
        obj.close()

def get_info(objects: List[Any]) -> List[Dict[str, Any]]:
    # Return metadata for reports
    return [{"id": obj.id} for obj in objects]

Mobly's AndroidDevice controller allows you to run long-running services (like adb logcat collection or screen recording) that persist even when the device state changes (e.g., during a reboot).

To implement a service, you must create a class that inherits from base_service.BaseService. You should override the following methods/properties:

• start(): Logic to begin the service.
• stop(): Logic to terminate the service.
• is_alive (property): Returns the current status of the service.

Additionally, you can implement optional pause() and resume() methods if your service needs to handle device disconnections that do not involve a full reboot.

class MyService(base_service.BaseService):
  def __init__(self, device, configs=None):
    self._device = device
    self._configs = configs
    self._is_alive = False

  @property
  def is_alive(self):
    return self._is_alive

  def start(self):
    self._is_alive = True

  def stop(self):
    self._is_alive = False

To run basic instrumentation tests, subclass base_instrumentation_test.BaseInstrumentationTestClass. In your test class, use self.register_controller(android_device) to get your device and self.run_instrumentation_test to execute the tests against a specific package name.

Configuration (sample_config.yml):

TestBeds:
  - Name: BasicTestBed
    Controllers:
        AndroidDevice: '*'

Test Implementation (instrumentation_test.py):

from mobly import base_instrumentation_test
from mobly import test_runner
from mobly.controllers import android_device

class InstrumentationTest(base_instrumentation_test.BaseInstrumentationTestClass):
    def setup_class(self):
        self.dut = self.register_controller(android_device)[0]

    def test_instrumentation(self):
        self.run_instrumentation_test(self.dut, 'com.example.package.test')

if __name__ == '__main__':
  test_runner.main()

Execution:

python instrumentation_test.py -c sample_config.yml

When testing interactions between multiple devices (e.g., Bluetooth discovery), follow these steps:

1. Register multiple controllers: Use self.register_controller(android_device, min_number=N) where N is the required number of devices.
2. Identify devices by label: Use android_device.get_device(self.ads, label='your_label') to retrieve specific devices from the controller list.
3. Set debug tags: Assign device.debug_tag = 'tag_name' to differentiate device logs.
4. Use asserts and logging: Use mobly.asserts for validation and device.log.info() for device-specific logging.

Example Implementation:

import logging
from mobly import asserts
from mobly import base_test
from mobly import test_runner
from mobly.controllers import android_device

class BluetoothTest(base_test.BaseTestClass):
    def setup_class(self):
        self.ads = self.register_controller(android_device, min_number=2)
        self.discoverer = android_device.get_device(self.ads, label='discoverer')
        self.discoverer.debug_tag = 'discoverer'
        self.target = android_device.get_device(self.ads, label='target')
        self.target.debug_tag = 'target'
        self.target.load_snippet('mbs', android_device.MBS_PACKAGE)
        self.discoverer.load_snippet('mbs', android_device.MBS_PACKAGE)

    def setup_test(self):
        self.target.mbs.btEnable()
        self.discoverer.mbs.btEnable()
        self.target.mbs.btSetName('LookForMe!')

    def test_bluetooth_discovery(self):
        target_name = self.target.mbs.btGetName()
        self.target.mbs.btBecomeDiscoverable(60)
        discovered_devices = self.discoverer.mbs.btDiscoverAndGetResults()
        discovered_names = [device['Name'] for device in discovered_devices]
        asserts.assert_true(target_name in discovered_names, 'Discovery failed')

    def teardown_test(self):
        self.target.mbs.btDisable()
        self.discoverer.mbs.btDisable()

if __name__ == '__main__':
  test_runner.main()

To create a basic test, define a configuration file (.yml) to specify controllers and a Python test script inheriting from base_test.BaseTestClass.

In the test script:

1. Use self.register_controller(android_device) in setup_class to declare dependency on Android hardware.
2. Access devices from the returned controller list (e.g., self.dut = self.ads[0]).
3. Load snippets using self.dut.load_snippet('name', package_path) to enable device actions.

Configuration (sample_config.yml): Using AndroidDevice: '*' tells the runner to find all connected Android devices automatically. You can also specify devices by serial number and add custom attributes.

TestBeds:
  - Name: SampleTestBed
    Controllers:
        AndroidDevice: '*'

Test Script (hello_world_test.py):

from mobly import base_test
from mobly import test_runner
from mobly.controllers import android_device

class HelloWorldTest(base_test.BaseTestClass):

  def setup_class(self):
    # Registering android_device controller module
    self.ads = self.register_controller(android_device)
    self.dut = self.ads[0]
    # Start Mobly Bundled Snippets (MBS).
    self.dut.load_snippet('mbs', android_device.MBS_PACKAGE)

  def test_hello(self):
    self.dut.mbs.makeToast('Hello World!')

if __name__ == '__main__':
  test_runner.main()

Execution:

$ python hello_world_test.py -c sample_config.yml

You can pass instrumentation options (like test filters) through the Mobly configuration file using TestParams. In your test class, use self.parse_instrumentation_options(self.user_params) to retrieve these options, then pass them to self.run_instrumentation_test(..., options=self.options).

Configuration (sample_config.yml):

TestBeds:
  - Name: BasicTestBed
    Controllers:
        AndroidDevice: '*'
    TestParams:
        instrumentation_option_annotation: android.support.test.filters.LargeTest
        instrumentation_option_nonAnnotation: android.support.test.filters.SmallTest

Test Implementation Snippet:

class InstrumentationTest(base_instrumentation_test.BaseInstrumentationTestClass):
    def setup_class(self):
        self.dut = self.register_controller(android_device)[0]
        self.options = self.parse_instrumentation_options(self.user_params)

    def test_instrumentation(self):
        self.run_instrumentation_test(self.dut, 'com.example.package.test',
            options=self.options)