Repository files navigation

Subliminal is a framework for writing iOS integration tests. Subliminal providesa familiar OCUnit/XCTest-like interface to Apple's UIAutomation framework,with tests written entirely in Objective-C. Subliminal also provides a powerfulmechanism for your tests to manipulate your application directly.

[Features •Getting Started •Requirements •Usage •Continuous Integration •Contributing •Contact •License]

Write your tests in Objective-C, and run them from Xcode. See rich-text logsand screenshots in Instruments. Use UIAutomation to simulate user interaction.Subliminal lets you use familiar tools, no dependencies required.

By using UIAutomation, Subliminal can simulate almost any interaction--withoutresorting to private APIs. From navigating in-app purchase dialogs, to puttingyour app to sleep, Subliminal lets you simulate complex interaction like a user.And when you want to manipulate your app directly, Subliminal will help you dothat too.

Define Objective-C methods to help set up and tear down tests. Leverage nativesupport for continuous integration. Take confidence in Subliminal's completedocumentation and full test coverage. Subliminal is the perfect foundationfor your tests.

• Download Subliminalandtry out the included example app
• See aninstallation walkthrough and screencast
• Check out Subliminal'sAPI documentationor theguides to using Subliminal on the Wiki
• Read acomparison of Subliminal to other integration test frameworks

1. Clone the Subliminal repo:git clone https://github.com/inkling/Subliminal.git.
2. cd into the directory:cd Subliminal.
3. If you haven't already, set up Subliminal:rake install.
4. Open the Example project:open Example/SubliminalTest.xcodeproj.
5. Switch to the "Integration Tests" scheme.You may also see a scheme called "Subliminal Integration tests"--make sure you choose "Integration Tests."
6. Choose Product > Profile (⌘+I).
7. Under the User Templates, choose Subliminal.

For an installation walkthrough, refer toSubliminal's wiki.

Subliminal supports projects built using Xcode 5.1 and iOS 7.x SDKs,and deployment targets running iOS 6.1 through 7.1.

For iOS 5.1 support, use Subliminal 1.1.0 (found in theReleases section or onCocoaPods). To test in the iOS 5.1 Simulator, you willneed to run OS X 10.8 and manually add the iOS 5.1 Simulator to Xcode 5.1,as describedhere.

Subliminal is designed to be instantly familiar to users of OCUnit/XCTest.In Subliminal, subclasses ofSLTest define tests as methods beginning withtest.At run-time, Subliminal discovers and runs these tests.

Tests manipulate the user interface and can evenmanipulate the application directly.Here's what a sample test case looks like:

@implementationSTLoginTest- (void)testLogInSucceedsWithUsernameAndPassword {SLTextField *usernameField = [SLTextFieldelementWithAccessibilityLabel:@"username field"];SLTextField *passwordField = [SLTextFieldelementWithAccessibilityLabel:@"password field"isSecure:YES];SLElement *submitButton = [SLElementelementWithAccessibilityLabel:@"Submit"];SLElement *loginSpinner = [SLElementelementWithAccessibilityLabel:@"Logging in..."];NSString *username =@"Jeff", *password =@"foo";    [usernameFieldsetText:username];    [passwordFieldsetText:password];    [submitButtontap];// wait for the login spinner to disappearSLAssertTrueWithTimeout([loginSpinnerisInvalidOrInvisible],3.0,@"Log-in was not successful.");NSString *successMessage = [NSStringstringWithFormat:@"Hello,%@!", username];SLAssertTrue([[SLElementelementWithAccessibilityLabel:successMessage]isValid],@"Log-in did not succeed.");// Check the internal state of the app.SLAssertTrue(SLAskAppYesNo(isUserLoggedIn),@"User is not logged in.")}@end

For more information, seeSubliminal's wiki.

Subliminal includes end-to-end CI support for building your project, running its tests on the appropriate simulator or device, and outputting results in a variety of formats.

For example scripts and guides to integrate with popular CI services like Travis and Jenkins, seeSubliminal's wiki.

• How is Subliminal different from other integration test frameworks?

  Most other integration test frameworks fall into two categories: entirelyObjective-C based, or entirely UIAutomation-based.

  Frameworks that are entirely Objective-C based, likeKIF,Frank, etc., must hack the application'stouch-handling system, using private APIs, to simulate user interaction.There is thus no guarantee that they accurately simulate a user's input.Moreover, these frameworks can only simulate interaction with the application,as opposed to interaction with the device, other processes like in-app purchasealerts, etc.

  Frameworks that are entirely based on Apple's UIAutomation framework requirecumbersome workflows--writing tests in JavaScript, in Instruments--which do notmake use of the developer's existing toolchain. Moreover, they offer the developerno means of manipulating the application directly--it is a complete black boxto a UIAutomation-based test.

  Only Subliminal combines the convenience of writing tests in Objective-Cwith the power of UIAutomation.

• How is Subliminal different than UIAutomation?

  Besides the limitations of UIAutomation described above, it is extremelydifficult to write UIAutomation tests. This is because UIAutomation requiresthat user interface elements be identified by their position within the"element hierarchy", like

  varcell=UIATarget.localTarget().frontMostApp().mainWindow().tableViews()[0].cells()["foo"];

  These references are not only difficult to read but are also difficult to write.To refer to any particular element, you have to describe its entire ancestry,while including only the views that UIAutomation deems necessary (images, yes;accessible elements, maybe; privateUIWebView subviews, sure!).

  UIAutomation-based tests are not meant to be written, but to be "recorded"using Instruments. This forces dependence on Instruments, and makes the testsdifficult to modify thereafter.

  Subliminal allows developers to identify elements by their properties,independent of their position in the element hierarchy:

  SLElement *fooCell = [SLElementelementWithAccessibilityLabel:@"foo"];

  Subliminal abstracts away the complexity of UIAutomation scripts to let developers focus on writing tests.

  Subliminal also fixes several bugs in UIAutomation and theinstruments CLI tool,such asinstruments' lack fortrue device support.And, last but not least, Subliminal rewritesinstruments' output using human-friendly formattingand ANSI colors:

  

Subliminal welcomes pull requests! Check out thecontributing guidelines to learn how to set up Subliminal for development and how to make a successful pull request.

Created byJeff Wear, made possible byInkling,with help from:

• William Green
• John Detloff
• Aaron Golden
• Lukhnos Liu
• Aaron Haney

and Subliminal'sgrowing list of contributors.

• If youneed help, useStack Overflow. (Tag 'subliminal'.)
• If you'd like toask a general question, useStack Overflow.
• If you'vefound a bug,open an issue.
• If youhave a feature request,open an issue.
• If you'dlike to contribute (awesome!), seethe contributing guidelines to get started.

If you'd like to chat, we hold "office hours" onGitter3-4pm Pacific Time, Tuesdays and Thursdays.

Lastly, you can follow Subliminal on Twitter for news and tips (@subliminaltest).

Copyright 2013-2014 Inkling Systems, Inc.

Licensed under the Apache License, Version 2.0 (the "License");you may not use this file except in compliance with the License.You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, softwaredistributed under the License is distributed on an "AS IS" BASIS,WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.See the License for the specific language governing permissions andlimitations under the License.