gimp/libgimp/tests/README.md

Unit testing for libgimp

We should test every function in our released libraries and ensure they return the correct data. This test infrastructure does this for the C library and the Python 3 binding.

Every new test unit should be added both in C and Python 3.

Procedure to add the C unit

C functions are tested in a real plug-in which is run by the unit test infrastructure. Most of the boiler-plate code is contained in c-test-header.c therefore you don't have to care about it.

All you must do is create a gimp_c_test_run() function with the following template:

static GimpValueArray *
gimp_c_test_run (GimpProcedure        *procedure,
                 GimpRunMode           run_mode,
                 GimpImage            *image,
                 gint                  n_drawables,
                 GimpDrawable        **drawables,
                 GimpProcedureConfig  *config,
                 gpointer              run_data)
{
  /* Each test must be surrounded by GIMP_TEST_START() and GIMP_TEST_END()
   * macros this way:
   */
  GIMP_TEST_START("Test name for easy debugging")
  /* Run some code and finish by an assert-like test. */
  GIMP_TEST_END(testme > 0)

  /* Do more tests as needed. */

  /* Mandatorily end the function by this macro: */
  GIMP_TEST_RETURN
}

This code must be in a file named only with alphanumeric letters and hyphens, and prepended with test-, such as: test-palette.c.

The part between test- and .c must be added to the tests list in libgimp/tests/meson.build.

Procedure to add the Python 3 unit

Unlike C, the Python 3 API is not run as a standalone plug-in, but as Python code directly interpreted through the python-fu-eval batch plug-in.

Simply add your code in a file named the same as the C file, but with .py extension instead of .c.

The file must mandatorily start with a shebang: #!/usr/bin/env python3

For testing, use gimp_assert() as follows:

#!/usr/bin/env python3

# Add your test code here.
# Then test that it succeeded with the assert-like test:
gimp_assert('Test name for easy debugging', testme > 0)

# Repeat with more tests as needed.