Skip to main content
Contexts define the environment(s) in which your tests run. A context specifies platform and browser combinations, allowing you to test your documentation across different operating systems and browsers.

​
What are Contexts?

A context is a combination of:
  • Platforms: Operating systems (Linux, macOS, Windows)
  • Browsers: Web browsers (Chrome, Firefox, Safari, WebKit)
You can define contexts at three levels, each overriding the previous:
  1. Config level: Default contexts for all tests
  2. Spec level: Contexts for all tests in a specification
  3. Test level: Contexts for a specific test
If no contexts are specified but a test requires a browser, Doc Detective will automatically detect and use an available browser in your current environment.

​
Basic Context Structure

{
  "contexts": [
    {
      "platforms": ["linux", "mac", "windows"],
      "browsers": ["firefox"]
    }
  ]
}
This creates three contexts:
  • Firefox on Linux
  • Firefox on macOS
  • Firefox on Windows
Each test will run three times, once in each context.

​
Platform Options

Doc Detective supports three platform values:
  • linux: Linux distributions
  • mac: macOS (also supports Darwin)
  • windows: Windows operating systems

​
Platform-Only Contexts

You can specify platforms without browsers for tests that don’t require browser automation: 
{
  "contexts": [
    {
      "platforms": ["linux"]
    }
  ],
  "tests": [
    {
      "steps": [
        {
          "action": "runShell",
          "command": "docker run hello-world",
          "stdio": "Hello from Docker!"
        }
      ]
    }
  ]
}

​
Browser Options

Doc Detective supports four browsers:
  • chrome: Google Chrome
  • firefox: Mozilla Firefox
  • safari: Apple Safari (macOS only)
  • webkit: WebKit browser engine

​
Simple Browser Configuration

Specify browsers as strings: 
{
  "contexts": [
    {
      "platforms": ["mac"],
      "browsers": ["chrome", "firefox", "safari"]
    }
  ]
}

​
Advanced Browser Configuration

For more control, use browser objects: 
{
  "contexts": [
    {
      "platforms": ["linux"],
      "browsers": [
        {
          "name": "firefox",
          "headless": true,
          "window": {
            "width": 1920,
            "height": 1080
          },
          "viewport": {
            "width": 1920,
            "height": 1080
          }
        }
      ]
    }
  ]
}

​
Browser Configuration Options

​
name
string
required
Browser name: chrome, firefox, safari, or webkit
​
headless
boolean
default:"false"
If true, runs the browser in headless mode (no visible window)
​
window
object
Browser window dimensions
​
viewport
object
Browser viewport dimensions

​
Context Hierarchy

Contexts can be defined at multiple levels. More specific definitions override more general ones.

​
Config-Level Contexts

Define default contexts in your .doc-detective.json configuration file:
.doc-detective.json
{
  "contexts": [
    {
      "platforms": ["windows", "mac", "linux"],
      "browsers": [
        {
          "name": "firefox",
          "headless": false
        }
      ]
    }
  ]
}
All tests will use these contexts unless overridden.

​
Spec-Level Contexts

Override config contexts for all tests in a specification:
tests.spec.json
{
  "contexts": [
    {
      "platforms": ["mac"],
      "browsers": ["safari"]
    }
  ],
  "tests": [
    // All tests in this spec run on Safari for macOS only
  ]
}

​
Test-Level Contexts

Override contexts for a specific test: 
{
  "tests": [
    {
      "testId": "windows-only-feature",
      "contexts": [
        {
          "platforms": ["windows"],
          "browsers": ["chrome"]
        }
      ],
      "steps": [
        // This test only runs on Chrome for Windows
      ]
    }
  ]
}

​
Multiple Contexts

You can specify multiple context objects to create different combinations: 
{
  "contexts": [
    {
      "platforms": ["windows", "linux"],
      "browsers": ["chrome"]
    },
    {
      "platforms": ["mac"],
      "browsers": ["safari"]
    }
  ]
}
This creates three contexts:
  • Chrome on Windows
  • Chrome on Linux
  • Safari on macOS

​
Real-World Examples

​
Cross-Browser Testing

Test your documentation across all major browsers on Linux: 
{
  "contexts": [
    {
      "platforms": ["linux"],
      "browsers": ["chrome", "firefox"]
    }
  ],
  "tests": [
    {
      "steps": [
        {
          "action": "goTo",
          "url": "https://docs.example.com"
        },
        {
          "action": "find",
          "selector": ".main-navigation"
        }
      ]
    }
  ]
}

​
Headless CI/CD Testing

Run tests in headless mode for faster CI/CD execution: 
{
  "contexts": [
    {
      "platforms": ["linux"],
      "browsers": [
        {
          "name": "firefox",
          "headless": true
        }
      ]
    }
  ]
}

​
Responsive Design Testing

Test different viewport sizes: 
{
  "contexts": [
    {
      "platforms": ["linux"],
      "browsers": [
        {
          "name": "chrome",
          "viewport": {
            "width": 375,
            "height": 667
          }
        },
        {
          "name": "chrome",
          "viewport": {
            "width": 1920,
            "height": 1080
          }
        }
      ]
    }
  ]
}

​
Platform-Specific Features

Test platform-specific commands: 
{
  "tests": [
    {
      "testId": "windows-powershell",
      "contexts": [
        {
          "platforms": ["windows"]
        }
      ],
      "steps": [
        {
          "action": "runShell",
          "command": "Get-Process"
        }
      ]
    },
    {
      "testId": "unix-bash",
      "contexts": [
        {
          "platforms": ["linux", "mac"]
        }
      ],
      "steps": [
        {
          "action": "runShell",
          "command": "ps aux"
        }
      ]
    }
  ]
}

​
Context Resolution

When Doc Detective resolves contexts:
  1. Starts with config-level contexts
  2. Overrides with spec-level contexts if present
  3. Overrides with test-level contexts if present
  4. If no contexts are defined but a browser is needed, auto-detects available browser
The resolved contexts are stored in the contexts property of each test result. This shows exactly which contexts were used for test execution.

​
Best Practices

Define your most common testing environment in your config file. This reduces duplication across test files.
.doc-detective.json
{
  "contexts": [
    {
      "platforms": ["linux"],
      "browsers": ["firefox"]
    }
  ]
}
Use headless browsers in automated environments for faster execution and lower resource usage.
{
  "contexts": [
    {
      "platforms": ["linux"],
      "browsers": [
        {
          "name": "firefox",
          "headless": true
        }
      ]
    }
  ]
}
Use test-level contexts to isolate platform-specific tests. This prevents failures on unsupported platforms.
Prioritize testing on platforms and browsers your users actually use. You don’t need to test every combination.
Safari is only available on macOS. Attempting to run Safari tests on other platforms will result in errors.

​
Next Steps

Tests

Learn about test specifications, tests, and steps

Configuration

Configure contexts and other options

Contexts Guide

Detailed guide on working with contexts

CI/CD Integration

Set up Doc Detective in your CI/CD pipeline

Build docs developers (and LLMs) love

Get started for freeTalk to us