using scan-line polygon conversion for constructing wxregion

[wxWidgets.git] / docs / tech / tn0017.txt

diff --git a/docs/tech/tn0017.txt b/docs/tech/tn0017.txt
index 5a5e8669dd1854895eb04a9ae265afac8c99ec5b..eeff4c2fee853b190489e36bf9a1b63ff9c5e4f7 100644 (file)
--- a/docs/tech/tn0017.txt
+++ b/docs/tech/tn0017.txt
@@ -1,7 +1,7 @@
-                    How to write unit tests for wxWindows
+                    How to write unit tests for wxWidgets

                     =====================================
 
                     =====================================
 

- Unit tests for wxWindows are written using small cppunit framework. To compile
+Unit tests for wxWidgets are written using small cppunit framework. To compile

 (but not to run) them you need to have it installed. Hence the first part of
 this note explains how to do it while the second one explains how to write the
 test.
 (but not to run) them you need to have it installed. Hence the first part of
 this note explains how to do it while the second one explains how to write the
 test.


@@ -10,14 +10,14 @@ I. CppUnit Installation
 -----------------------
 
 1. Get it from http://www.sourceforge.net/projects/cppunit
 -----------------------
 
 1. Get it from http://www.sourceforge.net/projects/cppunit

-   (latest version as of the time of this writing is 1.8.0)
+   (latest version as of the time of this writing is 1.10.2)

 
 2. Build the library:
 
 2. Build the library:

- a) Under Windows using VC++ (both versions 6 and 7 work):
+ a) Under Windows using VC++ (versions 6, 7, 8 & 9 work):

     - build everything in CppUnitLibraries.dsw work space
     - add include and lib subdirectories of the directory
       where you installed cppunit to the compiler search path
     - build everything in CppUnitLibraries.dsw work space
     - add include and lib subdirectories of the directory
       where you installed cppunit to the compiler search path

-      using "Tools|Options" menu in VC IDEA
+      using "Tools|Options" menu in VC IDE

 
  b) Under Unix: run configure && make && make install as usual
 
 
  b) Under Unix: run configure && make && make install as usual
 


@@ -38,12 +38,33 @@ II. Writing tests with CppUnit
     // register in the unnamed registry so that these tests are run by default
     CPPUNIT_TEST_SUITE_REGISTRATION(MBConvTestCase);
 
     // register in the unnamed registry so that these tests are run by default
     CPPUNIT_TEST_SUITE_REGISTRATION(MBConvTestCase);
 

-    // also include in it's own registry so that these tests can be run alone
+    // also include in its own registry so that these tests can be run alone

     CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(MBConvTestCase, "MBConvTestCase");
 
     CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(MBConvTestCase, "MBConvTestCase");
 

-   Read CppUnit documentation for more.
-
-3. add a '<sources>' tag for your source file to tests/test.bkl
+    Read CppUnit documentation for more.
+ d) wxUIActionSimulator can be used when user input is required, for example
+    clicking buttons or typing text. A simple example of this can be found
+    in controls/buttontest.cpp. After simulating some user input always
+    wxYield to allow event processing. When writing a test using
+    wxUIActionSimulator always add the test using WXUISIM_TEST rather than
+    CPPUNIT_TEST as then it won't run on unsupported platforms. The test itself
+    must also be wrapped in a #if wxUSE_UIACTIONSIMULATOR block.
+ e) There are a number of classes that are available to help with testing GUI
+    elements. Firstly throughout the test run there is a frame of type
+    wxTestableFrame that you can access through wxTheApp->GetTopWindow(). This
+    class adds two new functions, GetEventCount, which takes an optional
+    wxEventType. It then returns the number of events of that type that it has
+    received since the last call. Passing nothing returns the total number of
+    event received since the last call. Also there is OnEvent, which counts the
+    events based on type that are passed to it. To make it easy to count events
+    there is also a new class called EventCounter which takes a window and event
+    type and connects the window to the top level wxTestableFrame with the specific
+    event type. It disconnects again once it is out of scope. It simply reduces
+    the amount of typing required to count events.
+
+3. add a '<sources>' tag for your source file to tests/test.bkl. Make sure it's
+   in the correct section: the one starting '<exe id="test_gui"' for a gui test,
+   the one starting '<exe id="test" template="wx_sample_console' otherwise.

 
 
 III. Running the tests
 
 
 III. Running the tests


@@ -57,17 +78,37 @@ III. Running the tests
 2. Build the test program using one of the make/project files in the tests
    subdirectory.
 
 2. Build the test program using one of the make/project files in the tests
    subdirectory.
 

-3. Run the test program with no arguments to run the default set of tests
-   (which are all those registered with CPPUNIT_TEST_SUITE_REGISTRATION).
-   Or to list the tests without running them:
-      test -l
+3. Run the test program by using the command 'test' for the console tests,
+   'test_gui' for the gui ones. With no arguments, all the default set of tests
+   (all those registered with CPPUNIT_TEST_SUITE_REGISTRATION) are run.
+   Or to list the test suites without running them:
+      test -l   or   test_gui -l

 
 4. Tests that have been registered under a name using
    CPPUNIT_TEST_SUITE_NAMED_REGISTRATION can also be run separately. For
    example:
 
 4. Tests that have been registered under a name using
    CPPUNIT_TEST_SUITE_NAMED_REGISTRATION can also be run separately. For
    example:

-      test MBConvTestCase
-   or to list the tests:
-      test -l MBConvTestCase
+      test_gui ButtonTestCase
+   or to list the tests done by a particular testcase:
+      test -L MBConvTestCase
+
+5. Fault navigation.
+   VC++ users can run the programs as a post build step (Projects/Settings/
+   Post-build step) to see the test results in an IDE window. This allows
+   errors to be jumped to in the same way as for compiler errors, for
+   example by pressing F4 or highlighting the error and pressing return.
+   
+   Similarly for makefile users: makefiles can be modified to execute the
+   test programs as a final step. Then you can navigate to any errors in the
+   same way as for compiler errors, if your editor supports that.
+
+   Another alternative is to run the tests manually, redirecting the output
+   to a file. Then use your editor to jump to any failures. Using Vim, for
+   example, ':cf test.log' would take you to the first error in test.log, and
+   ':cn' to the next.
+
+   If you would like to set a breakpoint on a failing test using a debugger,
+   put the breakpoint on the function 'CppUnit::Asserter::fail()'. This will
+   stop on each failing test.

 
 
 IV. Notes
 
 
 IV. Notes


@@ -76,14 +117,29 @@ IV. Notes
 1. You can register your tests (or a subset of them) just under a name, and not
    in the unnamed registry if you don't want them to be executed by default.
 
 1. You can register your tests (or a subset of them) just under a name, and not
    in the unnamed registry if you don't want them to be executed by default.
 

-2. If you are going to register your tests both in the unnamed registry and
-   under a name, then use the name that the tests have in the 'test -l'
-   listing (which is often the name of the TestCase class). Then the top
-   level names in a 'test -l' listing can be a hint as to the name those
-   tests have been registered under.
+2. If you are going to register your tests both in the unnamed registry
+   and under a name, then use the name that the tests have in the 'test -l'
+   listing.
+
+3. Tests which fail can be temporarily registered under "fixme" while the
+   problems they expose are fixed, instead of the unnamed registry. That
+   way they can easily be run, but they do not make regression testing with
+   the default suite more difficult. E.g.:
+
+    // register in the unnamed registry so that these tests are run by default
+    //CPPUNIT_TEST_SUITE_REGISTRATION(wxRegExTestCase);
+    CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(wxRegExTestCase, "fixme");
+
+    // also include in its own registry so that these tests can be run alone
+    CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(wxRegExTestCase, "wxRegExTestCase");
+
+4. Tests which take a long time to execute can be registered under "advanced"
+   instead of the unnamed registry. The default suite should execute reasonably
+   quickly. To run the default and advanced tests together:
+    test "" advanced

 
 
 === EOF ===
 
 
 
 === EOF ===
 

-Author:  VZ
+Author:  VZ & MW

 Version: $Id$
 Version: $Id$