Workspace Host API Methods

Practical method guide for the session-bound ansight API in repository TypeScript tasks.

The ansight object in a repository task calls the resident host against the task’s enforced session. Await calls serially; overlapping host or app calls are rejected. Standard methods below need no task.hostTools entry. Use the Task API Reference for descriptor and result types, and the generated ansight-task.d.ts for exact arguments in your CLI version.

const found = await ansight.ui.waitFor({
  automationId: "checkout",
  condition: "visible",
});
expect(found.satisfied, { id: "checkout-visible" }).toBe(true);

An API call can return inspection data or perform an action, but a task only passes when it records a passing named expect and no failed assertions. Check method-specific result fields rather than treating a completed promise as an assertion.

The Mode column describes current task execution eligibility. SDK / device still requires a compatible platform, device and provider; it does not promise that data exists or every operation is supported on a physical phone. See compatibility, UI automation, device controls, and evidence for those restrictions.

Capabilities, session, and UI

MethodModeWhen to use it
ansight.capabilities.snapshot()SDK / deviceInspect current execution mode, providers, and available operations before an optional branch.
ansight.capabilities.require(requirements)SDK / deviceFail early when a branch needs capabilities or app tools that were not declared as mandatory in the descriptor.
ansight.session.getAppState()SDKCheck the app’s observed foreground/background state before interacting.
ansight.session.getProperties<T>()SDK / deviceRead grouped properties recorded by the session provider, with an optional local type for the returned properties.
ansight.session.getTimeline(args?)SDK / deviceCorrelate events across categories and time without making separate source queries.
ansight.ui.find(args?)SDK / deviceLocate matching nodes in the current visual tree; use a stable automationId where possible.
ansight.ui.waitFor(args?)SDK / deviceWait for a bounded UI state transition, such as a loading indicator disappearing.
ansight.ui.assert(args?)SDK / deviceHave the host evaluate a UI condition and retain its evidence; add a named expect for task status.
ansight.ui.tap(args?)SDK / deviceTap a selected node or coordinate and retain before/after evidence.
ansight.ui.longPress(args)SDK / devicePress and hold a selected node or coordinate, then release. Defaults to 800 ms; accepts 500–10000 ms. See long press.
ansight.ui.typeText(args)SDK / deviceEnter text into a selected input; select a stable input before passing text.
ansight.ui.swipe(args?)SDK / devicePerform a directional gesture when the exact drag path matters.
ansight.ui.scroll(args?)SDK / deviceMove a scrollable view to reveal an item, then find or wait for that item.
ansight.ui.pinch(args)SDK / devicePerform a two-contact zoom gesture on a selected region.
ansight.ui.back(args?)SDK / deviceSend the platform back action and inspect the destination screen.
ansight.ui.playPen(args)iOS Simulator; SDK required for hid+sdk / sdkPlay a pen file or samples on an explicit native/framework surface. See Pencil Input.
ansight.ui.runSequence(args)SDK / deviceBatch 1–32 known coordinate gestures when no intermediate decision is needed.
ansight.ui.getLiveVisualTree(args?)SDK / deviceRead device accessibility first; SDK mode can fall back to registered app trees. See the current response-envelope caveat in the UI reference.
ansight.ui.getLiveNavigationStructure(args?)SDKRead framework navigation state when visible nodes do not explain the route stack.
ansight.ui.getVisualTreeSnapshot(args?)SDK / deviceRead a previously retained visual tree after capture or when the app is no longer live.
ansight.ui.searchVisualTree(args?)SDK / deviceSearch persisted visual-tree snapshots for a node across captured evidence.

Selectors accept fields such as automationId, text, role, and nodeId. See UI selectors for the full contract. Framework navigation requires an SDK tool; live trees can use device accessibility. Snapshot and search methods read retained evidence.

Keyboard, screenshots, and database

MethodModeWhen to use it
ansight.keyboard.open(args)SDK / deviceFocus a selected input and verify that the system software keyboard appeared.
ansight.keyboard.isOpen()SDK / deviceRead current keyboard visibility from fresh device accessibility evidence.
ansight.keyboard.dismiss(args?)SDK / deviceClose an open keyboard safely; it does nothing when the keyboard is already closed.
ansight.keyboard.press({ key: "Enter" })SDK / deviceSend Enter to the focused app through device input.
ansight.keyboard.submit(args?)Compatible SDK toolInvoke the focused editor action through ui.submit_keyboard; no newline fallback.
ansight.screenshots.capture(args?)SDK / devicePersist a fresh frame and return its frameId, host path, dimensions, timestamp, and hash.
ansight.screenshots.take(args?)SDK / devicePersist a fresh frame in the existing app-tool envelope, including payload.result.frameId.
ansight.screenshots.getFrame(args?)SDK / deviceRead an already persisted frame, including after the live moment has passed.
ansight.screenshots.assert(args?)SDKCompare the current screen with a baseline frame and inspect the comparison result.
ansight.screenshots.compare(args)SDK / deviceCompare a retained actual frame with a workspace reference or retained frame; retain overlay, crops and regions.
ansight.screenshots.evaluate(args)SDK / deviceEvaluate retained actual and optional reference images against criteria using the configured AI provider; retain findings and annotation-ready regions.
ansight.database.assert(args)SDKPoll a read-only database query until the expected condition is met or its bound expires.

Keyboard open, isOpen, and dismiss require evidence of keyboard visibility. Press sends a key; submit invokes an editor action. Verify their effect with a named assertion. Screenshot capture requires a live capture provider, while getFrame reads retained evidence.

Network, logs, telemetry, and touches

MethodModeWhen to use it
ansight.network.get(args?)SDKPage through retained HTTP request summaries with time, host, method, status, and failure filters.
ansight.network.getRequest(args)SDKRead details and bounded headers for a request ID found by get.
ansight.network.readBody(args)SDKRead a bounded request or response body prefix by request ID and side; body: null means none was retained.
ansight.connectivity.summary(args?)SDKSummarize captured OS connection availability, transitions, quality, and gaps.
ansight.connectivity.timeline(args?)SDKPage through connectivity snapshots, changes, quality samples, or gaps.
ansight.connectivity.at(args)SDKInspect state at a time or annotation; unknown means no observation covers that point.
ansight.logs.get(args?)SDK / deviceRead bounded captured log entries for a time window.
ansight.logs.search(args)SDK / deviceFind log entries containing a known term or identifier.
ansight.logs.getContext(args?)SDK / deviceRead entries around a selected log to understand preceding and following activity.
ansight.logs.getFacets(args?)SDK / deviceCount matching logs by available dimensions before narrowing a query.
ansight.logs.getTimeline(args?)SDK / deviceAggregate log frequency over time to locate spikes.
ansight.logs.summarizeWindow(args?)SDK / deviceGet a bounded summary of a selected log window.
ansight.logs.extractExceptions(args?)SDK / deviceGroup exception-like entries to identify distinct failures.
ansight.telemetry.get(args?)SDK / deviceRead raw captured performance samples.
ansight.telemetry.getTimeline(args?)SDK / deviceAggregate samples over time for trend comparison.
ansight.telemetry.summarizeWindow(args?)SDK / deviceGet statistics for a selected telemetry interval.
ansight.touches.getTimeline(args?)SDKRead when captured touches occurred relative to other evidence.
ansight.touches.getContext(args?)SDKInspect evidence surrounding a selected touch.
ansight.touches.getGestureSegments(args?)SDKGroup touch points into gestures before reasoning about a swipe or drag.
ansight.touches.findTapTargets(args?)SDKIdentify likely UI targets for recorded taps.
ansight.touches.getHeatmap(args?)SDKFind regions with concentrated touches.
ansight.touches.findDead(args?)SDKFind touches with no apparent subsequent UI response.
ansight.touches.getArtifacts(args?)SDKRetrieve screenshots or other evidence associated with a touch.
ansight.touches.summarizeFlow(args?)SDKSummarize the captured sequence of touches and gestures.

These are retained-evidence reads: empty results do not prove that capture was enabled. For HTTP filters, pagination, body limits, and truncation, see Captured network requests. Connectivity evidence has different time fields and cursor rules. To change traffic conditions, use ansight.device.network below.

Artifacts, annotations, and files

MethodModeWhen to use it
ansight.artifacts.getNearest(args?)SDK / deviceFind evidence closest to a timestamp or event.
ansight.artifacts.getSession(args?)SDK / deviceList artifacts retained for the enforced session.
ansight.artifacts.listFiles(args?)SDK / deviceBrowse entries inside a captured artifact snapshot.
ansight.artifacts.readFile(args)SDK / deviceRead a selected file from a retained snapshot.
ansight.annotations.get(args?)SDK / deviceRead timeline and screenshot annotations before creating or changing one.
ansight.annotations.create(args)SDK / deviceAdd a timeline point, range, or screenshot annotation to the session.
ansight.annotations.update(args)SDK / devicePatch supplied fields on an existing annotation; unspecified fields remain.
ansight.annotations.delete(args)SDK / deviceDelete a known annotation, optionally guarding on its source.
ansight.files.list(args)DeviceBrowse the app’s external sandbox through the host provider.
ansight.files.read(args)DeviceRead up to 256 KiB of external sandbox file content as Base64.
ansight.files.capture(args)DeviceRetain a sandbox file copy as a session snapshot and receive its snapshotId.

ansight.artifacts reads captured session material. ansight.files accesses the selected app’s external sandbox and needs files.read or files.capture; app.files instead calls tools inside a connected SDK app. See External sandbox files and Timeline annotations.

Device, app lifecycle, and permissions

MethodModeWhen to use it
ansight.lifecycle.launch()SDK / deviceStart the selected app, including after a permission change terminated it.
ansight.lifecycle.foreground()SDK / deviceBring the selected app to the foreground before interacting.
ansight.lifecycle.background()SDK / devicePress Home on iOS Simulator or Android, including physical Android; physical iOS is unsupported.
ansight.lifecycle.terminate()SDK / deviceEnd the selected app process to test cold start or exit behavior.
ansight.device.setLocation(args)SDKSet one simulated coordinate on a supported virtual device.
ansight.device.playLocation(args)SDKStart GPX/KML route playback; the call returns after the first point, while playback continues.
ansight.device.clearLocation()SDKClear a simulated coordinate on iOS Simulator; it does not stop an active route.
ansight.device.shake(args?)SDKSend a fixed UIKit shake gesture to an iOS Simulator, or configurable acceleration pulses to an Android Emulator.
ansight.device.playAccelerometer(args)SDKSend a bounded sequence of timed accelerometer samples to an Android Emulator.
ansight.device.audioCapabilities()SDKCheck whether the selected virtual device can accept microphone injection before a recording test.
ansight.device.injectMicrophoneAudio(args)SDKDeliver supported WAV audio while the app is already recording, then assert the app’s result separately.
ansight.device.network.capabilities()SDKCheck the macOS virtual-device conditioning backend without changing traffic.
ansight.device.network.get(args)SDKRead a conditioning lease’s profile, current step, expiry and traffic counters.
ansight.device.network.set(args)SDKCreate a bounded TCP conditioning lease or replace its profile.
ansight.device.network.reset(args)SDKStop a known conditioning lease and close its proxied connections.
ansight.device.network.runScenario(args)SDKStart timed conditioning steps while serial UI actions continue.
ansight.permissions.query(args)SDK / deviceRead observed app authorization without changing it.
ansight.permissions.grant(args)SDK / deviceGrant a supported native permission for a controlled test.
ansight.permissions.revoke(args)SDK / deviceRevoke a supported native permission to test denied flows.
ansight.permissions.ios.query(args)SDK / deviceRead a supported Simulator service’s authorization.
ansight.permissions.ios.grant(args)SDK / deviceGrant a supported Simulator service.
ansight.permissions.ios.revoke(args)SDK / deviceRevoke a supported Simulator service.
ansight.permissions.ios.reset(args)SDK / deviceRestore iOS Simulator permission prompting for a service.
ansight.permissions.android.query(args)SDK / deviceRead declared native Android permission states.
ansight.permissions.android.grant(args)SDK / deviceGrant a declared permission that Android permits the host to change.
ansight.permissions.android.revoke(args)SDK / deviceRevoke a declared permission on an authorized emulator or physical device.

Shared permission names and platform-specific ios and android names are exposed under ansight.permissions. See the device support matrix, Permission API, Location route playback, Microphone audio setup, and Network conditioning.

Composition, app catalog, and extra host tools

MethodModeWhen to use it
ansight.appTools.list()SDKDiscover tool IDs published by the connected app before using a standard suite or custom app tool.
ansight.tasks.list(args?)SDK / deviceFind a task in the caller’s exact workspace and app scope by query or feature.
ansight.tasks.run(args)SDK / deviceRun a discovered task against the same live session; a non-passing child rejects.
ansight.spans.measure(name, operation, options?)SDK / deviceBracket an awaited operation with host-observed start, completion, or failure events for Trends.
ansight.callTool<TResult>(name, args?)Tool-specificCall an extra host tool named in task.hostTools; use typed methods above for standard operations.

Each host, app, discovery, or child-task call counts toward maximumActions. spans.measure uses two actions. The parent task must still make its own named assertion after a child passes.