attempts at documentation

This is my understanding of how xpcshell test harness works, not reviewed yet. --Nickolay 16:14, 6 September 2006 (PDT)

Creating the first test for a module

This section explains what needs to be done before creating a unit test for a module that doesn't have any tests yet:

Copy mozilla/tools/test-harness/xpcshell-simple/example to yourmoduledir/test
In yourmoduledir/test/Makefile.in change DEPTH and MODULE appropriately:

DEPTH should be a relative path pointing to mozilla/, e.g. if you're in netwerk/test, set DEPTH = ../..
MODULE should have a value of form test_yourmodule.

Reference the test dir in a parent makefile (yourmoduledir/Makefile.in):

ifdef ENABLE_TESTS
TOOL_DIRS  += test
endif

(Optional, but recommended) Add the new makefile to allmakefiles.sh (TODO: need more details about this)

Reconfigure (e.g. with make -f client.mk configure)

make / make check in yourmodule

You're now ready to start writing unit tests themselves.

You should place your test files in yourmoduledir/test/unit. There are actually three types of files that can be put there:

head_*.js - arbitrary JS code that gets executed before the tests are run.
test_*.js - the unit tests themselves.
tail_*.js - arbitrary JS code that gets executed after the actual tests are run.

In test_*.js files you can use the objects you defined in your head_*.js files, as well as common functions for unit tests defined in head.js

TODO: briefly document available functions here, see Necko:UnitTests

The unit tests can be run using make check or using test_all.sh directly:

To use make check, cd to an appropriate directory (e.g. to run tests for a single module, go to modulepath/test) and run make check.
When using test_all.sh, either cd to the folder with unit test files and run test_all.sh or run it from dist/bin with the directory containing the unit test files as a parameter, e.g.:
```
bash test_all.sh test_mymodule
```