Add unit tests for [break] and [return] during [fire_event]

Cherry-picked from b18b0e0f55,
including the docs from 16b900c273.

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,40 @@
     [/event]
 )}
 
+#####
+# API(s) being tested: [fire_event], [break]
+##
+# Expected end state:
+# [break] outside a loop is documented to be the same as [return], so skips the entire rest of the firing event, not just fired event.
+#####
+{GENERIC_UNIT_TEST check_interrupts_break_nested_event (
+    [event]
+        name=function_with_interrupt
+        [break][/break]
+        {FAIL}
+    [/event]
+    [event]
+        name=start
+        [fire_event]
+            name=function_with_interrupt
+        [/fire_event]
+        {FAIL}
+    [/event]
+    [event]
+        name=start
+        {SUCCEED}
+    [/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,7 +168,13 @@
     [/event]
 )}
 
-{GENERIC_UNIT_TEST check_interrupts_return_nested (
+#####
+# 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_command (
     [event]
         name=start
         [command]
@@ -117,6 +189,37 @@
     [/event]
 )}
 
+#####
+# API(s) being tested: [fire_event], [return]
+##
+# Expected end state:
+# [return] skips the entire rest of the firing event, not just fired event.
+#####
+{GENERIC_UNIT_TEST check_interrupts_return_nested_event (
+    [event]
+        name=function_with_interrupt
+        [return][/return]
+        {FAIL}
+    [/event]
+    [event]
+        name=start
+        [fire_event]
+            name=function_with_interrupt
+        [/fire_event]
+        {FAIL}
+    [/event]
+    [event]
+        name=start
+        {SUCCEED}
+    [/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 +255,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

wml_test_schedule

@@ -303,8 +303,10 @@
 0 check_interrupts_break
 0 check_interrupts_return
 0 check_interrupts_continue
+0 check_interrupts_break_nested_event
 0 check_interrupts_break_global
-0 check_interrupts_return_nested
+0 check_interrupts_return_nested_command
+0 check_interrupts_return_nested_event
 9 check_interrupts_continue_global
 0 check_interrupts_elseif
 0 check_interrupts_case