Wednesday, February 3, 2010

Using FoneMonkey With OCUnit

FoneMonkey, the world's first functional testing automation tool for the iPhone, now provides direct support for running FoneMonkey scripts from OCUnit test suites.

You can download the latest version of FoneMonkey here.

Running Under OCUnit

OCUnit (also known as SenTestingKit) is a unit testing framework for Objective-C that's bundled with the XCode IDE. As a member of the xUnit family of testing frameworks, OCUnit is similar to other popular frameworks such as JUnit (for Java), and FlexUnit (for Adobe Flex).

Using OCUnit, you can combine FoneMonkey- and non-FoneMonkey-based tests into comprehensive test suites that can be invoked interactively, as well as from build scripts, and from continuous integration frameworks such as Hudson or Cruise Control. It is also possible to combine OCUnit tests with non-OCUnit (for example, JUnit) tests, and combine the output so as to provide considated test reporting across all front- and back-end components of your application.

Please note that to run FoneMonkey with OCUnit, you should not create a testing bundle. Instead, you use the FoneMonkeyOCUnit plug-in to launch your OCUnit tests cases, as described later in this section.

Adding OCUnit to Your Project

You add OCUnit to your project much in the same way you add any framework.

  • Right click on the target that includes FoneMonkey, and select Get Info from the menu. The Target Info dialog will be displayed.
  • Add a new entry to the Linked Libraries by clicking the add (+) button at the bottom of the dialog window. A selection dialog will open.
  • Click the Add Other... button. A file selection dialog will open.
  • Navigate to the /Developer/Library/Frameworks folder. Select SenTestingKit.framework.
  • Click the Add button.

Adding the FoneMonkeyOCUnit Plug-In

The FoneMonkey distribution includes libFoneMonkeyOCUnit.a which is a static library that extends FoneMonkey with an OCUnit test launcher.

  • To add the library to your project, right-click on your FoneMonkey testing target and select Get Info. The Target Info dialog will be displayed.
  • On the Build Tab, scroll down to the Linking section. Add -lFoneMonkeyOCUnit to Other Linker Flags so that it now should look something like this:

    -ObjC -all_load -lFoneMonkey -lFoneMonkeyOCUnit 

Writing a Test Case

You write your test cases for FoneMonkey in the same way you write any OCUnit test. To create a test case, simply subclass SenTestCase and use STAssertions to test for expected results. For more information on OCUnit (SenTestingKit), see Apple's Documentation.

Using the FoneMonkey API, you can run FoneMonkey commands from within your test case, and you use OCUnit Let's look at an example:

#import "FoneMonkey.h"

@interface SampleTest : SenTestCase

- (void) testSample;


@implementation SampleTest

- (void) testSample {
NSString* lastResult = [[FoneMonkey sharedMonkey] playAndWait:@"Test1"];
STAssertNil(lastResult, lastResult);


You run a FoneMonkey script from a test case by calling runScript:(NSString*)script, where script is the name of a FoneMonkey script stored in your application's Documents directory. runScript: returns nil if the script runs successfully. For example, in the script above we call:

    NSString* lastResult = [[FoneMonkey sharedMonkey] runScript:@"Test1"];

If the script fails for any reason, runScript: returns the message generated from a failed Verify command, or other error message. You need to explicitly add an assertion to test for a non-nil result, and display the returned message if it's non-nil as follows:

STAssertNil(lastResult, lastResult);

You can of course do more in your test case than simply run a script and test its result. You can include addition programming logic and assertions, and run multiple scripts.

Using the FoneMonkey API, It is also possible to build scripts programatically at run time, rather than running a script previously saved.

Running OCUnit Tests

When you link your application with FoneMonkey and FoneMonkeyOCUnit, FoneMonkey will by default run all SenTestCase subclasses, and OCUnit output will be written to the console.

If you would like to exit your application after the OCUnit tests have run, set FM_ENABLE_AUTOEXIT the environment variable.

You can disable the running of OCUnit tests upon FoneMonkey start up by setting the FM_DISABLE_AUTOSTART environment variable. Omitting the -lFoneMonkeyOCUnit linker flag will also disable the running of any OCUnit tests at startup.

No comments: