dbusmock.testcase ================= .. py:module:: dbusmock.testcase .. autoapi-nested-parse:: unittest.TestCase convenience methods for DBusMocks Attributes ---------- .. autoapisummary:: dbusmock.testcase.__author__ dbusmock.testcase.__copyright__ Classes ------- .. autoapisummary:: dbusmock.testcase.BusType dbusmock.testcase.PrivateDBus dbusmock.testcase.DBusTestCase dbusmock.testcase.SpawnedMock Module Contents --------------- .. py:data:: __author__ :value: 'Martin Pitt' .. py:data:: __copyright__ :value: Multiline-String .. raw:: html
Show Value .. code-block:: python """ (c) 2012 Canonical Ltd. (c) 2017 - 2022 Martin Pitt """ .. raw:: html
.. py:class:: BusType Bases: :py:obj:`enum.Enum` Represents a system or session bus .. py:attribute:: SESSION :value: 'session' .. py:attribute:: SYSTEM :value: 'system' .. py:property:: environ :type: Tuple[str, Optional[str]] Returns the name and value of this bus' address environment variable .. py:method:: 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. .. py:method:: reload_configuration() Notify this bus that it needs to reload the configuration .. py:method:: 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. .. py:class:: 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. .. py:attribute:: bustype .. py:method:: __enter__() -> PrivateDBus .. py:method:: __exit__(exc_type, exc_val, exc_tb) .. py:property:: address :type: str Returns this D-Bus' address in the environment variable format, i.e. something like unix:path=/path/to/socket .. py:property:: servicedir :type: pathlib.Path The services directory (full path) for any ``.service`` files that need to be known to this D-Bus. .. py:property:: pid :type: int Return the pid of this D-Bus daemon process .. py:method:: start() Start the D-Bus daemon .. py:method:: stop() Stop the D-Bus daemon .. py:method:: 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. .. py:method:: 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. .. py:class:: DBusTestCase(methodName='runTest') Bases: :py:obj:`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. .. py:attribute:: session_bus_pid :value: None .. py:attribute:: system_bus_pid :value: None .. py:method:: get_services_dir(system_bus: bool = False) -> str :staticmethod: 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. .. py:method:: tearDownClass() :classmethod: Hook method for deconstructing the class fixture after running all tests in the class. .. py:method:: start_session_bus() -> None :classmethod: Set up a private local session bus This gets stopped automatically at class teardown. .. py:method:: start_system_bus() -> None :classmethod: Set up a private local system bus This gets stopped automatically at class teardown. .. py:method:: start_dbus(conf: Optional[str] = None) -> Tuple[int, str] :staticmethod: 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. .. py:method:: stop_dbus(pid: int) -> None :staticmethod: 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(). .. py:method:: get_dbus(system_bus: bool = False) -> dbus.Bus :staticmethod: 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. .. py:method:: wait_for_bus_object(dest: str, path: str, system_bus: bool = False, timeout: int = 600) :staticmethod: 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. .. py:method:: spawn_server(name: str, path: str, interface: str, system_bus: bool = False, stdout=None) -> subprocess.Popen :staticmethod: 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. .. py:method:: spawn_server_template(template: str, parameters: Optional[Dict[str, Any]] = None, stdout=None, system_bus: Optional[bool] = None) -> Tuple[subprocess.Popen, dbus.proxies.ProxyObject] :staticmethod: 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. .. py:method:: enable_service(service, system_bus: bool = False) -> None :staticmethod: 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. .. py:method:: disable_service(service, system_bus: bool = False) -> None :staticmethod: 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. .. py:class:: 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. .. py:property:: process :type: subprocess.Popen Returns the process that is this mock template .. py:property:: obj The D-Bus object this server was spawned for .. py:method:: __enter__() -> SpawnedMock .. py:method:: __exit__(exc_type, exc_val, exc_tb) .. py:method:: terminate() Terminate the process .. py:property:: stdout The stdout of the process, if no caller-specific stdout was specified in spawn_for_name() or spawn_with_template(). .. py:property:: stderr The stderr of the process, if no caller-specific stderr was specified in spawn_for_name() or spawn_with_template(). .. py:method:: spawn_for_name(name: str, path: str, interface: str, bustype: BusType = BusType.SESSION, stdout=subprocess.PIPE, stderr=subprocess.PIPE) -> SpawnedMock :classmethod: 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. .. py:method:: spawn_with_template(template: str, parameters: Optional[Dict[str, Any]] = None, bustype: Optional[BusType] = None, stdout=subprocess.PIPE, stderr=subprocess.PIPE) :classmethod: 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).