Keep app checks and automation in source control

Save the workflows and checks your team relies on so people and agents can run them again as the app changes. An Ansight workspace keeps tests, tasks, triggers, Trends rules, and privacy filters in a source-controlled ansight/ folder, where you can review and version them together.

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.

Start with one test. This quickstart takes you from an empty workspace to a user journey you can run again. Have an installed development build ready first; Getting Started covers SDK setup and External App Monitoring covers iOS simulators, Android emulators, and explicitly selected physical phones without the SDK. The test runner can launch an installed app, but it does not build it.

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, enables its repository automation connection, and enables automatic Trends analysis when a matching session is finalized. Review trigger code before registering an existing workspace. Use --no-register when you only want to scaffold the files.

Initialization creates the ansight/ folders, starter READMEs, and editor support files while preserving existing customizations. See Tooling and Validation for the full layout, editor setup, and intentional replacement of generated files.

2. Create a first test

Find the app’s bundle or package ID with ansight app list, then create a small observable scenario. Use your App ID and a journey that your development build can complete:

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"

3. Validate and run the test

Check the definition, then run it against the app:

ansight test validate .
ansight test run . onboarding.smoke

For an app without the SDK, choose device mode and its virtual device:

ansight test run . onboarding.smoke --execution-mode device \
  --platform ios --device-id <simulator-udid>

For an existing monitored capture, use --session-id <live-session-id> instead; its capture source determines the mode. See tests without the SDK for session reuse and capability limits. Workspace tasks and triggers that run without an SDK use descriptor version 2 with explicit requirements.

Review the result and captured evidence in the local player’s Tests area. If the run fails, use that evidence to check the app’s starting state and the test’s expected outcome. When it passes, you have your first reusable check; commit the definition so your team and agents can run it again.

Virtual-device windows open by default. See headless test runs when a local or CI run should not open them.

Optional next steps

Add another definition when it solves a problem you have. The first test does not require tasks, triggers, or Trends rules.

Extract a task from recorded behavior

Turn a useful interval from a recorded session into a task draft you can run again. Review the generated steps, establish the required starting state, and add an assertion for the product outcome before relying on it. Follow Extract a task from a session for the commands, supported interactions, and validation steps.

Add deterministic or automatic behavior

Write a task when you know the exact steps and checks to repeat. Add a trigger when an event should capture extra app data, such as a database snapshot after a migration or map state after a route changes. Tasks and triggers are trusted local TypeScript; review them like application code before running or connecting them.

Validate before committing

As you add definitions, run ansight test validate . to check YAML tests and cross-file references. For TypeScript modules, use the type checks and validation commands before committing changes. Keep only secret aliases in test definitions; store values in the host credential store or CLI secret store, or supply them through environment variables named for their aliases at run time.

Export and import a workspace ZIP

Export the workspace linked to a registered App ID:

ansight workspace export --app-id com.example.app --output workspace.zip

Use ansight workspace list to find registered apps with linked workspaces. Export by App ID requires a linked codebase; link an existing workspace with ansight app register com.example.app --codebase ./my-project if needed.

You can also export a workspace by its repository path:

ansight workspace export ./my-project --output workspace.zip
ansight workspace import workspace.zip ./another-project

The ZIP contains the ansight/ directory, including definitions, supporting modules, schemas, READMEs, and fixtures. .git, node_modules, and .DS_Store are excluded. Export requires either a workspace path or --app-id, and the output ZIP must be outside that workspace’s ansight/ directory. Host secrets, app registrations, and session history are stored separately and are not included. Custom files inside ansight/ retain their contents.

Import validates the archive and decompresses its files before updating the destination. ZIP entries must be rooted under ansight/; links, unsafe or duplicate paths, corrupt entries, and archives exceeding 100,000 entries (including parent directories) or 2 GiB expanded are rejected. Export uses the same limits. An existing output ZIP or conflicting destination file requires --force (--overwrite is an alias). Import preserves destination files absent from the archive. Add --json for paths, file counts, and expanded size in the ansight.workspace-archive/v1 result.

On Unix systems, regular file permissions, including executable bits, are preserved without setuid, setgid, or sticky bits. If a filesystem error interrupts an import, Ansight attempts to restore replaced files and remove newly imported files. If rollback also fails, the error identifies the retained recovery files.

ZIP validation checks archive structure and integrity. After importing, run ansight test validate ./another-project and the relevant TypeScript checks to validate the workspace definitions themselves.

Import does not execute or register the workspace. After reviewing the imported definitions, link the destination to its app separately:

ansight app register com.example.app --codebase ./another-project

Explore each feature