Introduction

Maven Central License

IdbClient

It is the way to get access to the idb programmatically, using kotlin. You can control Apple devices and simulators from your code with this client, which creates a connection to them by grpc. All you need to set up is to install the idb companion (https://fbidb.io/docs/installation) on your Mac and run it. You can use idb client connection from any architecture.

We provide commands' wrappers to functionality of idb companion(you can check the full list here https://fbidb.io/docs/commands)

License

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, software
distributed 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 and
limitations under the License.

Quick start

Add IdbClient dependency

<dependency>
  <groupId>io.github.sergkhram</groupId>
  <artifactId>idbclient</artifactId>
  <version>0.0.5-RELEASE</version>
</dependency>

Create idbClient

val idb = IOSDebugBridgeClient()

Connect companion

val udid = idb.connectToCompanion(TcpAddress("127.0.0.1", 10882))

Execute request

val result = idb.execute(
    LogRequest(
        predicate = {false}, 
        timeout = Duration.ofSeconds(10)
    ),
    udid
)
result.forEach(::println)

Disconnect companion

idb.disconnectCompanion(host, port)
//or idb.disconnectCompanion(udid)

Get current targets(connected)

val response = idb.getTargetsList()

App requests

Launch request

Launch request(https://fbidb.io/docs/commands#launch-an-app) - Launch an application. Any environment variables of the form IDB_X will be passed through with the IDB_ prefix removed. Example: 

idb.execute(
    LaunchRequest(
        launch = LaunchRequestBody.StartLaunchRequestBody(
            bundleId, //Bundle id of the app to launch
            env, //env map
            appArgs, //Arguments to start the app with
            foregroundIfRunning, //If the app is already running foreground that process
            waitFor, //Wait for the process to exit, tailing all output from the app
            waitForDebugger, //Suspend application right after the launch to facilitate attaching of a debugger (ex, lldb).
        ),
        predicate = {false}, //Executing until this become true or timeout
        timeout = Duration.ofSeconds(10) //Executing until predicate become true or timeout
    ),
    udid
)

List apps request

List apps request(https://fbidb.io/docs/commands#list-apps) - List the installed apps. Example: 

idb.execute(
    ListAppsRequest(
        suppressProcessState //Fetches App Process State
    ),
    udid
)

Terminate request

Terminate request(https://fbidb.io/docs/commands#kill-a-running-app) - Terminate a running application. Example: 

idb.execute(
    TerminateRequest(
        bundleId //Bundle id of the app to terminate
    ),
    udid
)

Uninstall request

Uninstall request(https://fbidb.io/docs/commands#uninstalling-an-app) - Uninstall an application. Example: 

idb.execute(
    UninstallRequest(
        bundleId //Bundle id of the app to uninstall
    ),
    udid
)

Install Request

Install Request(https://fbidb.io/docs/commands/#install-an-app)- Installs the given .app or .ipa. The app target architecture should match that of the target. Example: 

idb.execute(
    InstallRequest(
        bundlePath, //Path to the .app/.ipa to install. Note that .app bundles will usually be faster to install than .ipa files.
        makeDebuggable, //If set, will persist the application bundle alongside the iOS Target, this is needed for debugserver commands to function
        overrideMtime - If set, idb will disregard the mtime of files contained in an .ipa file. Current timestamp will be used as modification time. Use this flag to ensure app updates work properly when your build system normalises the timestamps of contents of archives.
    ),
    udid
)

Crash requests

Crash Delete Request

Crash Delete Request(https://fbidb.io/docs/commands#delete-crash-logs) - Delete a crash log. Example: 

idb.execute(
    CrashDeleteRequest(
        requestBody = CrashLogQueryRequestBody(
            name //The unique name of the crash
        )
    ),
    udid
)

Crash List Request

Crash List Request(https://fbidb.io/docs/commands#list-crash-logs) - List the available crashes. Example: 

idb.execute(
    CrashListRequest(
        requestBody = CrashLogQueryRequestBody(
            since, //Match based on being newer than the provided unix timestamp in long
            before, //Match based older than the provided unix timestamp in ling
            bundleId //Filter based on the bundle id of the crashed process
        )
    ),
    udid
)

Crash Show Request

Crash Show Request(https://fbidb.io/docs/commands#fetch-a-crash-log) - Fetches the crash log with the specified name. Example: 

idb.execute(
    CrashDeleteRequest(
        requestBody = CrashLogQueryRequestBody(
            name //The unique name of the crash
        )
    ),
    udid
)

File requests

Ls Request

Ls Request(https://fbidb.io/docs/file-containers#list-a-path-on-a-target) - Returns a list of all the files present within one or more directories. Example: 

idb.execute(
    LsRequest(
        lsRequestBody = LsRequestBody.SingleLsRequestBody(
            path, //Source path
            container //File container(Default is ROOT)
        ) or LsRequestBody.MultipleLsRequestBody(
            paths, //List of source paths
            container //File container(Default is ROOT)
        )
    ),
    udid
)

Mkdir Request

Mkdir Request(https://fbidb.io/docs/file-containers#make-a-new-directory) - Make a directory inside an application's container. Example: 

idb.execute(
    MkdirRequest(
        path, //Path to directory to create
        container //File container(Default is ROOT)
    ),
    udid
)

Mv Request

Mv Request(https://fbidb.io/docs/file-containers#moving-files-within-the-container) - Move a path inside an application's container. Example: 

idb.execute(
    MvRequest(
        srcPaths, //Source paths relative to Container
        dstPath, //Destination path relative to Container
        container //File container(Default is ROOT)
    ),
    udid
)

Pull Request

Pull Request(https://fbidb.io/docs/file-containers#copying-files-out-of-a-container) - Copy a file inside an application's container. Example: 

idb.execute(
    PullRequest(
        srcPath, //Relative Container source path
        container //File container(Default is ROOT)
    ),
    udid
)

Push Request

Push Request(https://fbidb.io/docs/file-containers#copying-files-into-a-container) - Copy file(s) from local machine to target. Example: 

idb.execute(
    PushRequest(
        srcPath, //Path of file(s) to copy to the target
        dstPath, //Directory relative to the data container of the application to copy the files into. Will be created if non-existent.(just directory)
        container //File container(Default is ROOT)
    ),
    udid
)

Rm Request

Rm Request(https://fbidb.io/docs/file-containers#remove-a-path-on-a-target) - Remove an item inside a container. Example: 

idb.execute(
    RmRequest(
        paths, //Path of item to remove (A directory will be recursively deleted)
        container //File container(Default is ROOT)
    ),
    udid
)

Tail Request

Tail Request - Tails a remote file. String as the result. Example: 

idb.execute(
    TailRequest(
        path, //Relative container source path
        container, //File container(Default is ROOT)
        predicate = {false}, //Executing until this become true or timeout
        timeout = Duration.ofSeconds(10) //Executing until predicate become true or timeout
    ),
    udid
)

Interaction requests

Accessibility Info Request

Accessibility Info Request(https://fbidb.io/docs/commands#accessibility-info) - Describes Accessibility Information for the entire screen or for point. Example: 

idb.execute(
    AccessibilityInfoRequest(
        accessibilityInfo = AccessibilityInfoRequestBody.AccessibilityInfoAllRequestBody(
            format = Format.NESTED //Will report data in the newer nested format, rather than the flat one - if Nested(default is Nested)
        ) or AccessibilityInfoRequestBody.AccessibilityInfoPointRequestBody(
            format = Format.NESTED, //Will report data in the newer nested format, rather than the flat one - if Nested(default is Nested)
            x, //The x-coordinate
            y //The y-coordinate
        )
    ),
    udid
)

Focus Request

Focus Request(https://fbidb.io/docs/commands#focus-a-simulators-window) - Brings the simulator window to front. Example: 

idb.execute(
    FocusRequest(),
    udid
)

Hid Requests

Hid Requests(https://fbidb.io/docs/commands#interact) - For simulators we provide a handful of commands for emulating HID events.

Tap(https://fbidb.io/docs/commands#tap) - Taps a location on the screen specified in the points coordinate system. Example: 

idb.execute(
    HidRequest(
        hid = HidRequestBody.TapCmdRequestBody(
            x, //The x-coordinate
            y, //The y-coordinate
            duration //Press duration
        )
    ),
    udid
)

Swipe(https://fbidb.io/docs/commands#swipe) - Swipe from one point to another point. Example: 

idb.execute(
    HidRequest(
        hid = HidRequestBody.SwipeCmdRequestBody(
            startX, //The x-coordinate of the swipe start point
            startY, //The y-coordinate of the swipe start point
            endX, //The x-coordinate of the swipe end point
            endY, //The y-coordinate of the swipe end point
            deltaValue, //delta in pixels between every touch point on the line between start and end points(Default is 0.0)
            durationValue //Swipe duration(Default is 0.0)
        )
    ),
    udid
)

Button press(https://fbidb.io/docs/commands#press-a-button) - A single press of a button. Example: 

idb.execute(
    HidRequest(
        hid = HidRequestBody.ButtonPressCmdRequestBody(
            button, //The button name from AppleButton(APPLE_PAY, HOME, LOCK, SIDE_BUTTON, SIRI)
            duration, //Press duration(Default is 0.0)
        )
    ),
    udid
)

Text input(https://fbidb.io/docs/commands#inputting-text) - Input text. Example: 

idb.execute(
    HidRequest(
        hid = HidRequestBody.TextCmdHidRequestBody(
            text, //Text to input
        )
    ),
    udid
)

Key press - A short press of a keycode or sequence of keycodes. Example: 

idb.execute(
    HidRequest(
        hid = HidRequestBody.KeyPressCmdRequestBody(
            code, //The key code
            duration, //Press duration
        ) or HidRequestBody.KeysPressCmdRequestBody(
            keys //list of key codes
        )
    ),
    udid
)

Open Url Request

Open Url Request(https://fbidb.io/docs/commands/#open-a-url) - Opens the specified URL on the target. Example: 

idb.execute(
    OpenUrlRequest(
        url = "https://facebook.com"
    ),
    udid
)

Send Notification Request

Send Notification Request - Sent notification. Example: 

idb.execute(
    SendNotificationRequest(
        bundleId, //Bundle id of the app
        jsonPayload //Notification data in json format
    ),
    udid
)

Set Location Request

Set Location Request(https://fbidb.io/docs/commands#set-a-simulators-location) - Overrides a simulators' location to the latitude, longitude specified. Example: 

idb.execute(
    SetLocationRequest(
        latitude, //Latitude to set
        longitude //Longitude to set
    ),
    udid
)

Simulate Memory Warning Request

Simulate Memory Warning Request- Simulate a memory warning. Example: 

idb.execute(
    SimulateMemoryWarningRequest(),
    udid
)

Management requests

Describe Request

Describe Request(https://fbidb.io/docs/commands/#describe-a-target)- Returns metadata about the specified target. Example: 

idb.execute(
    DescribeRequest(
        requestBody = TargetDescriptionRequestBody(
            fetchDiagnostics = true //Fetch additional target diagnostics
        )
    ),
    udid
)

Log Request

Log Request(https://fbidb.io/docs/commands/#log)- Obtain logs from the target or the companion. Example: 

idb.execute(
    LogRequest(
        predicate = {false}, //Executing until this become true or timeout
        timeout = Duration.ofSeconds(10), //Executing until predicate become true or timeout
        source = LogSource.TARGET, //TARGET or COMPANION
        arguments //Possible arguments:[system | process (pid|process) | parent (pid|process) ][ level default|info|debug][ predicate <predicate> ][ source ][ style (syslog|json) ][ timeout <num>[m|h|d] ][ type activity|log|trace ]
    ),
    udid
)

Media requests

Add Media Request

Add Media Request(https://fbidb.io/docs/commands/#add-media)- Files supplied to this command will be placed in the target's camera roll. Most common image and video file formats are supported. Example: 

idb.execute(
    AddMediaRequest(
        filePaths //Paths to all media files to add
    ),
    udid
)

Record Request

Record Request(https://fbidb.io/docs/commands/#record-a-video)- Record the target's screen to a mp4 video file and return byte array. Example: 

idb.execute(
    RecordRequest(
        predicate = {false}, //Recording until this become true or timeout
        timeout = Duration.ofSeconds(10), //Recording until predicate become true or timeout
    ),
    udid
)

You can use the "exportFile" function of the response to prepare the final video file.

Screenshot Request

Screenshot Request- Make a screenshot. Example: 

idb.execute(
    ScreenshotRequest(),
    udid
)

Video Stream Request

Video Stream Request(https://fbidb.io/docs/video#streaming)- Stream raw H264 from the target. Example: 

idb.execute(
    VideoStreamRequest(
        fps, //The frame rate of the stream. Default is a dynamic fps
        videoFormat, //The format of the stream
        compressionQuality, //The compression quality (between 0 and 1.0) for the stream
        scaleFactor, //The scale factor for the source video (between 0 and 1.0) for the stream
        predicate = {false}, //Streaming until this become true or timeout
        timeout = Duration.ofSeconds(10), //Streaming until predicate become true or timeout
    ),
    udid
)

Settings requests

Approve Request

Approve Request(https://fbidb.io/docs/commands/#approve)- For simulators idb can programmatically approve permission for an app. Example: 

idb.execute(
    ApproveRequest(
        bundleId, //Bundle id of the app
        permissions //list of permissions from the list - PHOTOS,CAMERA,CONTACTS,URL,LOCATION,NOTIFICATION,MICROPHONE
    ),
    udid
)

Clear Keychain Request

Clear Keychain Request(https://fbidb.io/docs/commands/#clear-the-keychain)- For simulators idb can clear the entire keychain. Example: 

idb.execute(
    ClearKeychainRequest(),
    udid
)

Contacts Update Request

Contacts Update Request(https://fbidb.io/docs/commands/#add-contacts)- For simulators idb can overwrite the simulators contacts db. Example: 

idb.execute(
    ContactsUpdateRequest(
        contactsDbFile // sqlite file's path with contacts
    ),
    udid
)

Get Setting Request

Get Setting Request- Gets a preference. Example: 

idb.execute(
    GetSettingRequest(
        setting = GetSettingRequestBody.LocaleSetting() //Gets a local preference value
            or GetSettingRequestBody.AnySetting(
                name, //Preference name
                domain //Preference domain, assumed to be Apple Global Domain if not specified
            )
    ),
    udid
)

Get Settings Request

Get Settings Request- Settings' list by type. Example: 

idb.execute(
    GetSettingsRequest(
        settingType //settings' type - LOCALE(default) or ANY
    ),
    udid
)

Revoke Request

Revoke Request- Revoke permissions for an app. Example: 

idb.execute(
    RevokeRequest(
        bundleId, //Bundle id of the app
        permissions, //Permissions to revoke from the list - PHOTOS,CAMERA,CONTACTS,URL,LOCATION,NOTIFICATION,MICROPHONE
        scheme //Url scheme registered by the app to revoke
    ),
    udid
)

Setting Request

Setting Request- Sets a preference. Example: 

idb.execute(
    SettingRequest(
        setting = SettingRequestBody.HardwareKeyboardSetting(
            enabled //activate/deactivate HardwareKeyboard setting
        ) or SettingRequestBody.LocaleSetting(
            localeIdentifier //Preference value
        ) or SettingRequestBody.AnySetting(
            name, //Preference name
            value, //Preference value
            valueType, //Specifies the type of the value to be set, for supported types see 'defaults get help' defaults to string. Example of usage: idb set --domain com.apple.suggestions.plist SuggestionsAppLibraryEnabled --type bool true
            domain //Preference domain, assumed to be Apple Global Domain if not specified
        )
    ),
    udid
)

Xctest requests

Xctest Install Request

Xctest Install Request(https://fbidb.io/docs/test-execution#installation-of-test-bundles)- Install an xctest. Example: 

idb.execute(
    XctestInstallRequest(
        testBundlePath, //Bundle path of the test bundle
    ),
    udid
)

Xctest List Bundles Request

Xctest List Bundles Request- List the installed test bundles. Example: 

idb.execute(
    XctestListBundlesRequest(),
    udid
)

Xctest List Tests Request

Xctest List Tests Request- List the tests inside an installed test bundle. Example: 

idb.execute(
    XctestListTestsRequest(
        appPath, //Path of the app of the test (needed for app tests)
        bundleName //Bundle id of the test bundle to list
    ),
    udid
)

Xctest Run Request

Xctest Run Request(https://fbidb.io/docs/test-execution#ios-simulators)- Run an installed xctest. Example: 

idb.execute(
    XctestRunRequest(
        xctestRunRequest = XctestRunRequestBody.LogicXctestRequestBody(
            testBundleId, //Bundle id of the test to launch
            reportActivities, //idb will report activity data emitted by your test bundle
            reportAttachments, //idb will report activity and attachment data emitted by your test bundle
            collectCoverage, //collect coverage or not
            collectLogs, //collect logs or not
            waitForDebugger, //Suspend test run process to wait for a debugger to be attached. (It is NOT supported by ui test).
            collectResultBundle, //collect result bundle or not
            coverageFormat, //Format for code coverage information: "EXPORTED (default value) a file in JSON format as exported by `llvm-cov export`; "RAW a folder containing the .profraw files as generated by the Test Bundle, Host App and/or Target App
            testsToRun, //Run these tests only. if not specified all tests are run. Format: className/methodName
            testsToSkip, //Skip these tests, has precedence over --tests-to-run. Format: className/methodName
            env, //env map
            args, //Arguments to start the test with
            timeout //The number of seconds to wait before the test times out. When the timeout is exceeded the test will exit and an attempt will be made to obtain a sample of the hung process
        ) or XctestRunRequestBody.UIXctestRequestBody(
            testBundleId, //Bundle id of the test to launch
            appBundleId, //Bundle id of the app to test
            reportActivities, //idb will report activity data emitted by your test bundle
            reportAttachments, //idb will report activity and attachment data emitted by your test bundle
            collectCoverage, //collect coverage or not
            collectLogs, //collect logs or not
            waitForDebugger, //Suspend test run process to wait for a debugger to be attached. (It is NOT supported by ui test).
            collectResultBundle, //collect result bundle or not
            coverageFormat, //Format for code coverage information: "EXPORTED (default value) a file in JSON format as exported by `llvm-cov export`; "RAW a folder containing the .profraw files as generated by the Test Bundle, Host App and/or Target App
            testHostAppBundleId, //Bundle id of the app that hosts ui test
            testsToRun, //Run these tests only. if not specified all tests are run. Format: className/methodName
            testsToSkip, //Skip these tests, has precedence over --tests-to-run. Format: className/methodName
            env, //env map
            args, //Arguments to start the test with
            timeout //The number of seconds to wait before the test times out. When the timeout is exceeded the test will exit and an attempt will be made to obtain a sample of the hung process
        ) or XctestRunRequestBody.ApplicationXctestRequestBody(
            testBundleId, //Bundle id of the test to launch
            appBundleId, //Bundle id of the app to test
            reportActivities, //idb will report activity data emitted by your test bundle
            reportAttachments, //idb will report activity and attachment data emitted by your test bundle
            collectCoverage, //collect coverage or not
            collectLogs, //collect logs or not
            waitForDebugger, //Suspend test run process to wait for a debugger to be attached. (It is NOT supported by ui test).
            collectResultBundle, //collect result bundle or not
            coverageFormat, //Format for code coverage information: "EXPORTED (default value) a file in JSON format as exported by `llvm-cov export`; "RAW a folder containing the .profraw files as generated by the Test Bundle, Host App and/or Target App
            testHostAppBundleId, //Bundle id of the app that hosts ui test
            testsToRun, //Run these tests only. if not specified all tests are run. Format: className/methodName
            testsToSkip, //Skip these tests, has precedence over --tests-to-run. Format: className/methodName
            env, //env map
            args, //Arguments to start the test with
            timeout //The number of seconds to wait before the test times out. When the timeout is exceeded the test will exit and an attempt will be made to obtain a sample of the hung process
        )
    ),
    udid
)