Inherits from NSObject
Declared in KIFTestStep.h

Overview

@class KIFTestStep

Steps are the most basic element of a test, and are added together to create the scenarios to be tested.

Steps are the building blocks of scenarios, and should be very simple. A number of useful factory steps are provided for mimicking basic user interaction. These steps leverage the built in accessibility of iOS to find and interact with views. As such, the accessibility inspector needs to be enabled under Settings in the simulator for them to work.

Tasks

Properties

description

@property (nonatomic, retain) NSString *description
Discussion

@property description

This is used to help describe what the test script is doing and where it may have failed.

Declared In

KIFTestStep.h

timeout

@property (nonatomic) NSTimeInterval timeout
Discussion

@property timeout

The timeout comes into play if a step returns the KIFTestStepResultWait result. If the step returns this result such that the step has been called repeatedly for a time greater than the timeout, then the step is considered to have failed. Steps are assumed to be well-behaved, and the timeout will not interrupt a step if it is running synchronously for an extended period of time.

Declared In

KIFTestStep.h

Class Methods

defaultTimeout

+ (NSTimeInterval)defaultTimeout
Discussion

@method defaultTimeout

To change the default value of the timeout property, either subclass KIFTestStep and override this method or call setDefaultTimeout: with a different value.

Declared In

KIFTestStep.h

setDefaultTimeout:

+ (void)setDefaultTimeout:(NSTimeInterval)newDefaultTimeout
Discussion

@method setDefaultTimeout:

To change the default value of the timeout property, either subclass KIFTestStep and override defaultTimeout or call this method with a different value.

Declared In

KIFTestStep.h

stepFailed

+ (void)stepFailed

stepThatFails

+ (id)stepThatFails
Discussion

@method stepThatFails

Mostly useful for test debugging or as a placeholder when building new tests.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepThatSucceeds

+ (id)stepThatSucceeds
Discussion

@method stepThatSucceeds

Mostly useful for test debugging or as a placeholder when building new tests.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToDismissPopover

+ (id)stepToDismissPopover
Discussion

@method stepToDismissPopover

With a popover up, tap at the top-left corner of the screen.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToEnterText:intoViewWithAccessibilityLabel:

+ (id)stepToEnterText:(NSString *)text intoViewWithAccessibilityLabel:(NSString *)label
Discussion

@method stepToEnterText:intoViewWithAccessibilityLabel:

The view or accessibility element with the given label is searched for in the view hierarchy. If the element isn’t found or isn’t currently tappable, then the step will attempt to wait until it is. Once the view is present and tappable, a tap event is simulated in the center of the view or element, then text is entered into the view by simulating taps on the appropriate keyboard keys.

Parameters

text

The text to enter.

label

The accessibility label of the element to type into.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToEnterText:intoViewWithAccessibilityLabel:traits:expectedResult:

+ (id)stepToEnterText:(NSString *)text intoViewWithAccessibilityLabel:(NSString *)label traits:(UIAccessibilityTraits)traits expectedResult:(NSString *)expectedResult
Discussion

@method stepToEnterText:intoViewWithAccessibilityLabel:traits:

The view or accessibility element with the given label is searched for in the view hierarchy. If the element isn’t found or isn’t currently tappable, then the step will attempt to wait until it is. Once the view is present and tappable, a tap event is simulated in the center of the view or element, then text is entered into the view by simulating taps on the appropriate keyboard keys.

Parameters

text

The text to enter.

label

The accessibility label of the element to type into.

traits

The accessibility traits of the element to type into. Elements that do not include at least these traits are ignored.

expectedResult

What the text value should be after entry, including any formatting done by the field. If this is nil, the “text” parameter will be used.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToEnterTextIntoCurrentFirstResponder:

+ (id)stepToEnterTextIntoCurrentFirstResponder:(NSString *)text
Discussion

@method stepToEnterTextIntoCurrentFirstResponder:

Text is entered into the view by simulating taps on the appropriate keyboard keys if the keyboard is already displayed. Useful to enter text in UIWebViews or components with no accessibility labels.

Parameters

text

The text to enter.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToLongPressViewWithAccessibilityLabel:duration:

+ (id)stepToLongPressViewWithAccessibilityLabel:(NSString *)label duration:(NSTimeInterval)duration
Discussion

@method stepToLongPressViewWithAccessibilityLabel:duration:

The view or accessibility element with the given label is searched for in the view hierarchy. If the element isn’t found or isn’t currently tappable, then the step will attempt to wait until it is. Once the view is present and tappable, touch events are simulated in the center of the view or element.

Parameters

label

The accessibility label of the element to tap.

duration

The length of time to long press the element.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToLongPressViewWithAccessibilityLabel:value:duration:

+ (id)stepToLongPressViewWithAccessibilityLabel:(NSString *)label value:(NSString *)value duration:(NSTimeInterval)duration
Discussion

@method stepToLongPressViewWithAccessibilityLabel:value:duration:

The view or accessibility element with the given label is searched for in the view hierarchy. If the element isn’t found or isn’t currently tappable, then the step will attempt to wait until it is. Once the view is present and tappable, touch events are simulated in the center of the view or element.

This variation allows finding a particular instance of an accessibility element. For example, a table view might have multiple elements with the accessibility label of “Employee”, but only one that also has the accessibility value of “Bob”.

Parameters

label

The accessibility label of the element to tap.

value

The accessibility value of the element to tap.

duration

The length of time to long press the element.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToLongPressViewWithAccessibilityLabel:value:traits:duration:

+ (id)stepToLongPressViewWithAccessibilityLabel:(NSString *)label value:(NSString *)value traits:(UIAccessibilityTraits)traits duration:(NSTimeInterval)duration
Discussion

@method stepToLongPressViewWithAccessibilityLabel:value:traits:duration:

The view or accessibility element with the given label is searched for in the view hierarchy. If the element isn’t found or isn’t currently tappable, then the step will attempt to wait until it is. Once the view is present and tappable, touch events are simulated in the center of the view or element.

This variation allows finding a particular instance of an accessibility element. For example, a table view might have multiple elements with the accessibility label of “Employee”, but only one that also has the accessibility value of “Bob”.

Parameters

label

The accessibility label of the element to tap.

value

The accessibility value of the element to tap.

traits

The accessibility traits of the element to tap. Elements that do not include at least these traits are ignored.

duration

The length of time to long press the element.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToScrollViewWithAccessibilityLabel:byFractionOfSizeHorizontal:vertical:

+ (id)stepToScrollViewWithAccessibilityLabel:(NSString *)label byFractionOfSizeHorizontal:(CGFloat)horizontalFraction vertical:(CGFloat)verticalFraction
Discussion

@method stepToScrollViewWithAccessibilityLabel:byFractionOfSizeHorizontal:vertical:

The view will get the view with the specified accessibility label and scroll it by the indicated fraction of its size, with the scroll centered on the center of the view.

Parameters

label

The accessibility label of the view to scroll.

horizontalFraction

The horizontal displacement of the scroll action, as a fraction of the width of the view.

verticalFraction

The vertical displacement of the scroll action, as a fraction of the height of the view.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToSelectPickerViewRowWithTitle:

+ (id)stepToSelectPickerViewRowWithTitle:(NSString *)title
Discussion

@method stepToSelectPickerViewRowWithTitle:

With a picker view already visible, this step will find an item with the given title, select that item, and tap the Done button.

Parameters

title

The title of the row to select.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToSetOn:forSwitchWithAccessibilityLabel:

+ (id)stepToSetOn:(BOOL)switchIsOn forSwitchWithAccessibilityLabel:(NSString *)label
Discussion

@method stepToSetOn:forSwitchWithAccessibilityLabel:

The UISwitch with the given label is searched for in the view hierarchy. If the element isn’t found or isn’t currently tappable, then the step will attempt to wait until it is. Once the view is present, the step will return if it’s already in the desired position. If the switch is tappable but not in the desired position, a tap event is simulated in the center of the view or element, toggling the switch into the desired position.

Parameters

switchIsOn

The desired position of the UISwitch.

label

The accessibility label of the element to switch.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToSimulateMemoryWarning

+ (id)stepToSimulateMemoryWarning
Discussion

@method stepToSimulateMemoryWarning

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToSwipeViewWithAccessibilityLabel:inDirection:

+ (id)stepToSwipeViewWithAccessibilityLabel:(NSString *)label inDirection:(KIFSwipeDirection)direction
Discussion

@method stepToSwipeViewWithAccessibilityLabel:inDirection:

The view will get the view with the specified accessibility label and swipe the screen in the given direction from the view’s center.

Parameters

label

The accessibility label of the view to swipe.

direction

The direction in which to swipe.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToTapRowInTableViewWithAccessibilityLabel:atIndexPath:

+ (id)stepToTapRowInTableViewWithAccessibilityLabel:(NSString *)tableViewLabel atIndexPath:(NSIndexPath *)indexPath
Discussion

@method stepToTapRowInTableViewWithAccessibilityLabel:atIndexPath:

This step will get the view with the specified accessibility label and tap the row at indexPath.

Parameters

tableViewLabel

Accessibility label of the table view.

indexPath

Index path of the row to tap.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToTapScreenAtPoint:

+ (id)stepToTapScreenAtPoint:(CGPoint)screenPoint
Discussion

@method stepToTapScreenAtPoint:

Taps the screen at a specific point. In general you should use the factory steps that tap a view based on its accessibility label, but there are situations where it’s not possible to access a view using accessibility mechanisms. This step is more lenient than the steps that use the accessibility label, and does not wait for any particular view to appear, or validate that the tapped view is enabled or has interaction enabled. Because this step doesn’t doesn’t validate that a view is present before tapping it, it’s good practice to precede this step where possible with a stepToWaitForViewWithAccessibilityLabel: with the label for another view that should appear on the same screen.

Parameters

screenPoint

The point in screen coordinates to tap. Screen points originate from the top left of the screen.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToTapViewWithAccessibilityLabel:

+ (id)stepToTapViewWithAccessibilityLabel:(NSString *)label
Discussion

@method stepToTapViewWithAccessibilityLabel:

The view or accessibility element with the given label is searched for in the view hierarchy. If the element isn’t found or isn’t currently tappable, then the step will attempt to wait until it is. Once the view is present and tappable, a tap event is simulated in the center of the view or element.

Parameters

label

The accessibility label of the element to tap.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToTapViewWithAccessibilityLabel:traits:

+ (id)stepToTapViewWithAccessibilityLabel:(NSString *)label traits:(UIAccessibilityTraits)traits
Discussion

@method stepToTapViewWithAccessibilityLabel:traits:

The view or accessibility element with the given label is searched for in the view hierarchy. If the element isn’t found or isn’t currently tappable, then the step will attempt to wait until it is. Once the view is present and tappable, a tap event is simulated in the center of the view or element.

Parameters

label

The accessibility label of the element to tap.

traits

The accessibility traits of the element to tap. Elements that do not include at least these traits are ignored.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToTapViewWithAccessibilityLabel:value:traits:

+ (id)stepToTapViewWithAccessibilityLabel:(NSString *)label value:(NSString *)value traits:(UIAccessibilityTraits)traits
Discussion

@method stepToTapViewWithAccessibilityLabel:value:traits:

The view or accessibility element with the given label is searched for in the view hierarchy. If the element isn’t found or isn’t currently tappable, then the step will attempt to wait until it is. Once the view is present and tappable, a tap event is simulated in the center of the view or element.

This variation allows finding a particular instance of an accessibility element. For example, a table view might have multiple elements with the accessibility label of “Employee”, but only one that also has the accessibility value of “Bob”.

Parameters

label

The accessibility label of the element to tap.

value

The accessibility value of the element to tap.

traits

The accessibility traits of the element to tap. Elements that do not include at least these traits are ignored.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToWaitForAbsenceOfViewWithAccessibilityLabel:

+ (id)stepToWaitForAbsenceOfViewWithAccessibilityLabel:(NSString *)label
Discussion

@method stepToWaitForAbsenceOfViewWithAccessibilityLabel:

The view or accessibility element with the given label is found in the view hierarchy. If the element is found, then the step will attempt to wait until it isn’t. Note that the view does not necessarily have to be visible on the screen, and may be behind another view or offscreen. Views with their hidden property set to YES are considered absent.

Parameters

label

The accessibility label of the element to wait for.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToWaitForAbsenceOfViewWithAccessibilityLabel:traits:

+ (id)stepToWaitForAbsenceOfViewWithAccessibilityLabel:(NSString *)label traits:(UIAccessibilityTraits)traits
Discussion

@method stepToWaitForAbsenceOfViewWithAccessibilityLabel:traits:

Parameters

label

The accessibility label of the element to wait for.

traits

The accessibility traits of the element to wait for. Elements that do not include at least these traits are ignored.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToWaitForAbsenceOfViewWithAccessibilityLabel:value:traits:

+ (id)stepToWaitForAbsenceOfViewWithAccessibilityLabel:(NSString *)label value:(NSString *)value traits:(UIAccessibilityTraits)traits
Discussion

@method stepToWaitForAbsenceOfViewWithAccessibilityLabel:value:traits:

Parameters

label

The accessibility label of the element to wait for.

value

The accessibility value of the element to tap.

traits

The accessibility traits of the element to wait for. Elements that do not include at least these traits are ignored.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToWaitForFirstResponderWithAccessibilityLabel:

+ (id)stepToWaitForFirstResponderWithAccessibilityLabel:(NSString *)label
Discussion

@method stepToWaitForFirstResponderWithAccessibilityLabel:

The first responder is found by searching the view hierarchy of the application’s main window and its accessibility label is compared to the given value. If they match, the step returns success else it will attempt to wait until they do.

Parameters

label

The accessibility label of the element to wait for.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToWaitForNotificationName:object:

+ (id)stepToWaitForNotificationName:(NSString *)name object:(id)object
Discussion

@method stepToWaitForNotificationName:object:

Useful when a test requires an asynchronous task to complete, especially when that task does not trigger a visible change in the view hierarchy

Parameters

name

The name of the NSNotification

object

The object to which the step should listen. Nil value will listen to all objects.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToWaitForNotificationName:object:whileExecutingStep:

+ (id)stepToWaitForNotificationName:(NSString *)name object:(id)object whileExecutingStep:(KIFTestStep *)childStep
Discussion

@method stepToWaitForNotificationName:object:whileExecutingStep:

Useful when step execution causes a notification to be emitted, but executes too quickly for stepToWaitForNotificationName: to observe it. An observer will be registered for the notification before the observedStep is executed.

Parameters

name

The name of the NSNotification

object

The object to which the step should listen. Nil value will listen to all objects.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToWaitForTappableViewWithAccessibilityLabel:

+ (id)stepToWaitForTappableViewWithAccessibilityLabel:(NSString *)label
Discussion

@method stepToWaitForTappableViewWithAccessibilityLabel:

The view or accessibility element with the given label is found in the view hierarchy. If the element isn’t found or isn’t currently tappable, then the step will attempt to wait until it is. Whether or not a view is tappable is based on [UIView hitTest:].

Parameters

label

The accessibility label of the element to wait for.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToWaitForTappableViewWithAccessibilityLabel:traits:

+ (id)stepToWaitForTappableViewWithAccessibilityLabel:(NSString *)label traits:(UIAccessibilityTraits)traits
Discussion

@method stepToWaitForTappableViewWithAccessibilityLabel:traits:

The view or accessibility element with the given label is searched for in the view hierarchy. If the element isn’t found or isn’t currently tappable, then the step will attempt to wait until it is. Whether or not a view is tappable is based on [UIView hitTest:].

Parameters

label

The accessibility label of the element to wait for.

traits

The accessibility traits of the element to wait for. Elements that do not include at least these traits are ignored.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToWaitForTappableViewWithAccessibilityLabel:value:traits:

+ (id)stepToWaitForTappableViewWithAccessibilityLabel:(NSString *)label value:(NSString *)value traits:(UIAccessibilityTraits)traits
Discussion

@method stepToWaitForTappableViewWithAccessibilityLabel:value:traits:

The view or accessibility element with the given label is searched for in the view hierarchy. If the element isn’t found or isn’t currently tappable, then the step will attempt to wait until it is. Whether or not a view is tappable is based on [UIView hitTest:].

Parameters

label

The accessibility label of the element to wait for.

value

The accessibility value of the element to tap.

traits

The accessibility traits of the element to wait for. Elements that do not include at least these traits are ignored.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToWaitForTimeInterval:description:

+ (id)stepToWaitForTimeInterval:(NSTimeInterval)interval description:(NSString *)description
Discussion

@method stepToWaitForTimeInterval:description:

In general when waiting for the app to get into a known state, it’s better to use -stepToWaitForTappableViewWithAccessibilityLabel, however this step may be useful in some situations as well.

Parameters

interval

The number of seconds to wait before executing the next step.

description

A description of why the wait is necessary. Required.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToWaitForViewWithAccessibilityLabel:

+ (id)stepToWaitForViewWithAccessibilityLabel:(NSString *)label
Discussion

@method stepToWaitForViewWithAccessibilityLabel:

The view or accessibility element with the given label is found in the view hierarchy. If the element isn’t found, then the step will attempt to wait until it is. Note that the view does not necessarily have to be visible on the screen, and may be behind another view or offscreen. Views with their hidden property set to YES are ignored.

If the view you want to wait for is tappable, use the stepToWaitForTappableViewWithAccessibilityLabel: methods instead as they provide a more strict test.

Parameters

label

The accessibility label of the element to wait for.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToWaitForViewWithAccessibilityLabel:traits:

+ (id)stepToWaitForViewWithAccessibilityLabel:(NSString *)label traits:(UIAccessibilityTraits)traits
Discussion

@method stepToWaitForViewWithAccessibilityLabel:traits:

Parameters

label

The accessibility label of the element to wait for.

traits

The accessibility traits of the element to wait for. Elements that do not include at least these traits are ignored.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepToWaitForViewWithAccessibilityLabel:value:traits:

+ (id)stepToWaitForViewWithAccessibilityLabel:(NSString *)label value:(NSString *)value traits:(UIAccessibilityTraits)traits
Discussion

@method stepToWaitForViewWithAccessibilityLabel:value:traits:

Parameters

label

The accessibility label of the element to wait for.

value

The accessibility value of the element to tap.

traits

The accessibility traits of the element to wait for. Elements that do not include at least these traits are ignored.

Return Value

A configured test step.

Declared In

KIFTestStep.h

stepWithDescription:executionBlock:

+ (id)stepWithDescription:(NSString *)description executionBlock:(KIFTestStepExecutionBlock)executionBlock
Discussion

@method stepWithDescription:executionBlock:

Parameters

description

A description of the what the step does. Required.

executionBlock

A block to execute which performs the step. Required.

Declared In

KIFTestStep.h

stepsToChoosePhotoInAlbum:atRow:column:

+ (NSArray *)stepsToChoosePhotoInAlbum:(NSString *)albumName atRow:(NSInteger)row column:(NSInteger)column
Discussion

@method stepsToChoosePhotoInAlbum:atRow:column:

This set of steps expects that the photo picker has been initiated and that the sheet is up. From there it will tap the “Choose Photo” button and select the desired photo.

Parameters

albumName

The name of the album to select the photo from.

row

The row number in the album for the desired photo.

column

The column number in the album for the desired photo.

Return Value

An array of configured test steps.

Declared In

KIFTestStep.h

Instance Methods

cleanUp

- (void)cleanUp
Discussion

@method cleanUp:

For anything that needs to be removed at completion rather than dealloc

Declared In

KIFTestStep.h

executeAndReturnError:

- (KIFTestStepResult)executeAndReturnError:(NSError **)error
Discussion

@method executeAndReturnError:

This method should not usually be invoked directly. The test controller will handle invoking steps as needed.

Parameters

error

An error that can be returned if the step fails or needs to wait.

Return Value

The result code for the result of executing the step.

Declared In

KIFTestStep.h