source: appstream-generator/build/girepo/gio/TestDBus.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

File size: 8.1 KB
Line 
1/*
2 * Licensed under the GNU Lesser General Public License Version 3
3 *
4 * This library is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as published by
6 * the Free Software Foundation, either version 3 of the license, or
7 * (at your option) any later version.
8 *
9 * This software is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12 * GNU Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public License
15 * along with this library.  If not, see <http://www.gnu.org/licenses/>.
16 */
17
18// generated automatically - do not change
19
20
21module gio.TestDBus;
22
23private import gi.gio;
24public  import gi.giotypes;
25private import glib.ConstructionException;
26private import glib.Str;
27private import gobject.ObjectG;
28
29
30/**
31 * A helper class for testing code which uses D-Bus without touching the user's
32 * session bus.
33 *
34 * Note that #GTestDBus modifies the user’s environment, calling setenv().
35 * This is not thread-safe, so all #GTestDBus calls should be completed before
36 * threads are spawned, or should have appropriate locking to ensure no access
37 * conflicts to environment variables shared between #GTestDBus and other
38 * threads.
39 *
40 * ## Creating unit tests using GTestDBus
41 *
42 * Testing of D-Bus services can be tricky because normally we only ever run
43 * D-Bus services over an existing instance of the D-Bus daemon thus we
44 * usually don't activate D-Bus services that are not yet installed into the
45 * target system. The #GTestDBus object makes this easier for us by taking care
46 * of the lower level tasks such as running a private D-Bus daemon and looking
47 * up uninstalled services in customizable locations, typically in your source
48 * code tree.
49 *
50 * The first thing you will need is a separate service description file for the
51 * D-Bus daemon. Typically a `services` subdirectory of your `tests` directory
52 * is a good place to put this file.
53 *
54 * The service file should list your service along with an absolute path to the
55 * uninstalled service executable in your source tree. Using autotools we would
56 * achieve this by adding a file such as `my-server.service.in` in the services
57 * directory and have it processed by configure.
58 * |[
59 * [D-BUS Service]
60 * Name=org.gtk.GDBus.Examples.ObjectManager
61 * Exec=@abs_top_builddir@/gio/tests/gdbus-example-objectmanager-server
62 * ]|
63 * You will also need to indicate this service directory in your test
64 * fixtures, so you will need to pass the path while compiling your
65 * test cases. Typically this is done with autotools with an added
66 * preprocessor flag specified to compile your tests such as:
67 * |[
68 * -DTEST_SERVICES=\""$(abs_top_builddir)/tests/services"\"
69 * ]|
70 * Once you have a service definition file which is local to your source tree,
71 * you can proceed to set up a GTest fixture using the #GTestDBus scaffolding.
72 *
73 * An example of a test fixture for D-Bus services can be found
74 * here:
75 * [gdbus-test-fixture.c](https://git.gnome.org/browse/glib/tree/gio/tests/gdbus-test-fixture.c)
76 *
77 * Note that these examples only deal with isolating the D-Bus aspect of your
78 * service. To successfully run isolated unit tests on your service you may need
79 * some additional modifications to your test case fixture. For example; if your
80 * service uses GSettings and installs a schema then it is important that your test service
81 * not load the schema in the ordinary installed location (chances are that your service
82 * and schema files are not yet installed, or worse; there is an older version of the
83 * schema file sitting in the install location).
84 *
85 * Most of the time we can work around these obstacles using the
86 * environment. Since the environment is inherited by the D-Bus daemon
87 * created by #GTestDBus and then in turn inherited by any services the
88 * D-Bus daemon activates, using the setup routine for your fixture is
89 * a practical place to help sandbox your runtime environment. For the
90 * rather typical GSettings case we can work around this by setting
91 * `GSETTINGS_SCHEMA_DIR` to the in tree directory holding your schemas
92 * in the above fixture_setup() routine.
93 *
94 * The GSettings schemas need to be locally pre-compiled for this to work. This can be achieved
95 * by compiling the schemas locally as a step before running test cases, an autotools setup might
96 * do the following in the directory holding schemas:
97 * |[
98 * all-am:
99 * $(GLIB_COMPILE_SCHEMAS) .
100 *
101 * CLEANFILES += gschemas.compiled
102 * ]|
103 *
104 * Since: 2.34
105 */
106public class TestDBus : ObjectG
107{
108        /** the main Gtk struct */
109        protected GTestDBus* gTestDBus;
110
111        /** Get the main Gtk struct */
112        public GTestDBus* getTestDBusStruct()
113        {
114                return gTestDBus;
115        }
116
117        /** the main Gtk struct as a void* */
118        protected override void* getStruct()
119        {
120                return cast(void*)gTestDBus;
121        }
122
123        protected override void setStruct(GObject* obj)
124        {
125                gTestDBus = cast(GTestDBus*)obj;
126                super.setStruct(obj);
127        }
128
129        /**
130         * Sets our main struct and passes it to the parent class.
131         */
132        public this (GTestDBus* gTestDBus, bool ownedRef = false)
133        {
134                this.gTestDBus = gTestDBus;
135                super(cast(GObject*)gTestDBus, ownedRef);
136        }
137
138
139        /** */
140        public static GType getType()
141        {
142                return g_test_dbus_get_type();
143        }
144
145        /**
146         * Create a new #GTestDBus object.
147         *
148         * Params:
149         *     flags = a #GTestDBusFlags
150         *
151         * Returns: a new #GTestDBus.
152         *
153         * Throws: ConstructionException GTK+ fails to create the object.
154         */
155        public this(GTestDBusFlags flags)
156        {
157                auto p = g_test_dbus_new(flags);
158               
159                if(p is null)
160                {
161                        throw new ConstructionException("null returned by new");
162                }
163               
164                this(cast(GTestDBus*) p, true);
165        }
166
167        /**
168         * Unset DISPLAY and DBUS_SESSION_BUS_ADDRESS env variables to ensure the test
169         * won't use user's session bus.
170         *
171         * This is useful for unit tests that want to verify behaviour when no session
172         * bus is running. It is not necessary to call this if unit test already calls
173         * g_test_dbus_up() before acquiring the session bus.
174         */
175        public static void unset()
176        {
177                g_test_dbus_unset();
178        }
179
180        /**
181         * Add a path where dbus-daemon will look up .service files. This can't be
182         * called after g_test_dbus_up().
183         *
184         * Params:
185         *     path = path to a directory containing .service files
186         */
187        public void addServiceDir(string path)
188        {
189                g_test_dbus_add_service_dir(gTestDBus, Str.toStringz(path));
190        }
191
192        /**
193         * Stop the session bus started by g_test_dbus_up().
194         *
195         * This will wait for the singleton returned by g_bus_get() or g_bus_get_sync()
196         * is destroyed. This is done to ensure that the next unit test won't get a
197         * leaked singleton from this test.
198         */
199        public void down()
200        {
201                g_test_dbus_down(gTestDBus);
202        }
203
204        /**
205         * Get the address on which dbus-daemon is running. If g_test_dbus_up() has not
206         * been called yet, %NULL is returned. This can be used with
207         * g_dbus_connection_new_for_address().
208         *
209         * Returns: the address of the bus, or %NULL.
210         */
211        public string getBusAddress()
212        {
213                return Str.toString(g_test_dbus_get_bus_address(gTestDBus));
214        }
215
216        /**
217         * Get the flags of the #GTestDBus object.
218         *
219         * Returns: the value of #GTestDBus:flags property
220         */
221        public GTestDBusFlags getFlags()
222        {
223                return g_test_dbus_get_flags(gTestDBus);
224        }
225
226        /**
227         * Stop the session bus started by g_test_dbus_up().
228         *
229         * Unlike g_test_dbus_down(), this won't verify the #GDBusConnection
230         * singleton returned by g_bus_get() or g_bus_get_sync() is destroyed. Unit
231         * tests wanting to verify behaviour after the session bus has been stopped
232         * can use this function but should still call g_test_dbus_down() when done.
233         */
234        public void stop()
235        {
236                g_test_dbus_stop(gTestDBus);
237        }
238
239        /**
240         * Start a dbus-daemon instance and set DBUS_SESSION_BUS_ADDRESS. After this
241         * call, it is safe for unit tests to start sending messages on the session bus.
242         *
243         * If this function is called from setup callback of g_test_add(),
244         * g_test_dbus_down() must be called in its teardown callback.
245         *
246         * If this function is called from unit test's main(), then g_test_dbus_down()
247         * must be called after g_test_run().
248         */
249        public void up()
250        {
251                g_test_dbus_up(gTestDBus);
252        }
253}
Note: See TracBrowser for help on using the repository browser.