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.

Capabilities, session, and UI

Method	When to use it
`ansight.capabilities.snapshot()`	Inspect current execution mode, providers, and available operations before an optional branch.
`ansight.capabilities.require(requirements)`	Fail early when a branch needs capabilities or app tools that were not declared as mandatory in the descriptor.
`ansight.session.getAppState()`	Check the app’s observed foreground/background state before interacting.
`ansight.session.getProperties<T>()`	Read grouped session properties recorded by the app, with an optional local type for the returned properties.
`ansight.session.getTimeline(args?)`	Correlate events across categories and time without making separate source queries.
`ansight.ui.find(args?)`	Locate matching nodes in the current visual tree; use a stable `automationId` where possible.
`ansight.ui.waitFor(args?)`	Wait for a bounded UI state transition, such as a loading indicator disappearing.
`ansight.ui.assert(args?)`	Have the host evaluate a UI condition and retain its evidence; add a named `expect` for task status.
`ansight.ui.tap(args?)`	Tap a selected node or coordinate and retain before/after evidence.
`ansight.ui.typeText(args)`	Enter text into a selected input; select a stable input before passing text.
`ansight.ui.swipe(args?)`	Perform a directional gesture when the exact drag path matters.
`ansight.ui.scroll(args?)`	Move a scrollable view to reveal an item, then find or wait for that item.
`ansight.ui.pinch(args)`	Perform a two-contact zoom gesture on a selected region.
`ansight.ui.back(args?)`	Send the platform back action and inspect the destination screen.
`ansight.ui.runSequence(args)`	Batch 1–32 known coordinate gestures when no intermediate decision is needed.
`ansight.ui.getLiveVisualTree(args?)`	Ask the live app for its current visual hierarchy; requires a registered SDK visual-tree tool.
`ansight.ui.getLiveNavigationStructure(args?)`	Read framework navigation state when visible nodes do not explain the route stack.
`ansight.ui.getVisualTreeSnapshot(args?)`	Read a previously retained visual tree after capture or when the app is no longer live.
`ansight.ui.searchVisualTree(args?)`	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. getLiveVisualTree and getLiveNavigationStructure use live SDK tools, while snapshot and search methods read retained host evidence.

Keyboard, screenshots, and database

Method	When to use it
`ansight.keyboard.open(args)`	Focus a selected input and verify that the system software keyboard appeared.
`ansight.keyboard.isOpen()`	Read current keyboard visibility from fresh device accessibility evidence.
`ansight.keyboard.dismiss(args?)`	Close an open keyboard safely; it does nothing when the keyboard is already closed.
`ansight.screenshots.take(args?)`	Capture the current live screen for immediate evidence.
`ansight.screenshots.getFrame(args?)`	Read an already persisted frame, including after the live moment has passed.
`ansight.screenshots.assert(args?)`	Compare the current screen with a baseline frame and inspect the comparison result.
`ansight.database.assert(args)`	Poll a read-only database query until the expected condition is met or its bound expires.

Keyboard methods fail when the device cannot report system keyboard presence; they do not infer it from input focus. Screenshot capture requires a live capture provider, while getFrame reads retained evidence.

Network, logs, telemetry, and touches

Method	When to use it
`ansight.network.get(args?)`	Page through retained HTTP request summaries with time, host, method, status, and failure filters.
`ansight.network.getRequest(args)`	Read details and bounded headers for a request ID found by `get`.
`ansight.network.readBody(args)`	Read a bounded request or response body prefix by request ID and side; `body: null` means none was retained.
`ansight.logs.get(args?)`	Read bounded captured log entries for a time window.
`ansight.logs.search(args)`	Find log entries containing a known term or identifier.
`ansight.logs.getContext(args?)`	Read entries around a selected log to understand preceding and following activity.
`ansight.logs.getFacets(args?)`	Count matching logs by available dimensions before narrowing a query.
`ansight.logs.getTimeline(args?)`	Aggregate log frequency over time to locate spikes.
`ansight.logs.summarizeWindow(args?)`	Get a bounded summary of a selected log window.
`ansight.logs.extractExceptions(args?)`	Group exception-like entries to identify distinct failures.
`ansight.telemetry.get(args?)`	Read raw captured performance samples.
`ansight.telemetry.getTimeline(args?)`	Aggregate samples over time for trend comparison.
`ansight.telemetry.summarizeWindow(args?)`	Get statistics for a selected telemetry interval.
`ansight.touches.getTimeline(args?)`	Read when captured touches occurred relative to other evidence.
`ansight.touches.getContext(args?)`	Inspect evidence surrounding a selected touch.
`ansight.touches.getGestureSegments(args?)`	Group touch points into gestures before reasoning about a swipe or drag.
`ansight.touches.findTapTargets(args?)`	Identify likely UI targets for recorded taps.
`ansight.touches.getHeatmap(args?)`	Find regions with concentrated touches.
`ansight.touches.findDead(args?)`	Find touches with no apparent subsequent UI response.
`ansight.touches.getArtifacts(args?)`	Retrieve screenshots or other evidence associated with a touch.
`ansight.touches.summarizeFlow(args?)`	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.

Artifacts, annotations, and files

Method	When to use it
`ansight.artifacts.getNearest(args?)`	Find evidence closest to a timestamp or event.
`ansight.artifacts.getSession(args?)`	List artifacts retained for the enforced session.
`ansight.artifacts.listFiles(args?)`	Browse entries inside a captured artifact snapshot.
`ansight.artifacts.readFile(args)`	Read a selected file from a retained snapshot.
`ansight.annotations.get(args?)`	Read timeline and screenshot annotations before creating or changing one.
`ansight.annotations.create(args)`	Add a timeline point, range, or screenshot annotation to the session.
`ansight.annotations.update(args)`	Patch supplied fields on an existing annotation; unspecified fields remain.
`ansight.annotations.delete(args)`	Delete a known annotation, optionally guarding on its source.
`ansight.files.list(args)`	Browse the app’s external sandbox through the host provider.
`ansight.files.read(args)`	Read up to 256 KiB of external sandbox file content as Base64.
`ansight.files.capture(args)`	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	When to use it
`ansight.lifecycle.launch()`	Start the selected app, including after a permission change terminated it.
`ansight.lifecycle.foreground()`	Bring the selected app to the foreground before interacting.
`ansight.lifecycle.background()`	Press Home on a simulator or emulator to test background behavior.
`ansight.lifecycle.terminate()`	End the selected app process to test cold start or exit behavior.
`ansight.device.setLocation(args)`	Set one simulated coordinate on a supported virtual device.
`ansight.device.playLocation(args)`	Start GPX/KML route playback; the call returns after the first point, while playback continues.
`ansight.device.clearLocation()`	Clear a simulated coordinate on iOS Simulator; it does not stop an active route.
`ansight.device.shake(args?)`	Send a fixed UIKit shake gesture to an iOS Simulator, or configurable acceleration pulses to an Android Emulator.
`ansight.device.playAccelerometer(args)`	Send a bounded sequence of timed accelerometer samples to an Android Emulator.
`ansight.device.audioCapabilities()`	Check whether the selected virtual device can accept microphone injection before a recording test.
`ansight.device.injectMicrophoneAudio(args)`	Deliver supported WAV audio while the app is already recording, then assert the app’s result separately.
`ansight.permissions.query(args)`	Read observed app authorization without changing it.
`ansight.permissions.grant(args)`	Grant a supported native permission for a controlled test.
`ansight.permissions.revoke(args)`	Revoke a supported native permission to test denied flows.
`ansight.permissions.ios.reset(args)`	Restore iOS Simulator permission prompting for a service.

Shared permission names and platform-specific ios and android names are exposed under ansight.permissions. The platform-specific namespaces also have query, grant, and revoke. See Permission API for OS mappings and limitations, Location route playback, and Microphone audio input.

Composition, app catalog, and extra host tools

Method	When to use it
`ansight.appTools.list()`	Discover tool IDs published by the connected app before using a standard suite or custom app tool.
`ansight.tasks.list(args?)`	Find a task in the caller’s exact workspace and app scope by query or feature.
`ansight.tasks.run(args)`	Run a discovered task against the same live session; a non-passing child rejects.
`ansight.spans.measure(name, operation, options?)`	Bracket an awaited operation with host-observed start, completion, or failure events for Trends.
`ansight.callTool<TResult>(name, args?)`	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.