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
| Method | Mode | When to use it |
|---|---|---|
ansight.capabilities.snapshot() | SDK / device | Inspect current execution mode, providers, and available operations before an optional branch. |
ansight.capabilities.require(requirements) | SDK / device | Fail early when a branch needs capabilities or app tools that were not declared as mandatory in the descriptor. |
ansight.session.getAppState() | SDK | Check the app’s observed foreground/background state before interacting. |
ansight.session.getProperties<T>() | SDK / device | Read grouped properties recorded by the session provider, with an optional local type for the returned properties. |
ansight.session.getTimeline(args?) | SDK / device | Correlate events across categories and time without making separate source queries. |
ansight.ui.find(args?) | SDK / device | Locate matching nodes in the current visual tree; use a stable automationId where possible. |
ansight.ui.waitFor(args?) | SDK / device | Wait for a bounded UI state transition, such as a loading indicator disappearing. |
ansight.ui.assert(args?) | SDK / device | Have the host evaluate a UI condition and retain its evidence; add a named expect for task status. |
ansight.ui.tap(args?) | SDK / device | Tap a selected node or coordinate and retain before/after evidence. |
ansight.ui.longPress(args) | SDK / device | Press 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 / device | Enter text into a selected input; select a stable input before passing text. |
ansight.ui.swipe(args?) | SDK / device | Perform a directional gesture when the exact drag path matters. |
ansight.ui.scroll(args?) | SDK / device | Move a scrollable view to reveal an item, then find or wait for that item. |
ansight.ui.pinch(args) | SDK / device | Perform a two-contact zoom gesture on a selected region. |
ansight.ui.back(args?) | SDK / device | Send the platform back action and inspect the destination screen. |
ansight.ui.playPen(args) | iOS Simulator; SDK required for hid+sdk / sdk | Play a pen file or samples on an explicit native/framework surface. See Pencil Input. |
ansight.ui.runSequence(args) | SDK / device | Batch 1–32 known coordinate gestures when no intermediate decision is needed. |
ansight.ui.getLiveVisualTree(args?) | SDK / device | Read 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?) | SDK | Read framework navigation state when visible nodes do not explain the route stack. |
ansight.ui.getVisualTreeSnapshot(args?) | SDK / device | Read a previously retained visual tree after capture or when the app is no longer live. |
ansight.ui.searchVisualTree(args?) | SDK / device | Search 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
| Method | Mode | When to use it |
|---|---|---|
ansight.keyboard.open(args) | SDK / device | Focus a selected input and verify that the system software keyboard appeared. |
ansight.keyboard.isOpen() | SDK / device | Read current keyboard visibility from fresh device accessibility evidence. |
ansight.keyboard.dismiss(args?) | SDK / device | Close an open keyboard safely; it does nothing when the keyboard is already closed. |
ansight.keyboard.press({ key: "Enter" }) | SDK / device | Send Enter to the focused app through device input. |
ansight.keyboard.submit(args?) | Compatible SDK tool | Invoke the focused editor action through ui.submit_keyboard; no newline fallback. |
ansight.screenshots.capture(args?) | SDK / device | Persist a fresh frame and return its frameId, host path, dimensions, timestamp, and hash. |
ansight.screenshots.take(args?) | SDK / device | Persist a fresh frame in the existing app-tool envelope, including payload.result.frameId. |
ansight.screenshots.getFrame(args?) | SDK / device | Read an already persisted frame, including after the live moment has passed. |
ansight.screenshots.assert(args?) | SDK | Compare the current screen with a baseline frame and inspect the comparison result. |
ansight.screenshots.compare(args) | SDK / device | Compare a retained actual frame with a workspace reference or retained frame; retain overlay, crops and regions. |
ansight.screenshots.evaluate(args) | SDK / device | Evaluate retained actual and optional reference images against criteria using the configured AI provider; retain findings and annotation-ready regions. |
ansight.database.assert(args) | SDK | Poll 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
| Method | Mode | When to use it |
|---|---|---|
ansight.network.get(args?) | SDK | Page through retained HTTP request summaries with time, host, method, status, and failure filters. |
ansight.network.getRequest(args) | SDK | Read details and bounded headers for a request ID found by get. |
ansight.network.readBody(args) | SDK | Read a bounded request or response body prefix by request ID and side; body: null means none was retained. |
ansight.connectivity.summary(args?) | SDK | Summarize captured OS connection availability, transitions, quality, and gaps. |
ansight.connectivity.timeline(args?) | SDK | Page through connectivity snapshots, changes, quality samples, or gaps. |
ansight.connectivity.at(args) | SDK | Inspect state at a time or annotation; unknown means no observation covers that point. |
ansight.logs.get(args?) | SDK / device | Read bounded captured log entries for a time window. |
ansight.logs.search(args) | SDK / device | Find log entries containing a known term or identifier. |
ansight.logs.getContext(args?) | SDK / device | Read entries around a selected log to understand preceding and following activity. |
ansight.logs.getFacets(args?) | SDK / device | Count matching logs by available dimensions before narrowing a query. |
ansight.logs.getTimeline(args?) | SDK / device | Aggregate log frequency over time to locate spikes. |
ansight.logs.summarizeWindow(args?) | SDK / device | Get a bounded summary of a selected log window. |
ansight.logs.extractExceptions(args?) | SDK / device | Group exception-like entries to identify distinct failures. |
ansight.telemetry.get(args?) | SDK / device | Read raw captured performance samples. |
ansight.telemetry.getTimeline(args?) | SDK / device | Aggregate samples over time for trend comparison. |
ansight.telemetry.summarizeWindow(args?) | SDK / device | Get statistics for a selected telemetry interval. |
ansight.touches.getTimeline(args?) | SDK | Read when captured touches occurred relative to other evidence. |
ansight.touches.getContext(args?) | SDK | Inspect evidence surrounding a selected touch. |
ansight.touches.getGestureSegments(args?) | SDK | Group touch points into gestures before reasoning about a swipe or drag. |
ansight.touches.findTapTargets(args?) | SDK | Identify likely UI targets for recorded taps. |
ansight.touches.getHeatmap(args?) | SDK | Find regions with concentrated touches. |
ansight.touches.findDead(args?) | SDK | Find touches with no apparent subsequent UI response. |
ansight.touches.getArtifacts(args?) | SDK | Retrieve screenshots or other evidence associated with a touch. |
ansight.touches.summarizeFlow(args?) | SDK | Summarize 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
| Method | Mode | When to use it |
|---|---|---|
ansight.artifacts.getNearest(args?) | SDK / device | Find evidence closest to a timestamp or event. |
ansight.artifacts.getSession(args?) | SDK / device | List artifacts retained for the enforced session. |
ansight.artifacts.listFiles(args?) | SDK / device | Browse entries inside a captured artifact snapshot. |
ansight.artifacts.readFile(args) | SDK / device | Read a selected file from a retained snapshot. |
ansight.annotations.get(args?) | SDK / device | Read timeline and screenshot annotations before creating or changing one. |
ansight.annotations.create(args) | SDK / device | Add a timeline point, range, or screenshot annotation to the session. |
ansight.annotations.update(args) | SDK / device | Patch supplied fields on an existing annotation; unspecified fields remain. |
ansight.annotations.delete(args) | SDK / device | Delete a known annotation, optionally guarding on its source. |
ansight.files.list(args) | Device | Browse the app’s external sandbox through the host provider. |
ansight.files.read(args) | Device | Read up to 256 KiB of external sandbox file content as Base64. |
ansight.files.capture(args) | Device | Retain 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
| Method | Mode | When to use it |
|---|---|---|
ansight.lifecycle.launch() | SDK / device | Start the selected app, including after a permission change terminated it. |
ansight.lifecycle.foreground() | SDK / device | Bring the selected app to the foreground before interacting. |
ansight.lifecycle.background() | SDK / device | Press Home on iOS Simulator or Android, including physical Android; physical iOS is unsupported. |
ansight.lifecycle.terminate() | SDK / device | End the selected app process to test cold start or exit behavior. |
ansight.device.setLocation(args) | SDK | Set one simulated coordinate on a supported virtual device. |
ansight.device.playLocation(args) | SDK | Start GPX/KML route playback; the call returns after the first point, while playback continues. |
ansight.device.clearLocation() | SDK | Clear a simulated coordinate on iOS Simulator; it does not stop an active route. |
ansight.device.shake(args?) | SDK | Send a fixed UIKit shake gesture to an iOS Simulator, or configurable acceleration pulses to an Android Emulator. |
ansight.device.playAccelerometer(args) | SDK | Send a bounded sequence of timed accelerometer samples to an Android Emulator. |
ansight.device.audioCapabilities() | SDK | Check whether the selected virtual device can accept microphone injection before a recording test. |
ansight.device.injectMicrophoneAudio(args) | SDK | Deliver supported WAV audio while the app is already recording, then assert the app’s result separately. |
ansight.device.network.capabilities() | SDK | Check the macOS virtual-device conditioning backend without changing traffic. |
ansight.device.network.get(args) | SDK | Read a conditioning lease’s profile, current step, expiry and traffic counters. |
ansight.device.network.set(args) | SDK | Create a bounded TCP conditioning lease or replace its profile. |
ansight.device.network.reset(args) | SDK | Stop a known conditioning lease and close its proxied connections. |
ansight.device.network.runScenario(args) | SDK | Start timed conditioning steps while serial UI actions continue. |
ansight.permissions.query(args) | SDK / device | Read observed app authorization without changing it. |
ansight.permissions.grant(args) | SDK / device | Grant a supported native permission for a controlled test. |
ansight.permissions.revoke(args) | SDK / device | Revoke a supported native permission to test denied flows. |
ansight.permissions.ios.query(args) | SDK / device | Read a supported Simulator service’s authorization. |
ansight.permissions.ios.grant(args) | SDK / device | Grant a supported Simulator service. |
ansight.permissions.ios.revoke(args) | SDK / device | Revoke a supported Simulator service. |
ansight.permissions.ios.reset(args) | SDK / device | Restore iOS Simulator permission prompting for a service. |
ansight.permissions.android.query(args) | SDK / device | Read declared native Android permission states. |
ansight.permissions.android.grant(args) | SDK / device | Grant a declared permission that Android permits the host to change. |
ansight.permissions.android.revoke(args) | SDK / device | Revoke 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
| Method | Mode | When to use it |
|---|---|---|
ansight.appTools.list() | SDK | Discover tool IDs published by the connected app before using a standard suite or custom app tool. |
ansight.tasks.list(args?) | SDK / device | Find a task in the caller’s exact workspace and app scope by query or feature. |
ansight.tasks.run(args) | SDK / device | Run a discovered task against the same live session; a non-passing child rejects. |
ansight.spans.measure(name, operation, options?) | SDK / device | Bracket an awaited operation with host-observed start, completion, or failure events for Trends. |
ansight.callTool<TResult>(name, args?) | Tool-specific | Call 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.