Examples

import XCTest
import gptd_swift

@MainActor
final class DemoUITests: XCTestCase {

    var app: XCUIApplication!
    var gptDriver: GptDriver!

    override func setUpWithError() throws {
        continueAfterFailure = false

        app = XCUIApplication()
        app.launch()

        gptDriver = GptDriver(
            apiKey: "<YOUR_API_KEY>",
            nativeApp: app
        )
    }

    override func tearDownWithError() throws {
        app = nil
    }

    func testNavigationToSecondScreen() async throws {
        try gptDriver.execute("Tap on the Go to Second Screen button")
        try gptDriver.execute("Check if you can see a screen with a second screen headline")
    }
}

With caching enabled

override func setUpWithError() throws {
    continueAfterFailure = false

    app = XCUIApplication()
    app.launch()

    gptDriver = GptDriver(
        apiKey: "<YOUR_API_KEY>",
        nativeApp: app,
        cachingMode: CachingMode.interactionRegion,
        testId: self.name
    )
}

func testLoginFlow() async throws {
    try gptDriver.execute("Tap the email field and enter test@example.com")
    try gptDriver.execute("Tap the password field and enter SecurePass123")
    try gptDriver.execute("Tap the Sign In button")
    try gptDriver.assert("The home screen is displayed with a welcome message")
}

Native-first with AI fallback

Run your own XCUITest code first and let the SDK fall back to AI only when it fails. This is the pattern to reach for in a real suite: stable steps stay fast and deterministic, and a step that breaks because the UI moved keeps the test alive instead of failing it.

func testSearchAndFilter() async throws {
    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()
    })

    try gptDriver.assert("Search results for wireless headphones are shown", nativeAction: {
        XCTAssertTrue(app.collectionViews["SearchResults"].waitForExistence(timeout: 10))
    })
}

Keep the natural language command descriptive of what the native code does. It is the AI fallback and the label the step carries in the session recording, so "Tap the Sign In button" is worth more than "fallback".

Bulk assertions and checks

Verify several things against one screenshot rather than one call each. assertBulk fails the test when any condition is not met; checkBulk returns the results so you can branch on them.

func testCartTotals() async throws {
    try gptDriver.execute("Open the cart")

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

    let results = try gptDriver.checkBulk([
        "A promo banner is visible",
        "A free shipping badge is visible"
    ])

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

Both take a nativeAction closure too. If the closure succeeds, checkBulk reports every condition as true:

let results = try gptDriver.checkBulk(["The cart badge shows 1"], nativeAction: {
    XCTAssertEqual(app.buttons["TabBar.Cart"].value as? String, "1")
})

Reporting the test result

Report the outcome in tearDown so each run is recorded as passed or failed rather than as auto-completed, and so the session’s slot against your account’s parallel session limit is released as soon as the test ends.

import XCTest
import gptd_swift

@MainActor
final class CheckoutUITests: XCTestCase {

    var app: XCUIApplication!
    var gptDriver: GptDriver!

    override func setUpWithError() throws {
        continueAfterFailure = false

        app = XCUIApplication()
        app.launch()

        gptDriver = GptDriver(
            apiKey: "<YOUR_API_KEY>",
            nativeApp: app,
            testId: self.name
        )
    }

    override func tearDownWithError() throws {
        if testRun?.failureCount == 0 {
            try? gptDriver.setSessionSucceeded()
        } else {
            try? gptDriver.setSessionFailed()
        }

        app = nil
    }

    func testCheckout() async throws {
        try gptDriver.execute("Add the first product to the cart")
        try gptDriver.execute("Open the cart and tap Checkout")
        try gptDriver.assert("The order confirmation screen is displayed")
    }
}

Use testRun?.failureCount rather than a flag you set yourself, so a failure raised anywhere in the test is reflected, including one from assert. Call both with try?: reporting the status is bookkeeping, and a network hiccup on the way out should not turn a passing test red.

With CI metadata

Record what your CI knows and the SDK does not, so a session can be found again by it and reporting can be sliced by it.

override func setUpWithError() throws {
    continueAfterFailure = false

    app = XCUIApplication()
    app.launch()

    let environment = ProcessInfo.processInfo.environment

    gptDriver = GptDriver(
        apiKey: "<YOUR_API_KEY>",
        nativeApp: app,
        testId: self.name,
        metadata: [
            "branch": environment["BUILDKITE_BRANCH"] ?? "local",
            "commit": environment["BUILDKITE_COMMIT"] ?? "unknown",
            "job": environment["BUILDKITE_JOB_ID"] ?? "unknown"
        ]
    )
}

Values are strings, so convert anything else before passing it. Keys are free-form apart from language and version, which the SDK reserves to report itself.

With additional context

gptDriver = GptDriver(
    apiKey: "<YOUR_API_KEY>",
    nativeApp: app,
    additionalUserContext: "When asked about Location Permissions, grant it. When a marketing popup appears, dismiss it."
)

func testOnboarding() async throws {
    try gptDriver.execute("Complete the onboarding flow by tapping Next on each screen")
    try gptDriver.execute("Tap Get Started on the final screen")
    try gptDriver.assert("The main dashboard is visible")
}

Local tooling

Agent skill

MCP

SDK

Basic navigation test

With caching enabled

Native-first with AI fallback

Bulk assertions and checks

Reporting the test result

With CI metadata

With additional context

​Basic navigation test

​With caching enabled

​Native-first with AI fallback

​Bulk assertions and checks

​Reporting the test result

​With CI metadata

​With additional context

Basic navigation test

With caching enabled

Native-first with AI fallback

Bulk assertions and checks

Reporting the test result

With CI metadata

With additional context