Workspace

An Ansight workspace is a source-controlled ansight/ folder for your app. It is the shared playbook for agentic tests, deterministic tasks, event-driven triggers, performance rules, privacy filters, and their validation schemas.

The workspace does not need to live in the same source repository as the app. Keeping it beside the app code can give an agent useful context while it builds workspace components, but co-locating them is not required.

You do not need every feature on day one. Start with one test or task, then add flows, quality checks, and trends when you want repeatable performance evidence.

1. Initialize the workspace

From the directory that will own the workspace, run:

ansight workspace init .

In an interactive terminal, Ansight asks which App ID belongs to the workspace. For scripts and CI, provide it explicitly:

ansight workspace init . --app-id com.example.app

Registration links the App ID to this trusted codebase. It also enables automatic flow, quality, and trend analysis when a matching session ends. Use --no-register when you only want to scaffold the files.

Initialization creates this layout:

ansight/
  README.md
  package.json
  tests/          Agentic end-to-end scenarios
  tasks/          Explicitly invoked deterministic TypeScript
  triggers/       Event-driven TypeScript reactions
  flows/          Semantic start/end event windows
  quality/        Per-run measurements and optional embedded trend policies
  sanitizers/     Privacy filters for exported sessions
  schema/         Versioned machine-readable contracts

Each folder receives an editable README.md with a starter example and its important constraints. Generated declaration files and TypeScript configuration are added where needed.

Initialization is idempotent: existing customized files are preserved. Use --force only when you intend to replace support files, including the generated READMEs, with the defaults from the installed host.

2. Choose the right definition

The performance path is deliberately layered:

SDK events -> flow window -> quality measurement -> optional trend decision

A flow decides when to measure. Quality decides what to measure and what is acceptable now. An optional trend policy decides whether the same measurement is getting worse over time. The policy shares the measurement’s authoring location and identity; its evaluation, history, events, and UI remain distinct.

3. Create a first test

Find the app’s bundle or package ID with ansight app list, then create a small observable scenario:

ansight workspace add test . onboarding.smoke \
  --app-id com.example.app \
  --prompt "Complete onboarding as a new user" \
  --assertion "The signed-in home screen is visible"

Validate the complete workspace before running it:

ansight test validate .
ansight test run . onboarding.smoke

The runner can launch an installed app and wait for its Ansight session, but it does not build the app. The development build must initialize the Ansight SDK and use the same App ID as the test.

4. Extract a task from recorded behavior

When a recorded session already contains the behavior you want to reproduce, turn just that timeline interval into a reviewable task draft. First find the session and inspect its touch and visual-tree evidence:

ansight session list --app-id com.example.app
ansight session show <session-id>
ansight session touches <session-id>
ansight session trees <session-id>

Choose the start and end of the behavior as seconds after session start, or use ISO-8601 timestamps from the captured evidence. Then extract it into the current workspace:

ansight task extract <session-id> \
  --start 12.5 \
  --end 24.8 \
  --workspace . \
  --title "Complete checkout"

Ansight segments recorded touches, converts taps with stable visual-tree targets and directional swipes into task actions, and writes the draft beneath ansight/tasks/. Review every REVIEW: comment, establish the task’s required starting state, and replace the generated UI-stability check with a meaningful product outcome assertion before relying on it. Long presses, multi-touch, and taps without a stable selector require manual authoring.

Validate and exercise the draft against a connected development build:

npx tsc -p ansight/tasks/tsconfig.json
ansight task run <generated-task-id> \
  --app-id com.example.app \
  --repository .

See Extract a task from a session for selection, output, and overwrite options.

5. Add deterministic or automatic behavior

Create a task when the exact steps and proof are already known:

ansight workspace add task . home.verify \
  --app-id com.example.app \
  --title "Verify signed-in home"

Create a trigger when a matching event should start work automatically:

ansight workspace add trigger . diagnostics.capture-errors \
  --app-id com.example.app \
  --event-kind session.log.received

Triggers are primarily session-enrichment hooks. At a meaningful event they can request one bounded app action—typically an app-owned artifact snapshot—so the replay timeline preserves hidden state alongside screenshots, touches, logs, and telemetry. For example, capture a database snapshot after a migration or the current map annotations and viewport after a route changes. A human or agent can then inspect how that state evolved during the session instead of inferring it from the final screen alone.

Tasks and triggers are trusted local TypeScript. Review them like application code before running a task or connecting triggers.

6. Validate before committing

Check JSON definitions and cross-file references through the host:

ansight test validate .

Check TypeScript modules without emitting JavaScript:

npx tsc -p ansight/tasks/tsconfig.json
npx tsc -p ansight/triggers/tsconfig.json
npx tsc -p ansight/sanitizers/tsconfig.json

Commit the ansight/ directory to source control. Keep only secret aliases in test JSON; store values in Studio’s credential vault or the CLI secret store, or provide them through environment variables named for their aliases at run time.

Explore each feature