App descriptor | Doc Detective

Referenced In

startSurface

Fields

Field	Type	Description	Default
app	string	Required. The app identifier: an executable path (`C:\\Windows\\System32\\notepad.exe`), a `.app` path, a bundle ID (`com.apple.TextEdit`), a package name (`com.example.myapp`), or a UWP AppUserModelID (`Microsoft.WindowsCalculator_8wekyb3d8bbwe!App`). Disambiguated by syntax — never by a type field. Minimum length: 1. Pattern: `\S`	—
name	string	Optional. Surface-registry name later steps use in `surface`. Default: the executable basename without extension, or the final dot-segment of an ID. Minimum length: 1. Pattern: `\S`	—
args	array of string	Optional. Launch arguments (desktop apps). On macOS they pass to the app as a real argument array. On Windows they join into a single shell-style argument string for the driver, so an argument with embedded spaces must carry its own quotes (e.g. ""My File.txt"").	—
workingDirectory	string	Optional. Working directory for the launched app. Not honored by the current desktop app drivers, so a non-default value fails with guidance: on Windows the NovaWindows driver ignores it (the app inherits the driver’s own working directory), and on macOS the driver launches apps through LaunchServices, which offers no working-directory control. Launch the app via runShell if the cwd matters. Reserved for when a driver gains support. Default: the run’s working directory. Minimum length: 1	`.`
env	object	Optional. Extra environment variables for the launched app (desktop apps). Supported on macOS; not supported by the Windows driver, where any value fails with guidance (set variables in the shell that launches Doc Detective instead).	—
install	string	Optional. Path to an installable artifact (`.apk`/`.app`/`.ipa`) to install on the device before launch. Supported on Android and iOS app surfaces. Minimum length: 1	—
activity	string	Optional. Android main activity override (defaults to the package’s launcher activity). Android-only. Minimum length: 1	—
device	one of: - string - object(Device descriptor)	Optional. Device the app runs on. Omit for a host desktop app, or (in a mobile context) to use the context’s default device. A string references a device by name; an object refines it. Supported on Android and iOS mobile targets.	—
driverOptions	object	Optional. Escape-hatch passthrough: merged into the automation session’s capabilities after the ones Doc Detective computes (namespaced per driver, e.g. `appium:noReset`). Driver- and version-specific; use sparingly.	—
waitUntil	object(App readiness)	Optional. Startup readiness: a fixed delay and/or an element that must exist before the surface is considered open. No condition applies by default.	—
timeout	integer	Optional. Startup ceiling in milliseconds (launch + install + readiness). Minimum: 0	`60000`

Examples

{
  "app": "example",
  "name": "example",
  "args": [],
  "workingDirectory": ".",
  "env": {},
  "install": "example",
  "activity": "example",
  "device": "example",
  "driverOptions": {},
  "waitUntil": {
    "delayMs": 42
  },
  "timeout": 60000
}