rialvalue.com » testing

Documenting functions and named parameters

Xavi Beumala — Fri, 04 Feb 2011 08:03:09 +0000

Sometime ago someone asked me how I’d pass custom paramaters to event listeners. I don’t remember the exact use case neither who asked me but basically he was asking for something like:

mc.addEventListener(MouseEvent.CLICK, myListener, "myCustomParam", 2);
functoin myListener(event: MouseEvent, custom :String, custom2 : int) : void;

While the exact syntax above would not be possible, closures are in any case the way to go. I explained him how I’d do it and I forgot about the topic until today.

Today while waiting for a long compilation process to complete I’ve came up with an idea on how to improve code readability on cases similar to this. Here’s the cleaneast syntax I’ve came up with (ideas are more than welcome to improve it):

mc.addEventListener( MouseEvent.CLICK, createListenerAdapterBasedOn(myListener, withParameters("myCustomParam", 2)));

Does it look too verbose? I guess it will highly depend on the exact use case where this is used. But under some circumstances I think the readability can be substantially improved.

createListenerAdapterBasedOn is a package level method. I could have used a utility static method like FunctionUtils.createListenerAdapter. But instead I’ve used a package function because I can reduce the length of the Class + method name (or use the same number of characters to add verbosity and clarity). On the other hand it’s unlikely that this utility class would have more methods.

Documenting functions

This is a concept I’ve never read about or used before, but I think I’ll start using in different places. withParameters method is a completely dummy method that simply returns the parameters it gets but giving them a semantic and contextual meaning. The solely purpose of this method is to improve the readability by converting the method invocation in a Fluent API that can be read as natural language. The method is simply documenting the usage of the call. Putting this together with the Builder pattern and named parameters I discussed a while ago it gives us an incredible weapon to create self-documented code that doesn’t need most-of-the-times useless, needless and confusing ASDoc or inline comments.

If necessary when you have a method accepting several parameters of the same type and that can be confusing to read you could used Documenting functions to create kind of named-parameters:

myMethod(name("John"), surname("Green"), age(33), weight(70))

Here are the details of the implementation in case you are interested in seeing the internal details and some of the tests.

createListenerAdapterBasedOn.as

package com.rialvalue.utils
{
public function createListenerAdapterBasedOn(callback:Function, ... args):Function
{
return function(... rest):*
{
if (args.length == 1)
return callback.apply(null, rest.concat(args[0]));
else
return callback.apply(null, rest.concat(args));
}
}
}

withParameters.as

package com.rialvalue.utils
{
public function withParameters(... args):Array
{
return args;
}
}

createListenerAdapterBasedOnTest.as

package com.rialvalue.utils
{
import flash.display.MovieClip;
import flash.events.Event;
import flash.events.IEventDispatcher;
import flash.events.MouseEvent;

import flashx.textLayout.debug.assert;

import org.flexunit.assertThat;
import org.hamcrest.object.equalTo;

public class ListenerUtilsTest
{

private static const ORIGINAL_PARAMETER:String = "originalParameter";

private static const FIRST_PARAM:String = "firstParam";

private static const SECOND_PARAM:String = "secondParam";

[Test]
public function createCallbackAdapterWithNoParameters():void
{
var callbackAdapter:Function = createListenerAdapterBasedOn(function(data:String):void
{
assertThat(ORIGINAL_PARAMETER, equalTo(data));
});

callbackAdapter(ORIGINAL_PARAMETER);
}

[Test]
public function createCallbackAdapterWithIndividualParameter():void
{
var callbackAdapter:Function = createListenerAdapterBasedOn(function(data:String, p1:String):void
{
assertThat(ORIGINAL_PARAMETER, equalTo(data));
assertThat(FIRST_PARAM, equalTo(p1));
}, withParameters(FIRST_PARAM));

callbackAdapter(ORIGINAL_PARAMETER);
}

[Test]
public function createCallbackAdapterWithIndividualParameterNoFluent():void
{
var callbackAdapter:Function = createListenerAdapterBasedOn(function(data:String, p1:String):void
{
assertThat(ORIGINAL_PARAMETER, equalTo(data));
assertThat(FIRST_PARAM, equalTo(p1));
}, FIRST_PARAM);

callbackAdapter(ORIGINAL_PARAMETER);
}

[Test]
public function createCallbackAdapterWithIndividualParameters():void
{
var callbackAdapter:Function = createListenerAdapterBasedOn(function(data:String, p1:String, p2:String):void
{
assertThat(ORIGINAL_PARAMETER, equalTo(data));
assertThat(FIRST_PARAM, equalTo(p1));
assertThat(SECOND_PARAM, equalTo(p2));
}, withParameters(FIRST_PARAM, SECOND_PARAM));

callbackAdapter(ORIGINAL_PARAMETER);
}

[Test]
public function createCallbackAdapterWithIndividualParametersNoFluent():void
{
var callbackAdapter:Function = createListenerAdapterBasedOn(function(data:String, p1:String, p2:String):void
{
assertThat(ORIGINAL_PARAMETER, equalTo(data));
assertThat(FIRST_PARAM, equalTo(p1));
assertThat(SECOND_PARAM, equalTo(p2));
}, FIRST_PARAM, SECOND_PARAM);

callbackAdapter(ORIGINAL_PARAMETER);
}
}
}

Streamlining your Flex project environment

Xavi Beumala — Thu, 10 Jun 2010 07:27:31 +0000

In case you missed it, a couple of days ago an article I wrote a while ago went live in Adobe Devnet

The article summarizes a set of best practices to configure your projects on Flash Builder and Eclipse in general for maximum efficiency and reduced maintenance effort.

As a software engineer joining a new project, I want to be able to get the code quickly, build it, and then run the application. I don’t want to have to work through a complex set up procedure, read countless how-to documents, or learn the detailed ins-and-outs of the application to simply get started.

You can read the article on Devnet.

Do you follow any other best practices? any tips?

HowTo create your developer ToolBox with Mixins

Xavi Beumala — Fri, 21 May 2010 11:25:33 +0000

In this post I’ll explain how you can develop a flex library that automatically initializes itself avoiding developers the hassle of remembering how, when and where the libraries need to be initialized and hooked into the application. This can be particularly helpful for debugging libraries like fxSpy, DeMonsterDebugger, KaptInspect, mrdoob, etc. and extremely useful to create your own Flex toolbox that simply plugs-in and can go with you on all your developments.

First, create a class in your library project with whatever name you pick, in my case I’ll call it LibraryInitializer.as, make sure you mark this class to be included on the final swc or even better use the new FB4 option “Include all classes from all sources”. Second and key point, add a public static method named init that receives a parameter and mark the class as a Mixin:

[Mixin]
public class LibraryInitializer
{
public static function init(systemManager:ISystemManager):void
{
}
}

The [Mixin] metadata tag is extensively used in the Flex automation API and it basically gives you a very interesting hook. The static init method of any class marked as a [Mixin] will be invoked at a very early point during the application initialization phase by the SystemManager class or FlexModuleFactory. The Mixins are executed before the preInitialize event is triggered on the main Application. The parameter that the init method receives is a reference to the related SystemManager so you can mark the parameter as an ISystemManager, InteractiveObject or whatever better fits your needs. You can read about another interesting use of the [Mixin] on the Global Exception Handler post .

By adding a Mixin class in a library and linking the library to an Application what you effectively get is a hook where the library can initialize itself and release the developer from manually initializing it.

Let’s see some real world examples.

Libraries like fxSpy, deMonsterDebugger, KaptInspect or mrdoob are extremely easy to use but on each project you end up doing some repetitive steps or adding conditionally compiled code to your Main application class.

I’ll focus on a sample with fxSpy where you can launch it from a contextual option when you right click on the application and see mrdoob memory monitor. The only step required to integrate this will is adding the following compiler option:

-include-libraries=libs/myToolbox.swc

And this is the library initializer, which basically adds a ContextMenuItem to the contextMenu of the systemManager. Note that we have to wait for the APPLICATION_COMPLETE event, otherwise the Flex SDK will override our contextMenu (it happens on the pre-initialize phase).

package
{
import com.flexspy.FlexSpy;

import flash.display.InteractiveObject;
import flash.events.ContextMenuEvent;
import flash.events.Event;
import flash.ui.ContextMenu;
import flash.ui.ContextMenuItem;

import flashx.textLayout.elements.GlobalSettings;

import mx.core.FlexGlobals;
import mx.events.FlexEvent;
import mx.managers.ISystemManager;

import spark.core.SpriteVisualElement;

[Mixin]
public class MyToolBoxInitializer
{
private static var initializer:MyToolBoxInitializer;

public static function init(systemManager:ISystemManager):void
{
systemManager.addEventListener(FlexEvent.APPLICATION_COMPLETE, applicationCompleteHandler);
}

private static function applicationCompleteHandler(event:Event):void
{
var systemManager:InteractiveObject = event.target as InteractiveObject;
systemManager.removeEventListener(FlexEvent.APPLICATION_COMPLETE, applicationCompleteHandler);

initializer = new MyToolBoxInitializer(systemManager);
}

public function MyToolBoxInitializer(target:InteractiveObject)
{
createContextMenu(target);
createMonitor();
}

private function createContextMenu(target:InteractiveObject):void
{
var contextMenu:ContextMenu = target.contextMenu;
contextMenu.customItems = [ createContextMenuItem() ];
}

private function createMonitor():void
{
var sve:SpriteVisualElement = new SpriteVisualElement();
sve.addChild(new Stats());
FlexGlobals.topLevelApplication.addElement(sve);
}

private function createContextMenuItem():ContextMenuItem
{
var contextItem:ContextMenuItem = new ContextMenuItem("Flex Spy");
contextItem.addEventListener(ContextMenuEvent.MENU_ITEM_SELECT, handleContextMenuItemSelect);

return contextItem;
}

private function handleContextMenuItemSelect(event:Event):void
{
FlexSpy.show();
}
}
}

In the Initializer you could also intialize the fps and memory monitor provided by mrdoob by simply adding a new instance to the DisplayList.

These are the benefits I see on this approach:

You won’t have to reapeat yourself in different projects initializing the same libraries always in the same way.
Your main file won’t be cluttered with infrastructure and glue code to configure your libraries.
You won’t need to use conditional compilation for this initializations. You can enable or disable all at once by removing the compiler option. Going an step further you could have diferent compiler profiles / environments on your ant tasks or maven builds or even use the -load-config compiler option to externalize your configurations to an xml file.

You can downdload a zip with 2 sample projects, one for the library and the other for the application using it.

Shortly I’ll blog about some of the things I have in my toolbox that could be helpful for you too.

Logging and catching (async) exceptions during invalidation

Xavi Beumala — Tue, 25 Aug 2009 12:21:44 +0000

Sometimes, due to many different reasons, there’re exceptions that happen during the invalidation/validation cycle of the flex SDK. Most times these exceptions end up being unveiled in the very core of the SDK, being not possible to catch them up because their async nature and the place where they happen.

The stacktrace of these exceptiosn, normally, looks like the lines below:

...
at mx.core::UIComponent/validateProperties()[C:\autobuild\3.x\frameworks\projects\framework\src\mx\core\UIComponent.as:5807]
at mx.managers::LayoutManager/validateProperties()[C:\autobuild\3.x\frameworks\projects\framework\src\mx\managers\LayoutManager.as:539]
at mx.managers::LayoutManager/doPhasedInstantiation()[C:\autobuild\3.x\frameworks\projects\framework\src\mx\managers\LayoutManager.as:689]
at Function/http://adobe.com/AS3/2006/builtin::apply()
at mx.core::UIComponent/callLaterDispatcher2()[C:\autobuild\3.x\frameworks\projects\framework\src\mx\core\UIComponent.as:8633]
at mx.core::UIComponent/callLaterDispatcher()[C:\autobuild\3.x\frameworks\projects\framework\src\mx\core\UIComponent.as:8582]

Today, snooping around the UIComponent class, I’ve found a nice unexpected thing. Basically the invalidation pattern in the SDK is built around the LayoutManager and the UIComponent classes. The callLater method is the responsible to delay the execution of certain functionalities to the next frame. callLater implementation relies on the RENDER and ENTER_FRAME frames. The handler for these events is the method callLaterDispatcher.

// At run-time, callLaterDispatcher2() is called
// without a surrounding try-catch.
if (!UIComponentGlobals.catchCallLaterExceptions)
{
callLaterDispatcher2(event);
}

// At design-time, callLaterDispatcher2() is called
// with a surrounding try-catch.
else
{
try
{
callLaterDispatcher2(event);
}
catch(e:Error)
{
var callLaterErrorEvent:DynamicEvent = new DynamicEvent("callLaterError");
callLaterErrorEvent.error = e;
systemManager.dispatchEvent(callLaterErrorEvent);
}
}

Here’s the surprise. If UIComponentGlobals.catchCallLaterExceptions is true, the execution of the validation cycle will be wrapped with a try..catch and a DynamicEvent will be dispatched through the systemManager with information about the error.

This opens the doors for at least catch the error and log it. In some cases, depending on the severity of the error and if the application is not too corrupted, we’ll even be able to display a message to the user notifying him the error. This is not a fix to FP-1499 nor FP-444 but under some circumstances it can be really helpful if combined with great logging practices as explained by Tom.

I’ve created a simple class that hooks into the systemManager, listens for the callLaterError event and logs it using the standard SDK logging mechanism. The AsyncErrorLogger is MXML friendly so that it can be instantiated in the root application. It provides an enable property to switch the behavior on and off. Additionally the property redispatchErrorEvent, which by default is false, redispatches the error causing the traditional flash player error dialog to appear (in debugger player versions) and not fail silently.

Here’s an example on how to use it:

version = "1.0" encoding = "utf-8"?>
xmlns:mx = "http://www.adobe.com/2006/mxml" xmlns:utils = "com.adobe.ac.utils.*">

>

import mx.logging.LogEventLevel;

//---------------------------------------------
// THAT'S THE WAY TO SIMULATE THE ASYNC ERROR
//---------------------------------------------

private var doItChange : Boolean = false;

private function doIt() : void
{
doItChange = true;
invalidateProperties();
}

override protected function commitProperties() : void{
super.commitProperties();

if( doItChange )
{
doItChange = false;
throw new Error("CallLater exception");
}
}
]]>
>

level = "{ LogEventLevel.ALL }"/>

/>

click = "doIt()" label = "Throw exception"/>
>

Here’s the code. You can download the class from here as well.

package com.adobe.ac.utils
{
import flash.events.ErrorEvent;
import flash.events.EventDispatcher;

import mx.core.Application;
import mx.core.UIComponentGlobals;
import mx.events.DynamicEvent;
import mx.events.FlexEvent;
import mx.logging.ILogger;
import mx.logging.Log;
import mx.managers.ISystemManager;

[Event(name="error",type="flash.events.ErrorEvent")]
public class AsyncErrorLogger extends EventDispatcher
{
//------------------------------------------------------------------------
//
// Constants
//
//------------------------------------------------------------------------
private static const CALL_LATER_ERROR:String = "callLaterError";

private static const LOG:ILogger = Log.getLogger("com.adobe.cairngorm.AsyncErrorLogger");

//------------------------------------------------------------------------
//
// Properties
//
//------------------------------------------------------------------------

//-------------------------------
// systemManager
//-------------------------------
private var systemManager:ISystemManager;

//-------------------------------
// logStackTrace
//-------------------------------

public var logStackTrace:Boolean = true;

//-------------------------------
// redispatchError
//-------------------------------
public var redispatchError:Boolean = false;

//-------------------------------
// enabled
//-------------------------------

[Bindable]
public function get enabled():Boolean
{
return UIComponentGlobals.catchCallLaterExceptions;
}

public function set enabled(value:Boolean):void
{
UIComponentGlobals.catchCallLaterExceptions = value;
}

//------------------------------------------------------------------------
//
// Constructor
//
//------------------------------------------------------------------------

public function AsyncErrorLogger(systemManager:ISystemManager = null)
{
enabled = true;

init(systemManager);
}

//------------------------------------------------------------------------
//
// Private Methods
//
//------------------------------------------------------------------------

private function init(systemManager:ISystemManager):void
{
if (systemManager)
{
initializeListener(systemManager);
}
else
{
var application:Object = Application.application;

if (!application.initialized)
{
application.addEventListener(FlexEvent.CREATION_COMPLETE, creationCompleteHandler);
}
else
{
initializeListener(application.systemManager);
}
}
}

private function creationCompleteHandler(event:Event):void
{
var application:Object = Application.application;
application.removeEventListener(FlexEvent.INIT_COMPLETE, creationCompleteHandler);

initializeListener(application.systemManager);
}

private function initializeListener(systemManager:ISystemManager):void
{
this.systemManager = systemManager;

if (this.systemManager)
{
LOG.debug("AsynErrorLogger initialized.");
this.systemManager.addEventListener(CALL_LATER_ERROR, errorHandler);
}
}

private function errorHandler(event:DynamicEvent):void
{
var error:Error = event.error as Error;

LOG.error("{0}", error.message);

if (logStackTrace)
{
LOG.error(error.getStackTrace());
}

if (redispatchError)
{
var errorEvent:ErrorEvent = new ErrorEvent(ErrorEvent.ERROR, false, false, error.getStackTrace(), error.errorID);
dispatchEvent(errorEvent);
}
}
}
}

Debugging production ready AIR applications

Xavi Beumala — Sun, 16 Aug 2009 02:19:49 +0000

One of the biggest problems around testing installed AIR applications is that testers can’t see when a runtime exception is triggered. Lots of times the symptom of a problem will be something completely different to the real cause and developers will have to spend much more time trying to figure out what was the root cause of the problem. Even though you have a good logging policy if there’s an uncaught exception there’s not too much you can do.

Here are some techniques I’ve came across to make testing less painful for everybody.

The debug flag way

One thing I’ve been thinking for a while is that there are not two different versions of the AIR runtime; one with debugging enabled and the other without it (the way Flash Player has). This means that there might be a way to enable and disable debugging in the same runtime. This would allow, at least in some controlled environments, to see Runtime Exceptions and make everybody’s life easier. At least until we have global error handling implemented directly on AIR or Flash Player. Yes, I agree, It’s unbelievable that on its 10th version we still are not able to capture global exceptions: FP-444 and FP-1499

Using Procmon I realized that when an AIR application is launched it tries to read a file in {INSTALLATION_FOLDER}/META-INF/AIR/debug. See the screenshot. What surprised me was the result “NAME NOT FOUND”. Basically the file didn’t exist in the app I was playing with. After some more trial / error, yes, you’re right, this is the flag that switches on and off debugging capabilities.

If an AIR application is launched and an empty file with name debug is found in {INSTALLATION_FOLDER}/META-INF/AIR/debug then, any runtime exception will be displayed in a system modal window! In OS the path for this file will be {APPLICATION_FOLDER}.app/Contents/Resources/META-INF/AIR/debug

So if testers (or users during the earlier versions of your app) are using your application, make sure they create the debug file and attach any stack trace they see to their bug reports.

The adl way

This is not as easy as the previous solution but it gives the testers more options.

Once installed, an AIR application, is not more than the swf file produced from FB, its application descriptor and a native launcher. Given that we have access to the main application swf file and its corresponding descriptor we can use ADL to launch the installed application instead of the native launcher.

Here’s how:

1. Installed the SDK you want to use from http://opensource.adobe.com/wiki/display/flexsdk/Downloads
2. Uncompress the zip in the location you prefer. I’ll refer to this folder as {FLEX_HOME}

In Windows
3. Right click on “My Computer” > Properties
4. Go to “Advanced” tab
5. Click in the option “Environment Variables”
6. In the “System variables” find the “Path” definition and add this to it (double clicking on it): “;{FLEX_HOME}/bin”
7. Make sure your replace {FLEX_HOME} with the path to the folder where you’ve uncompressed the SDK

In OS X
3. Open a terminal
4. Execute this command: open ~/.bash_profile
5. Add the following line to the opened file:
PATH=${PATH}:{FLEX_HOME}/bin
6. Make sure your replace {FLEX_HOME} with the path to the folder where you’ve uncompressed the SDK

In Linux
3. Open a terminal
4. Edit your profile file ~/.profile
5. Add the line: export PATH=$PATH:$FLEX_HOME

Then to launch the application you will have to:

In Windows
1. Open a command line window. Start > “Run …” > cmd
2. Navigate to the folder where the application is installed: cd “Program Files”/MyApp
3. Execute this command: adl META-INF/AIR/application.xml .
4. Don’t forget the dot at the end of the command

In OS X and Linux
1. Open a terminal
2. Navigate to the folder where the application is installed: cd /soft/testAirApp.app/Contents/Resources where testAirApp is the name of your application
3. Execute the following command: adl META-INF/AIR/application.xml .
4. Don’t forget the dot at the end of the command

If during the execution process there’s an exception, ADL will show it.