Skip to main content
A context defines the environment 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.

Schema Reference

$schema
string
JSON Schema reference for this object.Value: https://raw.githubusercontent.com/doc-detective/common/refs/heads/main/dist/schemas/context_v3.schema.json
contextId
string
Unique identifier for the context. Auto-generated if not provided.

Platform Configuration

platforms
string | string[]
Platforms to run tests on.Options: linux, mac, windows

Browser Configuration

browsers
string | object | array
Browsers to run tests on. Can be a simple string, a detailed configuration object, or an array of either.Browser names: chrome, firefox, safari, webkit
safari is just a shortcut for webkit. Both values are supported for clarity.

Simple String

"browsers": "chrome"

Browser Object

Array of Browsers

"browsers": ["chrome", "firefox", "webkit"]

Examples

Single Platform and Browser

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

Multiple Platforms and Browsers

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

Browser with Headless Mode

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

Multiple Browser Configurations

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

Browser with Window and Viewport Dimensions

{
  "platforms": ["mac", "linux"],
  "browsers": {
    "name": "chrome",
    "headless": true,
    "window": {
      "width": 1920,
      "height": 1080
    },
    "viewport": {
      "width": 1600,
      "height": 900
    }
  }
}

Complete Multi-Configuration Example

{
  "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
      }
    }
  ]
}

Safari on macOS

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

Usage in Configuration

Contexts can be specified at multiple levels:

Config Level

Applies to all tests:
{
  "runOn": [
    {
      "platforms": "linux",
      "browsers": "chrome"
    }
  ]
}

Test Level

Overrides config-level contexts for a specific test:
{
  "testId": "my-test",
  "runOn": [
    {
      "platforms": ["mac", "windows"],
      "browsers": "firefox"
    }
  ],
  "steps": [...]
}

Build docs developers (and LLMs) love