Writing Unit Tests

Create a directory named tests in the root level of your plugin or project. In other words, the directory should be at the same level as packages, tags, webskin, etc. Within the test directory you will create CFCs that hold all your tests. By creating your test CFCs in this directory, they will automatically be selectable in the Configure Tests screen described above.

Simple tests

The Test CFCs must extend mxunit.framework.TestCase. There is a file called ExampleTest.cfc in the testMXUnit plugin that you can use as a template. The contents of that file at the time of this writing are the following:

<cfcomponent extends="mxunit.framework.TestCase">
	<!--- setup and teardown --->
	<cffunction name="setUp" returntype="void" access="public">
		<!--- Any code needed to return your environment to normal goes here --->
	</cffunction>

	<cffunction name="tearDown" returntype="void" access="public">
		<!--- Any code needed to return your environment to normal goes here --->
	</cffunction>
	
	<!--- ////////////////////////////////////////////////////////////////// --->
	
	<cffunction name="passTest" returntype="void" access="public">
		<!--- Any code needed to return your environment to normal goes here --->
		<cfset assertEquals(true,true) />
	</cffunction>
	
	<cffunction name="failTest" returntype="void" access="public">
		<!--- Any code needed to return your environment to normal goes here --->
		<cfset assertEquals("yes", "no") />
	</cffunction>
	
</cfcomponent>

Since the tests are running from within the context of Farcry, all of the Farcry tags and functions are available from within your test. While it is not pedantically correct to write tests that use items outside of the unit test and method you are testing, it is often quite helpful (and sometimes required).

For documentation and tutorials on MXUnit see http://mxunit.org/doc/index.cfm

FarCry tests

Some tests require integration to a higher degree with the FarCry framework. For example, creating a bunch of ContentTypes and then rolling those back when the test is done. For tests that require this kind of integration, have your test CFCs extend farcry.plugins.testmxunit.tests.FarcryTestCase. This component provides functionality for creating and destroying test data. These tests work the same way as basic tests, but the following functions are available.

Temporary data

These functions create data in the database. The FarcryTestCase automatically removes this data once the test is complete. Generally these are used in setUp and tearDown. super.setUp() must be called at the start of the overriding setUp function, and super.tearDown() must be called at the end of the overriding tearDown function.

Function	Description
createTemporaryObject	Creates a temporary object in the database. One argument for each property. Include a categories to attach categories in refCategories. Object is automatically removed at the end of the test.
createTemporaryCategory	Requires alias, parentid, categoryid, and categoryLabel. Category (and references) is automatically removed at the end of the test.
pinCategories	Takes a list category and remembers them. At the end of each test all changes to these categories (and the object references) are reverted.
pinObjects	Takes typename, and optionally timeframe (seconds) which restricts match to objects created recently. Objects are reverted, re-added, or deleted as necessary to restore the snapshot.
pinScope	Takes variable defining a valid isdefined argument. If the variable exists it is duplicated and reset at the end of the test. If it does not, structdelete is used to remove the final part. e.g. request.a.b => structdelete("request.a","b"). Only useful for basic variable structures.

Assertions

These functions are FarCry specific assertions.

Function	Description
assertContentTypeExists	Asserts that typename can be instantiated. Optional message for failure..
assertObjectExists	Asserts that an object matching typename, optional timeframe (i.e. created in the last X seconds), and miscellaneous properties (passed as corresponding arguments), exists. Supports array properties (exact set match, but not sequence), and any property that the database can handle as a varchar. Optional message for failure..
assertNotObjectExists	Asserts that an object matching typename, optional timeframe (i.e. created in the last X seconds), and miscellaneous properties (passed as corresponding arguments), exists. Does NOT support array properties, and properties must be able to handled as varchar. Optional message for failure..
assertVariable	Asserts that variable exists and is equal to value. Only supports simple values. Optional message for failure.