## openBrowser Launches a browser with a tab. The browser will be closed when the parent node.js process is closed.
Note : `openBrowser` launches the browser in headful mode by default. ### Parameters - `options` **[Object][1]** extra options. See [Extra Options][2] for a list of available options (optional, default `{}`) - `options.ignoreCertificateErrors` **[boolean][3]** Option to ignore certificate errors. (optional, default `false`) - `options.observe` **[boolean][3]** Option to run each command after a delay. Useful to observe what is happening in the browser. (optional, default `false`) - `options.observeTime` **[number][4]** Option to modify delay time for observe mode. Accepts value in milliseconds. (optional, default `3000`) - `options.setDebugEvents` **[boolean][3]** Turn on debug event in console (optional, default `false`) - `options.browserType` **[string][5]** Option to choose browser. (optional, default `'chromium'`) - `options.contextName` **[Object][1]** Name context as specified - `options.device` **[Object][1]** Emulate given device. - `options.extraHTTPHeaders` **[Object][1]** Map with extra HTTP headers. - `options.headless` **[boolean][3]** Option to open browser in headless/headful mode. (optional, default `false`) - `options.navigationTimeout` **[number][4]** Navigation timeout value in milliseconds for navigation after click. (optional, default `30000`) - `options.timeout` **[number][4]** Default timeout for all action. (optional, default `10000`) - `options.url` **[string][5]** URL to navigate page to. - `options.waitUntil` **[string][5]** Events available to wait for "load"|"domcontentloaded"|"networkidle0"|"networkidle2" (optional, default `'load'`) ### Examples ```javascript await openBrowser({headless: false}) await openBrowser() await openBrowser({browserType:'webkit'}) ``` Returns **[Promise][6]** ## openContext Opens the specified URL in the browser's window. Adds `http` protocol to the URL if not present. ### Parameters - `options` **[Object][1]** extra options. See [Extra Options][2] for a list of available options (optional, default `{}`) - `options.contextName` **[Object][1]** Name context as specified - `options.device` **[Object][1]** Emulate given device - `options.extraHTTPHeaders` **[Object][1]** Map with extra HTTP headers. - `options.navigationTimeout` **[number][4]** Navigation timeout value in milliseconds for navigation after click. (optional, default `30000`) - `options.timeout` **[number][4]** Default timeout for all action. (optional, default `10000`) - `options.url` **[string][5]** URL to navigate page to. - `options.waitUntil` **[string][5]** Events available to wait for "load"|"domcontentloaded"|"networkidle0"|"networkidle2" (optional, default `'load'`) ### Examples ```javascript await openContext('https://google.com', { name: 'windowName' }) - Opens a Incognito window ``` Returns **[Promise][6]** ## openPage Launches a new ¨Page. If url is provided, the new tab is opened with the url loaded. ### Parameters - `options` **[Object][1]** extra options. See [Extra Options][7] for a list of available options (optional, default `{}`) - `options.extraHTTPHeaders` **[Object][1]?** Map with extra HTTP headers. - `options.navigationTimeout` **[number][4]** Navigation timeout value in milliseconds for navigation after click. (optional, default `30000`) - `options.timeout` **[number][4]** Default timeout for all action. (optional, default `10000`) - `options.url` **[string][5]** URL to navigate page to. - `options.waitUntil` **[string][5]** Events available to wait for "load"|"domcontentloaded"|"networkidle0"|"networkidle2" (optional, default `'load'`) ### Examples ```javascript await openPage('https://duckduckgo.com/') await openPage() # opens a blank tab. ``` Returns **[Promise][6]** ## goto Opens the specified URL in the browser's tab. Adds `http` protocol to the URL if not present. ### Parameters - `url` **[string][5]** URL to navigate page to. - `options` **[Object][1]** (optional, default `{}`) - `options.extraHTTPHeaders` **[Object][1]** Map with extra HTTP headers. - `options.navigationTimeout` **[number][4]** Navigation timeout value in milliseconds for navigation after click. (optional, default `30000`) - `options.timeout` **[number][4]** Default timeout for all action. (optional, default `10000`) - `options.waitUntil` **[string][5]** Events available to wait for "load"|"domcontentloaded"|"networkidle0"|"networkidle2" (optional, default `'load'`) ### Examples ```javascript await goto('https://duckduckgo.com') await goto({ navigationTimeout:10000, headers:{'Authorization':'Basic cG9zdG1hbjpwYXNzd29y2A=='}}) ``` Returns **[Promise][6]** ## switchPage Allows switching between pages using URL or page title in current Context. Will switch to the first matching tab. ### Parameters - `arg` **[string][5]** URL/Page title of the tab to switch. ### Examples ```javascript # switch using URL await switchTo('https://duckduckgo.com/') # switch using Title await switchTo('DuckDuckGo — Privacy, simplified.') # switch using regex URL await switchTo(/http(s?):\/\/(www?).google.(com|co.in|co.uk)/) # switch using regex Title await switchTo(/Go*gle/) ``` Returns **[Promise][6]** ## switchContext Allows switching between tabs using URL or page title in all opened Window. Will switch to the first matching tab. ### Parameters - `arg` **[string][5]** URL/Page title of the tab to switch. - `name` **[string][5]** Window name containing tab. Optional parameter ### Examples ```javascript # switch using URL on default window await switchContext('https://duckduckgo.com/','default') # switch using Title on all opened window will return first match await switchContext('Taiko') # switch using regex URL on window named 'Thirdwindow' await switchContext(/http(s?):\/\/(www?).google.(com|co.in|co.uk)/,'ThirdContext') ``` Returns **[Promise][6]** ## switchBack Allows switch to previous position ### Examples ```javascript # switch using URL on default window await switchback() ``` Returns **[Promise][6]** ## closeBrowser Closes the browser and along with all of its tabs. ### Examples ```javascript await closeBrowser() ``` Returns **[Promise][6]** ## closeContext Closes the specified browser context. ### Parameters - `name` ### Examples ```javascript await closeContext('windowName') - Closes a window with given arg or current if not provided ``` ## closePage Closes the given tab with given URL or closes current tab in current or given context. ### Parameters - `arg` **[string][5]** URL/Page title of the tab to close. Optionnal (optional, default `undefined`) - `contextName` **[string][5]** context to close page in. Optionnal (optional, default `undefined`) ### Examples ```javascript # Closes the current tab. await closePage() # Closes all the tabs with Title 'Open Source Test Automation Framework | Gauge' in currentWindow await closePage('Open Source Test Automation Framework | Gauge') # Closes all the tabs with URL 'https://gauge.org'. in 'default' named context. await closePage('https://gauge.org','default') ``` Returns **[Promise][6]** ## intercept Add interceptor for the network call. Helps in overriding request or to mock response of a network call in currentContext. ### Parameters - `requestUrl` **[string][5]** request URL to intercept - `option` **([function][8] \| [Object][1])** action to be done after interception. - `count` **[number][4]** number of times the request has to be intercepted . Optional parameter ### Examples ```javascript # case 1: block URL : await intercept(url) # case 2: mockResponse : await intercept(url, {mockObject}) # case 3: override request : await intercept(url, (request) => {request.continue({overrideObject})}) # case 4: redirect always : await intercept(url, redirectUrl) # case 5: mockResponse based on request : await intercept(url, (request) => { request.respond({mockResponseObject}) }) # case 6: block URL twice: await intercept(url, undefined, 2) # case 7: mockResponse only 3 times : await intercept(url, {mockObject}, 3) ``` Returns **[Promise][6]** ## clearIntercept Removes interceptor for the provided URL or all interceptors if no URL is specified ### Parameters - `requestUrl` - `options` **[Object][1]** - `options.requestUrl` **[string][5]** request URL to intercept. Optional parameters - `options.windowName` **[string][5]** request URL to intercept. Optional parameters ### Examples ```javascript # case 1: Remove intercept for a single URL : await clearIntercept(requestUrl) # case 2: Reset intercept for all URL : await clearIntercept() ``` ## setViewPort Overrides the values of device screen dimensions ### Parameters - `options` **[Object][1]** See [chrome devtools setDeviceMetricsOverride][9] for a list of options ### Examples ```javascript await setViewPort({width:600, height:800}) ``` Returns **[Promise][6]** ## getDevice Get the values of device screen dimensions according to a predefined list of devices. To provide custom device dimensions, use setViewPort API. ### Parameters - `deviceModel` **[string][5]** See [device model][10] for a list of all device models. ### Examples ```javascript await openBrowser({device:getDevice('iPhone 6')}); await openContext({device:getDevice('iPhone 6')}); ``` Returns **[object][1]** ## overridePermissions Override specific permissions to the given origin ### Parameters - `origin` **[string][5]** url origin to override permissions - `permissions` **[Array][11]<[string][5]>** See [Permission types][12] for a list of permission types. ### Examples ```javascript await overridePermissions('http://maps.google.com',['geolocation']); ``` Returns **[Promise][6]** ## clearPermissionOverrides Clears all permission overrides for all origins. ### Examples ```javascript await clearPermissionOverrides() ``` Returns **[Promise][6]** ## setCookie Sets a cookie with the given cookie data. It may overwrite equivalent cookie if it already exists. ### Parameters - `name` **[string][5]** Cookie name. - `value` **[string][5]** Cookie value. - `options` **[Object][1]** (optional, default `{}`) - `options.url` **[string][5]** sets cookie with the URL. (optional, default `undefined`) - `options.domain` **[string][5]** sets cookie with the exact domain. (optional, default `undefined`) - `options.path` **[string][5]** sets cookie with the exact path. (optional, default `undefined`) - `options.secure` **[boolean][3]** True if cookie to be set is secure. (optional, default `undefined`) - `options.httpOnly` **[boolean][3]** True if cookie to be set is http-only. (optional, default `undefined`) - `options.sameSite` **[string][5]** Represents the cookie's 'SameSite' status: Refer [https://tools.ietf.org/html/draft-west-first-party-cookies][13]. (optional, default `undefined`) - `options.expires` **[number][4]** UTC time in seconds, counted from January 1, 1970. eg: 2019-02-16T16:55:45.529Z (optional, default `undefined`) ### Examples ```javascript await setCookie("CSRFToken","csrfToken", {url: "http://the-internet.herokuapp.com"}) await setCookie("CSRFToken","csrfToken", {domain: "herokuapp.com"}) ``` Returns **[Promise][6]** ## deleteCookies Deletes browser cookies with matching name and URL or domain/path pair. If cookie name is not given or empty, all browser cookies are deleted. ### Parameters - `name` - `cookieName` **[string][5]** Cookie name. (optional, default `undefined`) - `options` **[Object][1]** - `options.url` **[string][5]** deletes all the cookies with the given name where domain and path match provided URL. eg: [https://google.com][14] (optional, default `undefined`) - `options.domain` **[string][5]** deletes only cookies with the exact domain. eg: google.com (optional, default `undefined`) - `options.path` **[string][5]** deletes only cookies with the exact path. eg: Google/Chrome/Default/Cookies/.. (optional, default `undefined`) ### Examples ```javascript await deleteCookies() # clears all browser cookies await deleteCookies("CSRFToken", {url: "http://the-internet.herokuapp.com"}) await deleteCookies("CSRFToken", {domain: "herokuapp.com"}) ``` Returns **[Promise][6]** ## getCookies Get browser cookies ### Parameters - `options` **[Object][1]** (optional, default `{}`) - `options.url` **[Array][11]<[string][5]>** get all the cookies with the given name where domain and path match provided URL. eg: [https://google.com][14] (optional, default `undefined`) ### Examples ```javascript await getCookies() ``` Returns **[Promise][6]<[Array][11]<[Object][1]>>** Array of cookie objects ## setLocation Overrides the Geolocation Position ### Parameters - `options` **[Object][1]** Latitue, logitude and accuracy to set the location. see [Detailed options][15] ### Examples ```javascript await setLocation({ latitude: 27.1752868, longitude: 78.040009, accuracy:20 }) ``` Returns **[Promise][6]** ## reload Reloads the page. ### Parameters - `options` **[Object][1]** - `options.waitForEvents` **[Array][11]<[string][5]>** Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint'] (optional, default `['domcontentloaded']`) - `options.navigationTimeout` **[number][4]** Navigation timeout value in milliseconds for navigation after click. (optional, default `30000`) ### Examples ```javascript await reload() await reload({ navigationTimeout: 10000 }) ``` Returns **[Promise][6]** ## goBack Mimics browser back button click functionality. ### Parameters - `options` **[Object][1]** - `options.waitForEvents` **[Array][11]<[string][5]>** Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint'] (optional, default `['domcontentloaded']`) - `options.navigationTimeout` **[number][4]** Navigation timeout value in milliseconds for navigation after click. (optional, default `30000`) ### Examples ```javascript await goBack() ``` Returns **[Promise][6]** ## goForward Mimics browser forward button click functionality. ### Parameters - `options` **[Object][1]** - `options.waitForEvents` **[Array][11]<[string][5]>** Events available to wait for ['DOMContentLoaded', 'loadEventFired', 'networkAlmostIdle', 'networkIdle', 'firstPaint', 'firstContentfulPaint', 'firstMeaningfulPaint'] (optional, default `['domcontentloaded']`) - `options.navigationTimeout` **[number][4]** Navigation timeout value in milliseconds for navigation after click. (optional, default `30000`) ### Examples ```javascript await goForward() ``` Returns **[Promise][6]** ## currentURL Returns window's current URL. ### Examples ```javascript await openBrowser(); await goto("www.google.com"); await currentURL(); # returns "https://www.google.com/?gws_rd=ssl" ``` Returns **[Promise][6]<[string][5]>** The URL of the current window. ## title Returns page's title. ### Examples ```javascript await openBrowser(); await goto("www.google.com"); await title(); # returns "Google" ``` Returns **[Promise][6]<[string][5]>** The title of the current page. ## click Fetches an element with the given selector, scrolls it into view if needed, and then clicks in the center of the element. If there's no element matching selector, the method throws an error. ### Parameters - `selector` **selector** A selector to search for element to click. If there are multiple elements satisfying the selector, the first will be clicked. - `options` **[Object][1]** see [Detailed Options][16] (optional, default `{}`) ### Examples ```javascript await click($('[id = btnK]')) await click($('//[@id = "btnK"]')) await click($('text=button text')) ``` Returns **[Promise][6]** ## hover Fetches an element with the given selector, scrolls it into view if needed, and then hovers over the center of the element. If there's no element matching selector, the method throws an error. ### Parameters - `selector` **(selector | [string][5])** A selector to search for element to right click. If there are multiple elements satisfying the selector, the first will be hovered. - `options` **[Object][1]** see [Detailed Options][17] ### Examples ```javascript await hover('text=Get Started') await hover($('[id="btnK"]')) ``` ## focus Fetches an element with the given selector and focuses it. If there's no element matching selector, the method throws an error. ### Parameters - `selector` **(selector | [string][5])** A selector of an element to focus. If there are multiple elements satisfying the selector, the first will be focused. - `options` **[Object][1]** see [Detailed Options][18] ### Examples ```javascript await focus($('text=Username:')) ``` ## write Types the given text into the focused or given element. ### Parameters - `text` **[string][5]** Text to type into the element. - `selector` - `options` **[Object][1]** ### Examples ```javascript await write('admin', $('[id=text]')) await write('admin') ``` Returns **[Promise][6]** ## clear Clears the value of given selector. If no selector is given clears the current active element. ### Parameters - `selector` **selector** A selector to search for element to clear. If there are multiple elements satisfying the selector, the first will be cleared. - `options` **[Object][1]** Click options. ### Examples ```javascript await clear() await clear($([placeholder:'Email'])) ``` Returns **[Promise][6]** ## attach Attaches a file to a file input element. ### Parameters - `filePath` - `to` **(selector | [string][5])** The file input element to which to attach the file. - `filepath` **[string][5]** The path of the file to be attached. ### Examples ```javascript await attach('c:/abc.txt', $('Please select a file:')) ``` Returns **[Promise][6]** ## press Presses the given keys. ### Parameters - `keys` **([string][5] \| [Array][11]<[string][5]>)** Name of keys to press. See [USKeyboardLayout][19] for a list of all key names. - `options` **[Object][1]** ### Examples ```javascript await press('Enter') await press('a') await press(['Shift', 'ArrowLeft', 'ArrowLeft']) ``` Returns **[Promise][6]** ## highlight Highlights the given element on the page by drawing a red rectangle around it. This is useful for debugging purposes. ### Parameters - `selector` **selector** A selector of an element to highlight. If there are multiple elements satisfying the selector, the first will be highlighted. ### Examples ```javascript await highlight('text=Get Started') await highlight($('//*[@id="button"]')) ``` Returns **[Promise][6]** ## mouseAction Performs the given mouse action on the given coordinates. This is useful in performing actions on canvas. ### Parameters - `selector` **[string][5]** Element to be selected on the canvas - `action` **[string][5]** Action to be performed on the canvas/selector - `coordinates` **[Object][1]** Coordinates of a point on canvas/selector to perform the action. - `options` **[Object][1]** (optional, default `{}`) ### Examples ```javascript await mouseAction('press', {x:0,y:0}) await mouseAction('move', {x:9,y:9}) await mouseAction('release', {x:9,y:9}) await mouseAction($("#elementID"),'press', {x:0,y:0}) await mouseAction($(".elementClass"),'move', {x:9,y:9}) await mouseAction($("//*[@id='plop']"),'release', {x:9,y:9}) ``` ## scrollTo Scrolls the page to the given element. ### Parameters - `selector` **selector** A selector of an element to scroll to. - `options` **[Object][1]** (optional, default `{}`) ### Examples ```javascript await scrollTo($('text=Get Started')) ``` Returns **[Promise][6]** ## screenshot Captures a screenshot of the page. Appends timeStamp to filename if no filepath given. ### Parameters - `selector` **(selector | [string][5])** - `options` **[Object][1]** (optional, default `{}`) ### Examples ```javascript await screenshot() await screenshot({path : 'screenshot.png'}) ``` Returns **[Promise][6]<[Buffer][20]>** Promise which resolves to buffer with captured screenshot if {encoding:'base64'} given. ## $ This [selector][21] lets you identify elements on the web page via XPath, CSS selector or text. ### Parameters - `selector` **[string][5]** XPath or CSS selector. - `options` (optional, default `{}`) ### Examples ```javascript await highlight($(`//*[text()='text']`)) await $(`[class='className']`).exists() await $(`text=lorem ipsum`) ``` Returns **Selector** ## setConfig Lets you configure global configurations. ### Parameters - `config` - `options` **[Object][1]** - `options.observeTime` **[number][4]** Option to modify delay time in milliseconds for observe mode. (optional, default `3000`) - `options.navigationTimeout` **[number][4]** Navigation timeout value in milliseconds for navigation after performing openPage, goto, reload, goBack, goForward, click, write, clear, press and evaluate. (optional, default `30000`) - `options.waitForNavigation` **[boolean][3]** Wait for navigation after performing goto, click, doubleClick, rightClick, write, clear, press and evaluate. (optional, default `true`) ### Examples ```javascript setConfig( { observeTime: 3000}); ``` ## getConfig Lets you read the global configurations. ### Parameters - `config` - `optionName` **[String][5]** Specifies the name of the configuration option/paramter you want to get (optional). If not specified, returns a shallow copy of the full global configuration. - `String` "navigationTimeout"] Navigation timeout value in milliseconds for navigation after performing - `String` "observeTime"] Option to modify delay time in milliseconds for observe mode. - `String` "timeout"] Option to modify delay time in milliseconds for all actions. - `String` "observe"] Option to run each command after a delay. Useful to observe what is happening in the browser. - `String` "waitForNavigation"] Wait for navigation after performing goto, click, write, clear, press and evaluate. - `String` "ignoreSSLErrors"] Option to ignore SSL errors encountered by the browser. - `String` "headless"] Option to open browser in headless/headful mode. ### Examples ```javascript getConfig("retryInterval"); ``` ## waitFor This function is used to wait for number of milliseconds given or a given Selector or a given condition. ### Parameters - `elementOrFunc` - `args` - `options` (optional, default `{}`) ### Examples ```javascript # case 1: wait for time : await waitFor(5000) # case 2: wait for Selector : await waitFor($("text=1 item in cart")) await waitFor($("text=Order Created"),'hidden') # case 3: wait for function : let f = () => {return window.innerWidth < 500;} await waitFor(f) # case 4: wait for function with single or multiple args in an array : await waitFor(([element,color]) => { return element.style.background == color;} ,[$('//*[@class="content-info__item"][1]'),'green']); ``` Returns **[promise][6]** ## evaluate Evaluates script on element matching the given selector. ### Parameters - `callback` **[function][8]** callback method to execute on the element or root HTML element when selector is not provided.
- `args` **any** single or multiple callback args embedded in an array.
- `options` **[Object][1]** options. NOTE : In callback, we can access only inline css not the one which are define in css files. ### Examples ```javascript await evaluate(() => { // Callback function have access to all DOM APIs available in the developer console. return document.title; } ) await evaluate((element) => element.style.backgroundColor),$("[button]")); await evaluate(([element,color]) => { element.style.background = color;} ,[$('//*[@class="content-info__item"][1]'),'green']); ``` Returns **[Promise][6]<[Object][1]>** Object with return value of callback given [1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object [2]: https://github.com/microsoft/playwright/blob/master/docs/api.md#browsernewcontextoptions [3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean [4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number [5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String [6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise [7]: https://github.com/microsoft/playwright/blob/master/docs/api.md#browsernewpageoptions [8]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function [9]: https://chromedevtools.github.io/devtools-protocol/tot/Emulation#method-setDeviceMetricsOverride [10]: https://github.com/Microsoft/playwright/blob/master/src/deviceDescriptors.ts [11]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array [12]: https://github.com/microsoft/playwright/blob/master/docs/api.md#browsercontextgrantpermissionspermissions-options [13]: https://tools.ietf.org/html/draft-west-first-party-cookies [14]: https://google.com [15]: https://github.com/microsoft/playwright/blob/master/docs/api.md#browsercontextsetgeolocationgeolocation [16]: https://github.com/microsoft/playwright/blob/master/docs/api.md#pageclickselector-options [17]: https://github.com/microsoft/playwright/blob/master/docs/api.md#pagehoverselector-options [18]: https://github.com/microsoft/playwright/blob/master/docs/api.md#pagefocusselector-options [19]: https://github.com/getgauge/taiko/blob/master/lib/data/USKeyboardLayout.js [20]: https://nodejs.org/api/buffer.html [21]: selector