crawl-common 2:0.13.1-1 / usr / share / crawl / docs / develop / testing.txt

A.   Unit tests
===============

Crawl has a set of unit tests in the source/test/ directory, with each lua
file being a separate unit test.  To use unit tests, you must compile Crawl
either with the macro DEBUG_DIAGNOSTICS defined (the debug make target) or
with both the macros DEBUG and DEBUG_TESTS defined (the wizard make target,
plus -DDEBUG_TESTS).  You can then do

    crawl -test

to run the unit tests.  To run paricular unit tests, you can do

    crawl -test foo

and that will run all unit tests which have "foo" in their file name.

If you want to write your own unit tests, take a look at the files in
source/test for examples.  test/los_maps.lua and test/bounce.lua have
examples which use vaults (maps) which are located in test/des.  You
might need to create new Lua functions in the source/l_*.cc files if none of
the crawl.foo()/dgn.foo()/etc functions do what you need.

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

B.    Testing with the arena
============================

Crawl's arena mode can be used to pit one set of monsters against another and
watch them fight.  For example,

    crawl -arena "3 rat v 2 kobold"

pits 3 rats against 2 kobolds.

If you put "arena_dump_msgs = true" into your crawl init file, then most
messages generated during the fight will be dumped to the file "arena.result".
Also adding "arena_dump_msgs_all = true" will additionally cause messages to
the diagnostics channel to be dumped.  Messages to some channels will be
prefixed with the channel name, to make grepping for results easier:

    MSGCH_ERROR is prefixed with "ERR:"
    MSGCH_WARN is prefixed with "WARN:"
    MSGCH_DIAGNOSTICS is prefixed with "DIAG:"
    MSGCH_SOUND is prefixed with "SOUND:
    The TALK channels are prefixed with "TALK:"

See docs/arena.txt for more details.

B.1  Testing specific problems with the arena
=============================================

Using the arena to test problems with specific monsters is rather easy:

    crawl -arena "problem monster v problem monster"

For specific ego items is not much harder.  Say you had a problem with chaos
branded melee items.  You could do

    crawl -arena "10 vault guard; long sword ego:chaos v
                  10 vault guard; long sword ego:chaos"

to pit two groups of 10 vault guards against each other, all armed with chaos
long swords.

Or if you wanted to test ammo of penetration:

    crawl -arena "10 centaur ; bow . arrow ego:penetration v
                  10 centaur ; bow . arrow ego:penetration"

Note that:

1) You have to specify "bow", since giving monsters any specific items at all
strips them of all the standard items they are normally generated with.

2) Different items are separated by "."

3) You don't use plurals in the item specification; for something like arrows
an appropriate amount is given automatically.

For more on monster and item specifications, look up ITEM and MONS in
docs/develop/level/syntax.txt

B.2  Testing general problems with the arena
============================================

You can also use the arena to just see if anything unusual is happening, or if
you can catch any crashes for unknown issues.

    crawl -arena "10 random v 10 random"

would pit two teams of random monsters against each other, appropriate for
D:20.  To change the place chosen for choosing random monsters, you can use
"arena_place:"

    crawl -arena "arena_place:D:27 10 random v 10 random"
    crawl -arena "arena_place:Abyss 10 random v 10 random"
    crawl -arena "arena_place:Zot:5 10 random v 10 random"
    etc

Note that "arena_place" controls what's generated by the spell Shadow
Creatures, in addition to the "random" monster spec used in the command line.

You can also pit random uniques against each other (this also affects Shadow
Creatures as well):

    crawl -arena "random_uniques 10 random v 10 random"

You might find that certain random monsters overwhelm the arena run, like
maybe jellies are eating so many corpses that they fill the whole arena.  You
can forbid monsters with certain glyphs from being randomly generated:

    crawl -arena "ban_glyphs:J 10 random v 10 random"

B.3  Getting the arena to run for a long time
==============================================

By default the arena exits when all the monsters on one team die, ending the
round.  You can specify that multiple rounds happen by adding "t:num", but
that's limited to 99 rounds.  A way to make it so that the arena will run
forever (or until you press ESC to exit it) is to add the "respawn" tag to the
arena specification.  You can then leave Crawl running under a debugger
waiting for a crash, or simply grep the arena.result file after it's run for
long enough.

For example:

    crawl -arena "respawn rat v kobold"

Will make it so that whenever the rat dies it's replaced by a new rat, and the
same for the kobold.

    crawl -arena "respawn random v random"

Will cause a new, random monster for the same team to be placed whenever one
or the other dies.

If you do

    crawl -arena "respawn 10 random v 10 random"

then the monsters tend to clump up in the middle in a huge brawl.  A way to
spread this out is by adding "move_respawns":

    crawl -arena "respawn move_respawns 10 random v 10 random"

This will make it so that when a monster respawns, it's teleported to a random
location in the arena, spreading out the fights.

Finally, if you're using non-unique random monsters, you can add
"cycle_random" so that the random monsters are chosen by linearly cycling
through the monsters that can possibly appear in the place chosen by
"arena_place:", rather than being chosen with the weights appropriate for that
place.  This will cause rare monsters to be generated a lot more often.

B.4  Speeding up the arena
==========================

You can speed up the arena by reducing the delay in miliseconds between turns.
You can do this on the command line with "delay:":

    crawl -arena "delay:0 random v random"

This will cause there to be no delay between turns, or when animating beams or
explosions.  You can also set the option "arena_delay" in your init file to
have it apply to all arena runs.

B.5  Changing the arena terrain
===============================

You can change the terrain used in the arena with the "arena:" tag.  For
example:

    crawl -arena "arena:smoke random v random"

will cause the monsters to fight in an arena which is filled with smoke.  The
available alternate terrains are in source/dat/arena.des.  If an arena you
want is tagged with "arena_foo" in the des file, then you put "arena:foo" on
the command line.