Contexts

Doc Detective uses contexts to determine which tests to run. A context is a set of conditions that must be met in order for a test to run. For example, a context might specify that a test should only run in Safari on macOS.

By default, Doc Detective runs tests in Chrome on Windows, macOS, and Linux. You can specify custom contexts to run tests in other apps.

Each context is name up of an app object and a platforms array. When Doc Detective runs tests, it checks the associated contexts to see if the app is available and if it’s running on a specified platform. If the conditions are met, the test runs in that context. You can specify multiple contexts for a test, and Doc Detective will run the test in each context that is met.

For comprehensive options, see the context reference.

Specifying contexts

You can specify contexts at three different levels, in order of precedence:

• Config: You can specify contexts in the config object. These contexts apply to all tests in the suite.
• Spec: You can specify contexts in a specification object. These contexts override config-level contexts and apply to all tests in the spec.
• Test: You can specify contexts in a test object. These contexts override config- and spec-level contexts and apply only to that test.

When you specify contexts, you use a contexts array. For example, the following JSON specifies three contexts:

{
  ...
  "contexts": [
    {
      "app": {
        "name": "chrome"
      },
      "platforms": ["windows","mac","linux"]
    },
    {
      "app": {
        "firefox"
      },
      "platforms": ["windows","mac","linux"]
    },
    {
      "app": {
        "name": "safari"
      },
      "platforms": ["mac"]
    }
  ],
  ...
}

Apps

Doc Detective can perform tests on a variety of apps. The following apps are supported:

• Chrome (chrome)
• Firefox (firefox)
• Safari (safari)
• Edge (edge)

Chrome

Chrome is available on Windows, macOS, and Linux. Doc Detective manages and runs a Chrome instance internally, so you don’t need to install anything extra.

Chrome is the only browser that supports recording test runs with the startRecording action.

Here’s a basic Chrome context:

{
  "app": {
    "name": "chrome"
  },
  "platforms": ["windows","mac","linux"]
}

Dimensions and visibility

You can specify the browser dimensions and visibility (headless) during tests. headless must be false to record test runs.

{
  "app": {
    "name": "chrome",
    "options": {
      "width": 1024,
      "height": 768,
      "headless": false
    }
  },
  "platforms": ["windows","mac","linux"]
}

Custom path

You can specify a Chrome installation on your system if you want to use a specific version of Chrome or a Chromium derivative. If you specify a custom path, you must also specify a path to a matching ChromeDriver executable. For example:

{
  "app": {
    "name": "chrome",
    "options": {
      "path": "/path/to/chrome",
      "driverPath": "/path/to/chromedriver"
    }
  },
  "platforms": ["windows","mac","linux"]
}

Firefox

Firefox is available on Windows, macOS, and Linux. Doc Detective manages and runs a Firefox instance internally, so you don’t need to install anything extra.

Here’s a basic Firefox context:

{
  "app": {
    "name": "firefox"
  },
  "platforms": ["windows","mac","linux"]
}

Dimensions and visibility

You can specify the browser dimensions and visibility (headless) during tests.

{
  "app": {
    "name": "chrome",
    "options": {
      "width": 1024,
      "height": 768,
      "headless": false
    }
  },
  "platforms": ["windows","mac","linux"]
}

Custom path

You can specify a Firefox installation on your system if you want to use a specific version of Firefox or a Firefox derivative. For example:

{
  "app": {
    "name": "firefox",
    "options": {
      "path": "/path/to/firefox"
    }
  },
  "platforms": ["windows","mac","linux"]
}

Safari

Safari is only available on macOS. Doc Detective runs tests in a sandboxed instance of your local Safari browser.

Before you run tests on Safari, you need to enable SafariDriver with the following command in a terminal:

safaridriver --enable

Note: SafariDriver is enabled by default in GitHub Actions.

If Doc Detective isn’t running tests in Safari, make sure

• SafariDriver is enabled.
• the Enable automation option is selected the Safari’s Develop menu.

Dimensions

You can specify the browser dimensions during tests.

Note: Safari doesn’t support headless mode.

{
  "app": {
    "name": "safari",
    "options": {
      "width": 1024,
      "height": 768,
    }
  },
  "platforms": ["mac"]
}

Edge

Edge is available on Windows, macOS, and Linux. edge is installed by default on Windows, but you must manually install it on macOS and Linux. If Edge is installed, Doc Detective can automatically detect and run tests in your local installation.

Here’s a basic Edge context:

{
  "app": {
    "name": "edge"
  },
  "platforms": ["windows","mac","linux"]
}

Dimensions and visibility

You can specify the browser dimensions and visibility (headless) during tests.

{
  "app": {
    "name": "edge",
    "options": {
      "width": 1024,
      "height": 768,
      "headless": false
    }
  },
  "platforms": ["windows","mac","linux"]
}

Platforms

Doc Detective can perform tests on a variety of platforms. The following platforms are supported:

• Windows (windows)
• macOS (mac)
• Linux (tested on Ubuntu) (linux)

When you specify a platform for a context, Doc Detective attempts to run associated tests when the context is executed on that platform. If a platform isn’t specified, Doc Detective attempts to run the tests on all platforms.

For example, the following context specifies that tests should only run on macOS:

{
  "app": {
    "name": "chrome"
  },
  "platforms": ["mac"]
}

Examples

Contexts

Here are some examples of contexts:

• Run tests in Chrome on Windows, macOS, and Linux:

  {
    "app": {
      "name": "chrome"
    },
    "platforms": ["windows","mac","linux"]
  }
  

• Run tests in Firefox on Windows and macOS:

  {
    "app": {
      "name": "firefox"
    },
    "platforms": ["windows","mac"]
  }
  

• Run tests in Safari on macOS:

  {
    "app": {
      "name": "safari"
    },
    "platforms": ["mac"]
  }
  

• Run tests in Edge on Windows:

  {
    "app": {
      "name": "edge"
    },
    "platforms": ["windows"]
  }
  

In a config

You can specify contexts in the config object. These contexts apply to all tests in the suite.

• Run all tests in each of the apps that are available by default on each platform:

  {
    "input":".",
    "contexts": [
      {
        "app": {
          "name": "chrome"
        },
        "platforms": ["windows","mac","linux"]
      },
      {
        "app": {
          "name": "firefox"
        },
        "platforms": ["windows","mac","linux"]
      },
      {
        "app": {
          "name": "safari"
        },
        "platforms": ["mac"]
      },
      {
        "app": {
          "name": "edge"
        },
        "platforms": ["windows"]
      }
    ]
  }
  

In a specification

You can specify contexts in the specification object. These contexts override config-level contexts and apply to all tests in the spec.

This example runs all tests in the spec with Chrome on Windows and macOS:

{
  "contexts": [
    {
      "app": {
        "name": "chrome"
      },
      "platforms": ["windows","mac"]
    }
  ],
  "tests": [
    ...
  ]
}

In a test

You can specify contexts in the test object. These contexts override config- and spec-level contexts and apply only to that test.

This example runs a single test in Chrome on Windows:

{
  "name": "Spec name",
  "tests": [
    {
      "name": "Test name",
      "contexts": [
        {
          "app": {
            "name": "chrome"
          },
          "platforms": ["windows"]
        }
      ],
      "steps": [
        ...
      ]
    },
    {
      ...
    }
  ]
}