Custom Assertions

h2. Custom Assertions - How To

Sometimes you need complex and/or repetitive assertions. This can put a damper on any TDD effort. So, we provide you an easy way to add custom assertions to your tests without having to change the mxunit core.

The steps for creating your custom assertion are as follows:
# Write a test for your assertion
# Write the assertion
# Decide how you want to load it: Always or only on selected tests.

Assertion Rules:

# Your assertion will need to throw mxunit.exception.AssertionFailedError or use an existing assertion that throws this exception.
# If you want to have optional first or last parameter message, you will need to call normalizeArguments(arguments) in your code.

*Custom Assertion Example:* Say you need to frequently validate email addresses. You can do this with a pretty regular expression such as this :
{noformat}
^[A-Za-z0-9](([_\.\-]?[a-zA-Z0-9]+)*)@([A-Za-z0-9]+)(([\.\-]?[a-zA-Z0-9]+)*)\.([A-Za-z]{2,})$

{noformat}

varemailAddress="[email protected]";

Much better\! And this has the added bonus of _not_ having to find a replace hundreds of complex regular expressions in your code; you would just do that in one place.
Here's how:


1. Write a test for your assertion:

var goodEmailAddress = "[email protected]";
var badEmailAddress = "so ~~/\/\/\/\/\~~ [email protected]";
addAssertDecorator("mxunit.framework.ext.ValidEmailAssertion");
assertIsValidEmail(goodEmailAddress);
try{
//expect failure
assertIsValidEmail(badEmailAddress);
}
catch(mxunit.exception.AssertionFailedError e){}
</cfscript>
</cffunction>

</cfcomponent>
{code}

The above fails because we do not yet have ValidEmailAssertion written. *Note{*}the addAssertDecorator("mxunit.framework.ext.ValidEmailAssertion") statement. This tells the MXUnit framework to load your assertion at runtime.

2. Write the assertion

<cfargument name="message" type="string" required="false" default="Email address does not appear valid." />

<cfscript>
arguments = normalizeArguments(arguments);
emailRegEx = "^[A-Za-z0-9](([_\.\-]?[a-zA-Z0-9]+)*)@([A-Za-z0-9]+)(([\.\-]?[a-zA-Z0-9]+)*)\.([A-Za-z]{2,})$";
actual = refind(emailRegEx,arguments.email);
</cfscript>

<cfif actual lt 1>
<cfthrow type="mxunit.exception.AssertionFailedError" message="arguments.message" />
</cfif>
<cfreturn true />
</cffunction>

You could also leverage existing assertions and write the following instead:

<cfargument name="message" type="string" required="false" default="Email address does not appear valid." />

<cfscript>
arguments = normalizeArguments(arguments);

<cfreturn true />
</cffunction>

</cfcomponent>
{code}

Note the arguments = normalizeArguments(arguments) statement. This allows for the flexibility if you want to be able to pass the message parameter first or last.

Ok. Now when we run our test, we're in the green. Our new assertion works as expected. Wahoo\!

3. Decide how you want to load the new code. The options are for each test or for{_}all_ tests. You've already seen how to load custom assertions in your code. This can also be done in setUp().

<cfscript>
addAssertDecorator("mxunit.framework.ext.ValidEmailAssertion");
</cfscript>
</cffunction>
{code}

What if you want your new assertion to _always_ be available? Edit the mxunit-config.xml file located in \{mxunit install\}/mxunit/framework/ Add the following line :