The automation interface (GBA) is a client-server program that includes 2 components:
- A client runs on your development machine. You can start a client from the shell by issuing the
gbcommand. A client issues the server commands, which executes them and returns the result back to the client.
- A server, which needs to be run as a background process on your development machine, manages the communication between your development machine and the devices connected.
Starting the Server
Before using the
gb client, the server needs to be started. On Linux you can start the server by executing the following:
sudo service gbaserver start
Or alternatively, in a separate terminal instance;
To list the devices connected to the development machine, execute the following:
This will return a list of devices with their name and UDID. Take note of the UDID as this is used to identify the device when using other
gb options documented below.
- Note: Due to issues with the Linux implementation of usbmuxd, when plugging in a new iOS device into a Linux host and hitting 'Trust' when prompted on the device, you may need to wait up to 60 seconds and disconnect and reconnect the device before GBA acknowledges it. Still having problems?
To list the apps installed on a device, execute the following:
gb --list-apps <udid>
This will return a list of apps installed on the device with their name and package name. Take note of the package name as this will be needed when using the
- Note: The first time you issue this command for a device, you may have to wait for an extended period of time as the server will need to setup the device. This includes installing the companion app for Android and mounting the developer disk images for iOS.
Before you can collect data from an iOS device, you need to obtain a zip of Developer Disk Images. At the very least, it will need to include the disk image for the version of iOS that is running on your device.
For more information, please read Developer Disk Images.
If you do wish to collect data from an iOS device, you will need to provide the path of the zip to GBA by executing the following, otherwise you may skip this step.
gb --setprop imgZip /home/user/ddimg.zip
To collect performance data of an application, launch the application on the device and execute the following:
gb --record <udid> <package> <email> [--no-screenshots]
<email>is a required parameter. To view this session in the Web Dashboard, you will need to register and login using this email address.
--no-screenshotsis an optional parameter to disable the collection of screenshots during the session.
This will start collecting data for all the available metrics on the device until a
--stop has been issued. You can stop recording by executing the following:
gb --stop <udid> [--outputDir <directory>]
--outputDircan be used to specify the directory in which the JSON file with this session's data will be written. If not provided, the file will be written in the
datafolder located in the
fileformatoption removed in version 4248
gb --stop <udid> [--fileformat json [<file>]]
--fileformatis an option that can be used to generate a JSON file with this session's data.
<file>is an optional parameter. If provided, the session will be written to this file path.
After all recordings have stopped you can upload your sessions to the Web Dashboard, by executing the following:
If you would like to automatically sync a single session after its completion, you can append the
--record option with the
--autosync option, like so:
gb --record <udid> <package> <email> --autosync
Before recording, you can select the metrics you would like to collect, by executing the following:
gb --setprop collect_<metric> [true|false]
Possible metrics for selecting are [
List Available Metrics
To list the available metrics for a device, execute the following:
gb --info <udid>
This will return some basic information about the device along with a list of metrics that are available for collection.