BrowserFlagsConfiguration

Here is an example of the browser flags format, which is a simple JSON format.

[
  {
    "browserName": "Safari",
    "minVersion": "11",
    "flags": [
      "My custom flag",
      "Different flag"
    ]
  }
]

A single flags definition file may contain many elements, like the one shown above. The flags mechanism, when used from a Web Driver Factory, will detect the identification of the browser and sign the appropriate flags matching:

• The browser name (or names)
• A minimum and/or maximum version
• An OS platform

More information is available by reading the documentation comments upon the FlagsDefinition type.

Best practices for using flags

Where possible, make flags additive only

It is possible to write a JSON browser flags definition which removes flags from a browser. This functionality is provided for edge-cases such as when a buggy browser version lacks a feature which other versions 'either side' do support.

When designing your flags and definitions, by far the clearest way is to make them additive. This avoids developers needing to understand complex add-then-remove combinations.

Flags should be feature-detection, not browser-detection

Flags should be named based upon single features which behave differently across browsers. Their names should be specific, not general; avoid the temptation to re-use flags. Flags are cheap, create as many as you need.

Do not duplicate Capabilities

WebDriver has a built-in mechanism named Capabilities. Do not use flags to duplicate any of these broad API-capability indicators. Flags are intended to supplement capabilities in order to indicate subtle functional differences between browsers which would have the same 'capabilities' sets.

Flags were conceived because many implementations of IHasCapabilities will raise an exception if a developer attempts to add arbitrary capabilities which are not directly supported by the underlying WebDriver.

Good names for flags

A good naming convention for browser flags is to indicate when a browser requires a certain treatment for a specific feature; use flags to indicate the exceptions from the norm. An example of a naming convention along these lines is:

RequiresXyzForAbc

In this example Xyz is the specific treatment that the browser requires. Abc indicates the feature which is being used. Looking at the example for IE and Chrome's differences with date input fields, you can see that the flags there have been named using this format.

Another useful naming convention is to indicate when a browser cannot do something which most other browsers can do. In this case a simpler format along the following lines will help.

CannotXyz

An example of where the is useful applies to Microsoft Edge. As recently as version 15, the Edge browser is incapable of clearing domain cookies programatically (the WebDriver raises an exception if you try). Most other browsers, on the other hand, can do thiss. In cases like this, WebDriver logic may use the flag to discern that it must not attempt the operation using the WebDriver.