API Reference

$browser.actions().sendKeys("synthetic").perform();

Example 1: To click, use the following code:

const element = await $browser.waitForAndFindElement(by, timeout);
$browser.actions().move({origin: element}).press().release().perform();

Example 2: To hover the mouse on a browser element, use the following code:

const element = await $browser.waitForAndFindElement(by, timeout);
$browser.actions().move({origin: element, duration: 2000}).perform();

To be compatible with the old mouseMove function, use the following command:

$browser.actions().mouseMove(element).perform();

Example 3: To send keys, run the following code:

await $browser.get("http://www.bing.com");
await $browser.actions().sendKeys("synthetic").perform();

$browser.addHeader(key: string, val: string): Promise<void>;

await $browser.addHeader(
  "User-Agent",
  "Mozilla/5.0 (iPhone; CPU OS 10_15_5 (Ergänzendes Update) like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/12.1.1 Mobile/14E304 Safari/605.1.15"
);

await $browser.get("https://www.yahoo.com/");
await $browser.takeScreenshot();

await $browser.addHeader(
  "User-Agent",
  "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.16; rv:86.0) Gecko/20100101 Firefox/86.0"
);

await $browser.get("https://www.yahoo.com/");
await $browser.takeScreenshot();

$browser.addHeaders(headers: { [key: string]: string }): Promise<void>;

await $browser.addHeaders({
  key1: "val1",
  key2: "val2",
});

$browser.addHostnamesToDenylist(hostnameArr: string[]): Promise<void>

$browser.addHostnamesToBlacklist(hostnameArr: string[]): Promise<void>

await $browser.addHostnamesToDenylist(["*.css", "*.png"]);
await $browser.addHostnamesToAllowlist(["*"]);

$browser.addHostnamesToAllowlist(hostnameArr: string[]): Promise<void>

$browser.addHostnamesToWhitelist(hostnameArr: string[]): Promise<void>

await $browser.addHostnamesToDenylist(["*.css", "*.png"]);
await $browser.addHostnamesToAllowlist(["*"]);

$browser.addHostnameToDenylist(hostname: string): Promise<void>

$browser.addHostnameToBlacklist(hostname: string): Promise<void>

await $browser.addHostnameToDenylist(`*.css`);
await $browser.addHostnameToAllowlist(`*`);

$browser.addHostnameToAllowlist(hostname: string): Promise<void>

$browser.addHostnameToWhitelist(hostname: string): Promise<void>

await $browser.addHostnameToDenylist(`*.css`);
await $browser.addHostnameToAllowlist(`*`);

$browser.clearProxy(): Promise<void>;

$browser.deleteHeader(key: string): Promise<void>;

await $browser.addHeader('header1-xxx', 'abcd');
await $browser.addHeaders({
    key1: 'val1',
    key2: 'val2',
});
await $browser.deleteHeaders(['key1']);

await $browser.get(`http://localhost:${devport}/header-test`);
let userHeaders: Map<string, any>  = $browser.getHeaders();
console.log("User customized headers: ", [...userHeaders]);
expect(userHeaders.size).toEqual(2);

$browser.deleteHeaders: (header: string[]) => Promise<void>;

await $browser.addHeader('header1-xxx', 'abcd');
await $browser.addHeaders({
    key1: 'val1',
    key2: 'val2',
});
await $browser.deleteHeaders(['key1']);

await $browser.get(`http://localhost:${devport}/header-test`);
let userHeaders: Map<string, any>  = $browser.getHeaders();
console.log("User customized headers: ", [...userHeaders]);
expect(userHeaders.size).toEqual(2);

$browser.deleteHostnameFromDenylist(hostname: string): Promise<void>;

$browser.deleteHostnameFromBlacklist(hostname: string): Promise<void>;

$browser.deleteHostnameFromAllowlist(hostname: string): Promise<void>;

$browser.deleteHostnameFromWhitelist(hostname: string): Promise<void>;

$browser.deleteHostnamesFromDenylist(hostnameArr: string[]): Promise<void>

$browser.deleteHostnamesFromBlacklist(hostnameArr: string[]): Promise<void>

$browser.deleteHostnamesFromAllowlist(hostnameArr: string[]): Promise<void>

$browser.deleteHostnamesFromWhitelist(hostnameArr: string[]): Promise<void>

$browser.$$(selector);

The index.html file is as follows:

<ul id="menu">
  <li><a href="/">Home</a></li>
  <li><a href="/">Developer Guide</a></li>
  <li><a href="/">API</a></li>
  <li><a href="/">Contribute</a></li>
</ul>

Use $$ to find elements as follows:

test("should get text a menu link", async () => {
  const menu = (await $browser.$$("#menu"))[0];
  const li = await menu.$$("li");

  console.log(await li[2].$("a").getText()); // outputs: "API"
});

test("should get text a menu link - JS Function", async () => {
  const text = (
    await $browser.$$(function () {
      // Arrow function is not allowed here.
      return document.querySelectorAll("#menu"); // Element[]
    })
  )[0];

  const li3Text = await (await text.$$("li"))[2].$("a").getText();
  console.log(li3Text); // outputs: "API"
});

$browser.$(selector): WebElementPromise;

The index.html file is as follows:

<ul id="menu">
  <li><a href="/">Home</a></li>
  <li><a href="/">Developer Guide</a></li>
  <li><a href="/">API</a></li>
  <li><a href="/">Contribute</a></li>
</ul>

Use $ to find element as follows:

test("should get text a menu link", async () => {
  const text = await $browser.$("#menu").$$("li");
  console.log(await text[2].$("a").getText()); // outputs: "API"
});

test("should get text a menu link - JS Function", async () => {
  const text = await $browser.$(function () {
      // Arrow function is not allowed here.
      return document.querySelector("#menu"); // Element
    }).$$("li");

  console.log(text.$$("li")[2].$("a").getText()); // outputs: "API"
});

$browser.execute(command) => Promise<T>

Promise<T> is a promise that will be resolved with the command result.

$browser.executeAsyncScript<T>(script: string|Function, ...var_args: any[]): Promise<T>;

Example 1: To perform a sleep that is synchronized with the currently selected window, use the commands as shown in the following example:

const start = new Date().getTime();
$browser.executeAsyncScript(
    "window.setTimeout(arguments[arguments.length - 1], 500);"
  ).then(function () {
    console.log("Elapsed time: " + (new Date().getTime() - start) + " ms");
  });

Example 2: To synchronize a test with an Ajax application, use the commands as shown in the following example:

const button = $browser.$("#compose-button");
button.click();
$browser.executeAsyncScript(
  "var callback = arguments[arguments.length - 1];" +
    "mailClient.getComposeWindowWidget().onload(callback);"
);
$browser.switchTo().frame("composeWidget");
$browser.$("#to").sendKeys("dog@example.com");

Example 3: To inject XMLHttpRequest and wait for the result, use the following commands. In this example, the inject script is specified with a function literal. When you use this format, the function is converted to a string for injection. So the function must not reference any symbols that are not defined in the scope of the page under test.

$browser.executeAsyncScript(function () {
    var callback = arguments[arguments.length - 1];
    var xhr = new XMLHttpRequest();
    xhr.open("GET", "/resource/data.json", true);
    xhr.onreadystatechange = function () {
      if (xhr.readyState == 4) {
        callback(xhr.responseText);
      }
    };
    xhr.send("");
  }).then(function (str) {
    console.log(JSON.parse(str)["food"]);
  });

$browser.executeScript<T>(script: string|Function, ...var_args: any[]): Promise<T>;

$browser.findElement(locator: Locator): WebElementPromise;

You must not use this function to test whether an element is present on the page. Instead, you must use findElements:

$browser.findElements($driver.By.id("foo"))
  .then((found) => console.log("Element found? %s", !!found.length));

You can define the search criteria for an element by using one of the factories in the webdriver.By namespace or as a short-hand webdriver.By.Hash object. For example, the following two statements are equivalent:

var e1 = $browser.findElement($driver.By.id("foo"));
var e2 = $browser.findElement({ id: "foo" });

You can also provide a custom locator function, which takes as input this instance and returns a WebElement, or a promise that will be resolved with a WebElement. If the returned promise resolves with an array of WebElements, WebDriver uses the first element. For example, to find the first visible link on a page, you can use the following commands:

var link = $browser.findElement(firstVisibleLink);

function firstVisibleLink(driver) {
  var links = driver.findElements(By.tagName("a"));
  return promise.filter(links, function (link) {
    return link.isDisplayed();
  });
}

$browser.findElements(locator: Locator): Promise<WebElement[]>;

$browser.generateTOTPToken(key: string, options?: TOTPOptions): string;

Example 1: To generate a TOTP token and log in with two-factor authentication in Browser Script test:

await $browser.waitForAndFindElement($driver.By.id("password"), 15000);

let totp_token = $browser.generateTOTPToken($secure.totpKey);

await $browser.findElement($driver.By.id("password")).then((element) => {
  return element.clear().then(() => {
    return element.sendKeys(totp_token);
  });
});

Example 2: To generate a TOTP token in Selenium SIDE script test:

{
  "id": "ec51296b-4d16-4167-ac83-ba87f89cc0c7",
  "comment": "Generate a TOTP token from a TOTP key",
  "command": "executeScript",
  "target": "return $browser.generateTOTPToken($secure.totpKey);",
  "targets": [],
  "value": "totpToken"
}

$browser.get(url: string): Promise<void>;

$browser.getAllWindowHandles(): Promise<string[]>;

$browser.getCapabilities(): Promise<Capabilities>;

$browser.getCurrentUrl(): Promise<string>;

$browser.getHeaders(): Map<string, any>;

await $browser.addHeader('header1-xxx', 'abcd');
await $browser.addHeaders({
    key1: 'val1',
    key2: 'val2',
});
await $browser.deleteHeaders(['key1']);

await $browser.get(`http://localhost:${devport}/header-test`);
let userHeaders: Map<string, any>  = $browser.getHeaders();
console.log("User customized headers: ", [...userHeaders]);
expect(userHeaders.size).toEqual(2);

$browser.getPageSource(): Promise<string>;

$browser.getProxy(): FFProxyConfig | CProxyConfig;

This API can also be called through the $network object:

$network.getProxy(): FFProxyConfig | CProxyConfig;

/**
 * Firefox extension - An object encapsulating a complete proxy configuration
 * https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/proxy/settings
 */
export interface FFProxyConfig {
  proxyType?: FFProxyType,
  http?: string;
  ssl?: string,
  ftp?: string;
  autoConfigUrl?: string,
  autoLogin?: boolean,
  httpProxyAll?: boolean,
  passthrough?: string,
  proxyDNS?: boolean,
  socks?: string,
  socksVersion?: number,
}

/**
 * Chrome extension - An object encapsulating a complete proxy configuration
 * https://developer.chrome.com/docs/extensions/reference/proxy/#type-ProxyConfig
 */
export interface CProxyConfig {
  mode: CProxyType,
  rules?: {
    bypassList?: string[],
    fallbackProxy?: ProxyServer,
    proxyForFtp?: ProxyServer,
    proxyForHttp?: ProxyServer,
    proxyForHttps?: ProxyServer,
    singleProxy?: ProxyServer,
  },
  pacScript?: {
    data?: string,
    mandatory?: boolean,
    url?: string,
  },
};

$browser.getSession(): Promise<Session>;

$browser.getTitle(): Promise<string>;

$browser.getWindowHandle(): Promise<string>;

$browser.manage(): Options;

The options provide methods for managing browser and driver state.

export interface ILocation {
  x: number;
  y: number;
}

export interface ISize {
  width: number;
  height: number;
}

export interface IRectangle {
  x: number;
  y: number;
  width: number;
  height: number;
}

An interface for managing the current window.

let tm = await $browser.manage().getTimeouts();
console.log('current timeout', tm.implicit, tm.pageLoad, tm.script);

await $browser.manage().timeouts().pageLoadTimeout(119);
tm = await $browser.manage().getTimeouts();
expect(tm.pageLoad).toBe(119);
console.log('current timeout', tm.implicit, tm.pageLoad, tm.script);

await $browser.manage().timeouts().pageLoadTimeout(89);
tm = await $browser.manage().getTimeouts();
expect(tm.pageLoad).toBe(89);
console.log('current timeout', tm.implicit, tm.pageLoad, tm.script);

$browser.navigate(): Navigation;

The navigation interface for going back and forth in the browser history.

$browser.setAuthentication(authName: string, authPass: string): Promise<void>;

await $browser.setAuthentication(basicauthuser, password);
await $browser.get(`http://${httpserver}/basic/page1.html`)
.then(() => $browser.takeScreenshot());

$browser.setProxy(proxyURL: string | URL, noProxy?: string): Promise<void>;

This API can also be called through the $network object.

$network.setProxy(proxyURL: string | URL, noProxy?: string): Promise<void>

$browser.setProxyAdvanced(proxyConfig: CProxyConfig | FFProxyConfig, authName?: string, authPass?: string): Promise<void>;

This API can also be called through the $network object.

$network.setProxyAdvanced(proxyConfig: CProxyConfig | FFProxyConfig, authName?: string, authPass?: string): Promise<void>;

async function testProxyAdvanced() {
  await $browser.clearProxy();
  var ffconfig = {
    proxyType: "manual",
    //proxyType: "autoConfig",
    http: proxy_4,
    ssl: proxy_4,
    ftp: proxy_4,
    autoConfigUrl: pacfile,
    passthrough: noproxy,
    autoLogin: true,
  }

  var pxyserver = {
    host: httpserver,
    port: 8088,
    scheme: "http",
  }

  var cconfig = {
    mode: "fixed_servers",
    rules: {
      bypassList: noproxy.split(','),
      fallbackProxy: {
        host: "my-proxy-server.us.ibm.com",
        port: 8080,
      },
      proxyForFtp: pxyserver,
      proxyForHttp: pxyserver,
      proxyForHttps: pxyserver,
    },
    pacScript: {
      url: pacfile,
    },
  }

  var bname = null;
  await $browser.getCapabilities().then(cap=> {
    bname = cap.getBrowserName();
   });

  var config = (bname == 'chrome') ? cconfig : ffconfig;

  await $browser.setProxyAdvanced(config, proxyuser, password);
  await $browser.get(`http://${httpserver}/demo/page2.html`)
    .then(() => $browser.takeScreenshot());
}

$browser.setProxyAuthentication(authName: string, authPass: string): Promise<void>;

async function testProxyAuthentication() {
  await $browser.clearProxy();
  await $browser.setProxy(proxy_3, noproxy);
  await $browser.setProxyAuthentication(proxyuser, password);
  await $browser.get(`http://${httpserver}/demo/page2.html`)
    .then(() => $browser.takeScreenshot());
}

$browser.setProxyForHttp(proxyURL: string | URL, noProxy?: string): Promise<void>

This API can also be called through the $network object.

$network.setProxyForHttp(proxyURL: string | URL, noProxy?: string): Promise<void>

let website;
let proxyServer = "proxyHost:proxyPort";

console.log(">>>>>>>>>>>>>>>>>>>", "Clear proxy configuration");
await $network.clearProxy();
console.log(">>>>>>>>>>>>>>>>>>>", "Set proxy configuration for HTTP request");
await $network.setProxyForHttp(proxyServer);
website = await accessWebSite();
checkHostname("www.google.com.hk", website)

$browser.setProxyForHttps(proxyURL: string | URL, noProxy?: string): Promise<void>;

This API can also be called through the $network object.

$network.setProxyForHttps(proxyURL: string | URL, noProxy?: string): Promise<void>;

let website;
let sslProxyServer = "username:password@proxyHost:proxyPort";

console.log(">>>>>>>>>>>>>>>>>>>", "Clear proxy configuration");
await $network.clearProxy();
console.log(">>>>>>>>>>>>>>>>>>>", "Set proxy configuration for HTTPS request");
let testURL = new URL("http://" + sslProxyServer);
await $network.setProxyForHttps(testURL);
website = await accessWebSite();
checkHostname("www.google.com", website);

$browser.setProxyPAC(pacScriptURL: string, noProxy?: string, authMap?: Map<string, any>): Promise<void>;

const httpserver = '<DemoServerIP>';
const noproxy = "localhost,google.com,192.168.1.0/24";
const pacfile = `http://${httpserver}/pacfile`;
const authmap = new Map([
  [ httpserver, {username: "proxyuser", password: "passw0rd"} ],
  [ "httpserver2", {username: "user1", password: "passw0rd"} ],
])

async function testProxyPAC() {
  await $browser.clearProxy();
  await $browser.setProxyPAC(pacfile, noproxy, authmap);
  await $browser
    .get(`http://${httpserver}/demo/page2.html`)
    .then(() => $browser.takeScreenshot());
}

$browser.sleep(ms: number): Promise<void>;

await $browser.get("https://www.yahoo.com/");
await $browser.sleep(3 * 1000);
await $browser.takeScreenshot();

$browser.switchTo(): TargetLocator;

An interface for changing the focus of the driver to another frame or window.

/**
 * samples of getting current window handle
 * switch to a new window
 * open new page in new tab
 */
console.log("Windows handle: ", await $browser.getWindowHandle(), "Current url: ", await $browser.getCurrentUrl());
console.log("switch to calendar tab");
let originalWindow = await $browser.getWindowHandle();
await $browser.switchTo().newWindow();

/**
 * navigate to www.timeanddate.com
 * assert page title by getTitle() api
 * assert page title by getPageSource() api
 */
console.log("Access time and date page");
await $browser.get("http://www.timeanddate.com");
let page = await $browser.getPageSource();
assert.isTrue(page.includes("<title>timeanddate.com</title>"));
console.log("Page title: ", await $browser.getTitle());

/**
 * switch back to original window
 * take screenshot
 */
await $browser.switchTo().window(originalWindow);
await $browser.takeScreenshot();

$browser.takeScreenshot(): Promise<string>;

$browser.wait(
    condition: WebElementCondition,
    opt_timeout?: number,
    opt_message?: string): WebElementPromise;

Example 1: To wait up to 10 seconds for an element to be present on the page, use the commands as shown in the following example:

async function example() {
  let button = await $browser.wait(
    $driver.until.elementLocated($driver.By.id("foo")),
    10000
  );
  await button.click();
}

Example 2: To wait for an element and click, use the commands as shown in the following example:

await $browser.wait(until.elementLocated(by), timeout);
const element = await $browser.findElement(by, timeout);
await $browser.wait(until.elementIsVisible(element), timeout, `${by} not visible`);
await $browser.wait(until.elementIsEnabled(element), timeout, `${by} not enabled`);
await element.click();

$browser.waitForAndFindElement(locator: Locator, timeout?: number) : WebElementPromise;

The function is similar as follows:

const element = await $browser.wait(until.elementLocated(locator), timeout);
await $browser.wait(until.elementIsVisible(element), timeout);
return await $browser.findElement(locator);

$browser.waitForAndFindElement($driver.By.id("username"), 10000);

$browser.waitForPendingRequests(timeout?: number): Promise<void>;

The function is similar as

let script = "return document.readyState === 'complete'";
await $browser.wait(() => {
    return $browser.executeScript(script);
}, timeout);