Skip to main content

GptDriver

Constructor

Pass the arguments by name. Everything after composeTestRule has a default, and the order has changed between releases.
A screen with an indefinite animation never reaches idle and never produces two matching frames, so it spends the full waitForIdleTimeoutMs and screenshotStabilityTimeoutSec budget on every step. Those two defaults are what to lower if such a screen makes a suite crawl.

AI commands

execute

Execute a natural language instruction on the current screen.

assert

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

assertBulk

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

checkBulk

The same check as assertBulk, but it returns the results instead of throwing, so you can branch on what is on screen.
assert, assertBulk and checkBulk take maxRetries (default 2) and retryDelayMs (default 1000). 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 a list and returns a map keyed by the strings you asked for.

Native-first execution

execute, assert and assertBulk take a trailing ComposeHandler lambda. The SDK runs your Compose or UiAutomator code first and only falls back to the natural language command when that code throws, so a step that works natively costs no AI round trip.
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. Successful blocks are reported to the platform with a screenshot taken just before the lambda runs, so they appear as steps in the recording alongside AI steps.
checkBulk takes no handler. Use assertBulk when you have native code to try, and checkBulk when you want the verdicts back.

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.
Pass the Throwable overload the failure you already have in hand, from a JUnit TestWatcher or an @After. Without it, a timeout or an assertion raised outside the SDK reaches the dashboard as a bare “Failed” with no reason attached. 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.
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 main alone for instance. Keys are free-form and values are strings. language and version are reserved for the SDK’s own identity: it reports Android-Kotlin and the library version it was built from, and a key of your own with either name is ignored rather than recorded.
metadata requires SDK 2.9.0 or later.