docs/devel/testing.txt: ways of testing Crawl

1 files changed, 180 insertions, 0 deletions

diff --git a/crawl-ref/docs/develop/testing.txt b/crawl-ref/docs/develop/testing.txt
new file mode 100644
index 0000000000..aae8c106cd
--- /dev/null
+++ b/crawl-ref/docs/develop/testing.txt
@@ -0,0 +1,180 @@
+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 example.  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 dies, 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 "respwan 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.