Last updated: 20 Apr 2023

TbUtil plugin for driving a headless Chrome instance. It exposes a subset of the functions available in the GOLang module "chromedp".

The plugin is designed to support features for driving the Turbonomic UI and extract information from it, but it can be used to control other web applications with care.

This document does not attempt to describe the underlying module itself but details the exposed features and nuances introduced by the plugin. The main differences lie in the fact that the plugin is used in JavaScript scripts whereas the module is written for GOLang.

var p = plugin("chromedp-plugin");
p.open(width, height [, client]);
p.verbose(boolean_flag);

The plugin function is used to load the plugin and return an object reference from which its methods can be accessed.

The open method must be the first to be called after loading the plugin, and defines the dimensions of the virtual screen used by the headless chrome instance and (optionally) the credentials to be used. The width and height must be specified in pixels. If the client argument is used it can either be the client handle for an instance or a string starting with "@" (in which case the client described in the tbutil credential store with that key is used). This allows the sendKeys function to send the user name or password configured for the client.

The verbose method is optional and sets the level of verbosity. If the flag is set to true then all plugin methods, URLs visited and console output is printed to the standard error file handle.

If the env variable CHROMEDP_SHOW_TIMES is set to true (and verbose is true), then action timing information will be output to stderr.

Many of the methods use a selector and an options list. The options are specified as an array of strings and indicate how the selector is to be interpreted. The table below lists the supported options, the equivalent GOLang option (which you should refer to for detailed documentation) and comments about plugin-specific nuances.

Note: you should only specify ONE of the "by..."" options. "ByQueryAll" is the default (NB: this is different from the GO library which uses "BySearch" as the default).

In addition to the selector options described above, you can also specify options to indicate what state should be waited for before returning. The table below lists these and the equivalent GOLang option (which you should refer to for detailed documentation)..

Note: you should only specify ONE of the "node..." options. "NodeReady" is the default.

The atLeast method returns an option that causes at least the specified number of nodes to be matched. Not specifiying this is equivalent to setting it to 1. Note that a value of 0 is allowed, and will match even if no nodes are found.

Example:

var headers = p.nodes("h1", [ "byQueryAll", p.atLeast(2) ]);

The "cacheNodes" option is a string that tells the nodes function to cache the matching nodes so that they can be used in the fromNode function in a subsequent call.

The fromNode function returns an option to start the query from the specified root. Note that this does not work with all match types and is usually best used with "byQuery" or "byQueryAll" options.

Example:

var tables = p.nodes("table", [ "byQueryAll", "cacheNodes" ]);
var table1rows = p.nodes("tr", [ "byQueryAll", p.fromNode(tables[0].nodeID) ]);

A call to nodes with no cacheNodes option clears the cache. Calls with the cacheNodes option set augments any existing cache with the newly mached node details. Other plugin methods (such as get dont change the cache contents).

The plugin exposes the following methods to the script. These should be called using the syntax..

p.methodName(arguments);

where p is the reference returned by the plugin function - as above.

If name is null, then a map of all attributes is returned, otherwise just the named attribute.

An element query action that unfocuses (blurs) the first element node matching the selector.

Equilvant to the GOLang Blur function.

Executes the jsFunction (must be a JS function), passing the jsArgs to it. The selection and options identify a DOM object that will be the "this" for the function call.

The function must include a return value (which cannot be null or undefined).

Example:

var rtn = p.callFunction("html", "function (mesg) { console.log(mesg); return true; }", [ "hello world"]);

This resolves to the GOLang CallFunctionOn function.

If the function has a name, then that name will be included in the verbose output message (if verbose mode is enabled). For example:

function waiting() { .... }

An element query action that clears the values of any input/textarea element nodes matching the selector.

Equilvant to the GOLang Clear function.

Equivalent to the GLang "Click" or "DoubleClick" function (depending on the value of the doubleClick boolean).

Example:

p.click("button", [], false);

An element query action that focuses the first element node matching the selector.

Equilvant to the GOLang Focus function.

Allows a number of different data about a node to be returned. The value of what selects the data type as follows..

Example:

var pageTitle = p.get("head title", "innerHtml");

This is not a standard chromedp method.

This function configures the plugin to ignore any warning or error messages written to the chrome console that match the regex pattern specified. Each call to this function appends to the list of ignored messages unless the pattern argument is omitted (or contains an empty string) in which case the list is wiped.

An element query action that retrieves the Javascript attribute for the first element node matching the selector.

Equivalent to the GOLang "JavascriptAttribute function.

Eqivalent to the GOLang method "Navigate"

Example:

p.navigate("https://10.11.12.13/");

The following additional special url strings are handled..

If logPatternSpec is specified, it provides a set of rules used to inspect the log strings printed by the page to help determine whether the page has finished loading. Each rule consists of a pattern and a flag which are used by the waitQuiet method to set it's internal logCompleted flag. The following example works for many Turbonomic UI pages..

p.navigate(url, [
   { pattern: "^INFO: => Event took [0-9.]+ sec for [1-9][0-9]* API requests to complete", flag: true },
   { pattern: "^REQUEST\\(\\d+\\): [A-Z]+ https://[^/]+/api/v\\d+/", flag: false }
]);

See waitComplete for more details of how the logPatternSpec is used.

If the environment variable CHROMEDP_DUMP_REQUESTS is set then all requests will be logged to the named file.

Equivalent to the GOLang "NodeIDs" function.

Returns a list of integer numbers.

Example:

var nodeIDList = p.nodeIDs("button");

Equivalent to the GOLang "Nodes" function.

Returns a list of cdp.Node objects, converted to a JavaScript object. This does not include any class functions or hidden fields.

Example:

var nodeList = p.nodes("input");

If the cacheNodes option is used, the returned nodes are cached by their nodeIDs in a lookup-table in the plugin for later use in the fromNode option. In this case, the existing cache is augmented with the newly identified nodes. If "cacheNodes" is not specified, then the cache is cleared.

Note: while the nodes function understands the cacheNodes option, other functions do not.

Prints the current screen to the specified PDF file using the browsers print-to-pdf feature. The config argument is a JS object with the following option fields..

Example:

p.printToPdf("page.pdf", { landscape: true, scale: 0.8 });

Eqivalent to the GOLang method "Query"

Example:

p.query(129, [ "byNodeID", "nodeVisible" ]);

An element query action that resets the parent form of the first element node matching the selector.

Equilvant to the GOLang Reset function.

Takes a screen-shot of part (or all) of the screen.

If a selector (and, optionally, a list of options) is specified then this function writes a screen-shot of the first of the selected elements to the specified file.

If no selector or options are specified then a screen-shot of the visible screen is written to the file.

The fileName must have an extension of ".png".

Example:

p.screenShot("widget.png", widget.nodeId, [ "byNodeID" ]);

An element query action that scrolls the window to the first element node matching the selector.

Equilvant to the GOLang ScrollIntoView function.

Equivalent to the GOLang "SendKeys" function.

The keys parameter can be..

Examples:

p.sendKeys("#username", "administrator");
p.sendKeys("#username", 1);

The special case of numbers 1 or 2 will result in nothing being sent if the client argument was not specified in the open function.

If value is null then RemoveAttribute is called, otherwise SetAttributeValue

An element query action that sets the element attribute with name to value (or removes the attribute) for the first element node matching the selector or

Sets a cookie with the given cookie data; may overwrite equivalent cookies if they exist.

The cookieObject argument should contain the following fields:

• name
• value
• domain
• path
• duration
• httpOnly
• secure

Equilvant to the GOLang SetCookie function.

This is eqivalent to the GOLang code...

browser.SetDownloadBehavior(browser.SetDownloadBehaviorBehaviorAllowAndName).
	WithDownloadPath(directoryName).
	WithEventsEnabled(false)

An element query action that sets the Javascript attribute for the first element node matching the selector.

Equilvalent to the GOLang "SetJavascriptAttribute" function.

Equivalent to the GOLang Sleep function.

Example:

p.sleep(30);

An element query action that submits the parent form of the first element node matching the selector.

Equilvant to the GOLang Submit function.

The following GOLang Wait... methods are implemented..

Examples:

p.waitVisible("#username");
p.waitEnabled(129, [ "byNodeID" ]);

This is not a standard chromedp method.

This waits for all the requests to URLs on the navigated-to host to complete (for a maximum of num_seconds seconds).

The function returns true if a quiet state was arrived at within the specified number of seconds. Otherwise it returns false.

It works by:

• counting the number of http requests made and responses recieved since navigate was called.
• matching log messages against the logPatternSpec specified to the navigate function (if any) and noting the flag associated with the most recent matched message.
• monitoring the CPU usage (clock ticks) of the headless chrome browser (linux only) every second.

The page is deemed to be "quiet" when all the follow conditions remain true for 4 seconds.

• the number of responses received matches the number of requests made.
• the most recently matched log message has an associated flag of true.
• the number of CPU clock ticks consumed by the chrome browser process in the last second is zero (linux only).

The behaviour can be modified using environment variables: