LuaAPI/unit test

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

Functions

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

• unit_test.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.