diff options
Diffstat (limited to 'docs/Reference/LuaUnitAssertionFunctions')
8 files changed, 375 insertions, 0 deletions
diff --git a/docs/Reference/LuaUnitAssertionFunctions/0_GeneralAssertions.md b/docs/Reference/LuaUnitAssertionFunctions/0_GeneralAssertions.md new file mode 100644 index 0000000..6282755 --- /dev/null +++ b/docs/Reference/LuaUnitAssertionFunctions/0_GeneralAssertions.md @@ -0,0 +1,63 @@ +# General Assertions + +* **_AFT.assertEquals(actual, expected)** + + Assert that two values are equal. + + For tables, the comparison is a deep comparison : + + * number of elements must be the same + * tables must contain the same keys + * each key must contain the same values. The values are also compared recursively with deep comparison. + + LuaUnit provides other table-related assertions, see [Table assertions](http://luaunit.readthedocs.io/en/luaunit_v3_2_1/#assert-table) + + ```lua + _AFT.assertEquals("string", "string") + ``` + +* **_AFT.assertNotEquals(actual, expected)** + + Assert that two values are different. The assertion fails if the two values are identical. + + It also uses table deep comparison. + + ```lua + _AFT.assertNotEquals("string", "Another string") + ``` + +* **_AFT.assertAlmostEquals(actual, expected, margin)** + + Assert that two floating point numbers are almost equal. + + When comparing floating point numbers, strict equality does not work. + Computer arithmetic is so that an operation that mathematically yields + 1.00000000 might yield 0.999999999999 in lua . That’s why you need an + almost equals comparison, where you specify the error margin. + + ```lua + -- convert pi/6 radian to 30 degree + pi_div_6_deg_calculated = math.deg(math.pi/6) + pi_div_6_deg_expected = 30 + + -- convert pi/3 radian to 60 degree + pi_div_3_deg_calculated = math.deg(math.pi/3) + pi_div_3_deg_expected = 60 + + -- check absolute error: it is not constant + print( (pi_div_6_deg_expected - pi_div_6_deg_calculated) / lu.EPS ) -- prints: 16 + print( (pi_div_3_deg_expected - pi_div_3_deg_calculated) / lu.EPS ) -- prints: 32 + + -- Better use relative error: + print( ( (pi_div_6_deg_expected - pi_div_6_deg_calculated) / pi_div_6_deg_expected) / lu.EPS ) -- prints: 0.53333 + print( ( (pi_div_3_deg_expected - pi_div_3_deg_calculated) / pi_div_3_deg_expected) / lu.EPS ) -- prints: 0.53333 + + -- relative error is constant. Assertion can take the form of: + assertAlmostEquals( (pi_div_6_deg_expected - pi_div_6_deg_calculated) / pi_div_6_deg_expected, lu.EPS ) + assertAlmostEquals( (pi_div_3_deg_expected - pi_div_3_deg_calculated) / pi_div_3_deg_expected, lu.EPS ) + ``` + +* **_AFT.assertNotAlmostEquals(actual, expected, margin)** + + Assert that two floating point numbers are not almost equal. +
\ No newline at end of file diff --git a/docs/Reference/LuaUnitAssertionFunctions/1_ValueAssertions.md b/docs/Reference/LuaUnitAssertionFunctions/1_ValueAssertions.md new file mode 100644 index 0000000..3769b62 --- /dev/null +++ b/docs/Reference/LuaUnitAssertionFunctions/1_ValueAssertions.md @@ -0,0 +1,79 @@ +# Value assertions + +* **_AFT.assertEvalToTrue(value)** + + Assert that a given value evals to true. Lua coercion rules are applied so + that values like 0,"",1.17 succeed in this assertion. If provided, extra_msg + is a string which will be printed along with the failure message. + + ```lua + _AFT.assertEvalToTrue(3 == 1+2) + ``` + +* **_AFT.assertEvalToFalse(Value)** + + Assert that a given value evals to *false*. Lua coercion rules are applied so + that *nil* and *false* succeed in this assertion. If provided, extra_msg is a + string which will be printed along with the failure message. + + ```lua + _AFT.assertEvalToFalse(3 == 2) + ``` + +* **_AFT.assertIsTrue(value)** + + Assert that a given value evals to true. Lua coercion rules are applied so + that values like 0, "", 1.17 all compare to true. + + ```lua + _AFT.assertIsTrue(3 == 1+2) + ``` + +* **_AFT.assertIsFalse(value)** + + Assert that a given value evals to false. Lua coercion rules are applied so + that only nil and false all compare to false. + + ```lua + _AFT.assertIsFalse(3 == 2) + ``` + +* **_AFT.assertIsNil(value)** + + Assert that a given value is nil. + + ```lua + var = nil + _AFT.assertIsNil(var) + ``` + +* **_AFT.assertNotIsNil(value)** + + Assert that a given value is not *nil* . Lua coercion rules are applied + so that values like ``0``, ``""``, ``false`` all validate the assertion. + If provided, *extra_msg* is a string which will be printed along with the + failure message. + +* **_AFT.assertIs(actual, expected)** + + Assert that two variables are identical. For string, numbers, boolean and + for nil, this gives the same result as assertEquals() . For the other types, + identity means that the two variables refer to the same object. + + Example : + + ```lua + `s1='toto' + s2='to'..'to' + t1={1,2} + t2={1,2} + _AFT.assertIs(s1,s1) -- ok + _AFT.assertIs(s1,s2) -- ok + _AFT.assertIs(t1,t1) -- ok + _AFT.assertIs(t1,t2) -- fail` + ``` + +* **_AFT.assertNotIs(actual, expected)** + + Assert that two variables are not identical, in the sense that they do not + refer to the same value. See assertIs() for more details.
\ No newline at end of file diff --git a/docs/Reference/LuaUnitAssertionFunctions/2_ScientificAssertions.md b/docs/Reference/LuaUnitAssertionFunctions/2_ScientificAssertions.md new file mode 100644 index 0000000..a9ce270 --- /dev/null +++ b/docs/Reference/LuaUnitAssertionFunctions/2_ScientificAssertions.md @@ -0,0 +1,48 @@ +# Scientific assertions + +>**Note** +>If you need to deal with value *minus zero* (-0), be very careful because Lua versions +are inconsistent on how they treat the >syntax -0 : it creates either a plus +zero or a minus zero. Multiplying or dividing 0 by -1 also yields inconsistent > +results. The reliable way to create the -0 value is : minusZero = -1 / (1/0). + +* **_AFT.assertIsNaN(value)** + Assert that a given number is a *NaN* (Not a Number), according to the + definition of IEEE-754_ . If provided, *extra_msg* is a string which will + be printed along with the failure message. + +* **_AFT.assertIsPlusInf(value)** + + Assert that a given number is *plus infinity*, according to the definition of + IEEE-754_. If provided, *extra_msg* is a string which will be printed along + with the failure message. + +* **_AFT.assertIsMinusInf(value)** + + Assert that a given number is *minus infinity*, according to the definition of + IEEE-754_. If provided, *extra_msg* is a string which will be printed along + with the failure message. + +* **_AFT.assertIsInf(value)** + + Assert that a given number is *infinity* (either positive or negative), + according to the definition of IEEE-754_. If provided, *extra_msg* is a string + which will be printed along with the failure message. + +* **_AFT.assertIsPlusZero(value)** + + Assert that a given number is *+0*, according to the definition of IEEE-754_. + The verification is done by dividing by the provided number and verifying + that it yields *infinity* . If provided, *extra_msg* is a string which will + be printed along with the failure message. + + Be careful when dealing with *+0* and *-0*, see note above + +* **_AFT.assertIsMinusZero(value)** + + Assert that a given number is *-0*, according to the definition of IEEE-754_. + The verification is done by dividing by the provided number and verifying that + it yields *minus infinity* . If provided, *extra_msg* is a string which will + be printed along with the failure message. + + Be careful when dealing with *+0* and *-0*
\ No newline at end of file diff --git a/docs/Reference/LuaUnitAssertionFunctions/3_StringAssertions.md b/docs/Reference/LuaUnitAssertionFunctions/3_StringAssertions.md new file mode 100644 index 0000000..929ec14 --- /dev/null +++ b/docs/Reference/LuaUnitAssertionFunctions/3_StringAssertions.md @@ -0,0 +1,38 @@ +# String assertions + +Assertions related to string and patterns. + +* **_AFT.assertStrContains(str, sub[, useRe])** + + Assert that a string contains the given substring or pattern. + + By default, substring is searched in the string. If useRe is provided and is + true, sub is treated as a pattern which is searched inside the string str. + +* **_AFT.assertStrIContains(str, sub)** + + Assert that a string contains the given substring, irrespective of the case. + + Not that unlike assertStrcontains(), you can not search for a pattern. + +* **_AFT.assertNotStrContains(str, sub, useRe)** + + Assert that a string does not contain a given substring or pattern. + + By default, substring is searched in the string. If useRe is provided and is + true, sub is treated as a pattern which is searched inside the string str. + +* **_AFT.assertNotStrIContains(str, sub)** + + Assert that a string does not contain the given substring, irrespective of + the case. + + Note that unlike assertNotStrcontains(), you can not search for a pattern. + +* **_AFT.assertStrMatches(str, pattern[, start[, final]])** + + Assert that a string matches the full pattern pattern. + + If start and final are not provided or are nil, the pattern must match the + full string, from start to end. The functions allows to specify the expected + start and end position of the pattern in the string.
\ No newline at end of file diff --git a/docs/Reference/LuaUnitAssertionFunctions/4_ErrorAssertions.md b/docs/Reference/LuaUnitAssertionFunctions/4_ErrorAssertions.md new file mode 100644 index 0000000..13d381f --- /dev/null +++ b/docs/Reference/LuaUnitAssertionFunctions/4_ErrorAssertions.md @@ -0,0 +1,43 @@ +# Error assertions + +Error related assertions, to verify error generation and error messages. + +* **_AFT.assertError(func, ...)** + + Assert that calls to the function **func** with the arguments yields an error. If the function does + not yield an error, the assertion fails. + + Note that the error message itself is not checked, which means that this function does not + distinguish between the legitimate error that you expect and another error that might be + triggered by mistake. + + The next functions provide a better approach to error testing, by checking explicitly the error + message content. + +>**Note** +>When testing LuaUnit, switching from assertError() to assertErrorMsgEquals() revealed quite a few bugs! + +* **_AFT.assertErrorMsgEquals(expectedMsg, func, ...)** + + Assert that calls to the function **func** will generate exactly the given error message. If the + function does not yield an error, or if the error message is not identical, the assertion fails. + + Be careful when using this function that error messages usually contain the file name and line + number information of where the error was generated. This is usually inconvenient. To ignore the + filename and line number information, you can either use a pattern with assertErrorMsgMatches() + or simply check if the message contains a string with assertErrorMsgContains() . + +* **_AFT.assertErrorMsgContains(partialMsg, func, ...)** + + Assert that calls to the function **func** will generate an error message containing partialMsg. + If the function does not yield an error, or if the expected message is not contained in the + error message, the assertion fails. + +* **_AFT.assertErrorMsgMatches(expectedPattern, func, ...)** + + Assert that calls to the function **func** will generate an error message matching expectedPattern. + If the function does not yield an error, or if the error message does not match the provided + pattern the assertion fails. + + Note that matching is done from the start to the end of the error message. Be sure to escape + magic all magic characters with % (like -+.?\*) .
\ No newline at end of file diff --git a/docs/Reference/LuaUnitAssertionFunctions/5_TypeAssertions.md b/docs/Reference/LuaUnitAssertionFunctions/5_TypeAssertions.md new file mode 100644 index 0000000..d96ef6b --- /dev/null +++ b/docs/Reference/LuaUnitAssertionFunctions/5_TypeAssertions.md @@ -0,0 +1,72 @@ +# Type assertions + +The following functions all perform type checking on their argument. If the +received value is not of the right type, the failure message will contain the +expected type, the received type and the received value to help you identify +better the problem. + +* **_AFT.assertIsNumber(value)** + + Assert that the argument is a number (integer or float) + + ```lua + _AFT.assertIsNumber(1) + ``` + +* **_AFT.assertIsString(value)** + + Assert that the argument is a string. + + ```lua + _AFT.assertIsString("string") + ``` + +* **_AFT.assertIsTable(value)** + + Assert that the argument is a table. + + ```lua + _AFT.assertIsTable({key = "value"}) + ``` + +* **_AFT.assertIsBoolean(value)** + + Assert that the argument is a boolean. + + ```lua + _AFT.assertIsBoolean(false) + ``` + +* **_AFT.assertIsFunction(value)** + + Assert that the argument is a function. + + ```lua + _AFT.assertIsFunction(function() print("HELLO WORLD!") end) + ``` + +* **_AFT.assertIsUserdata(value)** + + Assert that the argument is a userdata. + + ```lua + _AFT.assertIsUserdata(someCvariableImportedAsUserDataInLua) + ``` + +* **_AFT.assertIsThread(value)** + + Assert that the argument is a coroutine (an object with type thread ). + + ```lua + local corout = coroutine.create( print ) + + _AFT.assertIsUserdata(corout) + ``` + +* **_AFT.assertNotIsThread(value)** + + Assert that the argument is a not coroutine (an object with type thread ). + + ```lua + _AFT.assertNotIsThread(2) + ```
\ No newline at end of file diff --git a/docs/Reference/LuaUnitAssertionFunctions/6_TableAssertions.md b/docs/Reference/LuaUnitAssertionFunctions/6_TableAssertions.md new file mode 100644 index 0000000..8d29988 --- /dev/null +++ b/docs/Reference/LuaUnitAssertionFunctions/6_TableAssertions.md @@ -0,0 +1,19 @@ +# Table assertions + +* **_AFT.assertItemsEquals(actual, expected)** + + Assert that two tables contain the same items, irrespective of their keys. + + This function is practical for example if you want to compare two lists but + where items are not in the same order: + + ```lua + luaunit.assertItemsEquals( {1,2,3}, {3,2,1} ) -- assertion succeeds + ``` + The comparison is not recursive on the items: if any of the items are tables, + they are compared using table equality (like as in assertEquals() ), where the + key matters. + + ```lua + luaunit.assertItemsEquals( {1,{2,3},4}, {4,{3,2,},1} ) -- assertion fails because {2,3} ~= {3,2} + ```
\ No newline at end of file diff --git a/docs/Reference/LuaUnitAssertionFunctions/Introduction.md b/docs/Reference/LuaUnitAssertionFunctions/Introduction.md new file mode 100644 index 0000000..2bdf05c --- /dev/null +++ b/docs/Reference/LuaUnitAssertionFunctions/Introduction.md @@ -0,0 +1,13 @@ +# LuaUnit Assertion Functions + +Follow this section to know which luaUnit assertion functions are available !! + +Section's Table of content : + +* [General Assertions](0_GeneralAssertions.html) +* [Value Assertions](1_ValueAssertions.html) +* [Scientific Assertions](2_ScientificAssertions.html) +* [String Assertions](3_StringAssertions.html) +* [Error Assertions](4_ErrorAssertions.html) +* [Type Assertions](5_TypeAssertions.html) +* [Table Assertions](6_TableAssertions.html)
\ No newline at end of file |