Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Version License Platform


Apple's UI testing framework is a tremendously powerful tool to write ui tests for your application. There are however some edge cases were tests can become difficult/impossible to write. We've been developing this tool to cover different (at first sight unrelated) needs in our ui testing workflow.

SBTUITestTunnelHost includes a Mac App (Server) and a set of classes to be used in your UI test target which enables to:

  • launch shell commands on the Mac host from within the test target. This can come in handy if you have shell scripts that interact with your backend environment (user creation, deletion, content modification and so on)
  • perform mouse actions. We use this to perform very fast interaction (i.e. very fast and repeated swipes) with the app under test, which is not possible using XCTest capabilities
  • serve static content file. Lift you from installing a full web server when in need to serve simple static content

Installation (CocoaPods)

We strongly suggest to use cocoapods being the easiest way to embed the library inside your project. You simply need to add SBTUITestTunnelHost to your UI Test target.

Installation (Manual)

Add files in the SBTUITestTunnelHost to the UI test target.


Mac Server App

Launch the Mac App (either by compiling the SBTUITunnelHostServer/SBTUITunnelHostServer.xcworkspace or launching the executable in SBTUITunnelHostServer/Binary/ which will fire a server on your local machine on port 8667. The current status of the server will be shown in the macOS menubar.

Mouse actions - Catalina

To allow SBTUITestTunnelServer to interact with machine mouse you'll need to explicitly grant Accessibility permissions under 'Securtity & Privacy' > 'Privacy' in System preferences. If the SBTUITestTunnelServer is already listed but mouse interaction do not work try removing the entry and launching the app again.

Executable under Pods folder

Usually you should place the executable under /Applications so that the same instance can be shared across multiple projects, however there are scenarios where you might prefer to place the server's executable under your project Pods folder. This can be achieved adding the following post_install step in your Podfile:

post_install do |installer|
  puts "Fetching SBTUITestTunnelHost Server"
  system("curl -s > /tmp/; unzip -qqo /tmp/ -d #{installer.pods_project.path.dirname}/SBTUITestTunnelHost && rm -rf /tmp/")

Security Warnings 🔥🔥🔥

The tool is intended for testing enviornments only, use with care since it allows to access and execute commands on the running host. Make sure that the host is only reachable by trusted clients.

To increase security by default the application binds the server to localhost. This means that it will only receive requests from within the same machine that runs the tool, which should be fine in most cases. You can optionally launch the application passing the --skipLocalhostBinding or by manually toggling the option from menubar to bypass this limitation.

For additional security launch the tool with a system user with specific access privileges

UI Tests

In your code just import SBTUITestTunnelHost. This will add a host property to the XCTest class which is an instance of SBTUITestTunnelHost.

The Example project comes with several Tests in Swift and Objective-C that show the different use cases.

launching shell commands

To remotely execute a command invoke host.executeCommand(cmd) which will synchronously execute the command and return the stdout output.

mouse actions: Clicks

Create an instance of SBTUITunneledHostMouseClick by passing the XCUIElement you want to be clicked (center of element will be clicked) and specifying a delay, in seconds, to wait after the click has been performed. This is useful if you need to create a sequence of [SBTUITunneledHostMouseClick].

This will execute 3 consecutive mouse clicks on element btn with a pause of 50ms in between

let mouseClick = SBTUITunneledHostMouseClick(element: btn, completionPause: 0.05)
let mouseCliks = Array(repeating: mouseClick, count: 3)

mouse actions: Drags

Create an instance of SBTUITunneledHostMouseDrag by passing the XCUIElement you want to be dragged. Additionally you have to pass normalized coordinates (values between 0.0 and 1.0) of the start and stop points of the drag. (0.0, 0.0) represents top left corner, (1.0, 1.0) bottom right. As for clicks you specify a delay, in seconds, to wait after the drag has been performed.

This will execute 3 consecutive mouse drags (swipe ups) on element table with a duration of 100ms and a pause of 50ms in between

let mouseDrag = SBTUITunneledHostMouseDrag(element: table,
                                           startNormalizedPoint: CGPoint(x: 0.5, y: 0.9),
                                           stopNormalizedPoint: CGPoint(x: 0.5, y: 0.1),
                                           dragDuration: 0.1,
                                           completionPause: 0.05)
let mouseDrags = Array(repeating: mouseDrag, count: 3)

The result is a much faster scrolling as can be seen from the demo below.

serving files

Simply issue a GET request to http://localhost:8667/catfile?token=TOKEN&content-type=application/json&path=/tmp/tunnel-test

Additional resources

If you need to mock or inject data from a UI Test try SBTUITestTunnel.


Contributions are welcome! If you have a bug to report, feel free to help out by opening a new issue or sending a pull request.


Tomas Camin (@tomascamin)


SBTUITestTunnelHost is available under the Apache License, Version 2.0. See the LICENSE file for more info.