git.saurik.com Git - wxWidgets.git/blame_incremental

... / ...

Commit	Line	Data
	1	How to write unit tests for wxWidgets
	2	=====================================
	3
	4	Unit tests for wxWidgets are written using small cppunit framework. To compile
	5	(but not to run) them you need to have it installed. Hence the first part of
	6	this note explains how to do it while the second one explains how to write the
	7	test.
	8
	9	I. CppUnit Installation
	10	-----------------------
	11
	12	1. Get it from http://www.sourceforge.net/projects/cppunit
	13	(latest version as of the time of this writing is 1.8.0)
	14
	15	2. Build the library:
	16	a) Under Windows using VC++ (both versions 6 and 7 work):
	17	- build everything in CppUnitLibraries.dsw work space
	18	- add include and lib subdirectories of the directory
	19	where you installed cppunit to the compiler search path
	20	using "Tools\|Options" menu in VC IDEA
	21
	22	b) Under Unix: run configure && make && make install as usual
	23
	24
	25	II. Writing tests with CppUnit
	26	------------------------------
	27
	28	1. Create a new directory tests/foo
	29
	30	2. Write a cpp file for the test copying, if you want,
	31	from one of the existing tests. The things to look for:
	32	a) #include "wx/cppunit.h" instead of directly including CppUnit headers
	33	b) don't put too many things in one test case nor in one method of a test
	34	case as it makes understanding what exactly failed harder later
	35	c) 'register' your tests as follows so that the test program will find and
	36	execute them:
	37
	38	// register in the unnamed registry so that these tests are run by default
	39	CPPUNIT_TEST_SUITE_REGISTRATION(MBConvTestCase);
	40
	41	// also include in it's own registry so that these tests can be run alone
	42	CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(MBConvTestCase, "MBConvTestCase");
	43
	44	Read CppUnit documentation for more.
	45
	46	3. add a '<sources>' tag for your source file to tests/test.bkl
	47
	48
	49	III. Running the tests
	50	----------------------
	51
	52	1. Regenerate the make/project files from test.bkl using bakefile_gen, e.g.:
	53	cd build/bakefiles
	54	bakefile_gen -b ../../tests/test.bkl
	55	and if you're on a unix system re-run configure.
	56
	57	2. Build the test program using one of the make/project files in the tests
	58	subdirectory.
	59
	60	3. Run the test program with no arguments to run the default set of tests
	61	(which are all those registered with CPPUNIT_TEST_SUITE_REGISTRATION).
	62	Or to list the test suites without running them:
	63	test -l
	64
	65	4. Tests that have been registered under a name using
	66	CPPUNIT_TEST_SUITE_NAMED_REGISTRATION can also be run separately. For
	67	example:
	68	test MBConvTestCase
	69	or to list the tests:
	70	test -L MBConvTestCase
	71
	72	5. Fault navigation.
	73	VC++ users can run the programs as a post build step (Projects/Settings/
	74	Post-build step) to see the test results in an IDE window. This allows
	75	errors to be jumped to in the same way as for compiler errors, for
	76	example by pressing F4 or highlighting the error and pressing return.
	77
	78	Similarly for makefile users: makefiles can be modified to execute the
	79	test programs as a final step. Then you can navigate to any errors in the
	80	same way as for compiler errors, if your editor supports that.
	81
	82	Another alternative is to run the tests manually, redirecting the output
	83	to a file. Then use your editor to jump to any failures. Using Vim, for
	84	example, ':cf test.log' would take you to the first error in test.log, and
	85	':cn' to the next.
	86
	87	If you would like to set a breakpoint on a failing test using a debugger,
	88	put the breakpoint on the function 'CppUnit::Asserter::fail()'. This will
	89	stop on each failing test.
	90
	91
	92	IV. Notes
	93	---------
	94
	95	1. You can register your tests (or a subset of them) just under a name, and not
	96	in the unnamed registry if you don't want them to be executed by default.
	97
	98	2. If you are going to register your tests both in the unnamed registry
	99	and under a name, then use the name that the tests have in the 'test -l'
	100	listing.
	101
	102	3. Tests which fail can be temporarily registered under "fixme" while the
	103	problems they expose are fixed, instead of the unnamed registry. That
	104	way they can easily be run, but they do not make regression testing with
	105	the default suite more difficult. E.g.:
	106
	107	// register in the unnamed registry so that these tests are run by default
	108	//CPPUNIT_TEST_SUITE_REGISTRATION(wxRegExTestCase);
	109	CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(wxRegExTestCase, "fixme");
	110
	111	// also include in it's own registry so that these tests can be run alone
	112	CPPUNIT_TEST_SUITE_NAMED_REGISTRATION(wxRegExTestCase, "wxRegExTestCase");
	113
	114	4. Tests which take a long time to execute can be registered under "advanced"
	115	instead of the unnamed registry. The default suite should execute reasonably
	116	quickly. To run the default and advanced tests together:
	117	test "" advanced
	118
	119
	120	=== EOF ===
	121
	122	Author: VZ & MW
	123	Version: $Id$