testMXUnit

If you are reading this from within the plugin as the README.pdf, and any of this fails for you, please see http://farcry.jira.com/wiki/display/FCPLUG/testMXUnit for the latest information about testMXUnit.

Prerequisite

Farcry unit tests uses http://mxunit.org/ with a wrapper that adds in Farcry hooks and webskin compatibility. You can get the latest copy of the plugin by checking out the code from the following SVN repository URL:

http://modius.svn.cvsdude.com/farcry/plugins/testMXUnit/trunk

Once you have the code checked out into your plugins folder, you will need to add an Alias (in Apache) or a Virtual Directory in IIS. The path should be similar to the following:

Alias /mxunit /Users/robrohan/Sites/blarg/Yadda/plugins/testMXUnit/www/mxunit

Note the path goes in one level deeper than most Farcry alias'.

You will then need to add the plugin to your plugin list in your www/farcryConstructor.cfm file. For example:

<cfset THIS.plugins = "farcrypoll,farcryradiostar,farcrycms,farcryverity,farcrycfximage,testMXUnit" />

You will then need to deploy the mxTest ContentType. You can do this in the webtop in the Admin tab. Select Developer Utilities from the pull down, and then click on the Types link under the COAPI Tools heading. Scroll down until you see mxTest and click the deploy link.

Finally, you will need to run updateapp on your application.

You are ready to write and run tests.

Running Tests

To run unit tests, log into the webtop and choose the Admin tab. From the pull down select Testing. This will display two menu options Run Tests and Configure Tests.

Configure Tests

You select which tests you would like to run on the Configure Tests screen. After you have ticked the boxes next to the CFCs you'd like to run (and click Save Configuration), you can then proceed to Run Tests.

Run Tests

Run Tests Does what it says on the tin - it runs the tests selected from the Configure Tests screen.

Writing 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.

Assertions

These functions are FarCry specific assertions.