129 lines
5.4 KiB
Plaintext
129 lines
5.4 KiB
Plaintext
Unit tests and functional tests documentation.
|
|
|
|
Crossfire uses the 'check' C automated testing framework available at
|
|
http://check.sourceforge.net
|
|
The presence of this framework at compile time is not required but is STRONGLY
|
|
recommended for developpers. You should not commit changes to the CVS if they
|
|
are not unit tested. In fact you should even write your new test before writing
|
|
the change.
|
|
|
|
Organization
|
|
============
|
|
|
|
All automated tests are in subfolders of the test directory. Directory
|
|
structure is as follow:
|
|
|
|
test
|
|
+-rsc ** contains all runtime ressources unit tests might need (maps, etc)
|
|
+-include ** include files specific to unit tests
|
|
+-toolkit ** generic function and toolkit shared by several tests
|
|
+-unit ** contains all unit tests separated with same structure as tested code
|
|
| +-headers
|
|
| +-common
|
|
| +-socket
|
|
| +-random_maps
|
|
| +-server
|
|
+-bugs ** contains test of known bugs (fixed and opened)
|
|
| +-bugtrack ** Each file has the number of associated sourceforge bug id
|
|
| | +-bug_<id>.c
|
|
| +-unrelated ** Bugs that for a reason or another were not referenced on sf
|
|
+-functional ** contains all functional tests with structure of tested code
|
|
| +-common
|
|
| +-socket
|
|
| +-random_maps
|
|
| +-server
|
|
| +-general ** put here func test not in previous func categories
|
|
+-plugins
|
|
//structure still to be defined
|
|
|
|
All source file having tests in them should be named test_*.c
|
|
|
|
Unit Test
|
|
=========
|
|
Put in subfolders of test/unit, They test the various crossfire functions. You
|
|
must write exactly one test_xxx.c for each xxx.c in crossfire sourcecode. You
|
|
must test in this test_xxx each function available in xxx.c. If you add a
|
|
function to xxx.c, write a testcase in test_xxx.c
|
|
Do no put files other than the test_xyz.c where xyz.c is a crossfire
|
|
source file. If you need to write test that does not conform to this, this mean
|
|
they are not unit tests and should go to functional/*
|
|
|
|
when test/unit is complete, each function of crossfire will be tested at least
|
|
once.
|
|
|
|
Note: because crossfire makeis heavy use of macros, macros must be considered as
|
|
function and so must be unit tested too. Because macros are defined in .h file,
|
|
the unit test should have the form test_xxx for testing xxx.h. All unit tests
|
|
for .h files go to test/headers
|
|
|
|
Functional Test
|
|
===============
|
|
While unit tests are testing each function of the code, functionnal tests are
|
|
testing behaviour of the whole. They can test behaviour of server after a
|
|
specific series of actions and check the integration of various modules. So
|
|
they are not tied to specific .c file or specific function. However, most
|
|
testcases will be concerned by specific module, so try to put the in
|
|
corresponding test/function/<module> folder. If that's not possible, put them
|
|
in test/functional/general.
|
|
|
|
Bugs
|
|
====
|
|
When a bug is discovered, here is the procedure to follow:
|
|
1) write a testcase reproducing it (either in test/bugtrack or in
|
|
test/unrelated, depending upon the bug being reported on sf or not)
|
|
2) if the bug was not reported on sourceforge, provide enough information in
|
|
testcase comments to describe the bug, preferrably at the top of test
|
|
file, after the GPL licence header.
|
|
3) when you successfully wrote a failing testcase demonstrating the bug, start
|
|
to fix it (by writing the test you probably got a good idea of what goes
|
|
wrong and the automated test will test each fix attempt for you)
|
|
4) provide short information in test source code on what was wrong. If a later
|
|
change in crossfire revive the bug, it will help fix it quickly.
|
|
5) Commit your fix along with test.
|
|
6) If bug was reported on sourceforge, mark it closed or ask an admin to
|
|
close it. Mention you wrote a testcase for the bug.
|
|
|
|
Test ressources
|
|
===============
|
|
Some test requires maps, archetype or other kind of ressources to run. Those
|
|
are all provided in rsc or a subdirectory of it. Try to name those files
|
|
explicitly. Do not name it things like test-map or alike. Prefer forms like
|
|
rsc/maps/walls_blocks_move or like rsc/arch/selection_of_magic_books
|
|
each file in src/* should be documented in rsc/index.txt so other coders can
|
|
reuse those resources. Each subdirectory of rsc should have its own index file.
|
|
|
|
Toolkits
|
|
========
|
|
For some testcases (especially the functionnal one), you may need to have a
|
|
specific crossfire configuration loaded, or to do specific map operation. It
|
|
won't be surprising some of those operation are generic enough to be shared
|
|
amongst all testcases. Such support function (aka toolkits) will be made
|
|
available in the toolkit directory.
|
|
|
|
Includes
|
|
========
|
|
Testcases will share some include files not present in crossfire core. Those
|
|
test specific headers will be put in includes
|
|
|
|
|
|
How to add a subdirectory to test/
|
|
==================================
|
|
Directory to create is assumed to be "bugs/bugtrack"
|
|
|
|
Steps:
|
|
* edit test/Makefile.am, add in the SUBDIR line "bugs"
|
|
* copy eg unit/Makefile.am to bugs/Makefile.am
|
|
* edit this file:
|
|
* change the values for CHECK_FOLDER to bugs (will then read "CHECK_FOLDER=bugs")
|
|
* change the SUBDIRS line to "bugtrack"
|
|
* copy eg unit/server/Makefile.am to bugs/bugtrack/Makefile.am
|
|
* edit this file:
|
|
* change the TESTS line to add your files
|
|
* change CHECK_FOLDER to bugs/bugtrack
|
|
* change CHECK_PARENT_NAME to Bugs
|
|
* in server root, edit configure.ac to add to Makefile output test/bugs/Makefile and
|
|
test/bugs/bugtrack/Makefile
|
|
* in server root, run "sh autogen.sh" to regenerate the Makefiles
|
|
|
|
Your new test should be ready to run.
|