From 98bd91125d5757d245de4fe0a0c9698c4cab89d1 Mon Sep 17 00:00:00 2001 From: Matthew Cline Date: Sat, 21 Nov 2009 03:04:42 -0800 Subject: docs/devel/testing.txt: ways of testing Crawl --- crawl-ref/docs/develop/testing.txt | 180 +++++++++++++++++++++++++++++++++++++ 1 file changed, 180 insertions(+) create mode 100644 crawl-ref/docs/develop/testing.txt (limited to 'crawl-ref/docs') 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. -- cgit v1.2.3-54-g00ecf