How to add new units to the Clutter Conformance test suite
-------------------------------------------------------------------------------

If the new unit is not logically part of an existing file, you should create a
new source file and add it to the build. The built files are listed in the
Makefile.am template. Please, respect the sections already available there.

When creating a new file, you should include "test-conform-common.h", as well
as <clutter/clutter.h> and <glib.h>.

Each new test unit should be contained in a function named following this
pattern:

  void
  <section>_<unit> (void)
  {
  }

For instance:

  void
  actor_allocation_changes (void)
  {
    /* test allocation changes */
  }

  void
  rectangle_border (void)
  {
    /* test ClutterRectangle's border property */
  }

After adding the test unit, edit test-conform-main.c and add the unit to the
list of tests, by using one of these three macros:

  • TEST_CONFORM_SIMPLE (path, function_name);

    @path is the unit path in the suite, and it's used to generate the
          executable wrapper for running the unit as a stand-alone binary
          and for the HTML report.
    @function_name is the name of the function containing the newly added
          test unit.

    This is the simple form of test unit, and it will always be run.

  • TEST_CONFORM_SKIP (condition, path, function_name);

    @condition is used to decide whether to run the unit or not.

    This macro will check @condition on start, and if it evaluates to TRUE
    then the @function_name will be called and the unit executed; otherwise
    the test will automatically succeed.

  • TEST_CONFORM_TODO (path, function_name);

    This macro will execute @function_name and will succeed if the unit
    fails. This macro should be used for tests that are known to fail.

Notes:

  • Do not call clutter_init() in your units; initialization is handled
    by the conformance test suite itself.

  • All units are invoked in a new process, to prevent clobbering the
    state.