LuaAPI/unit test - Revision history

Laela at 18:05, 18 April 2024

2024-04-18T18:05:11Z

Celtic Minstrel: Note that it's not even manually loadable outside [test]

2022-07-25T06:08:13Z

Note that it's not even manually loadable outside [test]

Celtic Minstrel: /* unit_test.fire_wml_menu_item */ This is not the wesnoth module…!

2022-06-28T03:56:28Z

‎unit_test.fire_wml_menu_item: This is not the wesnoth module…!

Celtic Minstrel: Document the unit_test module

2021-07-04T22:59:34Z

Document the unit_test module

New page

<div class="tright"> __TOC__ </div>

The <tt>unit_test</tt> module contains functions for writing unit tests that can be run using Wesnoth's <tt>--unit</tt> command-line option (or its abbreviated form <tt>-u</tt>). The module is only loaded in scenarios defined using a <tt>[test]</tt> tag.

The outcome of a unit test is determined by the first failed assert or the first call to '''succeed'''() or '''finish'''(). All tests must call at least one of '''fail''', '''succeed''' or '''finish''', otherwise they will never end. A common idiom is to call '''succeed''' at the end of the test.

=== unit_test.fail ===

* '''unit_test.fail'''()

Marks the unit test as failed.

=== unit_test.succeed ===

* '''unit_test.succeed'''()

Marks the unit test as successful, provided no prior assertions failed.

=== unit_test.finish ===

* '''unit_test.finish'''(''result'')

Marks the unit test as finished. The result can take on several values, the most common being ''fail'' or ''pass''. Unless you need to use a special result, you should call either '''fail''' or '''succeed''' instead.

=== unit_test.log ===

* '''unit_test.log'''(''prefix'', ''message'')

Logs a message to the Wesnoth console output, using '''std_print'''. The message will be of the form "prefix: message".

=== unit_test.tostring ===

* '''unit_test.tostring''' ↔ ''function''(''value'') → ''string''

Converts a value to a string for the purpose of outputting in assertion test failure messages. This can be called directly, and will output strings as quoted and other values as vanilla '''tostring'''. If you need to output some more complex value, you can override it for the special case.

=== unit_test.fire_wml_menu_item ===

* '''wesnoth.fire_wml_menu_item'''(''id'', ''location'') → ''success''

Fires a WML menu item with the given ID as if the mouse were hovering the given location, and returns a boolean indicating whether an event was actually fired.

'''Note:''' If used with menu items that have '''needs_select=yes''', be sure to select a unit first with '''wesnoth.units.select''', otherwise the game might crash.

=== unit_test.assert ===

* '''unit_test.assert'''(''condition'', ''message'')

Assert that the specified condition is true. The message should describe the meaning of the ''condition'' somehow; the simplest way to do this is to copy-paste the condition as a string.

=== unit_test.assert_equal ===

* '''unit_test.assert_equal'''(''a'', ''b'', ''message'')

Assert that ''a'' is equal to ''b''. The message should describe the meaning of ''a'' and ''b'' somehow.

=== unit_test.assert_not_equal ===

* '''unit_test.assert_not_equal'''(''a'', ''b'', ''message'')

Assert that ''a'' is not equal to ''b''. The message should describe the meaning of ''a'' and ''b'' somehow.

=== unit_test.assert_approx_equal ===

* '''unit_test.assert_approx_equal'''(''a'', ''b'', ''tolerance'', ''message'')

Assert that ''a'' is approximately equal to ''b'' within the specified tolerance. Use this if you need to compare real (ie floating-point) numbers. The message should describe the meaning of ''a'' and ''b'' somehow.

=== unit_test.assert_greater ===

* '''unit_test.assert_greater'''(''a'', ''b'', ''message'')

Assert that ''a'' is greater than ''b''. The message should describe the meaning of ''a'' and ''b'' somehow.

=== unit_test.assert_greater_equal ===

* '''unit_test.assert_greater_equal'''(''a'', ''b'', ''message'')

Assert that ''a'' is greater than or equal to ''b''. The message should describe the meaning of ''a'' and ''b'' somehow.

=== unit_test.assert_less ===

* '''unit_test.assert_less'''(''a'', ''b'', ''message'')

Assert that ''a'' is less than ''b''. The message should describe the meaning of ''a'' and ''b'' somehow.

=== unit_test.assert_less_equal ===

* '''unit_test.assert_less_equal'''(''a'', ''b'', ''message'')

Assert that ''a'' is less than or equal to ''b''. The message should describe the meaning of ''a'' and ''b'' somehow.

=== unit_test.assert_in_range ===

* '''unit_test.assert_in_range'''(''value'', ''minimum'', ''maximum'', ''message'')

Asserts that ''value'' is within the range [''minimum'', ''maximum''] (that is, inclusive of both ends). The messag should describe the meaning of ''value'' somehow. If ''minimum'' and ''maximum'' are expressions, it should describe them too.

=== unit_test.assert_contains ===

* '''unit_test.assert_contains'''(''source'', ''fragment'', ''message'')

Asserts that the ''source'' string contains the ''fragment'' string as a substring. The message should describe the meaning of these strings somehow.

=== unit_test.assert_nothrow ===

* '''unit_test.assert_nothrow'''(''function'', ''message'')

Assert that the ''function'' runs without raising an error. The function is run in a protected context, so even if it raises an error, the test will continue. The message should describe the function somehow.

=== unit_test.assert_throws ===

* '''unit_test.assert_throws'''(''function'', ''message'')

Assert that the ''function'' raises an error when run. The function is run in a protected context, so even if it raises an error, the test will continue. The message should describe the function somehow.

=== unit_test.assert_throws_with ===

* '''unit_test.assert_throws_with'''(''error'', ''function'', ''message'')

Assert that the ''function'' raises an error when run and that the error raised either contains ''error'' as a substring or compares equal to ''error''. The function is run in a protected context, so even if it raises an error, the test will continue. The message should describe the function somehow.

[[Category:Lua Reference]]

← Older revision		Revision as of 18:05, 18 April 2024
Line 4:		Line 4:

	The outcome of a unit test is determined by the first failed assert or the first call to '''succeed'''() or '''finish'''(). All tests must call at least one of '''fail''', '''succeed''' or '''finish''', otherwise they will never end. A common idiom is to call '''succeed''' at the end of the test.		The outcome of a unit test is determined by the first failed assert or the first call to '''succeed'''() or '''finish'''(). All tests must call at least one of '''fail''', '''succeed''' or '''finish''', otherwise they will never end. A common idiom is to call '''succeed''' at the end of the test.
		+
		+	== Functions ==

	=== unit_test.fail ===		=== unit_test.fail ===

@@ Line 37: / Line 37: @@
 === unit_test.fire_wml_menu_item ===
-* '''wesnoth.fire_wml_menu_item'''(''id'', ''location'') &rarr; ''success''
+* '''unit_test.fire_wml_menu_item'''(''id'', ''location'') &rarr; ''success''
 Fires a WML menu item with the given ID as if the mouse were hovering the given location, and returns a boolean indicating whether an event was actually fired.

@@ Line 1: / Line 1: @@
 <div class="tright"> __TOC__ </div>
-The <tt>unit_test</tt> module contains functions for writing unit tests that can be run using Wesnoth's <tt>--unit</tt> command-line option (or its abbreviated form <tt>-u</tt>). The module is only loaded in scenarios defined using a <tt>[test]</tt> tag.
+The <tt>unit_test</tt> module contains functions for writing unit tests that can be run using Wesnoth's <tt>--unit</tt> command-line option (or its abbreviated form <tt>-u</tt>). The module is only loaded in scenarios defined using a <tt>[test]</tt> tag. At present, there is no way to load it in other scenarios.
 The outcome of a unit test is determined by the first failed assert or the first call to '''succeed'''() or '''finish'''(). All tests must call at least one of '''fail''', '''succeed''' or '''finish''', otherwise they will never end. A common idiom is to call '''succeed''' at the end of the test.