Quick start guide

This is intended as a quick, high speed coverage of using Simon. Details for all of this can be found in subsequent parts of this documentation. Only 5 easy steps.

Step 1: Including Simon in the test project

To run Simon, you need a test target. This is a duplicate of your app target which runs your app in the simulator or device. The only difference between this target and your main target is that this one includes the Simon and dNodi frameworks. See the installation page for details of the versions to include.

Step 2: Tell Simon to use it’s built in UI

This is simple. Open the Xcode scheme you are using to launch Simons build target and add a command line argument of -ui. This tells Simon that after the app has launched, it is to immediate overlay it with Simons in app control center so that you can manually run the stories. It should look something like this screen shot:

Step 3: Include story files

The next stage is to write to get together with the customer and write the story files. One done, make sure they are included in the test app target by adding them in the Copy Files stage. here’s an example of a simple story:

File: MyApp.stories

   Given the interface is up
   when I click the hello button
   Then the console should say "hello"

Step 4: Write the implementations

For Simon to execute a story successfully it needs to have methods which are matched to the steps in the stories and which perform the matching actions for that step. The classes that contain these methods do not need to implement any particular protocol or extend any particular classes. The best and simplest thing is to just create simple classes. For example:

@interface TestSteps : NSObject
@end

@implementation TestSteps

   -(void) whenTheAppIsUp {
       NSLog(@"The app is up");
   }

   -(void) clickAButtonCalled:(NSString *) aButtonName {
       NSLog(@"Clicking %@", aButtonName);
   }

   -(void) validateConsoleSays:(NSString *) aMsg {
       NSLog(@"Looking for console message %@", aMsg);
   }

@end

Map the stories to code

Now we have our story files and implementation classes, we need to bring them together. This is done using Simon’s SISIMapStepToSelector(regex, selector) macro. This macro creates the relationship between the step and method so that Simon knows to call it when it is executing the step.

#import <Simon/SISimon.h>

@interface TestSteps : NSOBject
@end

@implementation TestSteps

   SIMapStepToSelector(@"Given the interface is up", whenTheAppIsUp);
   -(void) whenTheAppIsUp {
       NSLog(@"The app is up");
   }

   SIMapStepToSelector(@"when I click the (.*) button", clickAButtonCalled:)
   -(void) clickAButtonCalled:(NSString *) aButtonName {
       NSLog(@"Clicking %@", aButtonName);
   }

   SIMapStepToSelector(@"Then the console should say \"(.*)\"", validateConsoleSays:)
   -(void) validateConsoleSays:(NSString *) aMsg {
       NSLog(@"Looking for console message %@", aMsg);
   }

@end

You will notice here the usage of regex expressions to capture values from the step text and pass them to the implementation.

Add actions and verifications

Simon provides a whole range of macros for interacting with the UI of you app and verifying results. Check out the Macro Reference for the complete list. Now lets look at our example with some of these macros added:

#import <Simon/SISimon.h>

@interface TestSteps : NSOBject
@end

@implementation TestSteps

   SIMapStepToSelector(@"Given the interface is up", whenTheAppIsUp);
   -(void) whenTheAppIsUp {
       NSLog(@"The app is up");
   }

   SIMapStepToSelector(@"when I click the (.*) button", clickAButtonCalled:)
   -(void) clickAButtonCalled:(NSString *) aButtonName {
       NSLog(@"Clicking %@", aButtonName);
       SITapButtonWithLabel(aButtonName);
   }

   SIMapStepToSelector(@"Then the console should say \"(.*)\"", validateConsoleSays:)
   -(void) validateConsoleSays:(NSString *) aMsg {
       NSLog(@"Looking for console message %@", aMsg);
       // Assuming that the Label has a tag value of 1.
       UILabel *label = SIFindView(@"//UILabel[@tag=1]");
       SIAssertObjectEquals(aMsg, label.text);
   }

@end

There are a couple of things happening here. Firstly after the app loads, Simon will tap the “Hello” button. Then Simon locates a UILabel which is acting as the console and checks it text for the required message. Notice here that Simon is not only able to find the UILabel, but to use one of it’s properties to ensure it has the correct one. Check out Interaction with the UI for more details about this.

Step 5: Run !

If you now run your test version of the app, Simon will wait for the app’s main interface to become active and then start running stories in the background. Once they have finished running, Simon will report the results to both the console and bring up a report screen on the simulator or device.

Alternatively you can modify the XCode Scheme that starts the app and add the —noautorun argument to stop Simon running immediately and jump straight to the report screen.

blog comments powered by Disqus

Index

Simon What is BDD? Why Simon?
Installation Quick Start Guide Simon's UI
Writing Stories Mapping Stories Step Conversations Validating Results Accessing your app's UI Exceptions and Errors
The Pieman
Macro reference API reference Simon's CLI args Pieman's CLI args Change Log Thank you BSD License

Download latest
static library
v0.2.0