Skip to navigation
Schemas

startSurface

Referenced In

Fields

FieldTypeDescriptionDefault
startSurfaceone of:
- object(App descriptor)
- object(Browser descriptor)
- object(Process descriptor)
- array of one of: object(App descriptor), object(Browser descriptor), object(Process descriptor)		Required. Open (provision) one or more surfaces and register them by name so later steps can target them with surface. Three kinds: a native APP (Windows/macOS desktop by executable path, .app path, bundle ID, or UWP AppUserModelID; Android/iOS apps on managed emulators/simulators — macOS desktop additionally requires the Accessibility permission for the process that runs Doc Detective), a BROWSER session (opens blank and ready on the context’s automation server; navigate it with a goTo step), or a background PROCESS (equivalent to runShell with background — both forms stay valid). An ARRAY of descriptors opens them all concurrently — the step completes when every one is ready, and device boots overlap. See docs/design/multi-surface-targeting.md and docs/design/native-app-surfaces.md.—

Examples

{
  "startSurface": {
    "app": "C:\\Windows\\System32\\notepad.exe"
  }
}
{
  "startSurface": {
    "app": "Microsoft.WindowsCalculator_8wekyb3d8bbwe!App",
    "name": "calc"
  }
}
{
  "startSurface": {
    "app": "/Applications/Calculator.app",
    "name": "calc",
    "args": [
      "--reset"
    ],
    "waitUntil": {
      "delayMs": 500
    },
    "timeout": 30000
  }
}
{
  "startSurface": {
    "app": "com.example.myapp",
    "install": "./build/MyApp.apk",
    "device": {
      "platform": "android",
      "name": "Pixel_7"
    }
  }
}
{
  "startSurface": {
    "browser": "firefox",
    "name": "admin",
    "headless": true,
    "size": {
      "width": 1366,
      "height": 768
    }
  }
}
{
  "startSurface": {
    "process": "node server.js",
    "name": "api",
    "waitUntil": {
      "httpGet": "http://localhost:8080"
    },
    "timeout": 30000
  }
}
{
  "startSurface": [
    {
      "browser": "chrome",
      "name": "web"
    },
    {
      "process": "node server.js",
      "name": "api",
      "waitUntil": {
        "port": 8080
      }
    }
  ]
}
{
  "startSurface": [
    {
      "app": "com.example.chat",
      "name": "alice",
      "device": {
        "platform": "android",
        "name": "Pixel_7"
      }
    },
    {
      "app": "com.example.chat",
      "name": "bob",
      "device": {
        "platform": "android",
        "name": "Pixel_7_second"
      }
    }
  ]
}