Integration Tests

These modules are built with the intent to provide a way to run a series of tests for drivers in an environment that mimics the driver running on the hub. It is important to note that these are NOT unit tests. Specifically these will heavily leverage the SmartThings Lua libraries, and thus potential bugs in those libraries could cause failures. See the testing guide in the guides section of the SmartThings documentation for more details on how to use these modules to build tests.

Integration Test Module

integration_test.add_test_env_setup_func(func)

Add functions that will be called with the driver under test table as an argument to

set up the driver with any test setup necessary.

Parameters: func (fun(Driver)) – A function to set up some driver condition on test start

integration_test.add_package_capability(capability_filename)

Add a capability definition from a yaml or json file within the driver package

This can be used to make the test environment function like a driver running on the hub where a custom capability definition is present if used by the driver/device profiles.

Parameters: capability_filename (str) – a capability filename expected to be in driver_package/capabilities/capability_filename.yaml

integration_test.load_all_caps_from_profile(profile_def)

Load all capabilities referenced in the profile provided

This can be used to make the test environment function like a driver running on the hub where capability definitions are present if used by the driver/device profiles. This will use the CLI to load these capability definitions, and thus requires smartthings to be an executable available on your path. Further, because retrieving the capabilities can be a bit slow, you can set an environment variable ST_CAPABILITY_CACHE with a path to a directory where the retrieved capability definitions will be stored and will be referenced on future runs to avoid requesting the definitions for every run.

Parameters: profile_def (table) – The loaded profile definition with capability references

integration_test.register_test(test_name, test_func, test_init, expected_error)

Register a test to be run

Parameters

test_name (str) – a name for the test used for logging/failure reporting
test_func (fun()) – the test function to run
test_init (fun()) – a function to run before the test to initialize information
expected_error (str) – A pattern (https://www.lua.org/pil/20.2.html) of an error that this test is expected to raise

integration_test.register_coroutine_test(test_name, co_func, opts)

Register a coroutine test

Parameters

test_name (str) – a name for the test used for logging/failure reporting
co_func (fun()) – The coroutine function test
opts (table) – A table of optional parameters to control the tests. See test guide for details

integration_test.register_message_test(test_name, manifest, opts)

Register a coroutine test

Parameters

test_name (str) – a name for the test used for logging/failure reporting
manifest (table) – An “array” of individual messages that are expected to be sent/received in the order presented
opts (table) – A table of optional parameters to control the tests. See test guide for details

Integration Test Utils

integration_test.utils.get_profile_definition(profile_file_name)

Load the definition of a profile from a <profile_name>.yaml file in the driver package

Parameters: profile_file_name (str) – the filename of the profile definition to load (expected in driver_package/profiles/<profile_file_name>)
Returns: The table representation of the expected profile to be included in the creation of a MockDevice
Return type: table

integration_test.utils.load_capability_definition_from_cli(capability_id, capability_version)

Load a capability definition using the SmartThings CLI

This will use the CLI to load this capability definition, and thus requires smartthings to be an executable available on your path. Further, because retrieving the capability can be a bit slow, you can set an environment variable ST_CAPABILITY_CACHE with a path to a directory where the retrieved capability definitions will be stored and will be referenced on future runs to avoid requesting the definitions for every run.

Parameters

capability_id (str) – The capabiity ID to read
capability_version (number) – The version of the capability to load the definition of

Returns

The first value is the Lua table version of the capability definition, the second is the string JSON of the definition

Return type

table or str

integration_test.utils.load_capability_definition_from_file(path_to_cap)

Load a capability definition from a JSON or yaml file

Parameters: path_to_cap (str) – A path to the capability definition file
Returns: The first value is the Lua table version of the capability definition, the second is the string JSON of the definition
Return type: table or str

integration_test.utils.load_capability_definition_from_package(capability_filename)

Load a capability definition from a JSON or yaml definition file within the driver package

This expects to find a driver_package/capabilities directory with the given filename inside

Parameters: capability_filename (str) – the filename containing the capability definition
Returns: The first value is the Lua table version of the capability definition, the second is the string JSON of the definition
Return type: table or str

Mock Device Module

mock_device.add_test_device(device)

Add this MockDevice to the manifest for this driver

By using this method, it will add this device’s info to be returned by the normal query methods for the driver requesting info about devices it is responsible for

Parameters: device (integration_test.MockDevice) – the device to add to the driver

mock_device.build_test_generic_device(device_template, additional_mock_fields)

Build a mock device from a template

Parameters

device_template (table) – the non-default st data about this device
additional_mock_fields (table) – any additional mock fields that should be present

Return type

integration_test.MockDevice

mock_device.build_test_child_device(device_template)

Build a mock Zigbee device from a template

This will include some additional mock functions necessary for easy construction of test messages.

Parameters: device_template (table) – the non-default st data about this device
Return type: integration_test.MockDevice

mock_device.build_test_zigbee_device(device_template)

Build a mock Zigbee device from a template

This will include some additional mock functions necessary for easy construction of test messages.

Parameters: device_template (table) – the non-default st data about this device
Return type: integration_test.MockDevice

mock_device.build_test_zwave_device(device_template)

Build a mock ZWave device from a template

Parameters: device_template (table) – the non-default st data about this device
Return type: integration_test.MockDevice

mock_device.build_test_matter_device(device_template)

Build a mock Matter device from a template

Parameters: device_template (table) – the non-default st data about this device
Return type: integration_test.MockDevice

Mock Device Class

class integration_test.MockDevice

generate_test_message(self, component_id, capability_event)

Generate a test message representing this device emitting the given event

Parameters

self (integration_test.MockDevice) –
component_id (str) – the component this event should be generated for
capability_event (table) – the capability event

Returns

the message objecte needed for a message test or __expect_send on the capability channel

Return type

table

static set_field(self, key, value, opts)

Set a device field value if the driver test hasn’t been initialized yet

Because the MockDevice typically is a passthrough into the actual device within the driver under test typically get_field will refer to the actual device object in the driver under test. However, because the MockDevice persists between tests and can be referred to when a test isn’t running and thus the device passthrough can’t be done, it will maintain it’s own fields store that will be used to populate the device object when the device does start. This mock method will only be called when the device passthrough is not available and will set a field in the mock field store

Parameters

self (integration_test.MockDevice) –
key (str) – the key of the field to get
value (any) – the value to store to the field
opts (table) – additional options (persist bool)

get_field(self, key)

Get a device field value if the driver test hasn’t been initialized yet

Because the MockDevice typically is a passthrough into the actual device within the driver under test typically get_field will refer to the actual device object in the driver under test. However, because the MockDevice persists between tests and can be referred to when a test isn’t running and thus the device passthrough can’t be done, it will maintain it’s own fields store that will be used to populate the device object when the device does start. This mock method will only be called when the device passthrough is not available and will return from the mock field store.

Parameters

self (integration_test.MockDevice) –
key (str) – the key of the field to get

expect_metadata_update(self, metadata)

Set the test to expect a device metadata update to be generated

This takes args of the same form as st.Device:try_update_metadata

Parameters

self (integration_test.MockDevice) –
metadata (table) – the metadata update command that is expected to be sent

expect_device_create(metadata)

Set the test to expect a device creation call to occur

This takes args of the same form as st.Driver:try_create_device

Parameters: metadata (table) – the metadata for the device that should be created

expect_native_cmd_handler_registration(capability_id, capability_cmd_id)

Set the test to expect a native capability command handler registration call to occur

This takes args of the same form as st.Device:register_native_capability_cmd_handler

Parameters

capability_id (str) – The ID of the capability to be handled natively
capability_cmd_id (str) – The ID of the command to be handled natively

generate_info_changed(self, metadata)

Generate a device_lifecycle infoChanged message to be queued in tests

This takes a table of key,value pairs to update info about this device. These should only be keys that would be present in the st_store of a device object

Parameters

self (integration_test.MockDevice) –
metadata (table) – the metadata update command that is expected to be sent

static init(raw_st_data, additional_mock_fields)

Create a MockDevice from st_data and additional mock fields

Parameters

raw_st_data (table) – the values representing this device that would be used on the ST platform
additional_mock_fields (table) – any additional fields that this device should mock out

Returns

the constructed mock device

Return type

integration_test.MockDevice