Isolated unit testing of D-Bus services

Hi all, long time no blog…

At Openismus these past months we’ve been making a series of improvements for the Evolution Data Server, again.

As it goes with patch reviews, better to take on one at a time, so this blog post will focus on isolated unit testing of your D-Bus services.

If you work on the implementation of D-Bus services you’ll be happy to know about the new GTestDBus object introduced in GIO since 2.34. Thanks to this nifty new object we can now perform unit tests on D-Bus services in a completely isolated fashion.

Using GTestDBus to implement a new test fixture for Evolution Data Server (EDS) now makes it possible to run ‘make check’ for EDS without running the actual EDS servers manually, and without even installing the EDS software into the target prefix before hand. With a little more work, we can even get regular distchecks passing for EDS again.

Here’s how:

• First of all, you need to have an in-tree directory holding your D-Bus .service description files. Typically you already have the .service.in files stored somewhere in tree to be installed somewhere into the install prefix, but you need a separate one (I think it’s good practice to add a subdirectory to your ‘tests/’ directory, so it becomes ‘$(top_builddir)/tests/services’)
• The contents of your separate .service.in files for testing should point to the in-tree location of your D-Bus service, typically it would look like this:

  [D-BUS Service]
  Name=org.gnome.MyProject.MyServiceName
  Exec=@abs_top_builddir@/src/my-server-name

  This will define a service which explicitly activates a server which you’ve built in your source tree.

• Then, you just need to provide that in-tree service directory to g_test_dbus_add_service_dir(), typically you would put the following into your tests/Makefile.am:

  -DTEST_SERVICE_DIRECTORY=\""$(abs_top_builddir)/tests/services"\"

• Finally you just need a basic test fixture, with this test fixture you can ensure that your temporary D-Bus session along with your test service is recreated for every test in the suite:

  typedef struct {
    GTestDBus *dbus;
    MyProxyType *proxy;
  } TestFixture;
  
  static void
  fixture_setup (TestFixture *fixture, gconstpointer unused)
  {
    /* Create a private dbus-daemon for this test */
    fixture->dbus = g_test_dbus_new (G_TEST_DBUS_NONE);
  
    /* Add the private directory with our in-tree service files */
    g_test_dbus_add_service_dir (fixture->dbus, TEST_SERVICE_DIRECTORY);
  
    /* Start the private D-Bus daemon */
    g_test_dbus_up (fixture->dbus);
  
    /* Get a proxy which we will be using in test cases, typically
     * this is some API generated by gdbus-codegen
     */
    fixture->proxy = my_generated_code_new_for_bus_sync (...);
  }
  
  static void
  fixture_teardown (TestFixture *fixture, gconstpointer unused)
  {
    /* Destroy the proxy */
    g_object_unref (fixture->proxy);
  
    /* Stop the private D-Bus daemon */
    g_test_dbus_down (fixture->dbus);
    g_object_unref (fixture->dbus);
  }

With this basic type of fixture, you can produce a series of tests using g_test_add() in the normal way, all testing various behaviours of fixture->proxy.

Of course, perfect isolation of your service’s test cases may need more efforts than just the above, for instance in the EDS test cases we create and delete a data directory between each test and setup the XDG_CONFIG_HOME, XDG_DATA_HOME and XDG_CACHE_HOME enviornment variables to point to that directory (avoiding any interaction with the user’s addressbook & calendar). We also compile a gsettings schema in the local data directory and setup GSETTINGS_SCHEMA_DIR to point to the in-tree directory (avoiding any need to have the EDS settings schemas already installed).

This morning before writing this post I also provided a simple patch to GIO adding an example of this testing paradigm.