dbusmock.testcase

unittest.TestCase convenience methods for DBusMocks

Attributes

__author__
__copyright__

Classes

BusType	Represents a system or session bus
PrivateDBus	A D-Bus daemon instance that represents a private session or system bus.
DBusTestCase	Base class for D-Bus mock tests.
SpawnedMock	An instance of a D-Bus mock template instance in a separate process.

Module Contents

dbusmock.testcase.__author__ = 'Martin Pitt'

dbusmock.testcase.__copyright__ = Multiline-String

Show Value

"""
(c) 2012 Canonical Ltd.
(c) 2017 - 2022 Martin Pitt <martin@piware.de>
"""

class dbusmock.testcase.BusType

Bases: enum.Enum

Represents a system or session bus

SESSION = 'session'

SYSTEM = 'system'

property environ: Tuple[str, str | None]

Returns the name and value of this bus’ address environment variable

get_connection() → dbus.bus.Connection

Get a dbus.bus.BusConnection() object to this bus.

This uses the current environment variables for this bus (if any) and falls back to dbus.SystemBus() or dbus.SessionBus() otherwise.

This is preferrable to dbus.SystemBus() and dbus.SessionBus() as those do not get along with multiple changing local test buses.

reload_configuration()

Notify this bus that it needs to reload the configuration

wait_for_bus_object(dest: str, path: str, timeout: float = 60.0)

Wait for an object to appear on D-Bus

Raise an exception if object does not appear within one minute. You can change the timeout in seconds with the “timeout” keyword argument.

class dbusmock.testcase.PrivateDBus(bustype: BusType)

A D-Bus daemon instance that represents a private session or system bus.

If used as a context manager it will automatically start the bus and clean up after itself on exit:

>>> with PrivateDBus(BusType.SESSION) as bus:
>>>    do_something(bus)

Otherwise, start() and stop() manually.

bustype

__enter__() → PrivateDBus

__exit__(exc_type, exc_val, exc_tb)

property address: str

Returns this D-Bus’ address in the environment variable format, i.e. something like unix:path=/path/to/socket

property servicedir: pathlib.Path

The services directory (full path) for any .service files that need to be known to this D-Bus.

property pid: int

Return the pid of this D-Bus daemon process

start()

Start the D-Bus daemon

stop()

Stop the D-Bus daemon

enable_service(service: str)

Enable the given well-known service name inside dbusmock

This symlinks a service file from the usual dbus service directories into the dbusmock environment. Doing that allows the service to be launched automatically if they are defined within $XDG_DATA_DIRS.

The daemon configuration is reloaded if a test bus is running.

disable_service(service)

Disable the given well known service name inside dbusmock

This unlink’s the .service file for the service and reloads the daemon configuration if a test bus is running.

class dbusmock.testcase.DBusTestCase(methodName='runTest')

Bases: unittest.TestCase

Base class for D-Bus mock tests.

This provides some convenience API to start/stop local D-Buses, so that you can run a private local session and/or system bus to run mocks on.

This also provides a spawn_server() static method to run the D-Bus mock server in a separate process.

session_bus_pid = None

system_bus_pid = None

static get_services_dir(system_bus: bool = False) → str

Returns the private services directory for the bus type in question. This allows dropping in a .service file so that the dbus server inside dbusmock can launch it.

classmethod tearDownClass()

Hook method for deconstructing the class fixture after running all tests in the class.

classmethod start_session_bus() → None

Set up a private local session bus

This gets stopped automatically at class teardown.

classmethod start_system_bus() → None

Set up a private local system bus

This gets stopped automatically at class teardown.

static start_dbus(conf: str | None = None) → Tuple[int, str]

Start a D-Bus daemon

Return (pid, address) pair.

Normally you do not need to call this directly. Use start_system_bus() and start_session_bus() instead.

static stop_dbus(pid: int) → None

Stop a D-Bus daemon

Normally you do not need to call this directly. When you use start_system_bus() and start_session_bus(), these buses are automatically stopped in tearDownClass().

static get_dbus(system_bus: bool = False) → dbus.Bus

Get a dbus.bus.BusConnection() object to this bus

This is preferrable to dbus.SystemBus() and dbus.SessionBus() as those do not get along with multiple changing local test buses.

This is a legacy method kept for backwards compatibility, use BusType.get_connection() instead.

static wait_for_bus_object(dest: str, path: str, system_bus: bool = False, timeout: int = 600)

Wait for an object to appear on D-Bus

Raise an exception if object does not appear within one minute. You can change the timeout with the “timeout” keyword argument which specifies deciseconds.

This is a legacy method kept for backwards compatibility, use BusType.wait_for_bus_object() instead.

static spawn_server(name: str, path: str, interface: str, system_bus: bool = False, stdout=None) → subprocess.Popen

Run a DBusMockObject instance in a separate process

The daemon will terminate automatically when the D-Bus that it connects to goes down. If that does not happen (e. g. you test on the actual system/session bus), you need to kill it manually.

This function blocks until the spawned DBusMockObject is ready and listening on the bus.

Returns the Popen object of the spawned daemon.

This is a legacy method kept for backwards compatibility, use SpawnedMock.spawn_for_name() instead.

static spawn_server_template(template: str, parameters: Dict[str, Any] | None = None, stdout=None, system_bus: bool | None = None) → Tuple[subprocess.Popen, dbus.proxies.ProxyObject]

Run a D-Bus mock template instance in a separate process

This starts a D-Bus mock process and loads the given template with (optional) parameters into it. For details about templates see dbusmock.DBusMockObject.AddTemplate().

Usually a template should specify SYSTEM_BUS = False/True to select whether it gets loaded on the session or system bus. This can be overridden with the system_bus parameter. For templates which don’t set SYSTEM_BUS, this parameter has to be set.

The daemon will terminate automatically when the D-Bus that it connects to goes down. If that does not happen (e. g. you test on the actual system/session bus), you need to kill it manually.

This function blocks until the spawned DBusMockObject is ready and listening on the bus.

Returns a pair (daemon Popen object, main dbus object).

This is a legacy method kept for backwards compatibility, use SpawnedMock.spawn_with_template() instead.

static enable_service(service, system_bus: bool = False) → None

Enable the given well known service name inside dbusmock

This symlinks a service file from the usual dbus service directories into the dbusmock environment. Doing that allows the service to be launched automatically if they are defined within $XDG_DATA_DIRS.

The daemon configuration is reloaded if a test bus is running.

This is a legacy method kept for backwards compatibility. Use PrivateDBus.enable_service() instead.

static disable_service(service, system_bus: bool = False) → None

Disable the given well known service name inside dbusmock

This unlink’s the .service file for the service and reloads the daemon configuration if a test bus is running.

class dbusmock.testcase.SpawnedMock(process: subprocess.Popen, obj: dbus.proxies.ProxyObject)

An instance of a D-Bus mock template instance in a separate process.

See SpawnedMock.spawn_for_name() and SpawnedMock.spawn_with_template() the typical entry points.

property process: subprocess.Popen

Returns the process that is this mock template

property obj

The D-Bus object this server was spawned for

__enter__() → SpawnedMock

__exit__(exc_type, exc_val, exc_tb)

terminate()

Terminate the process

property stdout

The stdout of the process, if no caller-specific stdout was specified in spawn_for_name() or spawn_with_template().

property stderr

The stderr of the process, if no caller-specific stderr was specified in spawn_for_name() or spawn_with_template().

classmethod spawn_for_name(name: str, path: str, interface: str, bustype: BusType = BusType.SESSION, stdout=subprocess.PIPE, stderr=subprocess.PIPE) → SpawnedMock

Run a DBusMockObject instance in a separate process

The daemon will terminate automatically when the D-Bus that it connects to goes down. If that does not happen (e. g. you test on the actual system/session bus), you need to kill it manually.

This function blocks until the spawned DBusMockObject is ready and listening on the bus.

By default, stdout and stderr of the spawned process is available via the SpawnedMock.stdout and SpawnedMock.stderr properties on the returned object.

classmethod spawn_with_template(template: str, parameters: Dict[str, Any] | None = None, bustype: BusType | None = None, stdout=subprocess.PIPE, stderr=subprocess.PIPE)

Run a D-Bus mock template instance in a separate process

This starts a D-Bus mock process and loads the given template with (optional) parameters into it. For details about templates see dbusmock.DBusMockObject.AddTemplate().

Usually a template should specify SYSTEM_BUS = False/True to select whether it gets loaded on the session or system bus. This can be overridden with the system_bus parameter. For templates which don’t set SYSTEM_BUS, this parameter has to be set.

The daemon will terminate automatically when the D-Bus that it connects to goes down. If that does not happen (e. g. you test on the actual system/session bus), you need to kill it manually.

This function blocks until the spawned DBusMockObject is ready and listening on the bus.

Returns a pair (daemon Popen object, main dbus object).