Add documentation to more WML unit tests.

data/test/scenarios/ability_id_active_test.cfg

@@ -11,7 +11,6 @@
 # Expected end state:
 # [have_unit]ability_id_active triggers on each recruit.
 #####
-
 {GENERIC_UNIT_TEST test_ability_id_active (
     [event]
         name=start

data/test/scenarios/ability_id_not_active_test.cfg

@@ -11,7 +11,6 @@
 # Expected end state:
 # [not][have_unit]ability_id_active does not trigger on either recruit
 #####
-
 {GENERIC_UNIT_TEST test_ability_id_not_active (
     [event]
         name=start

data/test/scenarios/as_text.cfg

@@ -1,7 +1,6 @@
 #####
 # API(s) being tested: wesnoth.as_text
 #####
-
 {GENERIC_UNIT_TEST "as_text" (
     [event]
         name = prestart

data/test/scenarios/feeding.cfg

@@ -9,7 +9,6 @@
 # Expected end state:
 # The Ghast gains +1 max hp.
 #####
-
 {GENERIC_UNIT_TEST "feeding_on_living" (
     [event]
         name=start
@@ -73,7 +72,6 @@
 # Expected end state:
 # The first Ghast does not gain +1 max hp.
 #####
-
 {GENERIC_UNIT_TEST "feeding_on_dead" (
     [event]
         name=start

data/test/scenarios/filter_this_unit.cfg

@@ -7,7 +7,6 @@
 # Expected end state:
 # bob's hp has been reduced by half.
 #####
-
 {GENERIC_UNIT_TEST filter_this_unit_wml (
     [event]
         name=prestart
@@ -37,7 +36,6 @@
 # Expected end state:
 # bob's level has been set to 2.
 #####
-
 {GENERIC_UNIT_TEST filter_this_unit_tl (
     [event]
         name=prestart
@@ -65,7 +63,6 @@
 # Expected end state:
 # bob's remaining moves is less than it's max moves.
 #####
-
 {GENERIC_UNIT_TEST filter_this_unit_formula (
     [event]
         name=prestart
@@ -93,7 +90,6 @@
 # Expected end state:
 # bob's remaining moves is less than it's max moves.
 #####
-
 {GENERIC_UNIT_TEST filter_formula_unit (
     [event]
         name=prestart
@@ -122,7 +118,6 @@
 # A warning is logged.
 # WML execution is otherwise not interrupted.
 #####
-
 {GENERIC_UNIT_TEST filter_formula_unit_error (
     [event]
         name=prestart

data/test/scenarios/filter_vision.cfg

@@ -112,7 +112,6 @@
 # Expected end state:
 # That any side sees each other.
 #####
-
 {TEST_FILTER_VISION_SCEN "filter_vision_all_no_side" (
     [event]
         name=start
@@ -128,7 +127,6 @@
 # Expected end state:
 # That side 2 sees any side.
 #####
-
 {TEST_FILTER_VISION_SCEN "filter_vision_all_side_2" (
     [event]
         name=start
@@ -144,7 +142,6 @@
 # Expected end state:
 # That side 4 sees any side.
 #####
-
 {TEST_FILTER_VISION_SCEN "filter_vision_all_side_4" (
     [event]
         name=start
@@ -160,7 +157,6 @@
 # Expected end state:
 # That side 1 sees side 4.
 #####
-
 {TEST_FILTER_VISION_SCEN "filter_vision_side_1_side_4" (
     [event]
         name=start
@@ -176,7 +172,6 @@
 # Expected end state:
 # That side 2 sees side 4.
 #####
-
 {TEST_FILTER_VISION_SCEN "filter_vision_side_2_side_4" (
     [event]
         name=start
@@ -192,7 +187,6 @@
 # Expected end state:
 # That side 3 sees side 4.
 #####
-
 {TEST_FILTER_VISION_SCEN "filter_vision_side_3_side_4" (
     [event]
         name=start
@@ -208,7 +202,6 @@
 # Expected end state:
 # That side side 4 sees side 1.
 #####
-
 {TEST_FILTER_VISION_SCEN "filter_vision_side_4_side_1" (
     [event]
         name=start
@@ -224,7 +217,6 @@
 # Expected end state:
 # That side 4 sees side 3.
 #####
-
 {TEST_FILTER_VISION_SCEN "filter_vision_side_4_side_3" (
     [event]
         name=start
@@ -240,7 +232,6 @@
 # Expected end state:
 # That side 4 does not see side 2.
 #####
-
 {TEST_FILTER_VISION_SCEN "filter_vision_side_4_not_side_2" (
     [event]
         name=start
@@ -256,7 +247,6 @@
 # Expected end state:
 # That no side sees a non-existent side.
 #####
-
 {TEST_FILTER_VISION_SCEN "filter_vision_not_side_5" (
     [event]
         name=start

data/test/scenarios/for-loops.cfg

@@ -73,7 +73,6 @@
 # Expected end state:
 # An error is logged and the rest of the event is skipped.
 #####
-
 {FOR_LOOP_TEST_STEP forloop_all_zero 0 0 0 (
     [event]
         name=no_error
@@ -94,7 +93,6 @@
 # Expected end state:
 # An error is logged and the rest of the event is skipped.
 #####
-
 {FOR_LOOP_TEST_STEP forloop_step_zero 0 1 0 (
     [event]
         name=no_error
@@ -115,7 +113,6 @@
 # Expected end state:
 # The loop executes once.
 #####
-
 {FOR_LOOP_TEST_STEP forloop_once_positive 0 0 1 (
     [event]
         name=no_error
@@ -136,7 +133,6 @@
 # Expected end state:
 # The loop executes once.
 #####
-
 {FOR_LOOP_TEST_STEP forloop_once_negative 0 0 -1 (
     [event]
         name=no_error
@@ -157,7 +153,6 @@
 # Expected end state:
 # The loop executes twice.
 #####
-
 {FOR_LOOP_TEST_STEP forloop_twice_matched 0 1 1 (
     [event]
         name=no_error
@@ -178,7 +173,6 @@
 # Expected end state:
 # The loop does not execute.
 #####
-
 {FOR_LOOP_TEST_STEP forloop_twice_unmatched 0 1 -1 (
     [event]
         name=no_error
@@ -199,7 +193,6 @@
 # Expected end state:
 # The loop executes twice.
 #####
-
 {FOR_LOOP_TEST_STEP forloop_step_large_positive 0 10 10 (
     [event]
         name=no_error
@@ -220,7 +213,6 @@
 # Expected end state:
 # The loop executes twice.
 #####
-
 {FOR_LOOP_TEST_STEP forloop_step_large_negative 10 0 -10 (
     [event]
         name=no_error
@@ -241,7 +233,6 @@
 # Expected end state:
 # It successfully does nothing.
 #####
-
 {GENERIC_UNIT_TEST forloop_empty_array (
     [event]
         name=start
@@ -275,7 +266,6 @@
 # Expected end state:
 # The value retreived during the final loop is 2.
 #####
-
 {FOR_LOOP_ARRAY_TEST forloop_array 2 no}
 
 #####
@@ -287,7 +277,6 @@
 # Expected end state:
 # The value retrieved from the final loop is 10.
 #####
-
 {FOR_LOOP_ARRAY_TEST forloop_array_reverse 10 yes}
 
 #####
@@ -300,7 +289,6 @@
 # Expected end state:
 # It correctly ends after two loops.
 #####
-
 {GENERIC_UNIT_TEST forloop_array_mutate (
     [event]
         name=start

data/test/scenarios/has_ally.cfg

@@ -53,7 +53,13 @@
     [/test]
 #enddef
 
-{TEST_HAS_ALLY_SCEN "has_ally" (
+#####
+# API(s) being tested: [has_ally],[has_unit]
+##
+# Expected end state:
+# dave is allied to bob.
+#####
+{TEST_HAS_ALLY_SCEN "dave_has_ally_bob" (
     [event]
         name=start
         {ASSERT (
@@ -68,6 +74,19 @@
                 [/filter_side]
             [/have_unit]
         )}
+        {SUCCEED}
+    [/event]
+)}
+
+#####
+# API(s) being tested: [has_enemy],[has_unit]
+##
+# Expected end state:
+# dave is an enemy of alice.
+#####
+{TEST_HAS_ALLY_SCEN "dave_has_enemy_alice" (
+    [event]
+        name=start
         {ASSERT (
             [have_unit]
                 id=dave
@@ -80,6 +99,19 @@
                 [/filter_side]
             [/have_unit]
         )}
+        {SUCCEED}
+    [/event]
+)}
+
+#####
+# API(s) being tested: [has_ally],[has_unit]
+##
+# Expected end state:
+# dave is not an ally of steve.
+#####
+{TEST_HAS_ALLY_SCEN "dave_not_has_ally_steve" (
+    [event]
+        name=start
         {ASSERT (
             [have_unit]
                 id=dave
@@ -94,6 +126,19 @@
                 [/filter_side]
             [/have_unit]
         )}
+        {SUCCEED}
+    [/event]
+)}
+
+#####
+# API(s) being tested: [has_enemy]
+##
+# Expected end state:
+# dave is an enemy of sides 1 and 4.
+#####
+{TEST_HAS_ALLY_SCEN "dave_has_enemy_sides" (
+    [event]
+        name=start
         {ASSERT (
             [have_unit]
                 id=dave
@@ -104,6 +149,19 @@
                 [/filter_side]
             [/have_unit]
         )}
+        {SUCCEED}
+    [/event]
+)}
+
+#####
+# API(s) being tested: [has_ally],[has_unit]
+##
+# Expected end state:
+# dave is not an ally of charlie.
+#####
+{TEST_HAS_ALLY_SCEN "not_dave_has_ally_charlie" (
+    [event]
+        name=start
         {ASSERT (
             [not]
                 [have_unit]

data/test/scenarios/heal.cfg

@@ -44,6 +44,17 @@
     [/if]
 #enddef
 
+#####
+# API(s) being tested: [heals]
+##
+# Actions:
+# Spawn a healer next to each leader.
+# Set all four units (two healers, two leaders) to 1 current hp and 999 max hp.
+# End turns and let healing be done.
+##
+# Expected end state:
+# Healing from the healer units as well as rest healing are applied correctly.
+#####
 {GENERIC_UNIT_TEST "heal" (
     [event]
         name = start
@@ -150,5 +161,4 @@
         name=turn 5
         {SUCCEED}
     [/event]
-
 )}

data/test/scenarios/interrupts.cfg

@@ -1,4 +1,12 @@
-
+#####
+# API(s) being tested: [break]
+##
+# Actions:
+# Break out of an infinite loop with [break].
+##
+# Expected end state:
+# The loop exits.
+#####
 {GENERIC_UNIT_TEST check_interrupts_break (
     [event]
         name=start
@@ -19,6 +27,15 @@
     [/event]
 )}
 
+#####
+# API(s) being tested: [return]
+##
+# Actions:
+# Break out of an infinite loop with [return], which also skips the rest of the event.
+##
+# Expected end state:
+# The loop exits.
+#####
 {GENERIC_UNIT_TEST check_interrupts_return (
     [event]
         name=start
@@ -43,6 +60,15 @@
     [/event]
 )}
 
+#####
+# API(s) being tested: [continue]
+##
+# Actions:
+# Use [continue] to skip part of a loop.
+##
+# Expected end state:
+# The part of the loop after the [continue] is not executed.
+#####
 {GENERIC_UNIT_TEST check_interrupts_continue (
     [event]
         name=start
@@ -59,6 +85,12 @@
     [/event]
 )}
 
+#####
+# API(s) being tested: [break]
+##
+# Expected end state:
+# [break] skips the rest of the event.
+#####
 {GENERIC_UNIT_TEST check_interrupts_break_global (
     [event]
         name=start
@@ -71,6 +103,15 @@
     [/event]
 )}
 
+#####
+# API(s) being tested: wesnoth.wml_actions.continue
+##
+# Actions:
+# Use continue directly in an event, outside a loop.
+##
+# Expected end state:
+# it causes an error.
+#####
 {GENERIC_UNIT_TEST check_interrupts_continue_global (
     [event]
         name=start
@@ -102,6 +143,12 @@
     [/event]
 )}
 
+#####
+# API(s) being tested: [command][return]
+##
+# Expected end state:
+# [return] skips the entire rest of the event, not just the [command] it's nested in.
+#####
 {GENERIC_UNIT_TEST check_interrupts_return_nested (
     [event]
         name=start
@@ -117,6 +164,12 @@
     [/event]
 )}
 
+#####
+# API(s) being tested: [elseif][return]
+##
+# Expected end state:
+# [return] skips the entire rest of the event, not just the [elseif] it's nested in.
+#####
 {GENERIC_UNIT_TEST check_interrupts_elseif (
     [event]
         name=start
@@ -152,6 +205,12 @@
     [/event]
 )}
 
+#####
+# API(s) being tested: [elseif][return]
+##
+# Expected end state:
+# [return] skips the entire rest of the event, not just the [case] it's nested in.
+#####
 {GENERIC_UNIT_TEST check_interrupts_case (
     [event]
         name=start

data/test/scenarios/lua_functional.cfg

@@ -1,7 +1,14 @@
 #textdomain wesnoth-test
 
-# Tests for the functional.lua library
-{GENERIC_UNIT_TEST "lua_functional" (
+#####
+# API(s) being tested: reduce()
+##
+# Expected end state:
+# The reduce on an empty table returns nil.
+# The reduce on two boolean false values returns false.
+# The reduce on a table of numbers to add them sums the provided values.
+#####
+{GENERIC_UNIT_TEST "lua_functional_reduce" (
     [event]
         name = start
         [lua]

data/test/scenarios/lua_map_find.cfg

@@ -1,6 +1,14 @@
 #textdomain wesnoth-test
 
-# Tests for the game kernel's version of w.map.find.
+#####
+# API(s) being tested: wesnoth.map.find()
+##
+# Expected end state:
+# The expected plain terrain is found.
+# The expected terrain with an overlay is found.
+# The expected terrain is found using wildcards.
+# The expected width and height is returned.
+#####
 {GENERIC_UNIT_TEST "lua_map_find" (
     [event]
         name = start

data/test/scenarios/mapgen_filter.cfg

@@ -1,8 +1,15 @@
 #textdomain wesnoth-test
 
-# Check that the mapgen kernel's wesnoth.map.filter correctly handles "terrain" values.
-# This will load the generic_unit_test map, change all of the hexes that are between Alice's and
-# Bob's castles to void, and then check that the map looks as expected.
+#####
+# API(s) being tested: [generator]create_map=,wesnoth.map.filter()
+##
+# Actions:
+# The generic test map is loaded.
+# All of the hexes that are between Alice's and Bob's castles are changed to void based on terrain type.
+##
+# Expected end state:
+# The map looks as expected.
+#####
 {GENERIC_UNIT_TEST "mapgen_filter_terrain" (
     map_generation=lua
     map_data=""
@@ -48,9 +55,16 @@
     [/event]
 )}
 
-# Check that the mapgen kernel's wesnoth.map.filter correctly handles "x" and "y" ranges.
-# This will load the generic_unit_test map, change all of the hexes that are between Alice's and
-# Bob's castles to void, and then check that the map looks as expected.
+#####
+# API(s) being tested: [generator]create_map=,wesnoth.map.filter()
+##
+# Actions:
+# The generic test map is loaded.
+# All of the hexes that are between Alice's and Bob's castles are changed to void based on x and y coordinates.
+##
+# Expected end state:
+# The map looks as expected.
+#####
 {GENERIC_UNIT_TEST "mapgen_filter_range" (
     map_generation=lua
     map_data=""

data/test/scenarios/move_skip_sighted.cfg

@@ -69,9 +69,80 @@
     [/test]
 #enddef
 
+#####
+# API(s) being tested: [move]skip_sighted=,[side]share_vision=
+##
+# Actions:
+# Move a unit from 16,3 to 11,3.
+# The sighted event is not skipped.
+# No vision is shared.
+##
+# Expected end state:
+# The moved unit stops at 15,3.
+#####
 {MOVE_SKIP_SIGHTED_SCEN move_skip_no_sighted_no_share_vision 15 3 no none}
+
+#####
+# API(s) being tested: [move]skip_sighted=,[side]share_vision=
+##
+# Actions:
+# Move a unit from 16,3 to 11,3.
+# The sighted event is skipped for allies.
+# No vision is shared.
+##
+# Expected end state:
+# The moved unit stops at 12,3.
+#####
 {MOVE_SKIP_SIGHTED_SCEN move_skip_ally_sighted_no_share_vision 12 3 only_ally none}
+
+#####
+# API(s) being tested: [move]skip_sighted=,[side]share_vision=
+##
+# Actions:
+# Move a unit from 16,3 to 11,3.
+# The sighted event is always skipped.
+# No vision is shared.
+##
+# Expected end state:
+# The moved unit stops at 11,3.
+#####
 {MOVE_SKIP_SIGHTED_SCEN move_skip_all_sighted_no_share_vision 11 3 all none}
+
+#####
+# API(s) being tested: [move]skip_sighted=,[side]share_vision=
+##
+# Actions:
+# Move a unit from 16,3 to 11,3.
+# The sighted event is not skipped.
+# All vision is shared.
+##
+# Expected end state:
+# The moved unit stops at 11,3.
+#####
 {MOVE_SKIP_SIGHTED_SCEN move_skip_no_sighted_yes_share_vision 11 3 no all}
+
+#####
+# API(s) being tested: [move]skip_sighted=,[side]share_vision=
+##
+# Actions:
+# Move a unit from 16,3 to 11,3.
+# The sighted event is skipped for allies.
+# All vision is shared.
+##
+# Expected end state:
+# The moved unit stops at 11,3.
+#####
 {MOVE_SKIP_SIGHTED_SCEN move_skip_ally_sighted_yes_share_vision 11 3 only_ally all}
+
+#####
+# API(s) being tested: [move]skip_sighted=,[side]share_vision=
+##
+# Actions:
+# Move a unit from 16,3 to 11,3.
+# The sighted event is always skipped.
+# All vision is shared.
+##
+# Expected end state:
+# The moved unit stops at 11,3.
+#####
 {MOVE_SKIP_SIGHTED_SCEN move_skip_all_sighted_yes_share_vision 11 3 all all}

data/test/scenarios/order_of_nested_events.cfg

@@ -1,17 +1,17 @@
-# The purpose of this test is to check that a First in, First out
-# order of events is being respected.
-#
-# A variable X is set to 1 during prestart, and just after
-# a start event is registered which would set it to 0.
-#
-# Within the scenario tag, a start event is also registered
-# to return (X == 1).
-#
-# If the "nested" event runs before the outer level start event,
-# we fail the test. The outer event should run first because
-# all of the events in [scenario] are registered before any
-# of them is executed.
+# The purpose of this test is to check that a First in, First out order of events is being respected.
+# The outer event should run first because all of the events in [scenario] are registered before any of them is executed.
 
+#####
+# API(s) being tested: [event]
+##
+# Actions:
+# Set X to 1 in the prestart event.
+# Set X to 0 in a nested start event.
+# Check if X is 1 in a non-nested start event.
+##
+# Expected end state:
+# The nested start event runs after the non-nested start event.
+#####
 {GENERIC_UNIT_TEST "order_of_nested_events" (
     [event]
         name = prestart

data/test/scenarios/poison_opponent.cfg

@@ -1,4 +1,15 @@
 # this unit test what 'poison' applied to opponent work perfectly after fixing.
+
+#####
+# API(s) being tested: [poison]apply_to=opponent
+##
+# Actions:
+# Give both units the poison weapon special.
+# Have both units hit each other.
+##
+# Expected end state:
+# Both units are poisoned.
+#####
 {GENERIC_UNIT_TEST "poison_opponent" (
     [event]
         name=start

data/test/scenarios/prestart_settings.cfg

@@ -1,8 +1,12 @@
-# Tests how various variable settings occurring in prestart
-# and in early events work out.
-# For example, whether setting gold of a side in prestart works, or goes OOS
-# Also, whether setting the turn counter works.
-
+#####
+# API(s) being tested: [modify_side]gold=
+##
+# Actions:
+# Give side 1 666 gold in a prestart event.
+##
+# Expected end state:
+# Side 1 has 666 gold when checked in a side 1 turn 1 event.
+#####
 {GENERIC_UNIT_TEST "set_gold_in_prestart_one" (
     [event]
         name=prestart
@@ -21,6 +25,15 @@
     [/event]
 )}
 
+#####
+# API(s) being tested: [gold]amount=
+##
+# Actions:
+# Give side 1 an additional 566 gold in a prestart event.
+##
+# Expected end state:
+# Side 1 has 666 gold when checked in a side 1 turn 1 event.
+#####
 {GENERIC_UNIT_TEST "set_gold_in_prestart_two" (
     [event]
         name=prestart
@@ -38,6 +51,15 @@
     [/event]
 )}
 
+#####
+# API(s) being tested: [modify_turns]value=
+##
+# Actions:
+# Set the turn limit to 42 in a prestart event.
+##
+# Expected end state:
+# The turn limit is 42 when checked in a side 1 turn 1 event.
+#####
 {GENERIC_UNIT_TEST "modify_turns_one" (
     [event]
         name=prestart
@@ -54,6 +76,15 @@
     [/event]
 )}
 
+#####
+# API(s) being tested: [modify_turns]current=
+##
+# Actions:
+# Set the current turn to 42 in a prestart event.
+##
+# Expected end state:
+# The next event to trigger is the side 1 turn 42 event.
+#####
 {GENERIC_UNIT_TEST "modify_turns_two" (
     [event]
         name=prestart
@@ -71,6 +102,15 @@
     [/event]
 )}
 
+#####
+# API(s) being tested: [modify_turns]current=
+##
+# Actions:
+# Set the current turn to 42 in a side 1 turn 1 event.
+##
+# Expected end state:
+# The next event to trigger is the side 1 turn 1 refresh event.
+#####
 {GENERIC_UNIT_TEST "modify_turns_three" (
     [event]
         name=side 1 turn 1
@@ -88,6 +128,16 @@
     [/event]
 )}
 
+#####
+# API(s) being tested: [modify_turns]current=
+##
+# Actions:
+# Set the current turn to 42 in a side 1 turn 1 event.
+# End the turn
+##
+# Expected end state:
+# The next event to trigger is the side 2 turn 42 event.
+#####
 {GENERIC_UNIT_TEST "modify_turns_four" (
     [event]
         name=side 1 turn 1
@@ -114,6 +164,15 @@
     [/event]
 )}
 
+#####
+# API(s) being tested: [replace_schedule]
+##
+# Actions:
+# Replace the current time schedule with only dusk in a prestart event.
+##
+# Expected end state:
+# The current time is dusk when checked from a side 1 turn 1 event.
+#####
 {GENERIC_UNIT_TEST "replace_schedule_prestart" (
     [event]
         name=prestart

data/test/scenarios/put_to_recall_and_modify.cfg

@@ -1,5 +1,9 @@
 #textdomain wesnoth-test
 
+# This is almost the same as the modify_unit_which_recall_list test, except that
+# creating Charlie on the map can leave an on-map x,y pair in Charlie's data,
+# which needs to be handled within the WML API.
+
 #####
 # API(s) being tested: [put_to_recall_list], [modify_unit], [role][auto_recall]
 ##
@@ -12,10 +16,6 @@
 # Expected end state:
 # Charlie is on the map next to side 2's leader.
 #####
-
-# This is almost the same as the modify_unit_which_recall_list test, except that
-# creating Charlie on the map can leave an on-map x,y pair in Charlie's data,
-# which needs to be handled within the WML API.
 {GENERIC_UNIT_TEST "put_to_recall_and_modify" (
     [event]
         name = start

data/test/scenarios/recall_by_unit_tag.cfg

@@ -1,13 +1,19 @@
 # wmllint: no translatables
 
-# The [unit] tag can recall units if a unit with that id already exists
-# on the recall list. Some edge cases were unclear, so this test finds
-# out what they do.
-#
 # This is a test where any failure should probably be fixed by changing the
 # test to match changes in the engine. Having the test will be useful for
 # reference to find out when the engine behavior changed.
 
+#####
+# API(s) being tested: [have_unit]search_recall_list=
+##
+# Actions:
+# Spawn a unit on the recall list.
+# Move the unit from the recall list to the map.
+##
+# Expected end state:
+# [have_unit] finds the unit on the recall list when it's on the recall list, and not when it's been moved from the recall list to the map.
+#####
 {GENERIC_UNIT_TEST "recall_by_unit_tag" (
     [event]
         name = start

data/test/scenarios/recruit_facing.cfg

@@ -1,4 +1,4 @@
-#define CHECK_RECRUIT CONTENT
+#define CHECK_FACES FACEDIR
     [event]
         name=recruit
         [lua]
@@ -12,14 +12,8 @@
                 >>
         [/lua]
         {ASSERT ({VARIABLE_CONDITIONAL unit.facing equals $synced_temp})}
-        {CONTENT}
-    [/event]
-#enddef
-
-#define CHECK_FACES FACEDIR
-    {CHECK_RECRUIT (
         {ASSERT ({VARIABLE_CONDITIONAL unit.facing equals {FACEDIR}})}
-    )}
+    [/event]
 #enddef
 
 #define RECRUIT TYPE TO FROM
@@ -57,6 +51,17 @@
     )}
 #enddef
 
+#####
+# API(s) being tested: N/A
+##
+# Actions:
+# Recruit a Spearman.
+# Recruit an Orcish Grunt.
+##
+# Expected end state:
+# The spearman is recruited facing northeast.
+# The Orcish Grunt is recruited facing northwest.
+#####
 {RECRUIT_TEST recruit_facing_enemy_one (
     [event]
         name=side 1 turn refresh
@@ -78,6 +83,21 @@
     [/event]
 )}
 
+#####
+# API(s) being tested: N/A
+##
+# Actions:
+# Recruit a Spearman.
+# Place an Orcish Grunt.
+# Recruit a Spearman.
+# Place an Orcish Warrior
+# Recruit a Spearman.
+##
+# Expected end state:
+# The first Spearman is facing northeast.
+# The second Spearman is facing north.
+# The third Spearman is facing south.
+#####
 {RECRUIT_TEST recruit_facing_enemy_two (
     [event]
         name=side 2 turn refresh
@@ -179,6 +199,22 @@ Gg, Gg, Gg, Gg, Gg, Gg, Gg, Gg, Gg, Gg, Gg"
     [/event]
 #enddef
 
+#####
+# API(s) being tested: N/A
+##
+# Actions:
+# Recruit a Spearman per turn for eight turns.
+##
+# Expected end state:
+# Turn 1 -> faces north.
+# Turn 2 -> faces south.
+# Turn 3 -> faces northwest.
+# Turn 4 -> faces northeast.
+# Turn 5 -> faces southwest.
+# Turn 6 -> faces southwest.
+# Turn 7 -> faces northwest.
+# Turn 8 -> faces southeast.
+#####
 {RECRUIT_TEST recruit_facing_leader (
     {EMPTY_MAP}
     {RECRUIT_AND_CHECK 1 ("n") (5,2)}
@@ -196,6 +232,23 @@ Gg, Gg, Gg, Gg, Gg, Gg, Gg, Gg, Gg, Gg, Gg"
         {SUCCEED}
     [/event]
 )}
+
+#####
+# API(s) being tested: N/A
+##
+# Actions:
+# Recall a Spearman per turn for eight turns.
+##
+# Expected end state:
+# Turn 1 -> faces south.
+# Turn 2 -> faces north.
+# Turn 3 -> faces southeast.
+# Turn 4 -> faces southwest.
+# Turn 5 -> faces northeast.
+# Turn 6 -> faces northeast.
+# Turn 7 -> faces southeast.
+# Turn 8 -> faces northwest.
+#####
 {RECRUIT_TEST recruit_facing_center (
     {EMPTY_MAP}
     {RECALL_AND_CHECK 1 ("s") (5,2)}

data/test/scenarios/scatter_units.cfg

@@ -1,3 +1,12 @@
+#####
+# API(s) being tested: 
+##
+# Actions:
+# Use the SCATTER_UNITS macro to place Mage units onto the map.
+##
+# Expected end state:
+# Three Mage units exist on the map.
+#####
 {GENERIC_UNIT_TEST "scatter_units" (
     [event]
         name=start
@@ -10,5 +19,4 @@
             [/have_unit]
         )}
     [/event]
-
 )}

wml_test_schedule

@@ -172,7 +172,11 @@
 0 test_shroud_modify_wml
 0 test_shroud_modify_lua
 0 scatter_units
-0 has_ally
+0 dave_has_ally_bob
+0 dave_has_enemy_alice
+0 dave_not_has_ally_steve
+0 dave_has_enemy_sides
+0 not_dave_has_ally_charlie
 0 xp_mod_1
 0 xp_mod_2
 0 xp_mod_3
@@ -388,7 +392,7 @@
 9 unknown_scenario_1_0
 
 # Lua API tests
-0 lua_functional
+0 lua_functional_reduce
 0 lua_map_find
 0 mapgen_filter_range
 0 mapgen_filter_terrain