Check service database name in OpenSCManager().
[wine] / documentation / testing.sgml
1   <chapter id="testing">
2     <title>Writing Conformance tests</title>
3
4     <sect1 id="testing-intro">
5       <title>Introduction</title>
6       <para>
7         The Windows API follows no standard, it is itself a de facto standard,
8         and deviations from that standard, even small ones, often cause
9         applications to crash or misbehave in some way.
10       </para>   
11       <para>
12         The question becomes, "How do we ensure compliance with that standard?"
13         The answer is, "By using the API documentation available to us and
14         backing that up with conformance tests." Furthermore, a conformance
15         test suite is the most accurate (if not necessarily the most complete)
16         form of API documentation and can be used to supplement the Windows
17         API documentation.
18       </para>
19       <para>
20         Writing a conformance test suite for more than 10000 APIs is no small
21         undertaking. Fortunately it can prove very useful to the development
22         of Wine way before it is complete.
23         <itemizedlist>
24           <listitem>
25             <para>
26               The conformance test suite must run on Windows. This is
27               necessary to provide a reasonable way to verify its accuracy.
28               Furthermore the tests must pass successfully on all Windows
29               platforms (tests not relevant to a given platform should be
30               skipped).
31             </para>
32             <para>
33               A consequence of this is that the test suite will provide a
34               great way to detect variations in the API between different
35               Windows versions. For instance, this can provide insights
36               into the differences between the, often undocumented, Win9x and
37               NT Windows families.
38             </para>
39             <para>
40               However, one must remember that the goal of Wine is to run
41               Windows applications on Linux, not to be a clone of any specific
42               Windows version. So such variations must only be tested for when
43               relevant to that goal.
44             </para>
45           </listitem>
46           <listitem>
47             <para>
48               Writing conformance tests is also an easy way to discover
49               bugs in Wine. Of course, before fixing the bugs discovered in
50               this way, one must first make sure that the new tests do pass
51               successfully on at least one Windows 9x and one Windows NT
52               version.
53             </para>
54             <para>
55               Bugs discovered this way should also be easier to fix. Unlike
56               some mysterious application crashes, when a conformance test
57               fails, the expected behavior and APIs tested for are known thus
58               greatly simplifying the diagnosis.
59             </para>
60           </listitem>
61           <listitem>
62             <para>
63               To detect regressions. Simply running the test suite regularly
64               in Wine turns it into a great tool to detect regressions.
65               When a test fails, one immediately knows what was the expected
66               behavior and which APIs are involved. Thus regressions caught
67               this way should be detected earlier, because it is easy to run
68               all tests on a regular basis, and be easier to fix because of the
69               reduced diagnosis work.
70             </para>
71           </listitem>
72           <listitem>
73             <para>
74               Tests written in advance of the Wine development (possibly even
75               by non Wine developers) can also simplify the work of the
76               future implementer by making it easier for him to check the
77               correctness of his code.
78             </para>
79           </listitem>
80           <listitem>
81             <para>
82               Conformance tests will also come in handy when testing Wine on
83               new (or not as widely used) architectures such as FreeBSD,
84               Solaris x86 or even non-x86 systems. Even when the port does
85               not involve any significant change in the thread management,
86               exception handling or other low-level aspects of Wine, new
87               architectures can expose subtle bugs that can be hard to
88               diagnose when debugging regular (complex) applications.
89             </para>
90           </listitem>
91         </itemizedlist>
92       </para>
93     </sect1>
94
95
96     <sect1 id="testing-what">
97       <title>What to test for?</title>
98       <para>
99         The first thing to test for is the documented behavior of APIs
100         and such as CreateFile. For instance one can create a file using a
101         long pathname, check that the behavior is correct when the file
102         already exists, try to open the file using the corresponding short
103         pathname, convert the filename to Unicode and try to open it using
104         CreateFileW, and all other things which are documented and that
105         applications rely on.
106       </para>
107       <para>
108         While the testing framework is not specifically geared towards this
109         type of tests, it is also possible to test the behavior of Windows
110         messages. To do so, create a window, preferably a hidden one so that
111         it does not steal the focus when running the tests, and send messages
112         to that window or to controls in that window. Then, in the message
113         procedure, check that you receive the expected messages and with the
114         correct parameters.
115       </para>
116       <para>
117         For instance you could create an edit control and use WM_SETTEXT to
118         set its contents, possibly check length restrictions, and verify the
119         results using WM_GETTEXT. Similarly one could create a listbox and
120         check the effect of LB_DELETESTRING on the list's number of items,
121         selected items list, highlighted item, etc. For concrete examples,
122         see <filename>dlls/user/tests/win.c</> and the related tests.
123       </para>
124       <para>
125         However, undocumented behavior should not be tested for unless there
126         is an application that relies on this behavior, and in that case the
127         test should mention that application, or unless one can strongly
128         expect applications to rely on this behavior, typically APIs that
129         return the required buffer size when the buffer pointer is NULL.
130       </para>
131     </sect1>
132
133
134     <sect1 id="testing-wine">
135       <title>Running the tests in Wine</title>
136       <para>
137         The simplest way to run the tests in Wine is to type 'make test' in
138         the Wine sources top level directory. This will run all the Wine
139         conformance tests.
140       </para>
141       <para>
142         The tests for a specific Wine library are located in a 'tests'
143         directory in that library's directory. Each test is contained in a
144         file (e.g. <filename>dlls/kernel/tests/thread.c</>). Each
145         file itself contains many checks concerning one or more related APIs.
146       </para>
147       <para>
148         So to run all the tests related to a given Wine library, go to the
149         corresponding 'tests' directory and type 'make test'. This will
150         compile the tests, run them, and create an '<replaceable>xxx</>.ok'
151         file for each test that passes successfully. And if you only want to
152         run the tests contained in the <filename>thread.c</> file of the
153         kernel library, you would do:
154 <screen>
155 <prompt>$ </>cd dlls/kernel/tests
156 <prompt>$ </>make thread.ok
157 </screen>
158       </para>
159       <para>
160         Note that if the test has already been run and is up to date (i.e. if
161         neither the kernel library nor the <filename>thread.c</> file has
162         changed since the <filename>thread.ok</> file was created), then make
163         will say so. To force the test to be re-run, delete the
164         <filename>thread.ok</> file, and run the make command again.
165       </para>
166       <para>
167         You can also run tests manually using a command similar to the
168         following:
169 <screen>
170 <prompt>$ </>../../../tools/runtest -q -M kernel32.dll -p kernel32_test.exe.so thread.c
171 <prompt>$ </>../../../tools/runtest -P wine -p kernel32_test.exe.so thread.c
172 thread.c: 86 tests executed, 5 marked as todo, 0 failures.
173 </screen>
174         The '-P wine' option defines the platform that is currently being
175         tested and is used in conjunction with the 'todo' statements (see
176         below). Remove the '-q' option if you want the testing framework
177         to report statistics about the number of successful and failed tests.
178         Run <command>runtest -h</> for more details.
179       </para>
180     </sect1>
181
182
183     <sect1 id="cross-compiling-tests">
184       <title>Cross-compiling the tests with MinGW</title>
185       <sect2>
186         <title>Setup of the MinGW cross-compiling environment</title>
187         <para>
188           Here are some instructions to setup MinGW on different Linux 
189           distributions and *BSD.
190         </para>
191         <sect3>
192           <title>Debian GNU/Linux</title>
193           <para>
194             On Debian do <command>apt-get install mingw32</>.
195           </para>
196           <para>
197             The standard MinGW libraries will probably be incomplete, causing
198             'undefined symbol' errors. So get the latest
199             <ulink url="http://mirzam.it.vu.nl/mingw/">mingw-w32api RPM</>
200             and use <command>alien</> to either convert it to a .tar.gz file
201             from which to extract just the relevant files, or to convert it
202             to a Debian package that you will install.
203           </para>
204         </sect3>
205         <sect3>
206           <title>Red Hat Linux like rpm systems</title>
207           <para>
208             This includes Fedora Core, Red Hat Enterprise Linux, Mandrake,
209             most probably SuSE Linux too, etc. But this list isn't exhaustive;
210             the following steps should probably work on any rpm based system.
211           </para>
212           <para>
213             Download and install the latest rpm's from 
214             <ulink url="http://mirzam.it.vu.nl/mingw/">MinGW RPM packages</>.
215             Alternatively you can follow the instructions on that page and
216             build your own packages from the source rpm's listed there as well.
217           </para>
218         </sect3>
219         <sect3>
220           <title>*BSD</title>
221           <para>
222             The *BSD systems have in their ports collection a port for the
223             MinGW cross-compiling environment. Please see the documentation
224             of your system about how to build and install a port.
225           </para>
226         </sect3>
227       </sect2>
228       <sect2>
229       <title>Compiling the tests</title>
230       <para>
231         Having the cross-compiling environment set up the generation of the
232         Windows executables is easy by using the Wine build system.
233       </para>
234       <para>
235         If you had already run <command>configure</>, then delete
236         <filename>config.cache</> and re-run <command>configure</>.
237         You can then run <command>make crosstest</>. To sum up:
238 <screen>
239 <prompt>$ </><userinput>rm config.cache</>
240 <prompt>$ </><userinput>./configure</>
241 <prompt>$ </><userinput>make crosstest</>
242 </screen>
243       </para>
244       </sect2>
245     </sect1>
246
247
248     <sect1 id="testing-windows">
249       <title>Building and running the tests on Windows</title>
250       <sect2>
251         <title>Using pre-compiled binaries</title>
252         <para>
253           The simplest solution is to download the
254           <ulink url="http://www.astro.gla.ac.uk/users/paulm/WRT/CrossBuilt/winetest-latest.exe">latest
255           version of winetest</>. This executable contains all the Wine
256           conformance tests, runs them and reports the results.
257         </para>
258         <para>
259           You can also get the older versions from
260           <ulink url="http://www.astro.gla.ac.uk/users/paulm/WRT/CrossBuilt/">Paul
261           Millar's website</>.
262         </para>
263       </sect2>
264       <sect2>
265         <title>With Visual C++</title>
266         <itemizedlist>
267           <listitem><para>
268             If you are using Visual Studio 6, make sure you have the
269             "processor pack" from
270             <ulink url="http://msdn.microsoft.com/vstudio/downloads/tools/ppack/default.aspx">http://msdn.microsoft.com/vstudio/downloads/tools/ppack/default.aspx</>.
271             The processor pack fixes <emphasis>"error C2520: conversion from
272             unsigned __int64 to double not implemented, use signed __int64"</>.
273             However note that the "processor pack" is incompatible with
274             Visual Studio 6.0 Standard Edition, and with the Visual Studio 6
275             Service Pack 6. If you are using Visual Studio 7 or greater you
276             do not need the processor pack. In either case it is recommended
277             to the most recent compatible Visual Studio
278             <ulink url="http://msdn.microsoft.com/vstudio/downloads/updates/sp/">service pack</>.
279           </para></listitem>
280           <listitem><para>
281             get the Wine sources
282           </para></listitem>
283           <listitem><para>
284             Run msvcmaker to generate Visual C++ project files for the tests.
285             'msvcmaker' is a perl script so you may be able to run it on
286             Windows.
287 <screen>
288 <prompt>$ </>./tools/winapi/msvcmaker --no-wine
289 </screen>
290           </para></listitem>
291           <listitem><para>
292             If the previous steps were done on your Linux development
293             machine, make the Wine sources accessible to the Windows machine
294             on which you are going to compile them. Typically you would do
295             this using Samba but copying them altogether would work too.
296           </para></listitem>
297           <listitem><para>
298             On the Windows machine, open the <filename>winetest.dsw</>
299             workspace. This will load each test's project. For each test there
300             are two configurations: one compiles the test with the Wine
301             headers, and the other uses the Microsoft headers.
302           </para></listitem>
303           <listitem><para>
304             If you choose the "Win32 MSVC Headers" configuration, most of the
305             tests will not compile with the regular Visual Studio headers. So
306             to use this configuration, download and install a recent
307             <ulink url="http://www.microsoft.com/msdownload/platformsdk/sdkupdate/">Platform SDK</>
308             as well as the latest <ulink url="http://msdn.microsoft.com/library/default.asp?url=/downloads/list/directx.asp">DirectX SDK</>.
309             Then, <ulink url="http://msdn.microsoft.com/library/default.asp?url=/library/EN-US/sdkintro/sdkintro/installing_the_platform_sdk_with_visual_studio.asp">configure Visual Studio</>
310             to use these SDK's headers and libraries. Alternately you could go
311             to the <menuchoice><guimenu>Project</> <guimenu>Settings...</></>
312             menu and modify the settings appropriately, but you would then
313             have to redo this whenever you rerun msvcmaker.
314           </para></listitem>
315           <listitem><para>
316             Open the <menuchoice><guimenu>Build</> <guimenu>Batch
317             build...</></> menu and select the tests and build configurations
318             you want to build. Then click on <guibutton>Build</>.
319           </para></listitem>
320           <listitem><para>
321             To run a specific test from Visual C++, go to
322             <menuchoice><guimenu>Project</> <guimenu>Settings...</></>. There
323             select that test's project and build configuration and go to the
324             <guilabel>Debug</> tab. There type the name of the specific test
325             to run (e.g. 'thread') in the <guilabel>Program arguments</>
326             field. Validate your change by clicking on <guibutton>Ok</> and
327             start the test by clicking the red exclamation mark (or hitting
328             'F5' or any other usual method).
329           </para></listitem>
330           <listitem><para>
331             You can also run the tests from the command line. You will find
332             them in either <filename>Output\Win32_Wine_Headers</> or
333             <filename>Output\Win32_MSVC_Headers</> depending on the build
334             method. So to run the kernel 'path' tests you would do:
335 <screen>
336 <prompt>C:\&gt;</>cd dlls\kernel\tests\Output\Win32_MSVC_Headers
337 <prompt>C:\wine\dlls\kernel\tests\Output\Win32_MSVC_Headers&gt;</> kernel32_test path
338 </screen>
339           </para></listitem>
340         </itemizedlist>
341       </sect2>
342       <sect2>
343         <title>With MinGW</title>
344         <para>
345          Wine's build system already has support for building tests with a MinGW
346          cross-compiler. See the section above called 'Setup of the MinGW 
347          cross-compiling environment' for instructions on how to set things up.
348          When you have a MinGW environment installed all you need to do is rerun
349          configure and it should detect the MinGW compiler and tools. Then run 
350          'make crosstest' to start building the tests.
351         </para>
352       </sect2>
353     </sect1>
354
355
356     <sect1 id="testing-test">
357       <title>Inside a test</title>
358
359       <para>
360         When writing new checks you can either modify an existing test file or
361         add a new one. If your tests are related to the tests performed by an
362         existing file, then add them to that file. Otherwise create a new .c
363         file in the tests directory and add that file to the
364         <varname>CTESTS</> variable in <filename>Makefile.in</>.
365       </para>
366       <para>
367         A new test file will look something like the following:
368 <screen>
369 #include &lt;wine/test.h&gt;
370 #include &lt;winbase.h&gt;
371
372 /* Maybe auxiliary functions and definitions here */
373
374 START_TEST(paths)
375 {
376    /* Write your checks there or put them in functions you will call from
377     * there
378     */
379 }
380 </screen>
381       </para>
382       <para>
383         The test's entry point is the START_TEST section. This is where
384         execution will start. You can put all your tests in that section but
385         it may be better to split related checks in functions you will call
386         from the START_TEST section. The parameter to START_TEST must match
387         the name of the C file. So in the above example the C file would be
388         called <filename>paths.c</>.
389       </para>
390       <para>
391         Tests should start by including the <filename>wine/test.h</> header.
392         This header will provide you access to all the testing framework
393         functions. You can then include the windows header you need, but make
394         sure to not include any Unix or Wine specific header: tests must
395         compile on Windows.
396       </para>
397       <para>
398         You can use <function>trace</> to print informational messages. Note
399         that these messages will only be printed if 'runtest -v' is being used.
400 <screen>
401   trace("testing GlobalAddAtomA\n");
402   trace("foo=%d\n",foo);
403 </screen>
404       </para>
405       <para>
406         Then just call functions and use <function>ok</> to make sure that
407         they behaved as expected:
408 <screen>
409   ATOM atom = GlobalAddAtomA( "foobar" );
410   ok( GlobalFindAtomA( "foobar" ) == atom, "could not find atom foobar\n" );
411   ok( GlobalFindAtomA( "FOOBAR" ) == atom, "could not find atom FOOBAR\n" );
412 </screen>
413         The first parameter of <function>ok</> is an expression which must
414         evaluate to true if the test was successful. The next parameter is a
415         printf-compatible format string which is displayed in case the test
416         failed, and the following optional parameters depend on the format
417         string.
418       </para>
419     </sect1>
420
421     <sect1 id="testing-error-messages">
422       <title>Writing good error messages</title>
423       <para>
424         The message that is printed when a test fails is
425         <emphasis>extremely</> important.
426       </para>
427       <para>
428         Someone will take your test, run it on a Windows platform that
429         you don't have access to, and discover that it fails. They will then
430         post an email with the output of the test, and in particular your
431         error message. Someone, maybe you, will then have to figure out from
432         this error message why the test failed.
433       </para>
434       <para>
435         If the error message contains all the relevant information that will
436         be easy. If not, then it will require modifying the test, finding
437         someone to compile it on Windows, sending the modified version to the
438         original tester and waiting for his reply. In other words, it will
439         be long and painful.
440       </para>
441       <para>
442         So how do you write a good error message? Let's start with an example
443         of a bad error message:
444 <screen>
445     ok(GetThreadPriorityBoost(curthread,&amp;disabled)!=0,
446        "GetThreadPriorityBoost Failed\n");
447 </screen>
448         This will yield:
449 <screen>
450 thread.c:123: Test failed: GetThreadPriorityBoost Failed
451 </screen>
452       </para>
453       <para>
454         Did you notice how the error message provides no information about
455         why the test failed? We already know from the line number exactly
456         which test failed. In fact the error message gives strictly no
457         information that cannot already be obtained by reading the code. In
458         other words it provides no more information than an empty string!
459       </para>
460       <para>
461         Let's look at how to rewrite it:
462 <screen>
463     BOOL rc;
464 ...
465     rc=GetThreadPriorityBoost(curthread,&amp;disabled);
466     ok(rc!=0 && disabled==0,"rc=%d error=%ld disabled=%d\n",
467        rc,GetLastError(),disabled);
468 </screen>
469         This will yield:
470 <screen>
471 thread.c:123: Test failed: rc=0 error=120 disabled=0
472 </screen>
473       </para>
474       <para>
475         When receiving such a message, one would check the source, see that
476         it's a call to GetThreadPriorityBoost, that the test failed not
477         because the API returned the wrong value, but because it returned an
478         error code. Furthermore we see that GetLastError() returned 120 which
479         winerror.h defines as ERROR_CALL_NOT_IMPLEMENTED. So the source of
480         the problem is obvious: this Windows platform (here Windows 98) does
481         not support this API and thus the test must be modified to detect
482         such a condition and skip the test.
483       </para>
484       <para>
485         So a good error message should provide all the information which
486         cannot be obtained by reading the source, typically the function
487         return value, error codes, and any function output parameter. Even if
488         more information is needed to fully understand a problem,
489         systematically providing the above is easy and will help cut down the
490         number of iterations required to get to a resolution.
491       </para>
492       <para>
493         It may also be a good idea to dump items that may be hard to retrieve
494         from the source, like the expected value in a test if it is the
495         result of an earlier computation, or comes from a large array of test
496         values (e.g. index 112 of _pTestStrA in vartest.c). In that respect,
497         for some tests you may want to define a macro such as the following:
498 <screen>
499 #define eq(received, expected, label, type) \
500         ok((received) == (expected), "%s: got " type " instead of " type "\n", (label),(received),(expected))
501
502 ...
503
504     eq( b, curr_val, "SPI_{GET,SET}BEEP", "%d" );
505 </screen>
506        </para>
507     </sect1>
508
509
510     <sect1 id="testing-platforms">
511       <title>Handling platform issues</title>
512       <para>
513         Some checks may be written before they pass successfully in Wine.
514         Without some mechanism, such checks would potentially generate
515         hundred of known failures for months each time the tests are being run.
516         This would make it hard to detect new failures caused by a regression.
517         or to detect that a patch fixed a long standing issue.
518       </para>
519       <para>
520         Thus the Wine testing framework has the concept of platforms and
521         groups of checks can be declared as expected to fail on some of them.
522         In the most common case, one would declare a group of tests as
523         expected to fail in Wine. To do so, use the following construct:
524 <screen>
525 todo_wine {
526     SetLastError( 0xdeadbeef );
527     ok( GlobalAddAtomA(0) == 0 && GetLastError() == 0xdeadbeef, "failed to add atom 0\n" );
528 }
529 </screen>
530         On Windows the above check would be performed normally, but on Wine it
531         would be expected to fail, and not cause the failure of the whole
532         test. However. If that check were to succeed in Wine, it would
533         cause the test to fail, thus making it easy to detect when something
534         has changed that fixes a bug. Also note that todo checks are accounted
535         separately from regular checks so that the testing statistics remain
536         meaningful. Finally, note that todo sections can be nested so that if
537         a test only fails on the cygwin and reactos platforms, one would
538         write:
539 <screen>
540 todo("cygwin") {
541     todo("reactos") {
542         ...
543     }
544 }
545 </screen>
546         <!-- FIXME: Would we really have platforms such as reactos, cygwin, freebsd & co? -->
547         But specific platforms should not be nested inside a todo_wine section
548         since that would be redundant.
549       </para>
550       <para>
551         When writing tests you will also encounter differences between Windows
552         9x and Windows NT platforms. Such differences should be treated
553         differently from the platform issues mentioned above. In particular
554         you should remember that the goal of Wine is not to be a clone of any
555         specific Windows version but to run Windows applications on Unix.
556       </para>
557       <para>
558         So, if an API returns a different error code on Windows 9x and
559         Windows NT, your check should just verify that Wine returns one or
560         the other:
561 <screen>
562 ok ( GetLastError() == WIN9X_ERROR || GetLastError() == NT_ERROR, ...);
563 </screen>
564       </para>
565       <para>
566         If an API is only present on some Windows platforms, then use
567         LoadLibrary and GetProcAddress to check if it is implemented and
568         invoke it. Remember, tests must run on all Windows platforms.
569         Similarly, conformance tests should nor try to correlate the Windows
570         version returned by GetVersion with whether given APIs are
571         implemented or not. Again, the goal of Wine is to run Windows
572         applications (which do not do such checks), and not be a clone of a
573         specific Windows version.
574       </para>
575       <!--para>
576         FIXME: What about checks that cause the process to crash due to a bug?
577       </para-->
578     </sect1>
579
580
581 <!-- FIXME: Strategies for testing threads, testing network stuff,
582  file handling... -->
583
584   </chapter>
585
586 <!-- Keep this comment at the end of the file
587 Local variables:
588 mode: sgml
589 sgml-parent-document:("wine-devel.sgml" "set" "book" "part" "chapter" "")
590 End:
591 -->