By Paulo Caroli
 
Paulo Caroli
By Henrik Lindahl
 
Henrik Lindahl
Modified
29 October 2008
 

Requirements

 
Prerequisite knowledge

You should have a good understanding of ActionScript 3.0 as well as the JUnit unit testing framework.
 

 
User level

Intermediate
 

 
Additional Requirements

 
Selenium Remote Control
 
FlashSelenium
Functional tests are intended to help you verify that a system, as a whole, functions as intended. Such tests verify that everything is wired together correctly. Selenium is an open-source testing tool for web applications. Selenium tests run directly in the web browser itself, mimicking what real users do. Furthermore, it supports a large variety of browsers and platforms. It is especially useful for executing tests to verify web application functionality and user acceptance. We used Selenium in our last project to verify that a web application (which contains one or more Flash components) worked the way we wanted.
 
Even though Selenium has been widely used for testing web applications, we did not find any resources linking Selenium to Flash or Flex when we started developing and testing Flash applications ourselves. After some work, however, we had a working solution for Selenium to test a deployed Flash application. This article describes how you can use the Selenium web testing tool to create and run functional tests for Flash and Flex web applications.
 

 
Solution overview

The solution we describe in this article relies on FlashSelenium to drive the Selenium communication with Adobe Flash Player client. Figure 1 gives an overview of the proposed solution. But before digging into the details, you'll need to understand a few terminologies and technologies.
 
Proposed FlashSelenium solution
Figure 1. Proposed FlashSelenium solution
Selenium RC (Selenium Remote Control) is a tool that allows you to launch browser sessions and run Selenium tests against those browsers. To do this, the Selenium RC server acts as an intercepting proxy for the browser. Typically, commands are dispatched to the Selenium RC server through a Selenium RC client driver.
 
For instance, you can programmatically create a Selenium RC test with JUnit and the Selenium-Java-client driver. Selenium RC currently provides client drivers for Java, .NET, Python, Ruby, and PHP. Selenium RC client drivers provide methods for interacting with the browser components in the native unit test language. Selenium RC uses JavaScript as the underlying communication between the Selenium RC client driver, the Selenium RC server, and the browser. Moreover, Selenium RC is simple to set up and easy to use.
 
The following is the "Hello World" example for Selenium RC Java Client Driver:
 
package com.thoughtworks.selenium; import junit.framework.*; import org.openqa.selenium.server.*; public class GoogleTest extends TestCase { private Selenium selenium; public void _eard() throws Exception { String url = "http://www.google.com"; selenium = new DefaultSelenium("localhost", SeleniumServer.getDefaultPort(), "*firefox", url); selenium.start(); } protected void _eardown() throws Exception { selenium.stop(); } public void testGoogle() throws Throwable { selenium.open("http://www.google.com/webhp?hl=en"); assertEquals("Google", selenium.getTitle()); selenium.type("q", "Selenium OpenQA"); assertEquals("Selenium OpenQA", selenium.getValue("q")); selenium.click("btnG"); selenium.waitForPageToLoad("5000"); assertEquals("Selenium OpenQA – Google Search", selenium.getTitle()); } }
The Flash ExternalInterface component (introduced in Flash Player 8) is an API that enables communication between a SWF file and the Flash Player container. One of its uses is to make it possible to invoke ActionScript functions in a SWF file from JavaScript.
 

 
The FlashSelenium component

Selenium RC uses JavaScript to communicate with the browser. Flash ExternalInterface provides a mechanism for which you can use JavaScript to call an ActionScript function in a SWF file embedded in an HTML page. Therefore, we created FlashSelenium, a Selenium RC client extension that uses JavaScript as the conduit between Selenium RC and the Flash application (see Figure 2).
 
FlashSelenium with JavaScript connecting to Flash ExternalInterface
Figure 2. FlashSelenium with JavaScript connecting to Flash ExternalInterface
FlashSelenium is the component that adds Flash communication capabilities to the Selenium framework. Basically, it is a Selenium RC client driver extension for helping execute the tests against the Flash component. The FlashSelenium constructor takes a Selenium instance and a Flash object ID as parameters.
 
An instance of FlashSelenium is used to invoke the functions on the Flash component. You can invoke functions that were externalized by the ExternalInterface, as well as the default functions of any Flash SWF (for example, isPlaying, PercentLoaded and TotalFrames). FlashSelenium is currently available for Java, .NET, Ruby, and Python. Analogous components are being created for PHP.
 
Next we will show you a complete example of a Flash-based web application and its corresponding Selenium RC tests.
 

 
Sample web application

The sample web application is very simple. It consists of a web page with an embedded Flash SWF object. The title of the page is "Clicking Colors." The Flash SWF object presents a clickable rectangle that repaints itself (rotating colors green, blue and red) for every click. Try it out on our demonstration page.
 
Below is the source code for colors.html, the web application containing a Flash SWF object:
 
<html> <head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> <title>Clicking Colors</title> <body> <object classid="clsid:d27cdb6e-ae6d-11cf-96b8-444553540000" codebase="http://fpdownload.macromedia.com/pub/shockwave/cabs/flash/swflash.cab#version=8,0,0,0" width="100" height="100" id="clickcolors" align="middle"> <param name="allowScriptAccess" value="sameDomain" /> <param name="movie" value="ColoredSquare.swf" /> <param name="quality" value="high" /> <param name="bgcolor" value="#ffffff" /> <embed src="ColoredSquare.swf" quality="high" bgcolor="#ffffff" width="500" height="500" name="clickcolors" align="middle" allowscriptaccess="*" type="application/x-shockwave-flash" pluginspage="/go/getflashplayer" /> </object> </body> </html>
Note that the Flash SWF object ID, clickcolors, will be used by the Selenium RC test.
 
Below is ColoredSquare.as, the source code for the Flash SWF component embedded in the web application:
 
package { import flash.display.Sprite; import flash.events.MouseEvent; import flash.external.ExternalInterface; import flash.text.TextField; import flash.text.TextFieldAutoSize; import flash.text.TextFormat; public class ColoredSquare extends Sprite { private const COLOR_HEX_VALUES:Array = [0×00ff00, 0×0000ff, 0xff0000]; private const COLORS:Array = ["GREEN", "BLUE", "RED"]; private const SQUARE_SIDE:uint = 500; private var currentColor:uint; private var currentColorIndex:uint = 0; private var buttonSprite:Sprite = new Sprite(); private var squareLabel:String = "(Click here)"; private var label:TextField = new TextField(); public function ColoredSquare() { currentColor = COLOR_HEX_VALUES[currentColorIndex % 3]; updateButtonLabel(); drawButton(); addEventListener(MouseEvent.CLICK, buttonClicked); // functions available for JavaSript calls ExternalInterface.addCallback("getColor", getColor); ExternalInterface.addCallback("click", changeColor); ExternalInterface.addCallback("getSquareLabel", getSquareLabel); ExternalInterface.addCallback("setSquareLabel", setSquareLabel); } private function buttonClicked(event:MouseEvent):void { changeColor(); } private function changeColor():void { currentColorIndex++; currentColor = COLOR_HEX_VALUES[currentColorIndex % 3]; this.squareLabel = COLORS[currentColorIndex % 3]; updateButtonLabel(); drawButton(); } private function updateButtonLabel():void { var format:TextFormat = new TextFormat(); format.size = SQUARE_SIDE / 10; var label:TextField = new TextField(); label.autoSize = TextFieldAutoSize.LEFT; label.selectable = false; label.defaultTextFormat = format; label.text = squareLabel; label.x = SQUARE_SIDE / 5; label.y = SQUARE_SIDE / 2.5; if (buttonSprite.contains(this.label)) { buttonSprite.removeChild(this.label); } this.label = label; buttonSprite.addChild(this.label); } private function drawButton():void { buttonSprite.graphics.beginFill(currentColor); buttonSprite.graphics.drawRect(0, 0, SQUARE_SIDE, SQUARE_SIDE); buttonSprite.graphics.endFill(); addChild(buttonSprite); } public function setSquareLabel(squareLabel:String):void { this.squareLabel = squareLabel; updateButtonLabel(); drawButton(); } public function getColor():String { return COLORS[currentColorIndex % 3]; } public function getSquareLabel():String { return this.squareLabel; } } }
The following ChangeColor functions are made available for JavaScript invocation by means of the ExternalInterface: getColor, changeColor, getSquareLabel, and setSquareLabel:
 
// functions available for JavaSript call ExternalInterface.addCallback("getColor", getColor); ExternalInterface.addCallback("click", changeColor); ExternalInterface.addCallback("getSquareLabel", getSquareLabel); ExternalInterface.addCallback("setSquareLabel", setSquareLabel);

 
The Selenium RC client

We selected the Selenium RC Java client to trigger the tests. Analogous implementations can be made for the other available Selenium RC clients: .NET, Perl, Python, and Ruby.
 
We encourage you to run the following Selenium RC Java client JUnit test against the sample web application. But before doing so, please make sure the environment is properly set up and that you are familiar with executing a basic Selenium RC Java client JUnit test.
 
FlashSelenium is the component that enables Selenium RC Java client to talk to Flash. To use it, all you need to do is add flashselenium-java-client-extension.jar (JAR, 3.6K) to your classpath, the same way you added junit.jar and selenium-client-driver.jar.
 
The following is the ChangeColorsSiteTest.java, a Selenium-based JUnit test case testing the web application containing the changecolor flash component:
 
import com.thoughtworks.selenium.DefaultSelenium; import com.thoughtworks.selenium.Selenium; import com.thoughtworks.selenium.SeleniumException; import junit.framework.TestCase; public class ColorsTest extends TestCase { private FlashSelenium flashApp; private Selenium browser; private final static String GREEN = "GREEN"; private final static String BLUE = "BLUE"; private final static String RED = "RED"; private final static String URL = "http://flashselenium.t35.com/colors.html"; public void setUp() { browser = new DefaultSelenium("localhost", 4444, "*firefox",URL); browser.start(); flashApp = new FlashSelenium(browser, "clickcolors"); browser.open(URL); } public void tearDown() { browser.stop(); } public void testColorTransition() { assertEquals("Clicking Colors", browser.getTitle()); assertEquals(GREEN, flashApp.call("getColor")); flashApp.call("click"); assertEquals(BLUE, flashApp.call("getColor")); flashApp.call("click"); assertEquals(RED, flashApp.call("getColor")); flashApp.call("click"); assertEquals(GREEN, flashApp.call("getColor")); } public void testRectangleLabel() { assertEquals("(Click here)", flashApp.call("getSquareLabel")); flashApp.call("setSquareLabel", "Dummy Label"); assertEquals("Dummy Label", flashApp.call("getSquareLabel")); } }
Notice at the testColorTransition method that the following statement is testing the web page title:
 
assertEquals("Clicking Colors", browser.getTitle());
This exemplifies that, beyond adding Flash testing capabilities, you are able to use Selenium for testing all other web application objects. You are also able to do all the web application verifications from the same test (if appropriate). This capability is particularly interesting for validating the interoperability of web application components—for example, validating corresponding values from the Flash component and the rest of the web application.
 
The remaining part of the testColorTransition method validates the color transition logic. Note that the changeColor() ActionScript 3.0 code method is directly invoked by the Selenium RC Client code:
 
flashApp.call("click");
The testRectangleLabel method shows a scenario in which the test validates an external parameter being passed to the Flash application, the rectangle label. Figure 3 shows the ChangeColorsSiteTest executed within the Eclipse IDE.
 
Executing the ChangeColorSiteTest within Eclipse
Figure 3. Executing the ChangeColorSiteTest within Eclipse
Figures 4 and 5 show the sequence (within the browser started by Selenium) when executing the testRectangleLabel() test.
 
testRectangleLabel() in execution: Step 1
Figure 4. testRectangleLabel() in execution: Step 1
testRectangleLabel() in execution: Step 2
Figure 5. testRectangleLabel() in execution: Step 2

 
Where to go from here

This article showed you how to run Selenium tests for your Flash-based web application. On the Selenium RC client side, you use FlashSelenium (for Java, available as flashselenium-java-client-extension.jar), a Selenium RC client extension that enables communication between the Selenium RC client and the Flash application. On the Flash side, you can verify the default functions of any Flash SWF (e.g., isPlaying, PercentLoaded, and TotalFrames) and/or a specific Flash application's functions externalized by Flash ExternalInterface. We walked you through testing a simple web application containing a Flash SWF object. For more examples, please refer to the Flash Selenium project page.
 
FlashSelenium is useful for testing both Flash and Flex applications. As we demonstrated in this article, the tests are executed against the deployed SWF. Flex originally was designed to support enterprise development for the Flash platform. For instance, Flex is geared towards application development. Testing is a fundamental practice for a successful enterprise development practice. Therefore, Flex developers should add Selenium and FlashSelenium to their test tools arsenal.
 
Selenium RC is the proposed solution's main component. Selenium drives the functional tests against the web application embedding the Flash SWFs. Because Selenium is an active open-source project, we can benefit from its current and future capabilities (for instance, Selenium Grid could be used for running tests in parallel and for validating Flash web applications' compatibility against a variety of browsers and operational systems). Also, as is usually the case, the Flash application executes in a web browser; and by using Selenium (and enhancing it to work with Flash), we are able to test the Flash application as well as the other web application components.
 
Our special thanks to Mark Striebeck, Paul Hammant, and Jason Huggins for encouraging and supporting this work.