API 參考資料

使用情形

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

參數

範例

範例 1: 若要按一下，請使用下列程式碼:

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

範例 2: 若要將滑鼠移至瀏覽器元素上，請使用下列程式碼:

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

若要與舊 mouseMove 函數相容，請使用下列指令:

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

附註: 基於與舊版的相容性，瀏覽器測試 API 支援 $browser.actions().mouseMove() 方法，並實作方法與 $browser.actions().move() ，因為 Selenium 已於 2021 年在此 PR中移除該方法。

範例 3: 若要傳送金鑰，請執行下列程式碼:

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>

附註: Instana 提供 addHostnamesToDenylist 功能來進行 URL 過濾，但不會移除 addHostnamesToBlacklist 函數，以確保程式碼與舊版相容。

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

參數

範例

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

使用情形

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

附註: Instana 提供 addHostnamesToAllowlist 函數來進行 URL 過濾，但不會移除 addHostnamesToWhitelist 函數，以確保程式碼與舊版相容。

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

參數

範例

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

使用情形

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

附註: Instana 提供 addHostnameToDenylist 函數來進行 URL 過濾，但不會移除 addHostnameToBlacklist 函數，以確保程式碼與舊版相容。

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

參數

範例

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

使用情形

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

附註: Instana 提供 addHostnameToAllowlist 功能來進行 URL 過濾，但不會移除 addHostnameToWhitelist 函數，以確保程式碼與舊版相容。

$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>;

附註: Instana 提供 deleteHostnameFromDenylist 函數來進行 URL 過濾，但不會移除 deleteHostnameFromBlacklist 函數，以確保程式碼與舊版相容。

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

參數

使用情形

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

附註: 程式碼會將 deleteHostnameFromAllowlist 函數新增至 API ，但不會移除 deleteHostnameFromWhitelist 函數，以確保程式碼與舊版相容。

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

參數

使用情形

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

附註: Instana 提供 deleteHostnamesFromDenylist 函數來進行 URL 過濾，但不會移除 deleteHostnamesFromBlacklist 函數，以確保程式碼與舊版相容。

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

參數

使用情形

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

附註: Instana 提供 deleteHostnamesFromAllowlist 函數來進行 URL 過濾，但不會移除 deleteHostnamesFromWhitelist 函數，以確保程式碼與舊版相容。

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

參數

使用情形

$browser.$$(selector);

參數

範例

index.html 檔案如下:

<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>

使用 $$ 來尋找元素，如下所示:

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;

參數

範例

index.html 檔案如下:

<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>

使用 $來尋找元素，如下所示:

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> 是將隨指令結果一起解析的承諾。

參數

使用情形

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

參數

範例

範例 1: 若要執行與目前選取的視窗同步的休眠，請使用下列範例中所示的指令:

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");
  });

範例 2: 如果要將測試與 Ajax 應用程式同步化，請使用下列範例所示的指令:

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");

範例 3: 若要注入 XMLHttpRequest 並等待結果，請使用下列指令。 在此範例中，使用函數文字指定 inject Script。 當您使用此格式時，會將函數轉換為字串以進行注入。 因此，函數不得參照未定義在受測試頁面範圍中的任何符號。

$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;

參數

範例

您不得使用此功能來測試頁面上是否存在元素。 您必須改用 findElements:

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

您可以使用 webdriver.By 名稱空間或作為速成 webdriver.By.Hash 物件。 例如，下列兩個陳述式相等:

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

您也可以提供自訂定位器函數，以作為此實例的輸入，並傳回 WebElement或將以 WebElement解析的承諾。 如果傳回的 promise 解析為 WebElements的陣列， WebDriver 會使用第一個元素。 例如，若要在頁面上尋找第一個可見的鏈結，您可以使用下列指令:

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.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;

也可以透過 $network 物件來呼叫此 API:

$network.getProxy(): FFProxyConfig | CProxyConfig;

參數

Proxy 配置

/** 
 * 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;

參數

選項

這些選項提供用來管理瀏覽器及驅動程式狀態的方法。

IWebDriverCookie

逾時

視窗

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;
}

用於管理現行視窗的介面。

範例

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;

參數

導覽

在瀏覽器歷程中來回的導覽介面。

使用情形

$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>;

也可以透過 $network 物件來呼叫此 API。

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

參數

使用情形

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

也可以透過 $network 物件來呼叫此 API。

$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>

也可以透過 $network 物件來呼叫此 API。

$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>;

也可以透過 $network 物件來呼叫此 API。

$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;

參數

TargetLocator

用於將驅動程式焦點變更為另一個頁框或視窗的介面。

實例方法

範例

/**
 * 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;

參數

範例

範例 1: 若要等待最多 10 秒，讓元素出現在頁面上，請使用下列範例中所示的指令:

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

範例 2: 若要等待元素並按一下，請使用指令，如下列範例所示:

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;

此函數類似如下:

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>;

此函數類似於

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

參數