Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface IGondolaWeb

Set of extended actions supported by Gondola

Hierarchy

  • IGondolaWeb

Index

Methods

Methods

attachFile

  • attachFile(element: string | ILocator, filePath: string): Promise<void>

  • Attaches a file to an element

    example
    
await gondola.attachFile("#ele","textFile.txt"); //attach file {projectDir}/textFile.txt to element #ele

    Parameters

    • element: string | ILocator

      element will be attached. It can be located by CSS|XPath|ILocator.

    • filePath: string

      path of attached file. This path is relative to the current project directory (where package.json is located)

    Returns Promise<void>

checkWindowExist

  • checkWindowExist(title: string): void

  • Checks that the title of a window/page is equal to the provided one. The verify point is considered: Passed if the values match; otherwise the test result is: Failed.

    example
    
// Check for the existence of a window whose title is "Scrum Board"
await gondola.checkWindowExist("Scrum Board");

    Parameters

    • title: string

      The title attribute of the current document.

    Returns void

clearField

  • clearField(element: string | ILocator): void

  • Clears an HTML <textarea> or text <input> element's value.

    example
    
const ele = "#elementLocator";
await gondola.clearField(ele);

    Parameters

    • element: string | ILocator

      located by CSS|XPath|ILocator.

    Returns void

click

  • click(element: string | ILocator, context?: undefined | string): void

  • Clicks on a link or a button, identified by a locator.

    example
    
await gondola.click("#elementId"); //click on element with the id "elementId";
await gondola.click("Login"); //click on button or link containing "Login";
await gondola.click({name : "submit"}, "#user>form");

    Parameters

    • element: string | ILocator

      located by CSS|XPath|ILocator.

    • Optional context: undefined | string

      (optional) element to search in CSS|XPath|ILocator.

    Returns void

clickPopup

  • clickPopup(option: string): void

  • Clicks on the active JavaScript native popup window, created by window.alert|window.confirm|window.prompt.

    example
    
gondola.clickPopup("ok");

    Parameters

    • option: string

      Click options:

      • "ok": click on the accept button of the popup
      • "cancel": click on the cancel button of the popup

    Returns void

closeCurrentTab

  • closeCurrentTab(): void

  • Closes the current tab

    example
    
gondola.closeCurrentTab();
    note

    This action is not supported when using the iOS version of Safari.

    Returns void

closeOtherTabs

  • closeOtherTabs(): void

  • Closes all tabs except for the current one.

    example
    
gondola.closeOtherTabs();
    note

    This action is not supported when using the iOS version of Safari.

    Returns void

deleteCookie

  • deleteCookie(cookie?: undefined | string): void

  • Clears all cookies. If a cookie is specified, it only deletes that cookie.

    example
    
gondola.deleteCookie();
gondola.deleteCookie("test");

    Parameters

    • Optional cookie: undefined | string

      (optional) cookie name.

    Returns void

doubleClick

  • doubleClick(element: string | ILocator, context?: string | ILocator): Promise<void>

  • Performs a double-click on an element matched by CSS|XPath|ILocator. The context can be specified as second parameter to narrow the search.

    example
    
await gondola.doubleClick("#elementId") //double click on element with the id "elementId";
await gondola.doubleClick("Login"); //double click on button or link containing "Login";
await gondola.doubleClick({name : "submit"}, ".context"); //double click on element with name "submit" inside element ".context"

    Parameters

    • element: string | ILocator

      located by CSS|XPath|ILocator.

    • Optional context: string | ILocator

      (optional) element to search in CSS|XPath|ILocator.

    Returns Promise<void>

dragAndDrop

  • Does one of the following actions:

    1. Drags an element to a destination element.
    2. Drags an element to a destination coordinate on the page.
    3. Drags anything at a coordinate on the page to a destination element.
    4. Drags and drops between 2 coordinates on the page.
    experimental

    v1.5 > Can be changed or removed soon

    example
    
// Element to Element
await gondola.dragAndDrop(`//img[@class='document'][1]`, `//div[contains(@class,'trash')]`, 3000);
// Element to Coordinate
await gondola.dragAndDrop(`//img[@class='document'][1]`, {x:450, y:170}, 3000);
// Coordinate to Element
await gondola.dragAndDrop({x: 38, y: 210}, `//div[contains(@class,'trash')]`, 3000);

// Coordinate to Coordinate
await gondola.dragAndDrop({x: 38, y: 280}, {x:450, y:170}, 4000);

    Parameters

    • source: string | ILocator | ICoordinate

      located by CSS|XPath|ILocator, or a coordinate (x,y)

    • destination: string | ILocator | ICoordinate

      located by CSS|XPath|ILocator, or a coordinate (x,y)

    • Optional duration: undefined | number

      drag and drop time in milliseconds.

    Returns void

executeScript

  • executeScript(fn: Function, ...args: any): Promise<any>

  • Executes a sync script on a page. Pass arguments to the function as additional parameters. Returns the results. To receive the results you should use an async function and await.

    example
    
await gondola.executeScript(function () {
     const element = document.getElementById('elementId');
});

await gondola.executeScript(function (text) {
     const element = document.getElementById('elementId');
     element.innerText = text;
}, "hello");

    Parameters

    • fn: Function
    • Rest ...args: any

      : list of arguments to pass to function.

    Returns Promise<any>

getAllWindowHandles

  • getAllWindowHandles(): Promise<string[]>

  • Returns a list of window handles for every open top-level browsing context. Useful for referencing a specific handle when calling gondola.switchToWindow(handle)

    example
    
const handles = await gondola.getAllWindowHandles();

    Returns Promise<string[]>

getCurrentBrowser

  • getCurrentBrowser(): any

  • Gets the current driver's browser object

    example
    
const browser = await gondola.getCurrentBrowser();

    Returns any

getCurrentUrl

  • getCurrentUrl(): Promise<string>

  • Gets the current URL from the browser

    example
    
const url = await getCurrentUrl();

    Returns Promise<string>

getCurrentWindowHandle

  • getCurrentWindowHandle(): Promise<string>

  • Returns the window handle for the current top-level browsing context. It can be used as an argument for switchToWindow().

    example
    
const handle = await gondola.getCurrentWindowHandle();

    Returns Promise<string>

getElementAttributes

  • getElementAttributes(element: string | ILocator, attributes: string[], context?: string | ILocator): Promise<{}>

  • Gets a list attributes of an element matched by CSS|XPath|ILocator. The context can be specified as second parameter to narrow the search.

    example
    
const result = await gondola.getElementAttributes("#elementId", ["name", "id", "class", "value"]);
const result = await gondola.getElementAttributes("Login", ["name", "id", "class", "value"]);
const result = await gondola.getElementAttributes({name : "submit"}, ["name", "id", "class", "value"], ".context");

    Parameters

    • element: string | ILocator

      located by CSS|XPath|ILocator.

    • attributes: string[]

      name of array attributes

    • Optional context: string | ILocator

      (optional) element to search in CSS|XPath|ILocator.

    Returns Promise<{}>

getElementBounds

  • Gets the width, height and location of given locator.

    example
    
const rect = await gondola.getElementBounds("#elementID");
// sample value { left: 226, top: 89, width: 527, height: 220 }

    Parameters

    • element: string | ILocator

      located by CSS|XPath|ILocator.

    Returns Promise<IRect>

getElementsAttribute

  • getElementsAttribute(element: string | ILocator, attribute: string): Promise<string[]>

  • Retrieves an attribute from each of the located elements.

    example
    
let value = await gondola.getElementsAttribute("#buttonId", "value");
    experimental

    v1 > Can be changed or removed soon

    Parameters

    • element: string | ILocator

      located by CSS|XPath|ILocator.

    • attribute: string

      attribute name.

    Returns Promise<string[]>

getPopupText

  • getPopupText(): Promise<string>

  • Gets the text from a popup created by window.alert|window.confirm|window.prompt. If no popup is visible, it returns an error.

    example
    
let text = await gondola.getPopupText();

    Returns Promise<string>

getTitle

  • getTitle(): Promise<string>

  • Retrieves a page title and returns it as string.

    example
    
let title = await gondola.getTitle();

    Returns Promise<string>

maximize

  • maximize(): void

  • Maximizes the current window. This method is for desktop browsers only.

    example
    
gondola.maximize();

    Returns void

moveMouse

  • Moves the mouse over the first element that matches the given locator. If the first parameter is null then the page is used. If the second parameter is given, then the mouse is moved to an offset based on the the element’s top-left corner. Otherwise, the mouse is moved to the center of the element.

    example
    
const testControl = "//a[text()='Methods']";     *
// move mouse to the top-left corner of the element
await gondola.moveMouse(testControl);
// move mouse to the element, at offset (80,50)
await gondola.moveMouse(testControl, {x:80, y:50});
// move mouse at location (400,400) of current web page
await gondola.moveMouse({x:400, y:400});

    Parameters

    • selectLocator: string | ILocator | ICoordinate

      located by CSS|XPath|ILocator.

    • Optional offset: ICoordinate

      offset from the element’s top-left corner or page.

    Returns void

navigate

  • navigate(url: string): void

  • Opens a web page in a browser. Requires a relative or absolute url. If url starts with /, it opens a web page of a site defined by the url config parameter.

    example
    
gondola.navigate("http://google.com");

    Parameters

    • url: string

      url path or global url.

    Returns void

openNewTab

  • openNewTab(): void

  • Opens a new tab and switches to it.

    example
    
gondola.openNewTab();
    note

    This action is not supported when using the iOS version of Safari.

    Returns void

pressKey

  • pressKey(key: string | string[]): Promise<void>

  • Presses a key in the browser (on a focused element). To press a key in combination with modifier keys, pass the sequence as an array

    example
    
await gondola.pressKey("Z"); //press key "Z" to focused control
await gondola.pressKey("Tab"); //press key "Tab" to focused control
await gondola.pressKey(KeyCode.Tab) ; //press key "Tab" to focused control use enum KeyCode
await gondola.pressKey([KeyCode.Control, "a"]); //press combine key ctrl+a

    Parameters

    • key: string | string[]

      or array of keys to press. Can use enum KeyCode to input key.

    Returns Promise<void>

refresh

  • refresh(): void

  • Reloads the current page.

    example
    
gondola.refresh();

    Returns void

rightClick

  • rightClick(element: string | ILocator, context?: string | ILocator): Promise<void>

  • Performs right click on a clickable element matched by semantic locator, CSS or XPath.

    example
    
await gondola.rightClick("#elementId"); //right click on element with the id "elementId";
await gondola.rightClick("Login"); //right click on button or link containing "Login";
await gondola.rightClick({name : "submit"}, ".context"); //right click on element with name "submit" inside element ".context"

    Parameters

    • element: string | ILocator

      located by CSS|XPath|ILocator.

    • Optional context: string | ILocator

      (optional) element to search in CSS|XPath|ILocator.

    Returns Promise<void>

scrollIntoView

  • Scrolls the element's parent container so the element is visible to the user.

    example
    
const testElement = `//h3[@id='scrollintoview']`;
await gondola.scrollIntoView(testElement);
await gondola.scrollIntoView(testElement, false);
await gondola.scrollIntoView(testElement, {block: "center", inline: "center"});

    Parameters

    • locator: string | ILocator

      located by CSS|XPath|ILocator.

    • Optional scrollIntoViewOptions: boolean | IScrollIntoViewOptions

      (optional) Object with the following properties: - "behavior": (optional) Defines the transition animation. Can be "auto" or "smooth". Defaults to "auto". - "block": (optional) Defines vertical alignment. Can be "start", "center", "end", or "nearest". Defaults to "start". - "inline": (optional) Defines horizontal alignment. Can be "start", "center", "end", or "nearest". Defaults to "nearest".

    Returns void

scrollTo

  • scrollTo(locator: string | ILocator, offsetX?: undefined | number, offsetY?: undefined | number): void

  • Scrolls to a particular set of coordinates inside a given element.

    example
    
const panelElement = `//div[@class='post']/article/div`;
// go to top-left element
await gondola.scrollTo(panelElement);
// scroll to a location inside element
await gondola.scrollTo(panelElement, 0 , 1000);

    Parameters

    • locator: string | ILocator

      located by CSS|XPath|ILocator.

    • Optional offsetX: undefined | number

      (optional, 0 by default) X-axis offset.

    • Optional offsetY: undefined | number

      (optional, 0 by default) Y-axis offset.

    Returns void

selectByIndex

  • selectByIndex(locator: string | ILocator, index: number): void

  • Selects an option inside a dropdown-list with a specific index.

    note

    In case of cross-domain iFrame automation on mobile, "Same-origin Policy" prevents Appium from automating iFrames that have a different domain to the parent. So, make your web application be testable, please refer this guide

    example
     await gondola.selectByIndex(`//select[@id='lstComponents']`, 5);
 or
 // open drop down list
 await gondola.click(`//a[@class='u28ham']`);
 // select item by index
 await gondola.selectByIndex(`//h3[.='Generation']/following-sibling::ul`, 2);

    Parameters

    • locator: string | ILocator

      the list control that contains the items, such as 'select' or 'ul' element.

    • index: number

      option index (zero-based)

    Returns void

setCookie

  • setCookie(cookie: object): Promise<void>

  • Sets one cookie for the current page. Make sure you are on the page that should receive the cookie.

    example
    
await gondola.setCookie({name: "id", value:"userId"});

    Parameters

    Returns Promise<void>

setPopupText

  • setPopupText(value: string): void

  • Sets the text in a javascript prompt popup.

    example
    
gondola.setPopupText("I am testing popup");

    Parameters

    • value: string

      text use to set

    Returns void

switchBrowserTab

  • switchBrowserTab(option: string, num?: undefined | number): void

  • Switches focus to a particular tab using its number. It waits for all tabs to load before switching.

    experimental

    v1.5 > Can be changed or removed soon. This action does not work well on Safari.

    example
    
gondola.switchBrowserTab("next");
    note

    This action is not supported when using the iOS version of Safari.

    Parameters

    • option: string

      "previous" | "next" indicate prev or next tab will be switch

    • Optional num: undefined | number

      (optional, default 1) offset from current handle index in sequence window handle.

    Returns void

switchFrame

  • switchFrame(element?: string | ILocator): void

  • Switches the context to another frame. In the case of a null locator it reverts to the parent frame.

    Note: In the case of cross-domain iFrame automation on mobile, "Same-origin Policy" prevents automated test tools from automating iFrames which have a different domain than their parent. To make your web application testable, please make sure that all cross-domain-iframe problems are bypassed.

    example
    
gondola.switchFrame(`//iframe[@src="https://paciellogroup.com"]`);

    Parameters

    • Optional element: string | ILocator

      located by CSS|XPath|strict locator.

    Returns void

switchToWindow

  • switchToWindow(handle: string): Promise<void>

  • Switches to the window with the specified handle.

    example
    
const handles = await gondola.getAllWindowHandles();
await gondola.switchToWindow(handles[0]);
    note

    This action is not supported when using the iOS version of Safari.

    Parameters

    • handle: string

      a string representing a window handle, should be one of the strings that was returned in a call to getAllWindowHandles

    Returns Promise<void>

waitForClickable

  • waitForClickable(element: string | ILocator, timeout?: undefined | number): Promise<void>

  • Waits a number of seconds for an element to become clickable.

    example
    
await gondola.waitForClickable("#btnLogin", 5); //waits 5 seconds for an element with id "btnLogin" to become clickable
await gondola.waitForClickable("#btnLogin"); //waits for element with id "btnLogin" to become clickable, uses smartwait as the timeout based on your configuration.

    Parameters

    • element: string | ILocator

      element located by CSS|XPath|ILocator.

    • Optional timeout: undefined | number

      (optional, default : 1s) time for waiting(seconds), uses smartwait as the timeout if timeout is not specified.

    Returns Promise<void>

waitForElementProperty

  • waitForElementProperty(element: string | ILocator, propName: string, propValue: any, timeout?: undefined | number, context?: string | ILocator): Promise<void>

  • Waits for an element's property have an expected value. At this time it only supports the "Webdriver" helper

    example
    
await gondola.waitForElementProperty("#id", "value", "exampleValue", 5); //wait up to 5 secs for the property "value" of the element "#id" to have the value "exampleValue".
await gondola.waitForElementProperty("#id", "value", "exampleValue", 5, ".context");  //wait up to 5 secs for the property "value" of the element "#id" in element ".context" to the have the value "exampleValue".

    Parameters

    • element: string | ILocator

      located by CSS|XPath|ILocator.

    • propName: string

      property name

    • propValue: any

      property's expected value

    • Optional timeout: undefined | number

      (optional, default : 1s) time for waiting(seconds), uses smartwait as the timeout if timeout is not specified.

    • Optional context: string | ILocator

      (optional) element to search in for the CSS|XPath|ILocator.

    Returns Promise<void>

waitForEnabled

  • waitForEnabled(element: string | ILocator, timeout?: undefined | number): Promise<void>

  • Waits for element to be enabled (by default waits for 1sec). Element can be located by CSS|XPath|ILocator.

    example
    
await gondola.waitForEnabled("#ele", 5); //waits for element have id "ele" enabled in 5 seconds
await gondola.waitForEnabled("#ele"); //waits for element with id "ele" enabled, uses smartwait as the timeout based on your configuration.

    Parameters

    • element: string | ILocator

      to be enabled.

    • Optional timeout: undefined | number

      (optional, default : 1s) time for waiting(seconds), uses smartwait as the timeout if a timeout is not specified.

    Returns Promise<void>

waitForText

  • waitForText(text: string, context?: string | ILocator, timeout?: undefined | number): Promise<void>

  • Waits for text appear in an html page. If context is specified, just wait for text appear in the context's container

    example
    
await gondola.waitForText("Hello gondola"); //wait for text "Hello gondola" appear in html page
await gondola.waitForText("Hello gondola", "#abc") //wait for text "Hello gondola" appear in container with the id "abc"
await gondola.waitForText("Hello gondola", undefined, 3) //wait for 3 seconds for the text "Hello gondola" appear in an html page

    Parameters

    • text: string

      text to wait for.

    • Optional context: string | ILocator

      (optional) element to narrow search CSS|XPath|ILocator.

    • Optional timeout: undefined | number

      (optional) time for waiting (seconds), uses smartwait as the timeout if timeout isn't specified.

    Returns Promise<void>

waitForValue

  • waitForValue(element: string | ILocator, value: string, timeout?: undefined | number): Promise<void>

  • Waits for the value attribute to equal the specified value

    example
    
await gondola.waitForValue("#idElement", "hello"); //wait for element with id "idElement" have text "hello" in "value" attribute with default wait time
await gondola.waitForValue("#idElement", "hello", 5); //wait for element with id "idElement" have text "hello" in "value" for no more than 5 seconds

    Parameters

    • element: string | ILocator

      element whose value attribute we're using

    • value: string

      text that we're waiting the the value attribute to be equal to

    • Optional timeout: undefined | number

      (optional, default : 1s) time for waiting(second), uses smartwait as the timeout if a timeout is not specified.

    Returns Promise<void>

waitForValueChanged

  • waitForValueChanged(element: string | ILocator, propName: string, oldValue?: any, timeout?: undefined | number, context?: string | ILocator): Promise<void>

  • Waits for an element's property to change value. At this time it only supports the "Webdriver" helper

    example
    
await gondola.waitForValueChanged("#id", "value", "exampleValue", 5); //wait up to 5 secs for the property "value" of the element "#id" to have the value "exampleValue".
await gondola.waitForValueChanged("#id", "value", "exampleValue", 5, ".context"); //wait up to 5 secs for the property "value" of the element "#id" in element ".context" to the have the value "exampleValue".

    Parameters

    • element: string | ILocator

      located by CSS|XPath|ILocator.

    • propName: string

      property name

    • Optional oldValue: any

      (optional) if current propValue doesn't equal oldValue, it will stop waiting.

    • Optional timeout: undefined | number

      (optional, default : 1s) time for waiting(seconds), uses smartwait as the timeout if timeout is not specified.

    • Optional context: string | ILocator

      (optional) element to search in CSS|XPath|ILocator.

    Returns Promise<void>

waitUntil

  • waitUntil(fn: Function, timeout?: undefined | number, interval?: undefined | number): Promise<void>

  • Waits for a function to return true.

    example
    
// waits for page title equal 'LogiGear' in 20 seconds. Checks condition every 5 seconds.
await gondola.waitUntil(async () => await gondola.getTitle() == "LogiGear", 20, 5);

    Parameters

    • fn: Function

      callback function will be executed

    • Optional timeout: undefined | number

      (optional, default : 1s) time to wait in seconds.

    • Optional interval: undefined | number

      (optional, default : 1s) interval between checking the conditional in seconds.

    Returns Promise<void>