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() 实现该方法，因为在本 PR 中，该方法已被 2021 年的 Selenium 删除。

示例 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 为 URL 过滤提供了 addHostnamesToDenylist 函数，但没有删除 addHostnamesToBlacklist 函数，以确保代码与早期版本兼容。

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

参数

示例

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

用法

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

Instana 为 URL 过滤提供了 addHostnamesToAllowlist 函数，但没有删除 addHostnamesToWhitelist 函数，以确保代码与早期版本兼容。

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

参数

示例

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

用法

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

Instana 为 URL 过滤提供了 addHostnameToDenylist 函数，但没有删除 addHostnameToBlacklist 函数，以确保代码与早期版本兼容。

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

参数

示例

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

用法

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

Instana 为 URL 过滤提供了 addHostnameToAllowlist 函数，但没有删除 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 为 URL 过滤提供了 deleteHostnameFromDenylist 函数，但没有删除 deleteHostnameFromBlacklist 函数，以确保代码与早期版本兼容。

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

参数

用法

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

该代码在 API 中添加了 deleteHostnameFromAllowlist 函数，但没有删除 deleteHostnameFromWhitelist 函数，以确保代码与早期版本兼容。

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

参数

用法

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

Instana 为 URL 过滤提供了 deleteHostnamesFromDenylist 函数，但没有删除 deleteHostnamesFromBlacklist 函数，以确保代码与早期版本兼容。

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

参数

用法

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

Instana 为 URL 过滤提供了 deleteHostnamesFromAllowlist 函数，但没有删除 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> 是将使用命令结果解析的 promise。

参数

用法

$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 并等待结果，请使用以下命令。 在此示例中，使用函数字面值指定注入脚本。 使用此格式时，函数将转换为字符串以进行注入。 因此，该函数不得引用未在被测试页面的作用域中定义的任何符号。

$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 解析的承诺。 如果返回的承诺使用数组 "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.generateTOTPToken(key: string, options?: TOTPOptions): string;

参数

示例

示例 1: 要在浏览器脚本测试中生成 TOTP 令牌并使用双因子认证登录:

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

示例 2: 要在 Selenium SIDE 脚本测试中生成 TOTP 令牌:

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

还可以通过 $network 对象来调用此 API:

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

参数

选项

这些选项提供了用于管理浏览器和驱动程序状态的方法。

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

参数