Sunday, March 27, 2011

Quick Guide for Installing and Running CFSelenium

I've been playing around with CFSelenium this week in order to come up with an implementation that will let me easily replicate and run tests I've created with the Firefox Selenium IDE plugin on multiple browsers.  I've learned a few things along the way that are worth blogging about, but I thought I should start with a blog post on how to get CFSelenium up and running quickly.


Installating CFSelenium

  1. First, you need to have a computer that has either ColdFusion 7, ColdFusion 8, or ColdFusion 9 installed and running such that you can call and execute a .cfm page on the machine (example "http://localhost/myLocalSite/index.cfm"), and you'll need Firefox installed.
  2. Go to Bob Silverberg's CFSelenium GitHub site - https://github.com/bobsilverberg/CFSelenium - and click on the "Downloads" button.  In the pop-up window that appears, click one of the two buttons under "Download source" to download either a .tar.gz archive or a .zip archive, and download the file to your computer.
  3. Extract the files and folders from the downloaded file wherever you like to start with - let's say a folder called cfSeleniumFiles.
  4. Create a folder called CFSelenium within your webroot folder (usually "http" or "www").  Copy the following files and folder from your cfSeleniumFiles folder into the new CFSelenium folder (*updated in August 2012 to reflect additional files):
    • selenium.cfc
    • selenium_tags.cfc
    • server.cfc
    • CFSeleniumTestCase.cfc
    • CFSeleniumTestCase_Tags.cfc
    • test
  5. Create a folder called selenium somewhere on your hard drive that isn't too deep in your folder hierarchy. On my Windows machine, I created it at the root of the hard drive (C:/selenium), while on my Macintosh system I created it under my user account (/Users/Brian/selenium).
  6. In your cfSeleniumFiles folder, open the Selenium-RC folder and copy the .jar file (the Selenium Server file) within that directory to the selenium folder you created in the previous step.
  7. If you're running ColdFusion 8 or ColdFusion 9, you'll want to download and install the MXUnit ColdFusion unit test framework (if you're running ColdFusion 7, skip this step; you'll still be able to execute Selenium commands via CFSelenium but in a different way).  If you don't already have MXUnit installed:
    • Go to the MXUnit website - http://www.mxunit.org/ - and click the download link ("1. Download").
    • Once the .zip file is downloaded, unzip the files into an mxunit folder in your webroot (so you should now have a CFSelenium folder and mxunit folder in your webroot).
That's all you need to do to install what you need to try out CFSelenium. Now you're ready to issue commands to the Selenium Server via CFSelenium and see it in action:


Testing CFSelenium

  1. Any time you want to run Selenium tests through CFSelenium, you need to start the Selenium Server (previously called Selenium-RC):
    • Open up a command line interface. On a Mac, simply open up the Terminal application. If you're machine runs windows, click on the Start button, choose "Run" from the menu, type "cmd" in the input box that appears, and hit the Enter key.
    • Use the "cd" command to navigate to the selenium folder you created earlier (the one where you copied the .jar file).
    • Type in the following command and hit the Enter key:
         java -jar selenium-server-standalone-2.0b2.jar
    • The Selenium Server should start: it will output several lines of activity then stop. If the server does not start, you may need to install Java 1.5 or Java 1.6 on your computer:  if you go to http://www.java.com, the download link/button is front and center.
  2. Now the Selenium Server is ready to respond to commands issued through CFSelenium. What you do next depends on the version of ColdFusion you're running:
    • If you're running ColdFusion 9, run the seleniumTest.cfc MXUnit test in the CFSelenium/test/cf9 folder by calling it in the browser like so:
         http://localhost/CFSelenium/test/cf9/seleniumTest.cfc?method=runTestRemote
    • If you're running ColdFusion 8, run the seleniumTest_cf8.cfc MXUnit test in the CFSelenium/test/cf7_cf8 folder by calling it in the browser like so:
         http://localhost/CFSelenium/test/cf7_cf8/seleniumTest.cfc?method=runTestRemote
    • If you're running ColdFusion 7, run the seleniumTest_cf7.cfm file in the CFSelenium/test/cf7_cf8 folder like so (it mimics the MXUnit test for CF8 and CF9 without using MXUnit):
         http://localhost/CFSelenium/test/cf7_cf8/seleniumTest_cf7.cfm
  3. If everything works, you should observe the Selenium Server react to the commands issued by CFSelenium.  It should start up an instance of Firefox, run through the test routines, and shut down again, and you should be presented with the results of those test routines.
    • If you're on a Windows machine and the Selenium Server fails to launch Firefox, that probably means that Firefox is not defined in your system path, so the Selenium Server does not know the location of the Firefox executable and cannot start Firefox. You can fix this by doing the following:
      • Locate where your firefox.exe file is on your machine (example: C:\Program Files\firefox.exe).
      • Open the appropriate "seleniumTest" file (as listed above).
      • Do a search for " *firefox " (it should only appear once in the file). Add a space after " *firefox " and type in the path to the firefox.exe file, like so:
           *firefox C:\Program Files\firefox.exe
      • Save the file and try again: it should work this time.
  4. To shut down the Selenium Server when you're done, go back to your command window and hit Control-C on your keyboard to shut down the server.

Going Further

Now you have CFSelenium installed, know how to start the Selenium Server that receives the commands from CFSelenium, and have run through one of the included tests, hopefully you'll want to learn how to create your own tests. For that, you should download and install the Selenium IDE plugin for Firefox so that you can record your own browser behavior tests. The documentation for using Selenium IDE is quite thorough.  Pay particular attention to the "Adding Verifications and Asserts With the Context Menu" section:  verifications and asserts are key to actually doing browser behavior testing with Selenium/CFSelenium (I'll touch on that briefly in my next blog post).

Included in the CFSelenium download file is a plugin for the Selenium IDE (yes, a plugin for a plugin) that adds the ability to export the Selenium IDE recordings (test cases) as CFSelenium commands wrapped in an MXUnit test case.  To install it, double-click on the cfml-formatters-1.0.xpi file in the cfSeleniumFiles/formats folder you created out of the CFSelenium download file.  Even if you're running ColdFusion 7 and can't run the plugin output directly (as MXUnit isn't supported in ColdFusion 7), the plugin still saves you the step of translating the recorded steps into CFML cfscript statements.  If you are using ColdFusion 8 or 9 and can run CFSelenium via MXUnit tests, I would suggest checking out the MXUnit documentation, especially the "Testing Basics" section, so you know a bit about how MXUnit works.

After you've recorded a few tests, you'll probably want to run those tests on other browsers.  The Selenium Server supports a number of different browsers but sometimes you have to do some tweaking to get the Selenium Server and the browser working together:  that'll be the subject of another post.

No comments:

Post a Comment