SeleniumMX

SeleniumMX is a lightweight framework that will make setting up for, and cleanup after, you run selenium tests much easier. Plus it helps with the integration of your Selenium tests into your Continuous Integration process (CruiseControl for example).

Overview

SeleniumMX uses convention and a touch of configuration to help make your life easier if you're using Selenium with your ColdFusion App. It does this by harnessing the power of MxUnit. Thus you need have MxUnit installed properly before using SeleniumMX. Obviously you also need Selenium (Core at least) installed on your server.

Why?

I needed an easy way to prepare my appliation with some seed data before various UI/functional tests were run. Plus, if a UI test failed I wanted to make sure my app was restored to its proper state when all was said and done. SeleniumMX makes this possible.

Usage

First off you need to understand the convention. I expect all of your ui tests to be in a nice clean directory structure. I strongly recommend adding a uitests directory to your project and then putting your selenium tests in directories beneath that uitests directory. Just don't put any tests in the uitests directory.

Directory Structure Example:

myproject
        uitests
                module1
                        someTestFile.html
                        anotherTestFile.html
                module2
                        module2SubDir
                                subDirTestFile.html
                        aTestFile.html
                        

Once you have your files in the right structure put the seleniumMX files in the uitests directory. Obviously you can call your directory something else but, for the sake of simplicity I will continue to refer to it as uitests.

Next you'll need to edit the _seleniumMXSettings.cfm file. That document is pretty well documented inline so I won't cover it here.

Finally, within each directory that you want to provide some setup or teardown (cleanup) logic for a ui test you will need to add a setup.cfc and a teardown.cfc. Please refer to the example application in the source when you do this the first time. Both setup.cfc and teardown.cfc must extend the seleniumMxBase.cfc that is in your uitests directory.

setup.cfc

The setup.cfc must have a public method called testUIsetup that takes in no arguments. The teardown.cfc must have a public method called testUIteardown that also takes in no arguments. For each test setup method you create and reference in your testUISetup method there must be a matching teardown function in the teardown.cfc and they must follow the naming convention of teardown{setuptestname} where {setuptestname} is the name of the test function in the setup.cfc that your teardown function is cleaning up. If this seems confusing please refer to the exampleProject.

Each setup function must return a struct and each teardown function must accept the struct that the setup function returns. This way your setup can tell your teardown what ids or other values it needs for cleaning up when all the tests are run.

Here is an example setup function from setup.cfc

<cffunction name="testLogin"    access="private" returntype="struct">
        <cfargument name="data" type="struct" required="true" hint="gives access to data created in other tests run before this one.. ordered via the comma delimited list in setupTests" />

        <cfset var outData = structNew() />
        <cfset var local = structNew() />

        <cfset outData.userID = createAUser("someusername","somepassword") />

        <cfreturn outData />
</cffunction>

Here is the matching teardown function from teardown.cfc

<cffunction name="teardownTestLogin"    access="private" returntype="void">
        <cfargument name="data" type="struct" required="true" />
        <!-- try using a helper method or two if you want --->
        <cfset deleteThisUser(data.userID) />

        <!--- do some more cleanup too if you need to! --->
</cffunction>

By convention I name my setup function the same thing as my selenium test file so I know what functions are paired with what selenium tests.

Also, note that in your setup.testUIsetup() function, the order you pass functions to the super.setupTests('Suite','test1,test2,test3') call can matter. Tests later in the list can see and use the data that was returned from those tests. Thus test3 could see test1's data by referncing arguments.data.test1; each test is trusted to not overwrite or damage the data from other tests.