4.5. Inside a C test

When writing new checks you can either modify an existing test file or add a new one. If your tests are related to the tests performed by an existing file, then add them to that file. Otherwise create a new .c file in the tests directory and add that file to the CTESTS variable in Makefile.in.

A new test file will look something like the following:

#include <wine/test.h>
#include <winbase.h>

/* Maybe auxiliary functions and definitions here */

START_TEST(paths)
{
   /* Write your checks there or put them in functions you will call from
    * there
    */
}

The test's entry point is the START_TEST section. This is where execution will start. You can put all your tests in that section but it may be better to split related checks in functions you will call from the START_TEST section. The parameter to START_TEST must match the name of the C file. So in the above example the C file would be called paths.c.

Tests should start by including the wine/test.h header. This header will provide you access to all the testing framework functions. You can then include the windows header you need, but make sure to not include any Unix or Wine specific header: tests must compile on Windows.

You can use trace to print informational messages. Note that these messages will only be printed if 'runtest -v' is being used.

  trace("testing GlobalAddAtomA");
  trace("foo=%d",foo);

Then just call functions and use ok to make sure that they behaved as expected:

  ATOM atom = GlobalAddAtomA( "foobar" );
  ok( GlobalFindAtomA( "foobar" ) == atom, "could not find atom foobar" );
  ok( GlobalFindAtomA( "FOOBAR" ) == atom, "could not find atom FOOBAR" );
The first parameter of ok is an expression which must evaluate to true if the test was successful. The next parameter is a printf-compatible format string which is displayed in case the test failed, and the following optional parameters depend on the format string.

It is important to display an informative message when a test fails: a good error message will help the Wine developper identify exactly what went wrong without having to add too many other printfs. For instance it may be useful to print the error code if relevant, or the expected value and effective value. In that respect, for some tests you may want to define a macro such as the following:

#define eq(received, expected, label, type) \
        ok((received) == (expected), "%s: got " type " instead of " type, (label),(received),(expected))

...

eq( b, curr_val, "SPI_{GET,SET}BEEP", "%d" );

Note