Core Built-in Assertions

This document outlines the core of unit testing, i.e. Assertions. Assertions are simple: You assert something, and if that assertion does not result in your expectation, the test fails. All code AFTER a failed assertion will NOT execute. Repeat: A failed assertion means the end of that test.

This is why it's best practice to not load your test functions with lots of assertions. A single failed assertion means that any subsequent assertions in a test will not execute and thus you won't know if those assertions indicate further problems in your code.

Need an assertion you don't see here? Roll your own ...

Without further delay, our players, The Assertions:

assertTrue(boolean condition [,String message])

assertTrue is one of the two "bread and butter" assertions in any testing framework. The philosophy is simple: you assert something to be true; if it's not, the test fails

assertTrue has an opposite, assertFalse:

assertFalse(boolean condition [, String message])*

assert(boolean condition [,String message])

assert is semantically equivalent to assertTrue, providing a shorter form :

assertEquals*(any expected, any actual [, String message])

assertEquals is the other core assertion. Here, you're asserting that some result equals some expected result. This could be two numbers, two strings, two structs, whatever. For now, MXUnit follows the JUnit pattern of using a single assertEquals to compare any type of data.

Comparing Arrays, Queries, and Structures

MXUnit will do a deep compare for arrays, queries, and structures. It is not fail-fast, meaning that an assertEquals( struct1, struct2 ) will compare every key in the struct, including any nested structures or arrays, accumulating mismatches. Once every key is visited, the existence of mismatches will signal an assertion failure. Array, Query, and Struct comparisons will add a Structure result into the debug output if the assertion fails, and you can view the full set of differences from there.

In addition, when using the Eclipse plugin, you can toggle the "Compare Dialog" to pop up Eclipse's comparison tool, which enables you to step through all the differences.

Here's an example

fail*(String message)

fail() is used to actively fail a test. It's useful when you're stubbing a test and you want to ensure it fails, like so:

It's also useful when you're testing an "error path", like so:

failNotEquals*(any value, any value2 [,String message])

Used to fail when two values do not equal. This doesn't perform any assertion... it's simply a convenience method for providing a specific type of failure message

assertSame*(any obj1, any obj2 [,String message])

Used to determine if the obj1 and obj2 refer to the same instance.
Note that arrays in Adobe ColdFusion are passed by value, so, this will always fail for arrays.

assertNotSame*(any obj1, any obj2 [,String message])

Used to determine if the obj1 and obj2 do not refer to the same instance.
Note that arrays in Adobe ColdFusion are passed by value, so, this will always pass for arrays.

MXUnit Assertion Extensions

These are extensions to the base set of assertions and are specific to ColdFusion.Note, that these are quite simple, can be easily implemented using the base assertions above, but are provided for convenience.

Note: These extensions can be disabled at runtime by editing the mxunit-config.xml located in /mxunit/framework/ directory. Simply remove or comment out these line:

assertXPath*(String xpath, any data, [String text], [String message])

Searches data using xpath. If text is specified, it tries to match the exact text to the xpath expression. Otherwise ,it returns true if any nodes are found that match the xpath expression. Note that, unlike most assertions, assertXPath returns an xml dom representation of any nodes found. This can be useful for further inspection.

Parameters String xpath: string representing an xpath expression
any data: String or URL to search; e.g., ..., http://google.com, file://c:/path/to/my.html
[string text]: The text to match against the xpath expression. If omitted, this assertion returns true if any elements of the xpath expression are found. Not required. Defaults to ""
[string message]: The message to display when this assertion fails Not required. Defaults to The XPath expression, #arguments.xpath#, did not match the data.

The above parses the results from urls and strings and searches the parsed results for the XPath expression.
Try it. Really, it works!

assertIsTypeOf*(component obj, String type)

Determines if obj is of type. type needs to be fully qualified.

assertIsXMLDoc*(any xml [, String message])

Determines if xml is a valid XML DOM object.

assertIsArray*(any obj1)

Determines if the obj1 is a valid array.

assertIsDefined*(any obj1)

Determines if the obj1 has been defined in the available scope.

assertIsEmpty*(any obj1)

Determines if the obj1 is a 0 length string or NULL equivalent.

assertIsEmptyArray*(any obj1,[String message])

Determines if the obj1 is an array with no elements.

assertIsEmptyQuery*(any obj1,[String message])

Determines if the obj1 is a query with no rows.

assertIsEmptyStruct*(any obj1,[String message])

Determines if the obj1 is a struct with no keys or values.

assertIsQuery*(any q)

Determines if q is a valid ColdFusion query.

assertIsStruct*(any obj)

Determines if obj is a valid ColdFusion structure.

---

Need more? Build your own ...