context | Doc Detective

A context in which to perform tests. If no contexts are specified but a context is required by one or more tests, Doc Detective attempts to identify a supported context in the current environment and run tests against it. For example, if a browser isn’t specified but is required by steps in the test, Doc Detective will search for and use a supported browser available in the current environment.

Referenced In

Fields

Field	Type	Description	Default
$schema	string	Optional. JSON Schema for this object. Accepted values: `https://raw.githubusercontent.com/doc-detective/common/refs/heads/main/dist/schemas/context_v3.schema.json`	—
contextId	string	Optional. Unique identifier for the context.	—
platforms	one of: - string - array of string	Optional. Platforms to run tests on.	—
browsers	one of: - string - object(Browser) - array of one of: string, object(Browser)	Optional. Browsers to run tests on. On a mobile (`android`/`ios`) platform entry, the browser runs on the managed device: `chrome` on Android, `safari` on iOS (other combinations skip the context), and it fills in automatically when omitted. Device browsers don’t take desktop display config: authored `window`/`viewport` dimensions and `headless: false` are rejected on mobile entries (the device owns its display — control it via the device descriptor’s `headless`/`deviceType`); `headless: true` matches this schema’s default and is ignored.	—
browserFallback	string	Optional. Per-context override for the config-level `browserFallback` policy that governs whether a context whose browser can’t start a driver session falls back to another available browser. Accepts the same values — `auto`, `explicit`, `off` — and, when set, takes precedence over the config-level value for the contexts this entry expands into. Omit it to inherit the config-level policy (which itself defaults to `auto`). Accepted values: `auto`, `explicit`, `off`	—
retries	integer	Optional. Per-context override for the config-level `retries` policy — how many times to re-run this context on a fresh session when its session turns out to be unusable mid-run. When set, takes precedence over the config-level value for the contexts this entry expands into. Omit it to inherit the config-level policy (which defaults to `1`). Set to `0` to disable retries for this context. Minimum: 0. Maximum: 10	—
requires	one of: - string - array of string - object(Requirements)	Optional. Capabilities the environment must provide for this context to run. A string names a required command; an array names several; the object form checks commands (on PATH), files (paths, with `$VAR`/`$HOME` expansion), and environment variables. All entries are AND-ed. Any unmet requirement marks the context as SKIPPED — the same non-failing outcome as a `platforms` mismatch.	—
device	one of: - string - object(Device descriptor)	Optional. Default device for a mobile (`android`/`ios`) context. A string references a device by name; an object refines it. The `platform` is implied by the context, so it is not required here. When the named device doesn’t already exist, Doc Detective creates it with defaults (see `deviceType`/`osVersion`), provided the toolchain is installed (`doc-detective install android` or `doc-detective install ios`). Same shape as `startSurface.device`.	—

Examples

{
  "platforms": "linux",
  "browsers": "chrome"
}

{
  "platforms": [
    "windows",
    "mac",
    "linux"
  ],
  "browsers": [
    "chrome",
    "firefox",
    "webkit"
  ]
}

{
  "browsers": {
    "name": "chrome",
    "headless": true
  }
}

{
  "browsers": [
    {
      "name": "chrome",
      "headless": true
    },
    {
      "name": "firefox"
    }
  ]
}

{
  "platforms": [
    "mac",
    "linux"
  ],
  "browsers": {
    "name": "chrome",
    "headless": true
  }
}

{
  "platforms": [
    "windows",
    "mac",
    "linux"
  ],
  "browsers": [
    {
      "name": "chrome",
      "headless": true,
      "window": {
        "width": 1920,
        "height": 1080
      },
      "viewport": {
        "width": 1600,
        "height": 900
      }
    },
    {
      "name": "firefox",
      "window": {
        "width": 1366,
        "height": 768
      }
    },
    {
      "name": "webkit",
      "headless": false,
      "viewport": {
        "width": 1440,
        "height": 900
      }
    }
  ]
}

{
  "platforms": "mac",
  "browsers": [
    {
      "name": "safari",
      "window": {
        "width": 1280,
        "height": 800
      }
    }
  ]
}

{
  "platforms": "android"
}

{
  "platforms": [
    "windows",
    "mac",
    "android",
    "ios"
  ],
  "browsers": "chrome"
}

{
  "platforms": "ios",
  "browsers": "safari",
  "device": {
    "name": "test-iphone",
    "deviceType": "phone"
  }
}