This site uses cookies for analytics. By continuing to browse this site, you agree to this use.
A JS Foundation Project

Connectors

Connectors

A connector is the interface between the hints and the website you are testing. It is responsible for loading the website and exposing all the information to webhint such as resources, network data, etc.

To configure a connector you need to update your .hintrc file to make it look like the following:

{
"connector": {
"name": "connectorName"
}
}

Where connectorName is the name of the connector.

Built-in connectors and platform support

All the built-in connectors run in any of the supported platforms: Linux, macOS, and Windows. The only caveat is that, for the connector that you specify in the.hintrc file, you will need to have the browser the connector is for installed as webhint will not install it for you.

The current supported connectors are:

  • jsdom: Your website will be loaded using jsdom.
  • chrome: Your website will be loaded using Chrome and the Chrome Debugging Protocol. This is one of the remote-debugging-connectors
  • edge: Your website will be loaded using Edge via the edge-diagnostics-adapter. You will need to run Windows 10 Creators Update or later to use it. This connector will only be installed if you are running on it. There are some known issues so please check the Edge issues section below.
  • local: This connector will analyze the files specified (a file or a directory).

Note: If you are running Windows 10 build 14951 (or later) and Windows Subsystem for Linux (WSL), webhint will be capable of running the browsers installed directly on Windows. If you are a user of the stable release of Window, you will need to use at least the Fall Creators Update.

Configuration

connectors can be configured. Maybe you want to do a request with another userAgent, change some of the other defaults, etc. For that, you have to add the property options to your connector property with the values you want to modify:

"connector": {
"name": "connectorName",
"options": {}
}

The following is the list of shared configurations for all connectors:

  • waitFor time in milliseconds the connector will wait after the site is ready before starting the DOM traversing and stop listening to any network request. By default, it will wait until the network is somehow “quiet” even though more requests could be processed after DOM traversing.

Depending on the connector, other configurations may be available.

jsdom configuration

jsdom allows you to configure the following:

  • headers: the headers used to fetch the resources. By default they are:
 {
"Accept-Language": "en-US,en;q=0.8,es;q=0.6,fr;q=0.4",
"Cache-Control": "no-cache",
"DNT": 1,
"Pragma": "no-cache",
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/68.0.3440.106 Safari/537.36"
}

remote-debugging-connector configuration

There are some connectors built on top of the Chrome DevTools Protocol. chrome and edge are some of these connectors.

The set of settings specific for them are:

  • defaultProfile (boolean): Indicates if the browser should use the default profile or create a new one. By default the value is false so a new one is created. You might want to set it to true if you want webhint to have access to pages where the default profile is already authenticated. This only applies for Google Chrome as Microsoft Edge doesn’t create a new profile.
  • useTabUrl (boolean): Indicates if the browser should navigate first to a given page before going to the final target. false by default.
  • tabUrl (string): The URL to visit before the final target in case useTabUrl is true. https://empty.webhint.io/ is the default value.
  • flags? (Array<string>): Allows you to pass in additional Chrome command line API flags. Useful if you would like to start your session in headless mode or with GPU disabled. Here’s the full list of [available command line flags][cli flags].
  • waitForContentLoaded (number): Time in milliseconds to wait for the loadingFinished event from the debugging protocol before requesting the body of a response. The default value is 10000 (10 seconds).
{
"defaultProfile": true,
"flags": ["--headless", "--disable-gpu"],
"tabUrl": "https://empty.webhint.io/",
"useTabUrl": false,
"waitForContentLoaded": 10000
}

local configuration

local allows you to configure the following:

  • pattern: Add or ignore files defined in the pattern. By default the local connector will use the following patter ['**', '!.git/**']. This doesn’t apply if you are targeting just a file or if you are using the options content.
  • watch: Run webhint in watch mode. Watch files and trigger the analysis on changes.
{
"pattern": ["**", "!.git/**"],
"watch": false
}

In addition, the local connector accept a new parameter in the method collect that allow you to pass the content to analyze as an string. To use that property, you need to call to the executeOn method in the engine with the content to analyze.

engine.executeOn(url, {content: '{{your content}}'});

Differences among connectors

Connectors are expected to implement at least some basic functionality (see how to develop a connector) but expose more events or have some extra functionality. The following document details the known differences or issues among the official connectors.

Edge

  • You need administrator privileges to run webhint on Edge. You should be automatically prompted when running it.
  • It’s best to close all instances of Edge before to avoid any issues.
  • The current implementation can have some problems when scanning multiple sites simultaneously. This should not be a common scenario.
  • The connector will make use of the useTabUrl and tabUrl properties. Removing those can cause unexpected results.

jsdom

  • It will not send the events for:

    • element::#document
    • element::#comment