GLib test framework for your own project

[Tommi Komulainen <tommi komulainen nokia com>]

Hi,

Here's a quick guide for setting up GLib testing framework for your own
project. It is the result of some trial and error when integrating for
hildon widgets the test framework from current trunk. There are some
autotools related details that might not be immediately obvious for mere
mortals. Thought it good to collect the details in one place. Hope it
helps.


1. Copy Makefile.decl

        [glib or gtk+ currently does not install any usable
        Makefile.decl]
        
        Copy Makefile.decl from glib or gtk+ source directory to the
        root directory of your project. The difference is that
        Makefile.decl from gtk+ will run the tests in Xvfb and thus only
        works for x11 backend.
        
        Edit Makefile.decl so that GTESTER and GTESTER_REPORT are
        correct for non-GLIB packages:
        
        GTESTER        = gtester                # in $PATH for non-GLIB packages
        GTESTER_REPORT = gtester-report         # in $PATH for non-GLIB packages
        
        
        When using Makefile.decl from gtk+ also add the following line
        after GTESTER_REPORT. This is needed for properly starting Xvfb
        for the test.
        
        gdktarget := $(shell pkg-config --variable=target gdk-2.0)


2. Edit every Makefile.am

        Add the following line to the top of every Makefile.am. This is
        needed to enable recursive 'make test' and friends.
        
        include $(top_srcdir)/Makefile.decl


        In every Makefile.am replace 'EXTRA_DIST = ...' with 'EXTRA_DIST
        += ...' to silence automake warnings.


3. Add new directory to the build.

        Assuming tests go to src/tests.
        
        Add 'SUBDIRS = tests' to src/Makefile.am.
        Add 'AC_CONFIG_FILES([src/tests/Makefile])' to configure.ac
        
        See Tim Janik's mail for suggestion where to place the
        testcases:
        http://mail.gnome.org/archives/gtk-devel-list/2007-December/msg00181.html
        
        Create src/tests/Makefile.am:
        ----------8<--------------------8<--------------------8<----------
        include $(top_srcdir)/Makefile.decl
        
        noinst_PROGRAMS = $(TEST_PROGS)
        
        TEST_PROGS        += testwidget
        testwidget_SOURCES = testwidget.c
        ----------8<--------------------8<--------------------8<----------
        
        
4. Write src/tests/testwidget.c

        Make sure your normal build flags do not include -DG_DISABLE_ASSERT 
        (or add #undef G_DISABLE_ASSERT at the top of the file) as it will disable
        all checks using g_assert() -- though not any of g_assert_cmp*()

        [See some other tutorial and API reference for how to organize
        the C code and which functions/macros to use. Currently glib
        trunk does not generate any documentation for the testing
        framework.]


5. Run the tests
        
        $ make test
        
        When running in emacs/vim the first failing test should be
        recognized and the cursor should be placed on the line of
        failing assertion.
        
        [See some other tutorial/reference for how to run tests more
        fine grained (./testwidget -p /foo, ./testwidget --help?)]


-- 
Tommi Komulainen                            <tommi komulainen nokia com>