Skip to content

Latest commit

 

History

History
207 lines (138 loc) · 7.54 KB

README.md

File metadata and controls

207 lines (138 loc) · 7.54 KB
Raw

Insider

Build Status Twitter: @amaimescu License

Insider is an utility framework which sets a backdoor into your app for testing tools like Appium, Calabash, Frank, etc.

Why do I need this?

There are many scenarios which are hard to cover during the automation testing because the testing environment is isolated from the tested app:

  • Set a particular state for the app during the test scenario;
  • Simulate push notifications;
  • Simulate app invocation using custom schemes / universal links;
  • Simulate handoff invocations;
  • Manage files / directories in application sandbox;
  • Collect metrics from the app during test execution (CPU, memory, etc.);
  • etc.

Insider runs an HTTP server inside the application and listens for commands (RPCs). By default, Insider runs on http://localhost:8080.

A command represents a simple HTTP request: http://localhost:8080/<command>. You can pre-configure your app to simulate an action when it receives such a remote command.

Features

Built-in Features Commands HTTP Method
🚚 Send a message (dictionary) to the app; /send POST
🚌 Send a message to the app and wait for response; /sendAndWaitForResponse POST
📢 Send local notifications through NSNotificationCenter with given parameters; /notification POST
📱 Get device system state information (CPU, memory, IP address, etc); /systemInfo GET
💾 Manage files / directories in application sandbox (Documents, Library, tmp); /documents/<command>
/library/<command>
/tmp/<command>		 See the table below

Supported commands for file managing feature:

File Managing Commands HTTP Method
List items: /<directory>/list GET
Download items: /<directory>/download GET
Upload items: /<directory>/upload POST
Move items: /<directory>/move POST
Delete items: /<directory>/delete POST
Create folder: /<directory>/create POST

In the scripts directory can be found sample ruby scripts which show the built-in features in action.

Check out the API reference for more information.

Installation

Manual installation

In order to include the Insider library into your project, you need to build a dynamic framework from provided source code and include it into your project, or inlcude the entire Insider library as sub-project by copying it to your project directory or include as Git submodule.

Carthage

If you are using Carthage, you can always use it to build the library within your workspace by adding the line below to your Cartfile.

github "alexmx/Insider"

CocoaPods

If you are using CocoaPods, you can as well use it to integrate the library by adding the following lines to your Podfile.

platform :ios, '8.0'
use_frameworks!

target 'YourAppTarget' do
    pod "Insider"
end

Usage

Use case #1: Simulate Push Notifications

import Insider

class AppDelegate: UIResponder, UIApplicationDelegate {

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

	// Launch the Isider with the given delegate
        Insider.shared.start(withDelegate: self)
        
        return true
  }
  
  func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable: Any]) { 
  	// Process push notification 
  }
}

extension AppDelegate: InsiderDelegate {

  // This delegate method is invoked when a remote message is sent to the app
  func insider(_ insider: Insider, didReceiveRemote message: InsiderMessage?) {
        // Simulate push notification
        application(UIApplication.shared, didReceiveRemoteNotification: message!)
  }
}

In order to test this example run InsiderDemo application target, after go to scripts directory and run send_message.rb script.

Use case #2: Simulate app invocation using a custom scheme

import Insider

class AppDelegate: UIResponder, UIApplicationDelegate {

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

        Insider.shared.start(withDelegate: self)
        
        return true
  }
  
  func application(_ application: UIApplication, handleOpen url: URL) -> Bool {
        
	// Process custom scheme invocation
        return true
  }
}

extension AppDelegate: InsiderDelegate {

  func insider(_ insider: Insider, returnResponseMessageForRemote message: InsiderMessage?) -> InsiderMessage? {
        // Simulate app invocation using a custom scheme
        let url = URL(string: "insiderDemo://hello/params")
        let response = application(UIApplication.shared, handleOpen: url!)
        
        return ["response" as NSObject : response as AnyObject]
  }
}

In order to test this example run InsiderDemo application target, after go to scripts directory and run send_message_with_response.rb script.

Use case #3: Get application system information during test execution

import Insider

class AppDelegate: UIResponder, UIApplicationDelegate {

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

        Insider.shared.start()
        
        return true
  }
}

As it is a built-in feature there is no need to set a delegate for Insider in this case. In order to test this example run InsiderDemo application target, after go to scripts directory and run system_info.rb script.

Use case #4: Add files to Documents folder in application sandbox.

import Insider

class AppDelegate: UIResponder, UIApplicationDelegate {

  func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {

        Insider.shared.start()
        
        return true
  }
}

As it is a built-in feature there is no need to set a delegate for Insider in this case.

There are 3 directories supported in application sandbox:

  • Documents: http://localhost:8080/documents
  • Library: http://localhost:8080/library
  • tmp: http://localhost:8080/tmp

You can create new folders. Upload, download, move, remove files / folders from application sandbox.

In order to test this example run InsiderDemo application target, and open in your browser:

You will see the files which are in your application sandbox.

Insider

If you need to use the sandbox files managing API in your automation scripts please check File Managing Commands section above.

Credits

Insider uses these amazing libaries under the hood:

License

This project is licensed under the terms of the MIT license. See the LICENSE file.