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}