Configuring Project Properties
Why
Some projects are special cases. Maybe the plugin cannot use its default behavior for figuring out the dot-notation for the project's CFCs.
Or maybe a specific project requires that all tests include some custom behavior before the test is run, but you don't want to pollute your test code itself.
Project Properties to the rescue!
The properties
You can set these properties at the project level
- Remote Facade URL: custom remote URL for this project
- Component root: the CFC notation path to stick in front of all unit test files in this project
- Username and password: credentials to use if the Remote Facade URL is protected by an authentication mechanism
How
- Right click on the project name in the Navigator or Project Explorer
- Select "Properties"
- Select "MXUnit Properties"
- Add a custom remote URL, a component root for the project, or both.
- NOTE: if you're just using this to point to an mxunit install on a different port, then you can skip the "/mxunit/framework/RemoteFacade.cfc" part of the URL. Just use http://localhost:8888, for example. In that case, the plugin will suffix your url with "mxunit/framework/RemoteFacade.cfc"
- Enter credentials if required
That component root.... in a bit more depth
Sometimes, your cfc notation doesn't start at the project level but maybe at a level underneath. For example, maybe you have c:\components\tests, and all your tests live under that directory. You have a mapping set up in ColdFusion that points "tests" to that directory. So any components under it are referenced as test.subdir.MyTest. Now, maybe you have an Eclipse project set up at c:\components. To correctly configure the plugin to work for your unit tests, it won't work to set the properties at the project level... you'll need to set the component root at the "directory" level. To do so, simply right click on that "tests" directory in Eclipse, select "Properties", go to the MXUnit page, and enter "tests" as the component path for that directory.
Examples
Custom Remote URL
- You have a set of unit tests that require something special at every test run
- You don't want to include that thing in the test itself (i.e. in the constructor or setUp() method)
What to do:
- Create a New CFC. Put it wherever. Name it whatever.
- Set the "extends" attribute of the component tag to "mxunit.Framework.RemoteFacade"
- Add a function named actOnTestCase. It takes an argument named TestCase. This is a TestCase object
- Implement your functionality in that method
- In the MXUnit properties for this project, add the URL to your new CFC
Sample Custom Remote URL
MyRemoteFacade.cfc
Component Root
- Your unit tests live at c:\nonwebrootcomponents.
- You have a CF mapping for this directory (in CFAdmin) named "components".
- Thus, CF sees c:\nonwebrootcomponents\test\MyBusinessObjectTest.cfc as components.test.MyBusinessObjectTest
What to do: specify "components" as the component root for this project.
Component Root: Using the special "empty" root indicator*
Imagine this scenario: Your applications live at d:\apps, and you have a monster project in Eclipse set up at d:\apps. You have some subdirs that look like: d:\apps\App1\tests, d:\apps\App2\tests, and so forth. You have mappings in CF set up that points "app1" to d:\apps\app1, "app2" to d:\apps\app2, etc.
In this case, the easiest choice is to use the "empty" root indicator. In this example, here's what to do:
- Right click on the project, select "Properties", and go to "MXUnit"
- In the component root field, simply add "/"
What's this do? Using a slash (or a period) as the component root property indicates "don't prefix anything underneath this container with a root, but don't try to derive the component path from the webroot, either. In this example, the components under apps\app2\tests would then start at app2.tests, essentially ignoring the "apps" directory.
*Props to a user named Alanyst for suggesting this feature and contributing code
Component Root: Specifying multiple roots in the same project, on any directory
Imagine this scenario: Your applications live at d:\apps, and you have a monster project in Eclipse set up at d:\apps. You have some subdirs that look like: d:\apps\v1\Client1\tests, d:\apps\v2\Client1\tests, etc. And you've added CF mappings like so:
- d:\apps\v1\Client1\tests = clientv1.tests
- d:\apps\v2\Client1\tests = clientv2.tests
Now... why you'd do this, I don't know. It's an example, live with it.
- In Eclipse, right click on the v1\Client1 directory, select the MXUnit properties, and add "clientv1" as the component root
- Do the same for v2, but using "clientv2" instead of clientv1
Granted... this is a bit more work; still, it gives you the granularity you need for correctly specifiying the CFC path at any folder level.
Username and password
If the remote url is protected by basic, digest, or NTLM authentication, enter the username and password in these fields. For NTLM authentication, you must enter the username as domain\username, e.g. MyDomain\BobbySue.
We suggest NOT using authentication for the remote facade URL. Best practice for unit testing is that testing happens locally, not on a shared dev server.
If you must use a shared server, then we additionally suggest using a custom URL for just the projects that require authentication. This is simple:
- Create a file named "RemoteFacade.cfc" in your protected directory
- In the MXUnit properties for this project, point the Test runner URL for just this project to your new file. For example, if your new file is at WEBROOT/SomeProtectedApp/unittests/RemoteFacade.cfc, set the URL to http://DEVSERVER/SomeProtectedApp/unittests/RemoteFacade.cfc
- Populate the RemoteFacade.cfc with the following code:
Next: How to Run Tests
After that: Running the Demo Tests