gio/auto/
test_dbus.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{ffi, TestDBusFlags};
6use glib::translate::*;
7
8glib::wrapper! {
9    /// A helper class for testing code which uses D-Bus without touching the user’s
10    /// session bus.
11    ///
12    /// Note that `GTestDBus` modifies the user’s environment, calling
13    /// [`setenv()`](man:setenv(3)). This is not thread-safe, so all `GTestDBus`
14    /// calls should be completed before threads are spawned, or should have
15    /// appropriate locking to ensure no access conflicts to environment variables
16    /// shared between `GTestDBus` and other threads.
17    ///
18    /// ## Creating unit tests using `GTestDBus`
19    ///
20    /// Testing of D-Bus services can be tricky because normally we only ever run
21    /// D-Bus services over an existing instance of the D-Bus daemon thus we
22    /// usually don’t activate D-Bus services that are not yet installed into the
23    /// target system. The `GTestDBus` object makes this easier for us by taking care
24    /// of the lower level tasks such as running a private D-Bus daemon and looking
25    /// up uninstalled services in customizable locations, typically in your source
26    /// code tree.
27    ///
28    /// The first thing you will need is a separate service description file for the
29    /// D-Bus daemon. Typically a `services` subdirectory of your `tests` directory
30    /// is a good place to put this file.
31    ///
32    /// The service file should list your service along with an absolute path to the
33    /// uninstalled service executable in your source tree. Using autotools we would
34    /// achieve this by adding a file such as `my-server.service.in` in the services
35    /// directory and have it processed by configure.
36    ///
37    /// ```text
38    /// [D-BUS Service]
39    /// Name=org.gtk.GDBus.Examples.ObjectManager
40    /// Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server
41    /// ```
42    ///
43    /// You will also need to indicate this service directory in your test
44    /// fixtures, so you will need to pass the path while compiling your
45    /// test cases. Typically this is done with autotools with an added
46    /// preprocessor flag specified to compile your tests such as:
47    ///
48    /// ```text
49    /// -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\"
50    /// ```
51    ///
52    /// Once you have a service definition file which is local to your source tree,
53    /// you can proceed to set up a GTest fixture using the `GTestDBus` scaffolding.
54    ///
55    /// An example of a test fixture for D-Bus services can be found
56    /// here:
57    /// [gdbus-test-fixture.c](https://gitlab.gnome.org/GNOME/glib/-/blob/HEAD/gio/tests/gdbus-test-fixture.c)
58    ///
59    /// Note that these examples only deal with isolating the D-Bus aspect of your
60    /// service. To successfully run isolated unit tests on your service you may need
61    /// some additional modifications to your test case fixture. For example; if your
62    /// service uses [`Settings`][crate::Settings] and installs a schema then it is important
63    /// that your test service not load the schema in the ordinary installed location
64    /// (chances are that your service and schema files are not yet installed, or
65    /// worse; there is an older version of the schema file sitting in the install
66    /// location).
67    ///
68    /// Most of the time we can work around these obstacles using the
69    /// environment. Since the environment is inherited by the D-Bus daemon
70    /// created by `GTestDBus` and then in turn inherited by any services the
71    /// D-Bus daemon activates, using the setup routine for your fixture is
72    /// a practical place to help sandbox your runtime environment. For the
73    /// rather typical GSettings case we can work around this by setting
74    /// `GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas
75    /// in the above `fixture_setup()` routine.
76    ///
77    /// The GSettings schemas need to be locally pre-compiled for this to work. This
78    /// can be achieved by compiling the schemas locally as a step before running
79    /// test cases, an autotools setup might do the following in the directory
80    /// holding schemas:
81    ///
82    /// ```text
83    ///     all-am:
84    ///             $(GLIB_COMPILE_SCHEMAS) .
85    ///
86    ///     CLEANFILES += gschemas.compiled
87    /// ```
88    ///
89    /// ## Properties
90    ///
91    ///
92    /// #### `flags`
93    ///  #GTestDBusFlags specifying the behaviour of the D-Bus session.
94    ///
95    /// Readable | Writeable | Construct Only
96    ///
97    /// # Implements
98    ///
99    /// [`trait@glib::ObjectExt`]
100    #[doc(alias = "GTestDBus")]
101    pub struct TestDBus(Object<ffi::GTestDBus>);
102
103    match fn {
104        type_ => || ffi::g_test_dbus_get_type(),
105    }
106}
107
108impl TestDBus {
109    /// Create a new #GTestDBus object.
110    /// ## `flags`
111    /// a #GTestDBusFlags
112    ///
113    /// # Returns
114    ///
115    /// a new #GTestDBus.
116    #[doc(alias = "g_test_dbus_new")]
117    pub fn new(flags: TestDBusFlags) -> TestDBus {
118        unsafe { from_glib_full(ffi::g_test_dbus_new(flags.into_glib())) }
119    }
120
121    /// Add a path where dbus-daemon will look up .service files. This can't be
122    /// called after g_test_dbus_up().
123    /// ## `path`
124    /// path to a directory containing .service files
125    #[doc(alias = "g_test_dbus_add_service_dir")]
126    pub fn add_service_dir(&self, path: &str) {
127        unsafe {
128            ffi::g_test_dbus_add_service_dir(self.to_glib_none().0, path.to_glib_none().0);
129        }
130    }
131
132    /// Stop the session bus started by g_test_dbus_up().
133    ///
134    /// This will wait for the singleton returned by g_bus_get() or g_bus_get_sync()
135    /// to be destroyed. This is done to ensure that the next unit test won't get a
136    /// leaked singleton from this test.
137    #[doc(alias = "g_test_dbus_down")]
138    pub fn down(&self) {
139        unsafe {
140            ffi::g_test_dbus_down(self.to_glib_none().0);
141        }
142    }
143
144    /// Get the address on which dbus-daemon is running. If g_test_dbus_up() has not
145    /// been called yet, [`None`] is returned. This can be used with
146    /// g_dbus_connection_new_for_address().
147    ///
148    /// # Returns
149    ///
150    /// the address of the bus, or [`None`].
151    #[doc(alias = "g_test_dbus_get_bus_address")]
152    #[doc(alias = "get_bus_address")]
153    pub fn bus_address(&self) -> Option<glib::GString> {
154        unsafe { from_glib_none(ffi::g_test_dbus_get_bus_address(self.to_glib_none().0)) }
155    }
156
157    /// Get the flags of the #GTestDBus object.
158    ///
159    /// # Returns
160    ///
161    /// the value of #GTestDBus:flags property
162    #[doc(alias = "g_test_dbus_get_flags")]
163    #[doc(alias = "get_flags")]
164    pub fn flags(&self) -> TestDBusFlags {
165        unsafe { from_glib(ffi::g_test_dbus_get_flags(self.to_glib_none().0)) }
166    }
167
168    /// Stop the session bus started by g_test_dbus_up().
169    ///
170    /// Unlike g_test_dbus_down(), this won't verify the #GDBusConnection
171    /// singleton returned by g_bus_get() or g_bus_get_sync() is destroyed. Unit
172    /// tests wanting to verify behaviour after the session bus has been stopped
173    /// can use this function but should still call g_test_dbus_down() when done.
174    #[doc(alias = "g_test_dbus_stop")]
175    pub fn stop(&self) {
176        unsafe {
177            ffi::g_test_dbus_stop(self.to_glib_none().0);
178        }
179    }
180
181    /// Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this
182    /// call, it is safe for unit tests to start sending messages on the session bus.
183    ///
184    /// If this function is called from setup callback of g_test_add(),
185    /// g_test_dbus_down() must be called in its teardown callback.
186    ///
187    /// If this function is called from unit test's main(), then g_test_dbus_down()
188    /// must be called after g_test_run().
189    #[doc(alias = "g_test_dbus_up")]
190    pub fn up(&self) {
191        unsafe {
192            ffi::g_test_dbus_up(self.to_glib_none().0);
193        }
194    }
195
196    /// Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test
197    /// won't use user's session bus.
198    ///
199    /// This is useful for unit tests that want to verify behaviour when no session
200    /// bus is running. It is not necessary to call this if unit test already calls
201    /// g_test_dbus_up() before acquiring the session bus.
202    #[doc(alias = "g_test_dbus_unset")]
203    pub fn unset() {
204        unsafe {
205            ffi::g_test_dbus_unset();
206        }
207    }
208}