What is Subliminal?

Subliminal is an open-source framework for writing iOS integration tests. Subliminal provides a familiar OCUnit/XCTest-like interface on top of Apple’s UIAutomation framework, with tests written entirely in Objective-C. Subliminal also provides a powerful mechanism for your tests to manipulate your application directly.

For News, Tips, and Support

Follow @SubliminalTest

Usage

Subliminal is designed to be instantly familiar to users of OCUnit/XCTest. In Subliminal, subclasses of SLTest define tests as methods beginning with "test". At run-time, the SLTestController discovers and runs these tests. Here's what a sample SLTest implementation looks like:

@implementation STLoginTest

- (void)testLogInSucceedsWithUsernameAndPassword {
        SLTextField *usernameField = [SLTextField elementWithAccessibilityLabel:@"username field"];
        SLTextField *passwordField = [SLTextField elementWithAccessibilityLabel:@"password field"];
        SLElement *submitButton = [SLElement elementWithAccessibilityLabel:@"Submit"];
        SLElement *loginSpinner = [SLElement elementWithAccessibilityLabel:@"Logging in..."];

        NSString *username = @"Jeff", *password = @"foo";
        [usernameField setText:username];
        [passwordField setText:password];

        [submitButton tap];

        // Wait for login to succeed
        SLAssertTrueWithTimeout([loginSpinner isInvalidOrInvisible],
                                3.0,
                                @"Log-in was not successful.");

        NSString *successMessage = [NSString stringWithFormat:@"Hello, %@!", username];
        SLAssertTrue([[SLElement elementWithAccessibilityLabel:successMessage] isValid],
                     @"Log-in did not succeed.");

	    // Check the internal state of the app.         
	    SLAssertTrue(SLAskAppYesNo(isUserLoggedIn), @"User is not logged in.")
}

@end

In the body of those tests, you do some work and then make some assertions.

That work can involve simulating user interaction, using instances of SLElement. SLElements are proxies for the "UIAElements" UIAutomation uses to represent user interface elements: when you -tap an SLElement, that SLElement causes the appropriate bit of Javascript to be executed to manipulate the corresponding UIAElement. Tests execute asynchronously, so they can block until UIAutomation is done evaluating the command, without blocking the application itself.

Your tests live inside your application, so you can also manipulate the application directly, using app hooks. App hooks are Objective-C methods defined by the application, made available to your tests--so you could have one test verify that your login UI works, while the rest of your tests use a programmatic interface.

To learn more about how to use Subliminal, check out the README on GitHub.