Reference

GptDriver

Constructor

GptDriver(
    apiKey: String,
    nativeApp: XCUIApplication = XCUIApplication(),
    cachingMode: CachingMode = .none,
    testId: String = "",
    additionalUserContext: String = "",
    logNativeExecutions: Bool = true,
    charactersPerSecond: Int? = 10,
    metadata: [String: String] = [:]
)

Parameter	Type	Description
`apiKey`	`String`	Your MobileBoost API key
`nativeApp`	`XCUIApplication`	The app instance to test
`cachingMode`	`CachingMode`	Caching strategy (`.none`, `.fullScreen`, `.interactionRegion`)
`testId`	`String`	Identifier for the test (used for caching and logging)
`additionalUserContext`	`String`	Context to guide AI behavior across all steps
`logNativeExecutions`	`Bool`	Report successful `nativeAction` blocks as steps in the session recording
`charactersPerSecond`	`Int?`	How fast to type text. Pass `nil` to type each string in one call
`metadata`	`[String: String]`	Your own key/values, recorded on the session

AI commands

execute

Execute a natural language instruction on the current screen.

try gptDriver.execute("Tap on the Go to Second Screen button")

assert

Verify a condition without taking action. Throws on failure, and marks the session as failed.

try gptDriver.assert("The home screen is displayed")

assertBulk

Verify several conditions against a single screenshot, in one round trip. Throws if any of them fails.

try gptDriver.assertBulk([
    "The subtotal is $499",
    "The grand total includes shipping",
    "The Place Order button is enabled"
])

checkBulk

The same check as assertBulk, but it returns the results instead of throwing, so you can branch on what is on screen.

checkBulk(_ conditions: [String], maxRetries: Int = 2, retryDelay: TimeInterval = 1.0, timeout: TimeInterval = 60) throws -> [String: Bool]

let results = try gptDriver.checkBulk([
    "A promo banner is visible",
    "The cart badge shows 1"
])

if results["A promo banner is visible"] == true {
    try gptDriver.execute("Dismiss the promo banner")
}

assert, assertBulk and checkBulk take maxRetries (default 2) and retryDelay (default 1.0 seconds). A condition that is not met yet is re-checked against a fresh screenshot, which covers a screen that is still settling.

extract

Extract information from the current screen. Takes an array and returns a dictionary keyed by the strings you asked for.

extract(_ extractions: [String], timeout: TimeInterval = 60) throws -> [String: Any]

let values = try gptDriver.extract(["username", "account balance"])
let username = values["username"] as? String

Native-first execution

Every AI command has an overload taking a nativeAction closure. The SDK runs your XCUITest code first and only falls back to the natural language command when that code fails, so a step that works natively costs no AI round trip.

execute(_ command: String, nativeAction: () throws -> Void, timeout: TimeInterval = 600, cachingMode: CachingMode? = nil) throws
assert(_ assertion: String, nativeAction: () throws -> Void, maxRetries: Int = 2, retryDelay: TimeInterval = 1.0, timeout: TimeInterval = 60) throws
assertBulk(_ assertions: [String], nativeAction: () throws -> Void, maxRetries: Int = 2, retryDelay: TimeInterval = 1.0, timeout: TimeInterval = 60) throws
checkBulk(_ conditions: [String], nativeAction: () throws -> Void, maxRetries: Int = 2, retryDelay: TimeInterval = 1.0, timeout: TimeInterval = 60) throws -> [String: Bool]

try gptDriver.execute("Tap on Search, type 'wireless headphones', and submit", nativeAction: {
    let searchField = app.textFields["Navigation.SearchBar.Input"]
    XCTAssertTrue(searchField.waitForExistence(timeout: 15))
    searchField.tap()
    searchField.typeText("wireless headphones")
    app.keyboards.buttons["Search"].tap()
})

The SDK falls back to AI when the closure throws, raises an Objective-C exception, or hits a failing XCTAssert. Assertion failures inside the closure are intercepted and are not recorded as test failures, since the fallback takes over. Only a failure of the fallback itself fails the test. Write the command to describe what the native code does, not only what to do if it breaks. It is also the label the step carries in the session recording. For checkBulk, a closure that succeeds reports every condition as true.

Successful blocks are reported to the platform with a screenshot taken just before the closure runs, so they appear as steps in the session recording alongside AI steps. Reporting is best effort and never fails a passing test. Set logNativeExecutions: false in the constructor to skip it and trade the recording for speed.

Session lifecycle

The session starts automatically on the first AI command. Report the outcome at the end of a test so the dashboard records it.

setSessionSucceeded(timeout: TimeInterval = 15) throws
setSessionFailed(timeout: TimeInterval = 15) throws

try gptDriver.setSessionSucceeded()

A failed assert or assertBulk marks the session as failed for you. Nothing marks it as succeeded, so a session you never close is recorded as auto-completed, which reads as “the test stopped calling” rather than “the test passed”. Closing a session also releases its slot against your account’s parallel session limit straight away, instead of leaving it held until it ages out.

Session metadata

Pass metadata to record your own key/values on the session, anything your CI knows and the SDK does not.

gptDriver = GptDriver(
    apiKey: "<YOUR_API_KEY>",
    nativeApp: app,
    metadata: [
        "branch": ProcessInfo.processInfo.environment["BUILDKITE_BRANCH"] ?? "unknown",
        "job": ProcessInfo.processInfo.environment["BUILDKITE_JOB_ID"] ?? "unknown"
    ]
)

Nothing in the SDK or the platform interprets these. They are stored on the session so a run can be found again by them, and so reporting can be sliced by them, failure rates on master alone for instance. Keys are free-form and values are strings. language and version are reserved for the SDK’s own identity: it reports Swift and the package version it was built from, and a key of your own with either name is ignored rather than recorded.

metadata requires SDK 1.12.0 or later.

Session URL

The SDK creates a session URL for each test run, accessible via:

gptDriver.sessionURL: public property
onSessionCreated callback: for real-time access
XCTest Attachments: saved as a .webloc file in test results
OS Logs: logged at .notice level

Retrieving in CI

The session URL is saved as an XCTest attachment named GPTDriver Session URL Link with lifetime .keepAlways. Extract it from the .xcresult bundle in your CI pipeline.

Local tooling

Agent skill

MCP

SDK

GptDriver

Constructor

AI commands

execute

assert

assertBulk

checkBulk

extract

Native-first execution

Session lifecycle

Session metadata

Session URL

Retrieving in CI

​GptDriver

​Constructor

​AI commands

​execute

​assert

​assertBulk

​checkBulk

​extract

​Native-first execution

​Session lifecycle

​Session metadata

​Session URL

​Retrieving in CI

GptDriver

Constructor

AI commands

execute

assert

assertBulk

checkBulk

extract

Native-first execution

Session lifecycle

Session metadata

Session URL

Retrieving in CI