# Welcome to Oxygen # What is Oxygen? Oxygen is an open-source automation platform that simplifies the work with Selenium and Appium. With Oxygen, manual testers and QA engineers can write automation tests within minutes. **Oxygen** significantly simplifies writing and running automation tests of any kind. It's an open source framework and tool-set built on top of [Selenium](https://www.selenium.dev/), [Appium](http://appium.io/), [WebdriverIO](https://webdriver.io), and [WinAppDriver](https://github.com/microsoft/WinAppDriver). It implements many commonly recurring patterns out-of-the-box and hides back-end complexities behind a concise API. Oxygen test scripts are written in JavaScript and is compatible with [ECMAscript 6](https://en.wikipedia.org/wiki/ECMAScript). Oxygen is comprised of [numerous modules](https://docs.oxygenhq.org/download-installation-start/modules) for each of the different functionalities that it supports. It also has native [support for BDD](https://docs.oxygenhq.org/howtos/how-tos/bdd-with-cucumber) - [Behavior-Driver Development](https://en.wikipedia.org/wiki/Behavior-driven_development), with its built-in [Cucumber ](https://cucumber.io/)implementation. **Oxygen** is made up of two components: **Oxygen CLI** - Command Line Interface and **Oxygen IDE** - Integrated Development Environment, a GUI (Graphic User Interface) application. * **Oxygen CLI** - Is a [Node.js](https://nodejs.org/en/) module and command-line toolset for running tests and generating reports either on a local workstation or as a part of [CI/CD process](https://en.wikipedia.org/wiki/CI/CD) Oxygen CLI can easily be integrated into any Node.js project or CI/CD tool, such as [Jenkins](https://jenkins.io/). Oxygen CLI lets you execute Test Suites containing multiple sets of test cases. * **Oxygen IDE** - Is a graphic user interface (GUI) application for Windows, Mac and Linux that used for recording, developing, and running tests on web browsers, mobile devices and windows desktop applications. Oxygen IDE is optional but is highly recommended for rapid test script development. ## Key Features * Best-in-class Node.js based test automation framework, with built-in support for many modern technologies: Web, Mobile, Desktop, Database, REST API, email, SMS, PDF, shell, IoT and more. Expandable with user-created modules. * Supports desktop windows application, web, native mobile, hybrid, and mobile-browser applications. * Intuitive IDE tailored specifically for writing automation scripts. * Cross-browser test recording and execution. * Run your tests locally or on any test execution cloud provider. * Seamless integration and one-click test execution on browsers and devices available in your LambdaTest, Sauce Labs, TestObject, Testing Bot, and Perfecto account (no need to define capabilities). * Built-in parameterization for Data-Driven Testing. * Object Repository (Page Objects) that allows for writing easily maintainable tests. * Straight-forward integration with any CI/CD tool using Oxygen CLI. ## Supported platforms Oxygen supports the following platforms: * Android - Native, Hybrid, and Web * iOS - Native, Hybrid, and Web * Windows - Desktop, Chrome, Firefox, Internet Explorer (Support for Microsoft EDGE coming soon in an upcoming version) * Linux - Chrome, Firefox * OS X - Safari, Chrome, Firefox Oxygen test scripts are written in JavaScript: ```javascript // Define capabilities var capabilities = { browserName: 'chrome', 'goog:chromeOptions': { args: [ '--headless', '--no-sandbox', '--disable-notifications', ], } } // Login into a web site (desktop web application). web.init(capabilities); web.open('http://example.org'); web.click('link=login'); web.type('id=username', 'USERNAME'); web.type('id=password', 'PASSWORD'); web.assertTitle('TITLE'); // Get value from a data base and validate that it matches the one we see on the screen. db.setConnectionString('Driver={SQL Server};Server=DESKTOP-NAME\\SQLEXPRESS;Database=db;'); var userEmailDb = db.executeQuery("SELECT email FROM users WHERE username = 'username';"); var userEmailEl = web.getText("id=userEmail"); assert.equal(userEmailEl, userEmailDb); // Launch native application running on a mobile device, click a button, validate that user is logged in. web.click('//*[@id="profile"]'); web.assertText('id=user_email', userEmailDb); ``` # Getting Started (Videos) # Oxygen IDE Controls Overview {% embed url="" %} # Recording a Web Test {% embed url="" %} # Oxygen Commands Explained {% embed url="" %} # Getting help Our growing community is always willing to lend a hand. you may post a question or offer a new feature and someone is sure to follow up. ## Where to get help? The Oxygen support forum is found on the discuss board here: {% embed url="" %}
Support page on Oxygen web site
You can also Send an email to # Download & Installation # Oxygen IDE Installation Oxygen IDE - Integrated development environment for recording, developing, and running tests - Download and Installation. ## Download Oxygen IDE for Windows, OS X and Linux from [here](https://github.com/oxygenhq/oxygen-ide/releases/latest): [Oxygen IDE Install Link](https://github.com/oxygenhq/oxygen-ide/releases/latest) ## **Prerequisites** 1. **Java 17 or above** to be installed. 2. **Node.js 12** to be installed. 3. If you are a **Mac user** please read special instructions on Mac installation written below. ## **Additional installations** 1. If you wish to run **mobile automation,** when you complete installing the IDE you are required to download additional [mobile automation installation files](https://docs.oxygenhq.org/download-and-installation/mobile-installation). 2. If you wish to run **Windows App automation,** when you complete installing the IDE you are required to download additional [Windows automation installation files](https://docs.oxygenhq.org/download-installation-start/download-and-installation/oxygen-for-windows-desktop-setup). 3. If you wish to run Oxygen using a **command line (CLI)**, when you complete installing the IDE you are required to download additional [CLI Installation guide](https://docs.oxygenhq.org/oxygen-cli/introduction-and-usage). {% hint style="info" %} ## Node.js Installation Node.js 12 download - {% endhint %} {% hint style="info" %} ## Java Installation To start working with Oxygen IDE - **you should also install Java 17** **or above** - For more information on downloading and working with Java see here: [Detailed Java Installation Instructions - Windows and Mac](https://docs.oxygenhq.org/download-and-installation/java-installation-and-path-environment-variable-for-java) {% endhint %} {% hint style="info" %} ## **Mac users:** Make sure you have installed and updated "Xcode". Open the Mac App Store application, search for "Xcode", install and/or update it. See additional details for Xcode installation on the following page: [Mac Installation](https://docs.oxygenhq.org/download-installation-start/download-and-installation/oxygen-for-mac-installation) Please ensure that you've[ installed Java for Mac](https://docs.oxygenhq.org/download-and-installation/java-installation-and-path-environment-variable-for-java) as detailed in the first section above. {% endhint %} [Oxygen for Mobile Installation](https://docs.oxygenhq.org/download-and-installation/mobile-installation) [Oxygen for Windows Installation](https://docs.oxygenhq.org/download-installation-start/download-and-installation/oxygen-for-windows-desktop-setup) [Oxygen CLI Installation](https://docs.oxygenhq.org/download-and-installation/cli-installation) [Java Installatio](https://docs.oxygenhq.org/download-and-installation/java-installation-and-path-environment-variable-for-java)[n - Windows and Mac](https://docs.oxygenhq.org/download-and-installation/java-installation-and-path-environment-variable-for-java) [Mac Installation Troubleshooting](https://docs.oxygenhq.org/download-and-installation/troubleshooting-installation-issues-mac) [Recording Troubleshooting](https://docs.oxygenhq.org/download-and-installation/recording-troubleshooting) # Oxygen for Mobile Installation Oxygen can run automation scripts on mobile devices (Native and Mobile Web, iOS and Android). ## Mobile Installation & Configuration To create and execute mobile test automation in Oxygen, we'll need to install and configure a few things: 1. Install Appium Desktop. 2. Install Android Studio and SDK. 3. Configure Environment Variables. {% hint style="info" %} **Mac users:** Make sure that you have Xcode installed and. Open the Mac App Store application, search for "Xcode", install and/or update it. See additional details for Xcode installation on the following page: [Mac Installation Troubleshooting](https://docs.oxygenhq.org/download-and-installation/troubleshooting-installation-issues-mac) Please ensure that you've[ installed Java for Mac](https://docs.oxygenhq.org/download-and-installation/java-installation-and-path-environment-variable-for-java) as detailed in the first section above. **Note**: scroll down to see cofiguring ADB for Mac {% endhint %} ## Download and install Appium Desktop Recording can be done using specially build Appium Desktop version with added recording support for Oxygen. 1. Appium Server: [https://appium.io](https://appium.io/) 2. Appium Inspector: ## Download and install Android Studio: **Android Studio**: **Note**: If you have wish to save disk space you may try to Download and install only the SDK tools instead of the entire Android studio: Scroll a little to the bottom and you will see SDK tools download. We do not recommend that since users sometimes encounter issues configuring appium and ADB without the entire Android Studio. ## Configure Environment Variables: Now that we've installed android studio, we have to create an environment variable called ANDROID\_HOME and give it the path to the SDK folder which was installed with android studio. 1. Open the SDK folder and copy it's path, it should be here: **C:\Users\\%UserProfile%\AppData\Local\Android\Sdk** 2. Open the search bar and type environment variables then press enter 3. Under system variables, click on new, and set variable name to **ANDROID\_HOME,** then paste the path to SDK inside vale value, as seen below: ![](/files/sCa7SivQTOIpF9ZaQ2b2) 4\. now we have to set two additional paths, one to **platform-tools** and another one to **tools** ![](/files/2weNOj8dYhKdUUF0jSs3) under system variables, double click on path and click on new, now copy the path to platform-tools folder and paste it inside, do the same to the tools folder, seen below: ![](/files/umZT6Mplm2tfX8b9KfUr) ## **and that's it, you're all set!** {% hint style="info" %} If you are the administrator of the computer - there should be no issues adding these environment variables in your system variable, but if you add it to a certain user, you must run the Appium Desktop and commands from cmd using the specific user. There could be permission issues so you need to make sure you are doing the configuration properly and all under one user. {% endhint %} ### Checking that adb is configured properly: Now in order to check if adb is configured open command line, and type **adb devices** and press Enter. You will now receive a list of all available devices that are connected to your machine. ![](/files/LkxOESTCjQikaR1nBBwz) #### Unlocking Developer options (Android only) In order to work with Appium Desktop - you must enable USB debugging , which is only possible while in Developer mode (No worries, it does not harm your phone). You can do it simply by following these steps: 1. Go to settings screen 2. Click 'System settings' 3. Click 'About phone' 4. Tap 10 times on 'Build number' - and you should receive a message the developer options are unlocked. 5. Go to Developer options (located differently on different phones). 6. Toggle 'USB debugging' on. And that's it, your phone is now ready for mobile automation! #### Recognizing your phone using adb commands In order to see that everything worked well , you need to write the following command in your command line: 'adb devices'. The list of all devices attached to your computer will be shown. ### Set ADB for MAC Users Setting up ADB on a MAC machine instructions may be found here: . If you already have Android Studio installed, follow these instructions: 1. Add `platform-tools` to your path ``` echo 'export ANDROID_HOME=/Users/$USER/Library/Android/sdk' >> ~/.bash_profile echo 'export PATH=${PATH}:$ANDROID_HOME/tools:$ANDROID_HOME/platform-tools' >> ~/.bash_profile ``` 2. Refresh your bash profile (or restart your terminal app) ``` source ~/.bash_profile ``` 3. Start using adb ``` adb devices ``` #### Checking adb is configured properly Now in order to check if adb is configured open command line, and type : 'adb devices' and press Enter. You will now receice a list of all available devices that are connected to your machine. #### Unlocking Developer options (Android only) In order to work with Appium Desktop - you must enable USB debugging , which is only possible while in Developer mode (No worries, it does not harm your phone). You can do it simply by following these steps: 1. Go to settings screen 2. Click 'System settings' 3. Click 'About phone' 4. Tap 10 times on 'Build number' - and you should receive a message the developer options are unlocked. 5. Go to Developer options (located differently on different phones). 6. Toggle 'USB debugging' on. And that's it, your phone is now ready for mobile automation! #### Recognizing your phone using adb commands In order to see that everything worked well , you need to write the following command in your command line: 'adb devices'. The list of all devices attached to your computer will be shown. # Oxygen for Windows Desktop Automation Setup You are now capable to automate windows applications - Windows 10 applications, including UWP, WPF, WinForms, and legacy Win32 ## Windows Installation & Configuration If you wish to use Oxygen to Automate Windows applications. we'll need to install and configure a few things: 1. Enable Developer Mode (Go to Developer Settings -> Developer Mode) 2. Install WinAppDriver from here: For further instructions of how to use Oxygen for Windows automation please refer to [Getting Started - Oxygen for Windows Desktop Automation](https://docs.oxygenhq.org/getting-started-windows-desktop) # Oxygen for Mac Installation To download Oxygen for Mac, the project Github page: {% embed url="" %} Click on the link for the DMG file. In the screenshot below that would be "oxygen-1.17.0-osx-x64.dmg" ![](/files/-M6BuyMYNHrotFNmLaD3) After the file downloads, open the dmg file by double clicking it. Click and drag the Oxygen icon to the shortcut icon for the Applications folder. ![](/files/-M6Bze_Tl3Wb0yoa_BYo) As detailed in the [Oxygen CLI documentation page](https://docs.oxygenhq.org/download-installation-start/download-and-installation/cli-installation). you have to install the Oxygen framework from the Terminal in order to have the benefit of being able to execute Oxygen from test suites. (multiple sets of tests) From the MacOS / Finder Spotlight Search, type Terminal. ![](/files/-M6C4HBSuCqnWnZ_5izv) ![](/files/-M6C6nioI7I53MNxGUpZ) A pre-requisite for installing Oxygen CLI and running it via the terminal, is having Node.js installed, which also includes NPM. Go to the [Node.JS downloads page here. ](https://nodejs.org/en/download/)Choose the macOS Installer (.pkg) - 64-bit download or simply click on the macOS Installer ![Node.js downloads page](/files/-M6CIFOA5ahSQeiMdMfk) Go through the steps to install Node.js by launching the Node installation package. This installer will install both Node.js and NPM. ![](/files/-M6CONHh03JoV_6W2q3A) ![](/files/-M6COgR7KRyq_1Pzz7Bk) ![](/files/-M6CQ9EKF1-0DyH3gNMw) After installation has complete, verify the successful installation of NPM by typing "npm" without the quotes in the Terminal window. ![](/files/-M6CQYZBGzzKrS3L-vFm) If NPM is successfully installed, to install Oxygen-CLI you can enter: ``` sudo npm install -g oxygen-cli ``` or ``` npm install -g oxygen-cli ``` sudo is used to elevate permissions (super-user do), if the current user had limited permissions. At this point, npm will install Oxygen-CLI on the system. You can confirm successful installation by typing Oxygen on the terminal prompt ``` oxygen ``` # Mac Installation Troubleshooting Installing Xcode on Mac. Troubleshooting Xcode issues. Installation of Oxygen IDE on Mac, for example on OS 10.15 Catalina, has a dependency on installing Apple's software development IDE which called Xcode from the Apple Mac App Store. Xcode is available to download for free from the Mac App Store with an Apple Developer account. If Xcode is not already installed or configured correctly, the user will receive a "Device Discover Service" warning message when launching Oxygen IDE with the text: "Could not find the instruments binary. Please ensure 'xcrun -find instruments' can locate it. NB: If you are a corporate user using a corporate machine, your organization may require that you download and install Xcode from your company's self-service portal for software installation packages. Downloading applications from the Mac App Store requires having your Apple ID set-up and entered. The following link goes through a step-by-step process for installing Xcode on Mac OS: If you continue to receive the Device Discovery Service error mentioned above and in the screenshot, try the process described here: You need to launch XCode and agree to the terms first, if this is your first time using a new installation. Then, go to: `Preferences > Locations` and you'll see a selection drop down for **Command Line Tools**. Click this select box and choose the version of XCode you'll be using. This should resolve the issue. ![Set the location of the Xcode Command Line Tools for the correct Xcode installation](/files/-M4XmaFC2XToafVnF3mc) {% embed url="" %} Additionally, in order to use the automatic script recording tool in Mac OS X, you must manually install and enable the Oxygen Extension for Chrome browser on Mac. [Install Oxygen Chrome Extension](https://chrome.google.com/webstore/detail/oxygen/ibbmgejonlmocgjnkmabigdgbolcomea) # Oxygen CLI Installation Command-line application for running Oxygen tests and generating reports. ## CLI Installation Oxygen CLI - Command-line application for running tests and generating reports. To start working with Oxygen Command-line (cli) - you must first install the following programs: 1. [Node.js](https://nodejs.org/) 8 or later. 2. [Java 8](https://www.java.com/en/download/) After installing the above programs you should do the following steps: 1. Open the command line (cmd command) 2. Type the following command in the command line: ```bash npm install -g oxygen-cli ``` After installation is finished, re-open your command-line. In some cases you may need to run the installation command using sudo to provide the super-user do elevated permission ```bash sudo install -g oxygen-cli ``` In case you encounter some permission errors during installation, you can try the following: ```bash sudo npm install --unsafe-perm --verbose -g oxygen-cli ``` ### Configuration Oxygen CLI doesn't come bundled with Selenium nor Appium and requires installing them manually. #### Desktop web applications automation Download [Selenium Standalone Server](http://www.seleniumhq.org/download/) and the drivers for browsers you wish to use: * Chrome - * Internet Explorer - * Firefox - Place everything into a single directory and launch with (update selenium version if necessary): ```bash java -Dwebdriver.chrome.driver=chromedriver.exe -Dwebdriver.ie.driver=IEDriverServer.exe -jar selenium-server-standalone-3.141.59.jar -port 4444 -timeout 320 -browserTimeout 320 ``` #### Mobile applications automation If you wish to execute CLI on mobile devices you should first read Oxygen for mobile guide and installation instructions: Download a [simulator](https://www.genymotion.com/) for the devices (optional). # Java Installation Instructions ## **Java Installation on Windows** Download Java from here: [https://www.java.com/en/download](https://www.java.com/en/download/win10.jsp) Continue with normal installation: ![](/files/-M4Y4HQffx1MegPUP4mI) Verify that java is install by opening cmd and typing java -version ![](/files/-M4Y4d2CEK8WYx1d1KWG) How to set Environment Variables 1. Click on my computer and open properties ![](/files/-M4Y4u4VwTlh4glQVdVF) 2\. Go to advanced system settings 3\. Go to environment variables ![](/files/-M4Y5FrfHQRASLtxhs0T) 4\. Click on new and name the variable as PATH 5\. Find and copy the path that leads to java\jdk\bin example: c:\Program Files\Java\jdk1.8.0\_181\bin ![](/files/-M4Y5X0mioAxn6PGI8PZ) 6\. Paste the path as the value ![](/files/-M4Y5iz0DyFnAq98bP3f) ## **Java installation for Mac OS X (10.15)** Download and install Java: Insure java is installed by typing java -version in the Terminal: ![](/files/-M4Y72sFf5-q6WhztB8j) Creating a .bash\_profile on your mac A typical install of OS X won't create a .bash\_profile for you. When you want to run functions from your command line, this is a must have. To set up the environment variables open the Terminal and go to the home folder by using the following command: "cd \~/ 1. Create a new file by typing: touch .bash\_profile 2. Edit .bash\_profle by typing: open -e .bash\_profile 3. Type: export JAVA\_HOME=$(/usr/libexec/java\_home) 4. Save the file (command + s) and return to the Terminal 5. Type: source .bash\_profile # Recording Troubleshooting Troubleshooting issues with test recording in Oxygen IDE ## Troubleshooting Script Recording Issues In order to record web scripts, Oxygen extension for Chrome needs to be installed and enabled. For Windows installation the extension is installed automatically during the installation process. For OS X & Linux the extension needs to be installed manually: [Install Oxygen Chrome Extension ](https://chrome.google.com/webstore/detail/oxygen/ibbmgejonlmocgjnkmabigdgbolcomea) Open Chrome, go to More Tools > Extensions, and verify that the extension is installed and enabled: ![Chrome Extension](/files/-M-U37H2OKdv6_US09GX) If the extension is not installed, please install it manually using the link provided above. {% hint style="info" %} On Windows, manually removing the extension from Chrome will prevent it from installing next time the IDE is updated or reinstalled. In such case it needs to be reinstalled manually. {% endhint %} # Start working with Oxygen # Getting Started - Web # Introduction - Web Testing For Oxygen IDE download instructions - please refer to the [Download Page](/download-installation-start/download-and-installation/download-oxygen-ide). The easiest way to start with Oxygen is with Oxygen IDE. It comes bundled with everything you need for developing and running tests.\ Oxygen **Mobile automation** and **Command Line (CLI)** on other hand require additional manual configuration. Please see[ Mobile introduction](https://docs.oxygenhq.org/getting-started-mobile/introduction) and [CLI Guide](https://app.gitbook.com/@cloudbeat/s/oxygen-docs/oxygen-cli/introduction-and-usage) for further details. Following guide concentrates on automation of **desktop web applications** using the IDE.[
](http://docs.oxygenhq.org/guide-web-recording.html) {% embed url="" %} {% embed url="" %} # Recording a Web Test ## Recording User Interactions For Oxygen IDE download instructions - please refer to the [Download Page](/download-installation-start/download-and-installation/download-oxygen-ide). Oxygen IDE allows you to record user interactions with the web browser and generate automation scripts.\ To begin recording open IDE and click on the microphone icon located in the top right corner. From here on, any action performed in the browser will be appended to the currently open script in the IDE. You may notice additional comment blocks preceding each command being recorded - those specify alternative locators which can be used with the command. Currently recording is supported on Chrome. {% hint style="info" %} It's advisable to disable Chrome extension when recording isn't used as it might unnecessary slow down the browser under regular use. {% endhint %} {% embed url="" %} ### Known Issues **General** * Transitions between dynamically generated iframes might fail sometimes. * Transitions between nested iframes might fail sometimes. * Transition between iframe and its parent doesn't work for pop-up windows. # Creating a Web Test ## Creating Scripts For Oxygen IDE download instructions - please refer to the [Download Page](/download-installation-start/download-and-installation/download-oxygen-ide). In this guide we will be using the following test scenario to demonstrate how to develop a simple test script: 1. Open Wikipedia website 2. Select English area 3. Enter "selenium" in the search field 4. Press "Search" button 5. Validate that the page header shows the word "Selenium" ### Basic Script Oxygen provides a number of built-in objects (modules) for automation purposes. Because in our sample scenario we want to automate only browser interactions, we will use the `web` module. Refer to API Reference for a complete list of provided modules and methods. 1. Open Wikipedia website. ```javascript web.open('https://www.wikipedia.org/'); ``` `open` command accepts only one argument - web site URL. It will open the provided URL and return once the web-page has been fully loaded. 2. Select English area. ```javascript web.click('id=js-link-box-en'); ``` 3. Enter "selenium" in the search field. ```javascript web.type('name=search', 'selenium'); ``` `type` allows typed strings into input elements and accepts two arguments: a locator which will be used for finding the element and a string which will be typed into that element. See API Reference for a list of supported locators. 4. Press "Search" (looking glass icon) button. This command will return once the web-page has been fully loaded. ```javascript web.click('name=go'); ``` Similarly to other commands `click` accepts a locator argument. It will click on the provided element and block until the new page has been fully loaded. 5. Validate that the page header shows the word "Selenium" ```javascript web.assertText('id=firstHeading', 'Selenium'); ``` `assertText` asserts whether the element contains the specified text. This command will fail the test if element doesn't contain the text or wasn't found at all. Entire script: ```javascript web.open('https://www.wikipedia.org/'); web.click('id=js-link-box-en'); web.type('name=search', 'selenium'); web.click('name=go'); web.assertText('id=firstHeading', 'Selenium'); ``` Now open a new script in the IDE and paste the above snippet into it. Save the file as `wikipedia.js`. In the dropdown menu select the browser you wish to run the script in and click Run. # Sample Project - Web Test A project should include 3 core files: **oxygen.conf.js**, which includes the project configuration, this file contains the tools for the project such as which modules to use, creating suites to run multiple scripts, reporting type, etc. **oxygen.env.js**, which includes the environments, different URLs, usernames, connection string for each environment, which can be later used by selecting the environment inside oxygen settings. **oxygen.po.js**, which includes all the page objects, locators, functions, etc.
### Simple web test example from scratch Let's start by creating a folder and inside it creating the **oxygen.env.js** and defining our environments ```javascript module.exports = { TEST: { url: 'https://test.wikipedia.org', db_con_string: 'Driver={SQL Server};Server=DESKTOP\\SQLEXPRESS;Database=test;' username: 'test.user', password: 'test123' }, PROD: { url: 'https://wikipedia.org', db_con_string: 'Driver={SQL Server};Server=DESKTOP\\SQLEXPRESS;Database=prod;', username: 'username', password: 'password' }, } ``` Now let's create the **oxygen.po.js** file ```javascript module.exports = { searchPage: { searchInput: 'id=searchInput', searchButton: '//button[@type="submit"]' }, search: (item) => { web.type(po.searchPage.searchInput, item) web.click(po.searchPage.searchButton) } } ``` Finally let's create the **oxygen.conf.js** file ```javascript module.exports = { suites: [{ name: 'End to End tests', cases: [ { path: './Scripts/01. ' }, { path: './Scripts/02. ' }, { path: './Scripts/03. ' }, ] }], modules: ['web', 'log', 'assert'], reporting: { reporters: ['html', 'json'] }, } ``` And now let's create a folder with our test scripts, our first test will be searching for Selenium in Wikipedia {% hint style="info" %} Don't forget to choose an environment {% endhint %} ![](/files/-MYnnVGJSzLML34xLedd) ```javascript web.transaction('01. Initialize') web.init() web.transaction('02. Open Wikipedia Main Page') web.open(env.url) web.transaction('03. Seach For Selenium') po.search('Selenium') web.transaction('04. Assert Results') web.assertTextPresent('Selenium') ``` The following repository is provided as a sample project. # Getting Started - Mobile # Introduction - Mobile Testing For mobile configuration instructions - please refer to [Mobile Installation Guide](/download-installation-start/download-and-installation/mobile-installation). Mobile - Getting Started: {% embed url="" %} Another example of what Oxygen-IDE is capable of: Mobile tests with Oxygen + Cloudbeat Integrated with Genymotion services: {% embed url="" %} # Recording a Test on Mobile ## Recording User Interactions For mobile configuration instructions - please refer to [Mobile Installation Guide](/download-installation-start/download-and-installation/mobile-installation). Launch Appium and start the server by clicking *Start Server* ![](/files/-M-U37DjOQhFo8t-XMz-) Select *New Session Window*...\ ![](/files/-M-U37DlH6QNVydF0tWY) This will open a new window where you can define capabilities for the application you wish to record. Add needed capabilities, optionally save them so they can be reused in the future, and click *Start Session*\ ![](/files/-M-U37DnspXNaKLmRaIh) Select *Start Recording*\ ![](/files/-M-U37DpmEFIiKnhdrOv) Locate the element you would like to tap using the elements tree. And press *Tap* ![](/files/-M-U37Drm-NVpAkSYeZd) List of recorded commands will appear in the recorder pane. Select *JS - Oxygen* to the commands for Oxygen.\ ![](/files/-M-U37DtQwuhwapUMCF1) # Creating a Test - Mobile For mobile configuration instructions - please refer to [Mobile Installation Guide](/download-installation-start/download-and-installation/mobile-installation). In this guide we will be using the following test scenario to demonstrate how to develop a simple test script: 1. Launch Calculator application. 2. Enter 2x2. 3. Validate that the result is 4. ## Basic Script Oxygen provides a number of built-in objects (modules) for automation purposes. Because in our sample scenario we want to automate only mobile application interactions, we will use the `mob` module. Refer to API Reference for a complete list of provided modules and methods. 1. Launch Calculator application. ```javascript var caps = { platformName: "Android", platformVersion: "9.0.1", deviceName: "934a9e01", appPackage: "com.android.calculator2", appActivity: "com.android.calculator2.Calculator", }; mob.init(caps); ``` In the above example , the fields 'AppPackage' and 'AppActivity' are depending on the type of phone you are using, some phones will have different path to their Calculator application. `init` command expects to receive capabilties object defining the application we would like to launch as well as the device specification. 2. Type 2x2 ```javascript mob.click('desc=2'); mob.click('desc=multiplication'); mob.click('desc=2'); ``` `click` performs tap on an element defined by a locator which will. See API Reference for a list of supported locators. 3. Validate result is 4. ```javascript mob.assertText('class=android.widget.EditText', '4'); ``` Entire script: ```javascript var caps = { platformName: "Android", platformVersion: "4.2", deviceName: "934a9e01", appPackage: "com.sec.android.app.popupcalculator", appActivity: "com.sec.android.app.popupcalculator.Calculator" }; mob.init(caps); mob.click('desc=2'); mob.click('desc=multiplication'); mob.click('desc=2'); mob.assertText('class=android.widget.EditText', '4'); ``` Now open a new script in the IDE and paste the above snippet into it. Save the file as `calculator.js`. Switch to the mobile mode by clicking phone icon, select the device on which to run the test from the dropdown menu, and click Run. # Sample Project - Mobile Similarly to web, a project should include 3 core files: **oxygen.conf.js**, which includes the project configuration, this file contains the tools for the project such as which modules to use, creating suites to run multiple scripts, reporting type, etc. **oxygen.env.js**, which includes the versions, different configurations, usernames, connection strings etc. **oxygen.po.js**, which includes all the page objects, locators, functions, etc.
### Simple mobile test example from scratch Let's start by creating a folder and inside it creating the **oxygen.env.js** and defining our app settings ```javascript module.exports = { test_version_9: { username: 'user', password: 'pass', con_string: 'Driver={SQL Server};Server=DESKTOP\\SQLEXPRESS;', capabilities: { "deviceName": "ad071702170f42d9a0", "platformVersion": "8.0.0", "platformName": "Android", "appPackage": "clalit.android", "appActivity": "clalit.android.MainActivity", "automationName": "UIAutomator2", "noReset": false } }, prod_version_9: { username: 'user', password: 'pass', con_string: 'Driver={SQL Server};Server=DESKTOP\\SQLEXPRESS;', capabilities: { "deviceName": "ad071702170f42d9a0", "platformVersion": "9.0.0", "platformName": "Android", "appPackage": "clalit.android", "appActivity": "clalit.android.MainActivity", "automationName": "UIAutomator2", "noReset": false } }, } ``` Now let's create the **oxygen.po.js** file ```javascript module.exports = { loginScreen: { usernameInput: 'id=app.android:id/user', passwordInput: 'id=app.android:id/pass', loginButton: 'id=app.android:id/login_button', }, searchScreen: { searchInput: 'id=app.android:id/search_input', searchButton: 'id=app.android:id/search_button', }, searchUser: (name) => { mob.type(po.searchScreen.searchInput, name) mob.click(po.searchScreen.searchButton) } } ``` Finally let's create the **oxygen.conf.js** file ```javascript module.exports = { suites: [{ name: 'End to End tests', cases: [ { path: './Scripts/01. ' }, { path: './Scripts/02. ' }, { path: './Scripts/03. ' }, ] }], modules: ['mob', 'log', 'assert'], reporting: { reporters: ['html', 'json'] }, } ``` And now let's create a folder with our test scripts {% hint style="info" %} Don't forget to choose an environment {% endhint %} ![](/files/-MZXlmLNhC-cSfmSutsj) ```javascript mob.transaction('01. Initialize') mob.init(env.capabilities) mob.transaction('02. Type username & password') mob.type(po.loginScreen.usernameInput, env.username) mob.type(po.loginScreen.passwordInput, env.password) mob.transaction('03. Login') mob.click(po.loginScreen.loginButton) mob.transaction('04. Search User') po.searchUser('Tony') mob.transaction('05. Assert Results') mob.assertText('android.view.View[2]/android.widget.UserText', 'Tony') ``` # Getting Started - Oxygen for Windows Desktop Automation You are now capable to automate windows applications - Windows 10 applications, including UWP, WPF, WinForms, and legacy Win32 For Windows installation instructions - please refer to [Oxygen for Windows installation](https://docs.oxygenhq.org/download-installation-start/download-and-installation/oxygen-for-windows-installation) ## Recording Windows Applications- Appium Desktop Recording of scripts for automation is not performed in the Oxygen IDE. Rather, the automation recording is achieved using Appium Desktop, which supports creating scripts for Oxygen. Recording on Appium desktop is explained here [Recording a test on Mobile](https://docs.oxygenhq.org/getting-started-mobile/getting-started-mobile/recording-mobile-tests) In order to be set-up for recording and executing tests on windows desktop, you would need to follow the same steps as you would for the getting started with Mobile testing, namely installing our customized version of Appium Desktop. When defining the Capabilities parameter in Appium Desktop, it is recommended / required to add the capability definition ``` "deviceName": "WindowsPC" ``` For example here is the capabilities as would be used inside Appium Desktop ``` { "app": "Microsoft.WindowsCalculator_8wekyb3d8bbwe!App", "platformName": "Windows", "deviceName": "WindowsPC" } ``` ## Oxygen Sample Code - Win Desktop In the following code sample we show how Oxygen will execute a test automation for windows applications (in this case- Calculator). Note that the **"deviceName": "WindowsPC"** is not needed here ``` win.init({ //"app": "Microsoft.WindowsCalculator_8wekyb3d8bbwe!App" app: "Calculator", platformName: "Windows" }); win.click("~num1Button"); win.click("~plusButton"); win.click("~num7Button"); win.click("~equalButton"); win.assertText("~CalculatorResults", "Display is 8"); ``` For a description of commands and Syntax for Windows Desktop Automation, please see the [windows automation documentation under Modules section](https://docs.oxygenhq.org/api-reference/modules/module-win) in his documentation. # Getting Started- Oxyge CLI ## Oxygen CLI For Oxygen-CLI download instructions - please refer to the [Download Page](https://docs.oxygenhq.org/download-installation-start/download-and-installation/cli-installation). ## Introduction Oxygen CLI is a command-line application for running test cases and test suites. It's intended mainly for integration with CI and build systems, but can be used as well for running scripts manually from the command-line. The results are produced as a set of XML/HTML/Excel/JSON/PDF reports plus the screenshots in case of test failures. ## Usage ```bash oxygen [OPTIONS]... FILE ``` Oxygen CLI can execute two types of files - test scripts (refered to as test cases) and test suites. Test suite allows defining and running collection of test cases. Example of test suite for desktop web applications (Selenium): ```javascript { "iterations": 2, "parallel": 1, "url": "http://localhost:4444/wd/hub", "cases": [ { "name": "case1", "path": "./testcase1.js" }, { "name": "case2", "path": "./testcase2.js" } ], "environment": { "some_parameter": "foo", "another_parameter": "bar" }, "capabilities": [ { "browserName": "ie" }, { "browserName": "chrome" } ], "options": { "autoReopen": true } } ``` Example of test suite for mobile applications (Appium): ```javascript { "iterations": 2, "parallel": 1, "server": { "host": "localhost", "port": 4723 }, "cases": [ { "name": "case1", "path": "./testcase1.js" }, { "name": "case2", "path": "./testcase2.js" } ], "environment": { "some_parameter": "foo", "another_parameter": "bar" }, "capabilities": [ { "platformName": "Android", "platformVersion": "4.2", "deviceName": "90a92348", "appPackage": "com.sec.android.app.popupcalculator", "appActivity": "com.sec.android.app.popupcalculator.Calculator" }, { "platformName": "Android", "platformVersion": "5.0", "deviceName": "ef4718a9", "appPackage": "com.sec.android.app.popupcalculator", "appActivity": "com.sec.android.app.popupcalculator.Calculator" } ] } ``` **General Options** * ```bash --rf={html|xml|excel|pdf|junit|json} ``` Format of the test reports. Default is html.\ Reports will be generated in the same directory where test script is located. * ```bash --ro=PATH ``` Output path for the report file. If specified, the report file will be simply generated in the specified directory and will overwrite any previous reports. If omitted, then report will be generated using date-time folder structure. This is the default behavior. * ```bash -i, --iter=COUNT ``` Number of times (iterations) to run the test. Default is 1. * ```bash -p, --param=FILE ``` Parameters file. If not specified an attempt will be made to load parameters from a file named same as the test script, located in the same directory, and having extension - xlsx, xls, csv, or txt. * ```bash --pm={seq|random|all} ``` Order in which to read the parameters - sequential, random, all. Default is `seq`. In `seq` and `random` modes test will run exact number of times specified with the `-i` option. In `all` mode, all available parameters will be read sequentially. This option is mutually exclusive with `-i` option. **Options for Web test** * ```bash -b, --browser={chrome|ie|firefox|safari} ``` Browser name. Default is chrome. * ```bash -s, --server=SERVER_URL ``` Selenium hub URL. Default is . * ```bash --reopen={true|false} ``` Reopen browser on each iteration. Default is false. # Running a Test Script on Windows run a test script using oxygen-cli ## Open oxygen-cli module inside node modules Open cmd and run the following command to find your node root directory: ``` $ npm -g root ``` Once inside, enter the oxygen-cli folder and open cmd inside it, your path should look like this: **C:\Users\Makeyev\AppData\Roaming\npm\node\_modules\oxygen-cli>** Now we're ready to run the script, type the following command: ```bash cls && node build\lib\cli ``` And then the path to your script (in quotes): ```bash cls && node build\lib\cli "C:\Users\Makeyev\Desktop\project\test.js" ``` {% hint style="info" %} Before running the test, make sure Selenium is running either in oxygen or as a standalone {% endhint %} ![](/files/-MKeizYH1Jts-972Vkl6) ## Run the command ![](/files/-MKemmj1KtURF1cA37Kr) oxygen will initialize it's modules and execute the script: ![](/files/-MKekzEO7ETaaywQv_7d) and finish by showing the status ![](/files/-MKeloZ_S-NWssij96P8) then will generate a reports folder inside your project folder with your test report as an html file ![](/files/-MKenXrzsZiGjVtCBtPd) ![](/files/-MKenhHe0wzeDWZeDWo1) # Running Multiple Tests (Suites) on Windows Oxygen also provides the option to run several tests one by one or parallel First, we need to create a new file called `oxygen.conf.js` inside our project folder {% hint style="info" %} for full configuration go to {% endhint %} The file should look like this: ``` module.exports = { "iterations": 1, "parallel": 1, "url": "http://localhost:4444/wd/hub", suites: [{ name: 'case1', cases: [{ path: "./test-script.js" }], }, { name: 'case2', cases: [{ path: "./second-test-script.js" }], }], "environment": { "some_parameter": "foo", "another_parameter": "bar" }, "capabilities": [ { "browserName": "chrome" } ], "options": { "autoReopen": true } } ``` We can config the number of iterations, number of parallel browsers, and add test cases inside suites And just like running a single test script, let's open the oxygen-cli folder inside node modules, open cmd and navigate to the following path: ``` cd C:\Users\YOUR-USER\AppData\Roaming\npm\node_modules\oxygen-cli ``` Now run the following command: `cls && node build\lib\cli` followed by the path to `oxygen.conf.js` file ``` cls && node build\lib\cli C:\Desktop\YourProject\oxygen.conf.js ``` {% hint style="info" %} Before running the test, make sure Selenium is running either in oxygen or as a standalone {% endhint %} And that's it, once again a report will be generated inside your project folder # Oxygen Modules | Module | Description | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | | [assert](/download-installation-start/modules/module-assert) | Provides generic assertion methods | | [date](/download-installation-start/modules/module-date) | Provides methods for working with dates | | [db](/download-installation-start/modules/module-db) | Provides methods for working with Data Bases through ODBC | | [email](/download-installation-start/modules/module-email) | Provides methods for working with email via IMAP | | [eyes](/download-installation-start/modules/module-eyes) | Provides access to Applitools Eyes service | | [http](/download-installation-start/modules/module-http) | Provides methods for working with HTTP(S) | | [log](/download-installation-start/modules/module-log) | Provides methods for printing user defined messages to test results | | [mailinator](/download-installation-start/modules/module-mailinator) | Provides methods for working with Mailinator service - [www.mailinator.com](http://www.mailinator.com) | | [mob](/download-installation-start/modules/module-mob) | Provides methods for mobile automation using Appium | | [pdf](/download-installation-start/modules/module-pdf) | Provides generic methods for asserting PDF file's content | | [proxy](/download-installation-start/modules/module-proxy) | Provides methods for intercepting network traffic via mitmproxy | | [serial](/download-installation-start/modules/module-serial) | Provides methods for working with serial ports | | [shell](/download-installation-start/modules/module-shell) | Provides methods for working with operating system shell | | [soap](/download-installation-start/modules/module-soap) | Provides methods for working with SOAP based Web Services | | [twilio](/download-installation-start/modules/module-twilio) | Provides methods for working with Twilio service | | [utils](/download-installation-start/modules/module-utils) | Provides miscellaneous utility methods | | [web](/download-installation-start/modules/module-web) | Provides methods for browser automation using Selenium and WebDriver | | [win](/download-installation-start/modules/module-win) | Provides methods for Windows native applications automation using Microsoft WinAppDriver | # assert Provides generic assertion methods. ## contain Asserts that the string value contains a substring. **Parameters:** | Name | Type | Description | | ---------- | -------- | ----------------------------------------------- | | `actual` | `String` | Actual value. | | `contains` | `String` | Verbatim string to be contained. | | `message` | `String` | `optional` Message to throw if assertion fails. | ## equal Asserts that two values are equal (non-strict equality). **Parameters:** | Name | Type | Description | | ---------- | -------- | -------------------------------------------------------------------- | | `actual` | `Object` | Actual value. | | `expected` | `Object` | Expected value. Either an object or a string prefixed with `regex:`. | | `message` | `String` | `optional` Message to throw if assertion fails. | ## fail Fails test with the given message. **Parameters:** | Name | Type | Description | | --------- | -------- | ----------------------------------- | | `message` | `String` | `optional` Error message to return. | ## notEqual Asserts that two values are not equal (non-strict inequality). **Parameters:** | Name | Type | Description | | ---------- | -------- | -------------------------------------------------------------------- | | `actual` | `Object` | Actual value. | | `expected` | `Object` | Expected value. Either an object or a string prefixed with `regex:`. | | `message` | `String` | `optional` Message to throw if assertion fails. | ## pass Passes the test with the given message. **Parameters:** | Name | Type | Description | | --------- | -------- | ----------------------------- | | `message` | `String` | `optional` Message to return. | # date Provides methods for working with dates. ## fromNow Returns a future or a past date **Parameters:** | Name | Type | Description | | -------- | -------- | --------------------------------------------------------------------------- | | `unit` | `String` | Unit type. See | | `value` | `Number` | Number of minutes/days/months/etc to add or subtract from the current date. | | `format` | `String` | Format string. | **Returns:** `String` - Date formatted according to the specified format string. ## now Returns current date and time See for supported format strings. **Parameters:** | Name | Type | Description | | -------- | -------- | -------------- | | `format` | `String` | Format string. | **Returns:** `String` - Date formatted according to the specified format string. # db Provides methods for working with Data Bases through ODBC. {% hint style="warning" %} Before using this module, make sure to install `unixodbc`: * Windows - Install `Windows SDK` * OS X - `brew install unixodbc` * Linux - `sudo apt-get install unixodbc unixodbc-dev` or `sudo dnf install unixODBC unixODBC-devel` {% endhint %} ## callProcedure Calls a stored procedure. \*\* Usage example:\*\* ```javascript // calls a procedure which expects two input parameters and one output parameter. var result = db.callProcedure('test', 3, 4, undefined); log.info(result); ``` **Parameters:** | Name | Type | Description | | ------ | ----------- | -------------------------------------------------------------------------------------------------------------------------- | | `name` | `String` | Name of the procedure to call. | | `args` | `...Object` | `optional` Procedure arguments. If procedure produces output parameters then these need to be specified using `undefined`. | **Returns:** `Object` - Procedure output if any. ## executeNonQuery Executes SQL statement. Any results from the query are discarded. **Parameters:** | Name | Type | Description | | ------- | -------- | --------------------- | | `query` | `String` | The query to execute. | ## executeQuery Executes SQL query and returns the result set. **Parameters:** | Name | Type | Description | | ------- | -------- | --------------------- | | `query` | `String` | The query to execute. | **Returns:** `Object` - The result set. ## getScalar Executes SQL query and returns the first column of the first row in the result set. **Parameters:** | Name | Type | Description | | ------- | -------- | --------------------- | | `query` | `String` | The query to execute. | **Returns:** `Object` - The first column of the first row in the result set, or null if the result set is empty. ## setConnectionString Sets DB connection string to be used by other methods. This method doesn't actually open the connection as it's opened/closed automatically by query methods.\ Example connection strings:\ \- `Driver={MySQL ODBC 9.0 Unicode Driver};Server=localhost;Database=myDatabase; User=myUsername;Password=myPassword;Option=3;`\ \- `Driver={Oracle in instantclient_11_2};dbq=127.0.0.1:1521/XE;uid=myUsername; pwd=myPassword;` **Parameters:** | Name | Type | Description | | ------------ | -------- | ----------------------- | | `connString` | `String` | ODBC connection string. | # email Provides methods for working with email via IMAP. ## getLastEmail Retrieves last unseen email. \*\* Usage example:\*\* ```javascript email.init('[YOUR_EMAIL]@gmail.com', 'password', 'imap.gmail.com', 993, true, 3000); var mail = email.getLastEmail(60, 'email subject', 5000); log.info(mail); if(r.attachments && r.attachments.length > 0){ const fs = require('fs'); r.attachments.map((attachment) => { let fileDescriptor; try{ fileDescriptor = fs.openSync(attachment.filename, 'w'); } catch(e) { throw 'could not open file: ' + e; } try{ fs.writeFileSync(fileDescriptor, attachment.data); } catch(e) { throw 'error writing file: ' + e; } fs.closeSync(fileDescriptor); }); } ``` **Parameters:** | Name | Type | Description | | -------------- | ----------------- | --------------------------------------------------------------------------- | | `sinceMinutes` | `Number` | Search for emails received since the specified amount of minutes into past. | | `subject` | `String`\|`Regex` | Return email matching the specified subject. | | `timeout` | `Number` | Timeout (in milliseconds) for waiting for the message to arrive. | **Returns:** `Object` - Email body, text, textAsHtml, attachments if any, and TO, FROM, SUBJECT, DATE headers. ## init Set email connection details. **Parameters:** | Name | Type | Description | | ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------- | | `user` | `String` | Username (e.g. ''). | | `password` | `String` | Password. | | `host` | `String` | Host name (e.g. 'imap.gmail.com'). | | `port` | `Number` | Port number (e.g. 993). | | `tls` | `Boolean` | true to use TLS, false otherwise. | | `authTimeout` | `Number` | `optional` Authentication timeout in milliseconds. | | `enableSNI` | `Boolean` | `optional` Enable sending SNI when establishing the connection. This is required for some mail servers. Default is false. | ## send Send email using SMTP. **Parameters:** | Name | Type | Description | | --------- | ----------------- | ---------------------------------------- | | `to` | `String`\|`Array` | Receiver's email address. | | `subject` | `String` | Email subject. | | `content` | `String` | Email body as a plain text. | | `html` | `String` | `optional` Optional, Email body as HTML. | # eyes Provides access to Applitools Eyes service. ## check Preform visual validation for a certain target. **Parameters:** | Name | Type | Description | | ------ | -------- | --------------------------------------- | | `name` | `string` | A name to be associated with the match. | ## checkWindow Takes a snapshot of the application under test and matches it withthe expected output. ## dispose Closes Applitools Eyes session, terminates the sequence of checkpoints, and then waits for and returns the test results. **Returns:** `TestResult` - Eyes test result. ## init Initializes Applitools Eyes session. **Parameters:** | Name | Type | Description | | -------- | ------------------ | ---------------------------------------------------------------------------------------- | | `module` | `string`\|`object` | A module name or a reference to the mododule to be associated with Eyes current session. | # http Provides methods for working with HTTP(S) ## assertCookie Assert if HTTP cookie is presented in the response **Parameters:** | Name | Type | Description | | -------------------- | -------- | ------------------------------------------------- | | `cookieName` | `String` | A HTTP cookie name. | | `cookieValuePattern` | `String` | `optional` An optional HTTP cookie value pattern. | ## assertHeader Assert if HTTP header is presented in the response **Parameters:** | Name | Type | Description | | -------------------- | -------- | ------------------------------------------------- | | `headerName` | `String` | A HTTP header name. | | `headerValuePattern` | `String` | `optional` An optional HTTP header value pattern. | ## assertResponseTime Assert response time **Parameters:** | Name | Type | Description | | --------- | -------- | -------------------------------------- | | `maxTime` | `Number` | Maximum response time in milliseconds. | ## assertStatus Assert the last HTTP response's status code **Parameters:** | Name | Type | Description | | ---------- | ----------------- | ---------------------------------------- | | `codeList` | `Number`\|`Array` | A single status code or a list of codes. | ## assertStatusOk Assert HTTP 200 OK status ## assertText Assert whether the specified pattern is present in the response body. **Parameters:** | Name | Type | Description | | --------- | -------- | ------------------ | | `pattern` | `String` | Pattern to assert. | ## delete Performs HTTP DELETE **Parameters:** | Name | Type | Description | | --------- | -------- | ------------------------ | | `url` | `String` | URL. | | `headers` | `Object` | `optional` HTTP headers. | | `data` | `Object` | Data. | **Returns:** `Object` - Response object. ## get Performs HTTP GET \*\* Usage example:\*\* ```javascript // Basic usage example: var response = http.get( 'https://api.github.com/repos/oxygenhq/oxygen-ide/releases', { 'Accept-Encoding': 'gzip, deflate', 'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:86.0) Gecko/20100101 Firefox/86.0' }); log.info(response.body); // If server returns Deflate-compressed stream without headers, `deflateRaw` can be used to decompress the content. http.setOptions({ deflateRaw: true }); var response = http.get('https://FOO.BAR'); log.info(response.body); ``` **Parameters:** | Name | Type | Description | | --------- | -------- | ------------------------ | | `url` | `String` | URL. | | `headers` | `Object` | `optional` HTTP headers. | **Returns:** `Object` - Response object. ## getResponse Returns last response object **Returns:** `Object` - Response object. ## getResponseBody Returns last response body **Returns:** `String` - Response body. ## getResponseHeaders Returns response headers **Returns:** `Object` - Response headers. ## getResponseUrl Returns response URL **Returns:** `String` - Response URL. ## patch Performs HTTP PATCH **Parameters:** | Name | Type | Description | | --------- | -------- | ------------------------ | | `url` | `String` | URL. | | `data` | `Object` | Data. | | `headers` | `Object` | `optional` HTTP headers. | **Returns:** `Object` - Response object. ## post Performs HTTP POST **Parameters:** | Name | Type | Description | | ------------ | --------- | --------------------------------------------------------------------- | | `url` | `String` | URL. | | `data` | `Object` | Data. | | `headers` | `Object` | `optional` HTTP headers. | | `isFormData` | `Boolean` | `optional` Indicates if "data" parameter is of URL-encoded form type. | **Returns:** `Object` - Response object. ## put Performs HTTP PUT **Parameters:** | Name | Type | Description | | --------- | -------- | ------------------------ | | `url` | `String` | URL. | | `data` | `Object` | Data. | | `headers` | `Object` | `optional` HTTP headers. | **Returns:** `Object` - Response object. ## setNtlmUser Sets user credentials for NTLM authentication process **Parameters:** | Name | Type | Description | | ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `username` | `String` | NTLM username. | | `password` | `String` | NTLM password. | | `domain` | `String` | `optional` NTLM domain name, if applicable.In addition to the options listed in the linked document, 'deflateRaw' option can be used when server returns Deflate-compressed stream without headers. | ## setOptions Sets user defined HTTP options (such as proxy, decompress and etc.) **Parameters:** | Name | Type | Description | | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `opts` | `Object` | HTTP request options object, see [Request Options](https://github.com/sindresorhus/got/blob/main/documentation/2-options.md). In addition to the options listed in the linked document, 'deflateRaw' option can be used when server returns Deflate-compressed stream without headers. | ## setProxy Sets proxy url to be used for connections with the service. **Parameters:** | Name | Type | Description | | ----- | -------- | -------------------------------------------------------------------------- | | `url` | `String` | Proxy server URL. Not passing this argument will reset the proxy settings. | ## transaction Opens new transaction. The transaction will persist till a new one is opened. Transaction names must be unique. **Parameters:** | Name | Type | Description | | ------ | -------- | --------------------- | | `name` | `String` | The transaction name. | # log Provides methods for printing user defined messages to test results. ## debug Print a DEBUG message. **Parameters:** | Name | Type | Description | | ----- | -------- | ----------------- | | `msg` | `String` | Message to print. | ## error Print an ERROR message. **Parameters:** | Name | Type | Description | | ----- | -------- | ----------------- | | `msg` | `String` | Message to print. | ## info Print an INFO message. **Parameters:** | Name | Type | Description | | ----- | -------- | ----------------- | | `msg` | `String` | Message to print. | ## warn Print a WARN message. This will mark the test with Warning status (unless the test fails later on, then it will be marked as Failed.). **Parameters:** | Name | Type | Description | | ----- | -------- | ----------------- | | `msg` | `String` | Message to print. | # mailinator Provides methods for working with Mailinator service - www\.mailinator.com ## delete Deletes sepcific email. \*\* Example of the returned object:\*\* ```json { "status": "ok" } ``` **Parameters:** | Name | Type | Description | | ---- | -------- | ----------- | | `id` | `String` | Message ID. | **Returns:** `Object` - Status. ## fetch Fetches specific email. \*\* Example of the returned object:\*\* ```json { "data": { "fromfull":"noreply@example.com", "headers": { ... email headers ... }, "subject":"test subject", "requestId":"REQUEST ID", "parts": [ { "headers":{ "content-type":"text/plain; charset=utf-8" }, "body":"EMAIL BODY (TEXT)" }, { "headers":{ "content-type":"text/html; charset=utf-8" }, "body":"EMAIL BODY (HTML)" } ], "from":"Test Tester", "origfrom":"Test Tester noreply@example.com", "to":"cb-test-2", "id":"RANDOMLY GENERATED ID", "time":1491200030000, "seconds_ago":1174 }, "apiEmailFetchesLeft":1999 } ``` **Parameters:** | Name | Type | Description | | ---- | -------- | ----------- | | `id` | `String` | Message ID. | **Returns:** `Object` - Email details. E.g. ## getBody Extracts first available email body. **Parameters:** | Name | Type | Description | | ---------- | -------- | ------------------------------------------ | | `emailObj` | `Object` | Email object returned by mailiniator.fetch | **Returns:** `String` - Email body. ## getSubject Extracts email's subject. **Parameters:** | Name | Type | Description | | ---------- | -------- | ------------------------------------------ | | `emailObj` | `Object` | Email object returned by mailiniator.fetch | **Returns:** `String` - Email subject. ## init Initializes mailinator module. **Parameters:** | Name | Type | Description | | --------------- | -------- | ----------------------------------------------------- | | `token` | `String` | API token. | | `privateDomain` | `String` | `optional` Specifies whether to use a private domain. | ## list Fetches inbox messages or all saved messages. \*\* Example of the returned object:\*\* ```json { "messages": [ { "fromfull": "noreply@example.com", "subject": "Subject", "from": "Test Tester", "origfrom": "Test Tester noreply@example.com", "to": "inbox-name", "id": "RANDOMLY GENERATED ID", "time": 1491200030000, "seconds_ago": 234 }, ] } ``` **Parameters:** | Name | Type | Description | | ------- | -------- | ------------------------------------------------------------------------- | | `inbox` | `String` | `optional` Inbox name. If ommited saved messages will be fetched instead. | **Returns:** `Object` - List containing message details. # mob Provides methods for mobile automation. **Locators:** Native application locators for![](/files/-LzMCnYgv7H6u3PgSgCn) * `/XPATH` - Locates element using an XPath 1.0 expression. * `~ACCESSIBILITY_ID` - Locates element by its Accessibility Id. * `id=ID` - Locates element by its id. * `class=CLASS` - Locates element by its class. * `text=TEXT` - Locates element by its visible text. * `text-contains=TEXT` - Locates element whose visible text contains the specified string. * `desc=DESCRIPTION` - Locates element by its description. * `desc-contains=DESCRIPTION` - Locates element whose description contains the specified string. * `scrollable` - Locates elements that are scrollable. Native application locators for![](/files/-LzMCnYj4jzbe0FF-lfz) * `/XPATH` - Locates element using an XPath 1.0 expression. * `id=ID` - Locates element by its ID. * `~ACCESSIBILITY_ID` - Locates element by its Accessibility Id. * `-ios predicate string:PREDICATE_STRING` - Locates element using a [predicate query](https://github.com/facebookarchive/WebDriverAgent/wiki/Predicate-Queries-Construction-Rules). * `-ios class chain:CLASS_CHAIN` - Locates element using a [class chain expression](https://github.com/facebookarchive/WebDriverAgent/wiki/Class-Chain-Queries-Construction-Rules). Hybrid![](/files/-LzMCnYlcIVyA_03dlwr) and Web![](/files/-LzMCnYnarLXRJuo9Y-H) application locators for![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) * `/XPATH` - Locates element using an XPath 1.0 expression. * `id=ID` - Locates element by its id. * `name=NAME` - Locates element by its name attribute. * `tag=NAME` - Locates element by its tag name. * `link=TEXT` - Locates anchor element whose text matches the given string. * `link-contains=TEXT` - Locates anchor element whose text contains the given string. * `css=CSS_SELECTOR` - Locates element using a CSS selector. **Pattern arguments:** Commands which expect a string matching pattern in their arguments, support following patterns unless specified otherwise: * `regex:PATTERN` - Match using regular expression. * `PATTERN` - Verbatim matching. ## alertAccept Accepts an alert or a confirmation dialog. In case of an alert box this command is identical to `alertDismiss`. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.click("id=Submit");// Clicks an element and opens an alert. mob.alertAccept();//Automatically press on 'OK' button in the alert pop-up. ``` **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## alertDismiss Dismisses an alert or a confirmation dialog. In case of an alert box this command is identical to `alertAccept`. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.click("id=Submit");// Clicks an element and opens an alert. mob.alertDismiss();//Automatically press on 'Cancel' button in the alert pop-up. ``` **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## assertAlert Asserts whether alert matches the specified pattern and dismisses it. Text pattern can be any of the supported string matching patterns(on the top of page). \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.click("id=Submit");// Clicks an element and opens an alert. mob.assertAlert("Your Alert's text");//Asserts the alert's text. ``` **Parameters:** | Name | Type | Description | | --------- | -------- | ---------------------------------------------------------- | | `pattern` | `String` | Text pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Supported On**: ![](/files/-LzMCnYnarLXRJuo9Y-H) ## assertText Asserts element's inner text. Text pattern can be any of the supported string matching patterns (on the top of page). If the element is not interactable, then it will allways return empty string as its text. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.assertText("id=UserName","John Doe");// Asserts if an element’s text is as expected. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `pattern` | `String` | Assertion text or pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## assertTitle Asserts the page title. Assertion pattern can be any of the supported string matching patterns(on the top of page). \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.assertTitle("Your websites title!");// Asserts if the title of the page. ``` **Parameters:** | Name | Type | Description | | --------- | -------- | ---------------------------------------------------------- | | `pattern` | `String` | Assertion text or pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Supported On**: ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## assertValue Asserts element's value. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.assertValue("id=UserName", "John Doe");// Asserts if the value of an element. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `pattern` | `String` | Value pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## back Navigate backwards in the browser history or simulates back button on Android device. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.click("id=NextPage);// Clicks an element and opens an alert. mob.back();//Navigate back to previous page. ``` **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## clear Clears element's value or content \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.type("id=Password", "Password");//Types a password to a field. mob.clear("id=Password");//Clears the characters from the field of an element. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## click Clicks on an element. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.click("id=Submit");// Clicks an element. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## clickHidden Clicks on a non-visible element. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.clickHidden("id=hiddenContent);// Clicks an hidden element. ``` **Parameters:** | Name | Type | Description | | ------------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `clickParent` | `Boolean` | `optional` If true, then parent of the element is clicked. | **Supported On**: ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## clickLong Performs a long click/touch on an element. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.clickLong("id=Mark",6000);// Clicks an element for a certain duration. ``` **Parameters:** | Name | Type | Description | | ---------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `duration` | `Number` | Touch duration in milliseconds. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## clickMultipleTimes Performs tap on an element multiple times in quick succession. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.clickMultipleTimes("id=Mark",4);// Clicks an element certain amount of times. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `taps` | `Number` | Number of taps. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## closeApp Closes the currently open app. \*\* Usage example:\*\* ```javascript mob.init(caps); // Starts a mobile session and opens app from desired capabilities mob.launchApp(); // Launch the app. mob.closeApp(); // Close the app. ``` **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ## debug Stop test execution and allow interactive command execution (REPL). \*\* Usage example:\*\* ```javascript mob.init(); mob.open("www.yourwebsite.com"); mob.debug(); ``` **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## dispose Ends the current session. **Parameters:** | Name | Type | Description | | -------- | -------- | ---------------------------------------------------- | | `status` | `String` | `optional` Test status, either `passed` or `failed`. | ## dragAndDrop Tap on an element, drag by the specified offset, and release. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.dragAndDrop("id=Mark",-80,100);// Tap on an element, drag by the specified offset, and release. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ------------------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator on which to perform the initial tap. | | `xoffset` | `Number` | Horizontal offset. Positive for right direction; Negative for left. | | `yoffset` | `Number` | Vertical offset. Positive for down direction; Negative for up. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ## enableNetwork Enable or disable wifi or data. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.enableNetwork(true,false);//Enable wifi and disable data. ``` **Parameters:** | Name | Type | Description | | ------ | --------- | -------------------------------------- | | `wifi` | `Boolean` | Enable (true) or disable (false) wifi. | | `data` | `Boolean` | Enable (true) or disable (false) data. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ## execute Executes JavaScript in the context of the currently selected frame or window. If return value is null or there is no return value, `null` is returned. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.execute(function(){ angular.element("#closeBtn").trigger('ng-click').click() });//Executes / injects a javascript functions. ``` **Parameters:** | Name | Type | Description | | -------- | -------------------- | ---------------------------------------------------------------------- | | `script` | `String`\|`Function` | The JavaScript to execute. | | `arg` | `...Object` | `optional` Optional arguments to be passed to the JavaScript function. | **Returns:** `Object` - The return value. **Supported On**: ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## findElement Finds an element. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities var el = mob.findElement("id=Password"); mob.click(el); ``` **Parameters:** | Name | Type | Description | | --------- | --------- | ---------------------------------------------------------- | | `locator` | `String` | Element locator. | | `parent` | `Element` | `optional` Optional parent element for relative search. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `Element` - A Element object. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## findElements Finds elements. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities var els = mob.findElements("//div"); for (let el of els) { var text = mob.getText(el); log.info(text); } ``` **Parameters:** | Name | Type | Description | | --------- | --------- | ---------------------------------------------------------- | | `locator` | `String` | Element locator. | | `parent` | `Element` | `optional` Optional parent element for relative search. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `Array.` - Collection of Element objects. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## getAlertText Gets the text displayed by an alert or confirm dialog. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.click("id=Submit");// Clicks an element and opens an alert. var a = mob.getAlertText();//Gets alert text. ``` **Returns:** `String` - Alert's text. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## getAppiumLogs Collects logs from the Appium server. \*\* Usage example:\*\* ```javascript mob.init(caps); //Starts a mobile session and opens app from desired capabilities mob.getAppiumLogs(); //Collects logs from the Appium server ``` **Returns:** `Array.` - A list of logs. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## getBrowserLogs Collects browser logs from the mobile device. \*\* Usage example:\*\* ```javascript mob.init(caps); //Starts a mobile session and opens app from desired capabilities mob.getBrowserLogs(); //Collects logs from the browser console ``` **Returns:** `Array.` - A list of logs. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## getCapabilities Returns currently defined capabilities. **Returns:** `Object` - Current capabilities object. ## getCurrentActivity Gets current Android app's activity name. \*\* Usage example:\*\* ```javascript mob.init(caps); // Starts a mobile session and opens app from desired capabilities let activity = mob.getCurrentActivity(); // Gets current Android activity. ``` **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ## getCurrentPackage Gets current Android app's package name. \*\* Usage example:\*\* ```javascript mob.init(caps); // Starts a mobile session and opens app from desired capabilities let package = mob.getCurrentPackage(); // Gets current Android package. ``` **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ## getDeviceLogs Collects logs from the mobile device. \*\* Usage example:\*\* ```javascript mob.init(caps); //Starts a mobile session and opens app from desired capabilities mob.getDeviceLogs(); //Collects logs from the mobile device ``` **Returns:** `Array.` - A list of logs. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## getDeviceTime Gets the time on the device. \*\* Usage example:\*\* ```javascript mob.init(caps); //Starts a mobile session and opens app from desired capabilities mob.getDeviceTime(); //Gets the device time ``` **Returns:** `String` - Time. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ## getDriver Returns the underlying WDIO driver. **Returns:** `Object` - WDIO driver. ## getLocation Get element's location. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities var loc = mob.getLocation("id=element");//Get element's location. var x = loc.x; var y = loc.y; ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `Object` - X and Y location of the element relative to top-left page corner. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## getSource Gets the source code of the page. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities var a = mob.getSource();//Gets the source code of the page. ``` **Returns:** `String` - HTML in case of web or hybrid application or XML in case of native. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## getText Returns the text (rendered text shown to the user; whitespace-trimmed) of an element. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities var a = mob.getText("id=TextArea");//Gets the text from an element. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `String` - Element's text. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## getTitle Returns the title of the currently active window. **Returns:** `String` - The page title. **Supported On**: ![](/files/-LzMCnYnarLXRJuo9Y-H) ## getUrl Gets the URL of the currently active window. \*\* Usage example:\*\* ```javascript mob.init();//Opens browser session. mob.open("www.yourwebsite.com");// Opens a website. mob.getUrl();//Gets the url from the current page. ``` **Returns:** `String` - The page URL. **Supported On**: ![](/files/-LzMCnYnarLXRJuo9Y-H) ## getValue Gets element's value (whitespace-trimmed). \*\* Usage example:\*\* ```javascript mob.init(caps); var a = mob.getValue("id=ValueArea");//Gets the value from an element. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `String` - Element's value. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## getWindowHandles Gets handles of currently open windows. \*\* Usage example:\*\* ```javascript mob.init();// Starts a mobile session. mob.open("www.yourwebsite.com");// Opens a website. mob.getWindowHandles();//Gets the window handles of currently open windows. ``` **Returns:** `Array.` - Array of all available window handles. **Supported On**: ![](/files/-LzMCnYnarLXRJuo9Y-H) ## hideKeyboard Hides device keyboard. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.type("id=Password", "Password");//Types a password to a field. mob.hideKeyboard("pressKey", "Done");//Hides device keyboard. ``` **Parameters:** | Name | Type | Description | | ---------- | -------- | -------------------------------------------------------------------------------------------------------------------------- | | `strategy` | `String` | `optional` Strategy to use for closing the keyboard - 'press', 'pressKey', 'swipeDown', 'tapOut', 'tapOutside', 'default'. | | `key` | `String` | `optional` Key value if strategy is 'pressKey'. | | `keyCode` | `String` | `optional` Key code if strategy is 'pressKey'. | | `keyName` | `String` | `optional` Key name if strategy is 'pressKey'. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## init Initializes a new Appium session. **Parameters:** | Name | Type | Description | | ----------- | -------- | --------------------------------------------------------------------------------------------------- | | `caps` | `String` | `optional` Desired capabilities. If not specified capabilities will be taken from suite definition. | | `appiumUrl` | `String` | `optional` Remote Appium server URL (default: ). | ## installApp Install an app on the remote device. \*\* Usage example:\*\* ```javascript mob.init(caps); // Starts a mobile session and opens app from desired capabilities mob.installApp('/mylocalappfile.apk'); // Install the app. ``` **Parameters:** | Name | Type | Description | | -------------- | -------- | --------------------------------------- | | `appLocalPath` | `String` | The local file path to APK or IPA file. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ## isAppInstalled Determines if an app is installed on the device. \*\* Usage example:\*\* ```javascript mob.init(caps); //Starts a mobile session and opens app from desired capabilities let installed = mob.isAppInstalled('com.android.calculator2'); // Determines if calculator app is installed. ``` **Parameters:** | Name | Type | Description | | ----- | -------- | ----------- | | `app` | `String` | App's ID. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ## isCheckable Determines if checkbox or radio element is checkable. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.isCheckable("id=checkBox");//Determines if checkbox or radio element is checkable. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `Boolean` - true if element is checkable. false otherwise. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ## isChecked Determines if checkbox or radio element is checked. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.isChecked("id=checkBox");//Determines if checkbox or radio element is checked. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `Boolean` - true if element is checked. false otherwise. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ## isClickable Determines if an element is clickable. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.isClickable("id=Element");//Determines if element is clickable. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `Boolean` - true if element is clickable. false otherwise. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ## isExist Wait for an element to become available. The element is not necessary needs to be visible. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.isExist("id=Element");//Determines if element exists. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ------------------------------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Time in milliseconds to wait for the element. Default is 60 seconds. | **Returns:** `Boolean` - true if the element exists. false otherwise. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## isSelected Determines if an element is selected. \*\* Usage example:\*\* ```javascript mob.init(caps); var a = mob.isSelected("id=Selection"); if (a) { ... } else { ... } ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `Boolean` - true if element is selected. false otherwise. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## isVisible Checks if element is present and visible. Returns false if element was not found or wasn't visible within the specified timeout. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.isVisible("id=Selection");//Determines if element is visible. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds to wait for element to appear. Default is 60 seconds. | **Returns:** `Boolean` - True if element was found and it was visible. False otherwise. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## isWebViewContext Checks if the current context is of WebView type. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.isWebViewContext();//Checks if the current context is of WebView type. ``` **Returns:** `Boolean` - true if the context name is WEBVIEW or CHROMIUM. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## launchApp Launches the app defined in the current session's capabilities. \*\* Usage example:\*\* ```javascript mob.init(caps); // Starts a mobile session and opens app from desired capabilities mob.launchApp(); // Launch the app defined in the session's capabilities. ``` **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ## longPressKeyCode Press and hold a particular key code on the device. \*\* Usage example:\*\* ```javascript https://developer.android.com/reference/android/view/KeyEvent.html - list of key codes mob.init();//Starts a mobile session mob.open('https://keycode.info/'); mob.longPressKeyCode(32);// 32 - d key ``` **Parameters:** | Name | Type | Description | | --------- | -------- | ------------------------------- | | `keycode` | `Number` | Key code pressed on the device. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## open Opens an URL. The `open` command waits for the page to load before proceeding. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.open('www.yourwebsite.com');//Opens an URL. ``` **Parameters:** | Name | Type | Description | | ----- | -------- | --------------------------------------------- | | `url` | `String` | The URL to open; may be relative or absolute. | **Supported On**: ![](/files/-LzMCnYnarLXRJuo9Y-H) ## pause Pause test execution for the given amount of milliseconds. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.pause(10*1000);//Pauses the execution for 10 seconds (10000ms) ``` **Parameters:** | Name | Type | Description | | ---- | -------- | ---------------------------------------- | | `ms` | `Number` | Milliseconds to pause the execution for. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## removeApp Remove an app from the device. \*\* Usage example:\*\* ```javascript mob.init(caps); // Starts a mobile session and opens app from desired capabilities mob.removeApp('com.android.calculator2'); // Remove the calculator app from the device. ``` **Parameters:** | Name | Type | Description | | ----- | -------- | ----------- | | `app` | `String` | App's ID. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ## resetApp Reset the currently running app's state (e.g. local settings) on the device. \*\* Usage example:\*\* ```javascript mob.init(caps); // Starts a mobile session and opens app from desired capabilities mob.resetApp(); // Reset curently running app ``` **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ## scrollIntoElement Scrolls the view element until a specified target element inside the view is found. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.scrollIntoElement('id=bottomPanel','id=Button',0,30,50);//Scrolls the view element until a specified target element inside the view is found. ``` **Parameters:** | Name | Type | Description | | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `scrollElmLocator` | `String` | View element to scroll. | | `findElmLocator` | `String` | Target element to find in the view. | | `xoffset` | `Number` | `optional` Indicates the size in pixels of the horizontal scroll step (positive - scroll right, negative - scroll left). Default is 0. | | `yoffset` | `Number` | `optional` Indicates the size in pixels of the vertical scroll step (positive - scroll down, negative - scroll up). Default is 30. | | `retries` | `Number` | `optional` Indicates the number of scroll retries before giving up if element not found. Default is 50. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | | `duration` | `Number` | `optional` Duration of swipe. Default is 3000 (3sec) | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ## scrollIntoView Scrolls the page or a container element to the location of the specified element. \*\* Usage example:\*\* ```javascript mob.scrollIntoView('id=bottomPanel', true); // or mob.scrollIntoView('id=bottomPanel', { behavior: 'auto', // Optional. Defines the transition animation: `auto` or `smooth`. Defaults to `auto`. block: 'start', // Optional. Defines vertical alignment - `start`, `center`, `end`, `nearest`. Defaults to `start`. inline: 'start' // Optional. Defines horizontal alignment - `start`, `center`, `end`, `nearest`. Defaults to `start`. }); ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `options` | `Boolean`\|`Object` | `optional` If `true`, the top of the element will be aligned to the top of the visible area of the scrollable ancestor. This is the default. If `false`, the bottom of the element will be aligned to the bottom of the visible area of the scrollable ancestor. This parameter can also accept an `options` object. See the usage example above. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Supported On**: ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## select Selects an option from a drop-down list using an option locator. This command works with multiple-choice lists as well. Option locator can be one of the following (No prefix is same as label matching):\ \- `label=STRING` - Matches option based on the visible text.\ \- `value=STRING` - Matches option based on its value.\ \- `index=STRING` - Matches option based on its index. The index is 0-based. \*\* Usage example:\*\* ```javascript mob.init(); //Starts a mobile session mob.open("www.yourwebsite.com");// Opens a website. mob.select("id=Selection","label=United States");// Selects an option from a list. ``` **Parameters:** | Name | Type | Description | | --------------- | -------- | ---------------------------------------------------------- | | `selectLocator` | `String` | An element locator identifying a drop-down menu. | | `optionLocator` | `String` | An option locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Supported On**: ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## selectFrame Selects a frame or an iframe within the current window. Available frame locators:\ \- `'parent'` - Select parent frame.\ \- `'top'` - Select top window.\ \- `NUMBER` - Select frame by its 0-based index.\ \- `LOCATOR` - Locator identifying the frame (relative to the top window). Multiple locators can be passed in order to switch between nested frames. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.selectFrame("//iframe[@id='frame1']", "//iframe[@id='nested_frame']"); ``` **Parameters:** | Name | Type | Description | | -------------- | --------------------- | ------------------------------------------------------------------------------ | | `frameLocator` | `...String`\|`Number` | `optional` A locator identifying the frame or iframe. Or a series of locators. | **Supported On**: ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## selectWindow Selects window. Once window has been selected, all commands go to that window. `windowLocator` can be: * `title=TITLE` Switch to the first window which matches the specified title. `TITLE` can be any ofthe supported string matching patterns (see top of the page). When using title locator, this commandwill wait for the window to appear first similarly to `waitForWindow` command. * `url=URL` Switch to the first window which matches the specified URL. `URL` can be any ofthe supported string matching patterns (see top of the page). When using url locator, this commandwill wait for the window to appear first similarly to `waitForWindow` command. * `windowHandle` Switch to a window using its unique handle. \*\* Usage example:\*\* ```javascript mob.init();// Starts a mobile session. mob.open("www.yourwebsite.com");// Opens a website. mob.selectWindow("title=Website");// Selects and focus a window. ``` **Parameters:** | Name | Type | Description | | --------------- | -------- | ------------------------------------------------------------------------------------------------------ | | `windowLocator` | `String` | `optional` Window locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds when using 'title' window locating strategy. Default is 60 seconds. | **Returns:** `String` - windowHandle of the previously selected window. **Supported On**: ![](/files/-LzMCnYnarLXRJuo9Y-H) ## sendKeys Send a sequence of keyboard strokes to the active window or element. Refer to [Key Codes](https://w3c.github.io/webdriver/#keyboard-actions) for the list of supported raw keyboard key codes. \*\* Usage example:\*\* ```javascript mob.init();//Opens browser session. mob.open("www.yourwebsite.com");// Opens a website. mob.sendKeys("Hello World"); mob.sendKeys(["Backspace", "Backspace", "Enter"]); // send two Backspace key codes and Enter. // Unicode representation can be used directly as well: mob.sendKeys("Hello World\uE003\uE003\uE007"); ``` **Parameters:** | Name | Type | Description | | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------- | | `value` | `String`\|`Array.` | Sequence of key strokes to send. Can be either a string or an array of strings for sending raw key codes. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## setContext Sets a specific context (NATIVE\_APP, WEBVIEW, etc.). \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.setContext('NATIVE_APP');//Sets a specific context (NATIVE_APP, WEBVIEW, etc.). ``` **Parameters:** | Name | Type | Description | | --------- | -------- | ----------------- | | `context` | `String` | The context name. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## setNativeContext Sets context to NATIVE\_APP. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.setNativeContext();//Sets context to NATIVE_APP. ``` **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## setTimeout Specifies the amount of time that Oxygen will wait for actions to complete. This includes the `open` command, `waitFor*` commands, and commands which wait for elements to appear in DOM or become visible before operating on them.\ If command wasn't able to complete within the specified period it will fail the test.\ The default time-out is 60 seconds. \*\* Usage example:\*\* ```javascript mob.init();//Opens browser session. mob.setTimeout(60000);//Sets the time out to amount of milliseconds . ``` **Parameters:** | Name | Type | Description | | --------- | -------- | --------------------------- | | `timeout` | `Number` | A time-out in milliseconds. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## setWebViewContext Sets context to the first available WEBVIEW or CHROMIUM (Crosswalk WebView) view. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.setWebViewContext();//Sets context to the first available WEBVIEW or CHROMIUM (Crosswalk WebView) view. ``` **Returns:** `String` - Context name, or null if no web context found. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## shake Perform shake action on the device Supported on Android and iOS 9 or earlier versions. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.shake();//Perform shake action on the device. ``` **Supported On**: ![](/files/-LzMCnYj4jzbe0FF-lfz) ## smsClickLink Clicks SMS message URL. `SMSPopup` application must be installed and running on the device to use this command. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.click("id=sendSmS");// Clicks an element. mob.smsClickLink(60000);//Clicks SMS message URL. ``` **Parameters:** | Name | Type | Description | | --------- | -------- | ----------------------------------------------------------------------------- | | `timeout` | `Number` | `optional` Time in milliseconds to wait for sms popup. Default is 60 seconds. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ## smsGetText Gets SMS text on Android phone. `SMSPopup` application must be installed and running on the device to use this command. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.click("id=sendSmS");// Clicks an element. var a = mob.smsGetText(60000);//Gets SMS text on Android phone. ``` **Parameters:** | Name | Type | Description | | --------- | -------- | ----------------------------------------------------------------------------- | | `timeout` | `Number` | `optional` Time in milliseconds to wait for sms popup. Default is 60 seconds. | **Returns:** `String` - SMS text. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ## swipe Perform a swipe on an element. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.swipe("id=Element",-60,0,150);//Perform a swipe on the screen or an element. ``` **Parameters:** | Name | Type | Description | | ---------- | ------------------- | --------------------------------------------------------------------------------------------- | | `locator` | `String`\|`Element` | Locator of the element to swipe on. | | `xoffset` | `Number` | `optional` Horizontal offset (positive - scroll right, negative - scroll left). Default is 0. | | `yoffset` | `Number` | `optional` Vertical offset (positive - scroll down, negative - scroll up). Default is 30. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | | `duration` | `Number` | `optional` Duration of swipe. Default is 3000 (3sec) | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ## swipeElement Perform swipe on the element. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.swipeElement("id=Element",-60,0,150);//Perform a swipe on the screen or an element. ``` **Parameters:** | Name | Type | Description | | ---------- | -------- | --------------------------------------------------------------------------------------------- | | `locator` | `String` | Locator of the element to swipe on. | | `xoffset` | `Number` | `optional` Horizontal offset (positive - scroll right, negative - scroll left). Default is 0. | | `yoffset` | `Number` | `optional` Vertical offset (positive - scroll down, negative - scroll up). Default is 30. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | | `duration` | `Number` | `optional` Duration of swipe. Default is 3000 (3sec) | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ## swipeScreen Perform a swipe on the screen. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.swipeScreen(0, 0, 0, 900);//Perform a swipe on the screen ``` **Parameters:** | Name | Type | Description | | ---------- | -------- | ---------------------------------------------------------- | | `x1` | `Number` | Starting X position (top-left screen corner is the origin) | | `y1` | `Number` | Starting Y position. | | `x2` | `Number` | Ending X position. | | `y2` | `Number` | Ending Y position. | | `duration` | `Number` | `optional` Duration of swipe. Default is 3000 (3sec) | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ## takeScreenshot Take a screenshot of the current page or screen and return it as base64 encoded string. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities var ss = mob.takeScreenshot();//Take a screenshot of the current page or screen and return it as base64 encoded string. require("fs").writeFileSync("c:\\screenshot.png", ss, 'base64'); ``` **Returns:** `String` - Screenshot image encoded as a base64 string. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## tap Perform tap at the specified coordinate. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.tap(60,300);//Perform tap at the specified coordinate. ``` **Parameters:** | Name | Type | Description | | ---- | -------- | ----------- | | `x` | `Number` | x offset. | | `y` | `Number` | y offset. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ## transaction Opens new transaction. The transaction will persist till a new one is opened. Transaction names must be unique. **Parameters:** | Name | Type | Description | | ------ | -------- | --------------------- | | `name` | `String` | The transaction name. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## type Send a sequence of key strokes to an element (clears value before). Refer to [Key Codes](https://w3c.github.io/webdriver/#keyboard-actions) for the list of supported raw keyboard key codes. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.type('id=TextArea', 'hello world\uE007'); ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `value` | `String` | The value to type. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## unlockPattern Unlocks a pattern lock **:** ``` 1 2 3 4 5 6 7 8 9 a b c ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ----------------------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator for the pattern lock. | | `cols` | `Number` | Number of columns in the pattern. | | `rows` | `Number` | Number of rows in the pattern. | | `pattern` | `String` | Pattern sequence. Pins are hexadecimal and case sensitive. See example. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ## waitForExist Wait for an element for the provided amount of milliseconds to exist in DOM. The element is not necessary needs to be visible. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.waitForExist('id=Element');//Wait for an element for the provided amount of milliseconds to exist in DOM. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ------------------------------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Time in milliseconds to wait for the element. Default is 60 seconds. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## waitForInteractable Waits for element to become interactable. \*\* Usage example:\*\* ```javascript mob.init();//Opens browser session. mob.waitForInteractable("id=UserName");//Waits for an element is clickable in DOM. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) ## waitForVisible Waits for element to become visible. \*\* Usage example:\*\* ```javascript mob.init(caps);//Starts a mobile session and opens app from desired capabilities mob.waitForVisible("id=Title", 45*1000);//Waits for an element to be visible. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ------------------------------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Time in milliseconds to wait for the element. Default is 60 seconds. | > **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ![](/files/-LzMCnYj4jzbe0FF-lfz) ![](/files/-LzMCnYlcIVyA_03dlwr) ![](/files/-LzMCnYnarLXRJuo9Y-H) # pdf Provides generic methods for working with PDF files. ## assert Asserts that text is present in a PDF file **Parameters:** | Name | Type | Description | | ------------- | --------- | ------------------------------------------------ | | `pdfFilePath` | `String` | Relative or absolute path to the PDF file. | | `text` | `String` | Text to assert. | | `pageNum` | `Number` | `optional` Page number. | | `message` | `String` | `optional` Message to throw if assertion fails. | | `reverse` | `Boolean` | `optional` Check also reverse variant of string. | ## assertNot Asserts that text is not present in a PDF file **Parameters:** | Name | Type | Description | | ------------- | --------- | ------------------------------------------------ | | `pdfFilePath` | `String` | Relative or absolute path to the pdf file. | | `text` | `String` | Text to assert. | | `pageNum` | `Number` | `optional` Page number. | | `message` | `String` | `optional` Message to throw if assertion fails. | | `reverse` | `Boolean` | `optional` Check also reverse variant of string. | ## count Count the number of times specified text is present in a PDF file. **Parameters:** | Name | Type | Description | | ------------- | --------- | ------------------------------------------------ | | `pdfFilePath` | `String` | Relative or absolute path to the pdf file. | | `text` | `String` | Text to count. | | `pageNum` | `Number` | `optional` Page number. | | `reverse` | `Boolean` | `optional` Check also reverse variant of string. | **Returns:** `Number` - Number of times the specified text was found. # proxy Provides methods for intercepting network traffic via mitmproxy. ## assertStatusCode Assert whether HTTP response status code matches the specified value. **Parameters:** | Name | Type | Description | | ---------------- | ------------------ | ----------------------------------------------------- | | `url` | `String`\|`RegExp` | A request URL to match verbatim or a RegExp. | | `statusCode` | `Number` | A response status code to match verbatim or a RegExp. | | `failureMessage` | `String` | `optional` An optional failure message. | | `timeout` | `Number` | `optional` Timeout. Default is 60 seconds. | **Returns:** `Object` - Network request details if the network request was found. ## assertUrl Assert if network request matching the specified URL. **Parameters:** | Name | Type | Description | | --------- | ------------------ | -------------------------------------------- | | `url` | `String`\|`RegExp` | A request URL to match verbatim or a RegExp. | | `timeout` | `Number` | `optional` Timeout. Default is 60 seconds. | **Returns:** `Object` - Network request details if the network request was found. ## dispose Disposes this module. ## getRequests Return all the collected network requests so far. **Returns:** `Array.` - Array containing network requests. ## init Initializes proxy. \*\* Launching mitmproxy manually:\*\* ```shell mitmdump --anticache -s mitmproxy-node\scripts\proxy.py --ssl-insecure --set httpCommPort=8765 ``` **Parameters:** | Name | Type | Description | | ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `proxyPort` | `Number` | Proxy port. | | `proxyCommPort` | `Number` | `optional` Port for internal proxy communication. If specified, then mitmproxy should be launched manually.Otherwise mitmpoxy will be launched automatically. | | `saveRequestBody` | `Boolean` | `optional` Save request bodies. | | `saveResponseBody` | `Boolean` | `optional` Save response bodies. | ## start Begin collecting network requests. Any previously collected requests will be discarded. \*\* Usage example:\*\* ```javascript proxy.init(8080); proxy.start(); // print the collected request so far: let requests = proxy.getRequests(); for (let req of requests) { log.info(req); } // wait for a request using a verbatim URL match: proxy.waitForUrl('https://www.yourwebsite.com/foo/bar'); // wait for a request using a regular expression URL match: proxy.waitForUrl(/https:\/\/.*\/foo\/bar/); // wait for a request using a custom matcher: proxy.waitFor(function (request) { return request.status === '200' && request.url === 'https://www.yourwebsite.com/foo/bar'; }); ``` ## stop Stop collecting network requests. ## waitFor Wait for a network request. **Parameters:** | Name | Type | Description | | --------- | ---------- | ------------------------------------------------------------------- | | `matcher` | `Function` | Matching function. Should return true on match, or false otherwise. | | `timeout` | `Number` | `optional` Timeout. Default is 60 seconds. | **Returns:** `Object` - Network request details if the network request was found. ## waitForUrl Wait for a network request matching the specified URL. **Parameters:** | Name | Type | Description | | --------- | ------------------ | ------------------------------------------ | | `pattern` | `String`\|`RegExp` | An URL to match verbatim or a RegExp. | | `timeout` | `Number` | `optional` Timeout. Default is 60 seconds. | **Returns:** `Object` - Network request details if the network request was found. # serial Provides methods for working with serial ports. ## getBuffer Return data buffer. **Returns:** `CircularStringBuffer` - Data buffer. ## list Returns list of available ports. See for details about the structure of returned values. **Returns:** `Array.` - Array of port descriptions. ## open Opens a serial port. Data from the opened port will be automatically read line by line into a circular buffer. Once the buffer reaches it's maximum capacity specified by `bufferSize` argument, eldest entries are evicted to make room for new data. \*\* Serial port properties with default values:\*\* ```json { baudRate: 9600, dataBits: 8, // Must be one of: 8, 7, 6, or 5. stopBits: 1, // Must be one of: 1 or 2. parity: 'none' // Must be one of: 'none', 'even', 'mark', 'odd', 'space'. rtscts: false, xon: false, xoff: false, xany: false } ``` **Parameters:** | Name | Type | Description | | ------------ | -------- | ----------------------------------------------------------------- | | `port` | `String` | Path to serial port. E.g. '/dev/tty-usbserial1', 'COM5', etc. | | `opts` | `Object` | Port properties. | | `bufferSize` | `Number` | `optional` Size of the input data buffer. Default is 65536 bytes. | **Returns:** `SerialPort` - SerialPort object. ## waitForText Waits for text to appear in the input data buffer. Text pattern can be any of the supported string matching patterns(on the top of page). **Parameters:** | Name | Type | Description | | --------- | -------- | ---------------------------------------------------------- | | `pattern` | `String` | Text pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## write Write data to the port. \*\* Usage example:\*\* ```javascript serial.write('Hello\r\n'); ``` **Parameters:** | Name | Type | Description | | ------ | ----------------- | --------------------------------------------------- | | `data` | `String`\|`Array` | Data to send. Either a string or an array of bytes. | # shell Provides methods for working with operating system shell. ## assertErrorOutput Assert that the shell command's error output (stderr) matches the specified pattern. **Parameters:** | Name | Type | Description | | --------- | -------- | ------------------ | | `pattern` | `String` | Pattern to assert. | ## assertOutput Assert that the shell command's output (stdout) matches the specified pattern. **Parameters:** | Name | Type | Description | | --------- | -------- | ------------------ | | `pattern` | `String` | Pattern to assert. | ## exec Execute command Spawn child process **Parameters:** | Name | Type | Description | | --------- | -------- | ----------------------------------------------------------------- | | `command` | `String` | Shell command to be executed, including arguments, if applicable. | **Returns:** `Object` - Response object containing stdout, stderr, exit code, and signal (if process was terminated by a signal). # soap Provides methods for working with SOAP based Web Services. ## authBasic Sets Basic Authentication details to be used for connections with the service. **Parameters:** | Name | Type | Description | | ------ | -------- | ----------- | | `user` | `String` | Username. | | `pass` | `String` | Password. | ## authBearer Sets Bearer Token Authentication details to be used for connections with the service. **Parameters:** | Name | Type | Description | | ------- | -------- | ----------- | | `token` | `String` | Token. | ## authClientSSL Sets Client SSL Authentication details to be used for connections with the service. **Parameters:** | Name | Type | Description | | --------- | --------------------------- | -------------------------------------------------------- | | `key` | `Buffer`\|`String` | Private key path or a Buffer containing the key. | | `cert` | `Buffer`\|`String` | Certificate path or a Buffer containing the certificate. | | `ca` | `Buffer`\|`String`\|`Array` | CA path or a Buffer. | | `options` | `Object` | `optional` Options. | ## authClientSSLPFX Sets Client SSL (PFX) Authentication details to be used for connections with the service. **Parameters:** | Name | Type | Description | | ------------ | ------------------ | ----------------------------------------------- | | `pfx` | `Buffer`\|`String` | PFX path or a Buffer containing the PFX bundle. | | `passphrase` | `Buffer`\|`String` | `optional` Passphrase for the PFX. | | `options` | `Object` | `optional` Options. | ## authNTLM Sets NTLM Authentication details to be used for connections with the service. **Parameters:** | Name | Type | Description | | ------------- | -------- | ------------ | | `user` | `String` | Username. | | `pass` | `String` | Password. | | `domain` | `String` | Domain. | | `workstation` | `String` | Workstation. | ## describe Returns SOAP service description. **Parameters:** | Name | Type | Description | | ------------- | -------- | ----------------------------------------------------------- | | `wsdlUrl` | `String` | URL pointing to the WSDL XML. | | `wsdlHeaders` | `Object` | `optional` custom HTTP headers to be sent on WSDL requests. | **Returns:** `Object` - Service description. ## get Initiates a SOAP request and returns the response. \*\* Usage example:\*\* ```javascript // get SOAP service description, so we can understand what methods it provides, // what input parameters it expects, and what is the output structure. var serviceUrl = 'http://www.dataaccess.com/webservicesserver/numberconversion.wso?WSDL'; var serviceDescription = soap.describe(serviceUrl); log.info(serviceDescription); // NumberToWords method in this service converts number to words. var result = soap.get(serviceUrl, 'NumberToWords', { 'ubiNum': 2019 }); log.info(result.NumberToWordsResult); ``` **Parameters:** | Name | Type | Description | | ------------- | -------- | ----------------------------------------------------------- | | `wsdlUrl` | `String` | URL pointing to the WSDL XML. | | `method` | `String` | Method name (case sensitive). | | `args` | `Object` | `optional` Object containing the arguments. | | `wsdlHeaders` | `Object` | `optional` custom HTTP headers to be sent on WSDL requests. | **Returns:** `Object` - The response object. ## getLastResponseHeaders Returns last response headers. **Returns:** `Object` - IncomingHttpHeaders (). ## setProxy Sets proxy url to be used for connections with the service. **Parameters:** | Name | Type | Description | | ----- | -------- | --------------------------------------------------------------------------- | | `url` | `String` | Proxy url. Invocation without arguments will remove any previously set url. | # twilio Provides methods for working with Twilio service. ## getLastSentApiSms Retrieves last SMS message sent from API. **Parameters:** | Name | Type | Description | | -------------- | --------- | ------------------------------------------------------------------------------------------------------- | | `removeOnRead` | `Boolean` | Specifies whether to delete the message after reading it. | | `timeout` | `Number` | Timeout in milliseconds for waiting for the message to arrive. | | `notOlderThan` | `Number` | `optional` Retrieve message only if it arrived not before the given time (in ms). Default is 4 minutes. | **Returns:** `String` - SMS text. ## getLastSms Retrieves last SMS message. **Parameters:** | Name | Type | Description | | -------------- | --------- | ------------------------------------------------------------------------------------------------------- | | `removeOnRead` | `Boolean` | Specifies whether to delete the message after reading it. | | `timeout` | `Number` | Timeout in milliseconds for waiting for the message to arrive. | | `notOlderThan` | `Number` | `optional` Retrieve message only if it arrived not before the given time (in ms). Default is 4 minutes. | | `fromNumber` | `String` | `optional` From number to filter message | **Returns:** `String` - SMS text. ## init Set Twilio authentication details. **Parameters:** | Name | Type | Description | | ------------ | -------- | --------------------- | | `accountSid` | `String` | Account SID. | | `authToken` | `String` | Authentication token. | ## sendSms Send an SMS. \*\* Usage example:\*\* ```javascript twilio.init('Account Sid', 'Account Token'); twilio.sendSms('+1xxxxxxxxxx', '+972xxxxxxxxx', 'Hello World!'); ``` **Parameters:** | Name | Type | Description | | --------- | -------- | -------------------------- | | `from` | `String` | Phone number to send from. | | `to` | `String` | Phone number to send to. | | `message` | `String` | Message to send. | **Returns:** `String` - Message SID. # utils Provides miscellaneous utility methods. ## decrypt Decrypt text \*\* Usage example:\*\* ```javascript // to encrypt plaintext into ciphertext const encrypt = utils.encrypt('https://www.wikipedia.org'); log.info(encrypt); // will print b757ba2c2fc50fbb511d596816ca06c4fa56f4e98ce222f30bc58d5251ed635e // to decrypt ciphertext and use it in script const decrypt = utils.decrypt(encrypt); log.info(decrypt); // will print ENCRYPTED web.init(); web.open(decrypt); // will open https://www.wikipedia.org // to get original plaintext use getDecryptResult const value = decrypt.getDecryptResult(); log.info(value); //will print https://www.wikipedia.org ``` **Parameters:** | Name | Type | Description | | ------ | -------- | ----------- | | `text` | `String` | Text | **Returns:** `Object` - DecryptResult Object with getDecryptResult method ## dnsResolve Uses the DNS protocol to resolve a host name **Parameters:** | Name | Type | Description | | ---------- | -------- | ---------------------------------------------- | | `hostname` | `String` | Host name to resolve. | | `rrType` | `String` | `optional` Resource record type. Default: 'A'. | **Returns:** `(Array.|Object)` - Array or Object of resource records. The type and structure of individual results vary based on rrtype ## encrypt Encrypt text \*\* Usage example:\*\* ```javascript // to encrypt plaintext into ciphertext const encrypt = utils.encrypt('https://www.wikipedia.org'); log.info(encrypt); // will print b757ba2c2fc50fbb511d596816ca06c4fa56f4e98ce222f30bc58d5251ed635e // to decrypt ciphertext and use it in script const decrypt = utils.decrypt(encrypt); log.info(decrypt); // will print ENCRYPTED web.init(); web.open(decrypt); // will open https://www.wikipedia.org // to get original plaintext use getDecryptResult const value = decrypt.getDecryptResult(); log.info(value); //will print https://www.wikipedia.org ``` **Parameters:** | Name | Type | Description | | ------ | -------- | ----------- | | `text` | `String` | Text | **Returns:** `String` - Encrypted text ## pause Pause test execution for the given amount of milliseconds. **Parameters:** | Name | Type | Description | | ---- | -------- | ---------------------------------------- | | `ms` | `Number` | Milliseconds to pause the execution for. | ## readCsv Reads data from csv file **Parameters:** | Name | Type | Description | | ---------- | -------- | ------------------------------------------------------- | | `filePath` | `String` | Absolute path to file | | `options` | `Object` | `optional` [Options](https://csv.js.org/parse/options/) | ## readXlsx Reads data from Xlsx file **Parameters:** | Name | Type | Description | | ---------- | -------- | --------------------- | | `filePath` | `String` | Absolute path to file | **Returns:** `Array` - Array of xlsx data ## transaction Opens new transaction. The transaction will persist untill a new one is opened. Transaction names must be unique. **Parameters:** | Name | Type | Description | | ------ | -------- | --------------------- | | `name` | `String` | The transaction name. | ## writeCsv Writes data into csv file **Parameters:** | Name | Type | Description | | ---------- | -------- | ---------------------------------------------------------------------------------------------- | | `filePath` | `String` | Absolute path to file | | `data` | `Array` | CSV data in format \[{column\_name\_1: 'foo', column\_name\_2: 'bar'}] | | `options` | `Object` | `optional` [Options](https://github.com/anton-bot/objects-to-csv#async-todiskfilename-options) | ## xmlToJson Parse XML data to JS object **Parameters:** | Name | Type | Description | | ------------ | ------------------- | ---------------------------------------------------------------------------------------------------------- | | `xmlDataStr` | `string`\|`Buffer` | Like | | `options` | `boolean`\|`Object` | [Options](https://github.com/NaturalIntelligence/fast-xml-parser/blob/master/docs/v4/2.XMLparseOptions.md) | # web Provides methods for browser automation. **Notes:** Commands which operate on elements such as click, assert, waitFor, type, select, and others will automatically wait for a period of time for the element to appear in DOM and become visible. By default this period equals to 60 seconds, but can be changed using the `setTimeout`command. **String matching patterns:** Commands which expect a string matching pattern in their arguments, support following patterns unless specified otherwise: * `regex:PATTERN` - Match using regular expression. * `regexi:PATTERN` - Match using case-insensitive regular expression. * `exact:STRING` - Match the string verbatim. * `glob:PATTERN` - Match using case-insensitive glob pattern. `?` will match any single character except new line (\n). `*` will match any sequence (0 or more) of characters except new line. Empty PATTERN will match only other empty strings. * `PATTERN` - Same as glob matching. **Locators:** Commands which expect an element locator in their arguments, support following locator types unless specified otherwise: * `id=ID` - Locates element by its ID attribute. * `css=CSS_SELECTOR` - Locates element using a CSS selector. * `link=TEXT` - Locates link element whose visible text matches the given string. * `link-contains=TEXT` - Locates link element whose visible text contains the given string. * `name=NAME` - Locates element by its NAME attribute. * `tag=NAME` - Locates element by its tag name. * `/XPATH` - Locates element using an XPath 1.0 expression. * `(XPATH)[]` - Locates element using an XPath 1.0 expression. ## alertAccept Accepts an alert or a confirmation dialog. In case of an alert box this command is identical to `alertDismiss`. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session web.open("www.yourwebsite.com");// Opens a website. web.click("id=SaveButton");//Clicks on save – an alert would pop up web.alertAccept();//Clicks on "OK" in the alert dialog. ``` ## alertDismiss Dismisses an alert or a confirmation dialog. In case of an alert box this command is identical to `alertAccept`. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session web.open("www.yourwebsite.com");// Opens a website. web.click("id=SaveButton");//Clicks on save – an alert would pop up web.alertDismiss();//Clicks on Cancel in the alert dialog. ``` ## assertAlert Asserts whether alert matches the specified pattern and dismisses it. Text pattern can be any of the supported string matching patterns(on the top of page). \*\* Usage example:\*\* ```javascript web.init();//Opens browser session web.open("www.yourwebsite.com");// Opens a website. web.click("id=SaveButton");//Clicks on save – an alert would pop up web.assertAlert("Your Alert's text");//Asserts the alert's text. ``` **Parameters:** | Name | Type | Description | | --------- | -------- | ---------------------------------------------------------- | | `pattern` | `String` | Text pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## assertExist Asserts whether element exists in the DOM. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session web.open("www.yourwebsite.com");// Opens a website. web.assertExist ("id=Username");// Asserts if an element exists in the DOM. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## assertSelectedLabel Asserts text of the currently selected option in a drop-down list. Assertion pattern can be any of the supported string matching patterns(on the top of page). \*\* Usage example:\*\* ```javascript web.init();//Opens browser session web.open("www.yourwebsite.com");// Opens a website. web.assertSelectedLabel("id=Selection", "United States");// Asserts if an element's label is selected in the drop down list. ``` **Parameters:** | Name | Type | Description | | ---------------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `pattern` | `String` | The assertion pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | | `waitForVisible` | `Boolean` | `optional` Wait for visible. | ## assertSelectedValue Asserts value of the currently selected option in a drop-down list. Assertion pattern can be any of the supported string matching patterns(on the top of page). \*\* Usage example:\*\* ```javascript web.init();//Opens browser session web.open("www.yourwebsite.com");// Opens a website. web.assertSelectedValue("id=Selection", "3");// Asserts if an element's value is selected in the drop down list. ``` **Parameters:** | Name | Type | Description | | ---------------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `pattern` | `String` | The assertion pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | | `waitForVisible` | `Boolean` | `optional` Wait for visible. | ## assertText Asserts element's inner text. Text pattern can be any of the supported string matching patterns(on the top of page). If the element is not interactable, then it will allways return empty string as its text. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session web.open("www.yourwebsite.com");// Opens a website. web.assertText ("id=UserName","John Doe");// Asserts if an element's text is as expected. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `pattern` | `String` | Text pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## assertTextNotPresent Asserts whether the given text is *not* present on the page. That is, whether there are no elements containing this text on the page. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session web.open("www.yourwebsite.com");// Opens a website. web.assertTextNotPresent("John Doe");// Asserts if a text is not presented somewhere on the page. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `text` | `String`\|`Element` | Text. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## assertTextPresent Asserts whether the given text is present somewhere on the page. That is whether an element containing this text exists on the page. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session web.open("www.yourwebsite.com");// Opens a website. web.assertTextPresent("John Doe");// Asserts if a text is presented somewhere on the page. ``` **Parameters:** | Name | Type | Description | | --------- | -------- | ---------------------------------------------------------- | | `text` | `String` | Text. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## assertTitle Asserts the page title. Assertion pattern can be any of the supported string matching patterns(on the top of page). \*\* Usage example:\*\* ```javascript web.init();//Opens browser session web.open("www.yourwebsite.com");// Opens a website. web.assertTitle("Your websites title!");// Asserts the title of the page. ``` **Parameters:** | Name | Type | Description | | --------- | -------- | ---------------------------------------------------------- | | `pattern` | `String` | The assertion pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## assertValue Asserts element's value. Value pattern can be any of the supported string matching patterns(on the top of page). \*\* Usage example:\*\* ```javascript web.init();//Opens browser session web.open("www.yourwebsite.com");// Opens a website. web.assertValue("id=UserName", "John Doe");// Asserts the value of an element. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `pattern` | `String` | Value pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## back Navigate backwards in the browser history. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.click("id=NextPage");//Clicks on next page link. web.back();//Navigate back to previous page. ``` ## clear Clear the value of an input field. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.type("id=Password", "Password");//Types a password to a field. web.clear("id=Password");//Clears the characters from the field of an element. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## click Clicks on an element. If the click causes new page to load, the command waits for page to load before proceeding. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.click("id=NextPage");//Clicks on next page link. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## clickHidden Clicks on a non-visible element. If the click causes new page to load, the command waits for page to load before proceeding. \*\* Usage example:\*\* ```javascript web.clickHidden("id=HiddenLink"); ``` **Parameters:** | Name | Type | Description | | ------------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `clickParent` | `Boolean` | `optional` If true, then parent of the element is clicked. | ## closeWindow Closes the currently active window. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.closeWindow();//Closes the current window. ``` ## debug Stop test execution and allow interactive command execution (REPL). \*\* Usage example:\*\* ```javascript web.init(); web.open("www.yourwebsite.com"); web.debug(); ``` ## deleteCookies Delete cookies visible to the current page. **Parameters:** | Name | Type | Description | | ------- | -------------------------- | ----------------------------------------------------------- | | `names` | `String`\|`Array.` | `optional` Cookie name or a list of cookie names to delete. | ## deselect Deselects an option from multiple-choice drop-down list. Option locator can be one of the following (No prefix is same as label matching):\ \- `label=STRING` Matches option based on the visible text.\ \- `value=STRING` Matches option based on its value.\ \- `index=STRING` Matches option based on its index. The index is 0-based. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.deselect("id=Selection","label=United States");//Deselect option from multiple choice drop down list. ``` **Parameters:** | Name | Type | Description | | --------------- | -------- | ---------------------------------------------------------- | | `selectLocator` | `String` | An element locator identifying a drop-down menu. | | `optionLocator` | `String` | An option locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## dispose Ends the current session. **Parameters:** | Name | Type | Description | | -------- | -------- | ---------------------------------------------------- | | `status` | `String` | `optional` Test status, either `passed` or `failed`. | ## doubleClick Double clicks on an element. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.doubleClick("id=Mark");//Double clicks on a element. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## dragAndDrop Drag and Drop element into another element \*\* Usage example. Drops grey rectangle into red square.:\*\* ```javascript web.init(); web.open('http://webdriverjs.christian-bromann.com/'); web.dragAndDrop('id=overlay', '/html/body/section/div[1]'); web.pause(10*1000); ``` **Parameters:** | Name | Type | Description | | ------------ | -------- | ---------------------------------------------------------- | | `srcElement` | `String` | Element to drag and drop. | | `dstElement` | `String` | Destination element to drop into. | | `duration` | `Number` | `optional` How long the drag should take place. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## execute Executes JavaScript in the context of the currently selected frame or window. If return value is null or there is no return value, `null` is returned. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.execute(function() { angular.element(".password").trigger("ng-click").click() } );//Executes/injects JavaScript code. ``` **Parameters:** | Name | Type | Description | | -------- | -------------------- | ---------------------------------------------------------------------- | | `script` | `String`\|`Function` | The JavaScript to execute. | | `arg` | `...Object` | `optional` Optional arguments to be passed to the JavaScript function. | **Returns:** `Object` - The return value. ## fileBrowse Uploads a local file \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.fileBrowse("id=ProfilePicture","C:\\picture.jpg");//Uploads a file to an element. ``` **Parameters:** | Name | Type | Description | | ---------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Locator for a `input type=file` element. | | `filepath` | `String` | Path to a local file. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## findElement Finds an element. \*\* Usage example:\*\* ```javascript web.open('https://www.wikipedia.org'); var el = web.findElement("id=js-link-box-en"); web.click(el); ``` **Parameters:** | Name | Type | Description | | --------- | --------- | ---------------------------------------------------------- | | `locator` | `String` | Element locator. | | `parent` | `Element` | `optional` Optional parent element for relative search. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `Element` - A Element object. ## findElements Finds elements. \*\* Usage example:\*\* ```javascript web.open('https://www.wikipedia.org'); var els = web.findElements("//div"); for (let el of els) { var text = web.getText(el); log.info(text); } ``` **Parameters:** | Name | Type | Description | | --------- | --------- | ---------------------------------------------------------- | | `locator` | `String` | Element locator. | | `parent` | `Element` | `optional` Optional parent element for relative search. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `Array.` - Collection of Element objects. ## fullscreenWindow Fullscreen Window. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.fullscreenWindow(); ``` ## getAlertText Gets the text displayed by an alert or confirm dialog. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. var text = web.getAlertText();//Gets the text in the alert dialog. ``` **Returns:** `String` - The alert's text. ## getAttribute Returns the element's attribute. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.getAttribute("id=UserName","value");//Gets an attribute from an element. ``` **Parameters:** | Name | Type | Description | | ----------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `attribute` | `String` | The name of the attribute to retrieve. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `String` - The attribute's value or null if no such attribute. ## getBrowserLogs Collects logs from the browser console. Works only in Chrome. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. var logs = web.getBrowserLogs(); //Collects logs from the browser console ``` **Returns:** `Array.` - An array of browser console logs. **Supported On**: ## getCapabilities Returns currently defined capabilities. **Returns:** `Object` - Current capabilities object. ## getCookies Returns a specific cookie or a list of cookies visible to the current page. **Parameters:** | Name | Type | Description | | ------- | -------- | --------------------------------- | | `names` | `String` | Names of the cookies to retrieve. | **Returns:** `String` - The attribute's value. ## getCssValue Returns the value of a CSS property of an element. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.getCssValue("id=UserName","color");//Gets a CSS value from an element. ``` **Parameters:** | Name | Type | Description | | -------------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `propertyName` | `String` | CSS property name. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `String` - CSS property value or null if no such property. ## getDriver Returns the underlying WDIO driver. **Returns:** `Object` - WDIO driver. ## getElementCount Retrieves the count of elements matching the given locator. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. var count = web.getElementCount("//*[@class=Title]");//Gets the element count. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------- | | `locator` | `String`\|`Element` | Element locator. | **Returns:** `Number` - Element count or 0 if no elements were found. ## getHTML Gets source code of specified DOM element. \*\* Usage example:\*\* ```javascript web.getHTML("id=Username", false); ``` **Parameters:** | Name | Type | Description | | ------------------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `includeElementTag` | `Boolean` | If true, it includes the element tag. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `String` - Source code of the element. ## getSource Gets the source of the currently active window. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.getSource();//Gets the source of the page. ``` **Returns:** `String` - The page source. ## getText Returns the text (rendered text shown to the user; whitespace-trimmed) of an element. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. var text = web.getText("id=Title");//Gets the text from an element. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `String` - The element's text. ## getTitle Returns the title of the currently active window. **Returns:** `String` - The page title. ## getUrl Gets the URL of the currently active window. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.getUrl();//Gets the url from the current page. ``` **Returns:** `String` - The page URL. ## getValue Returns the (whitespace-trimmed) value of an input field. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.getValue("id=UserName");//Gets the value from an element. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `String` - The value. ## getWindowHandles Gets handles of currently open windows. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.getWindowHandles();//Gets the window handles of currently open windows. ``` **Returns:** `Array.` - Array of all available window handles. ## getWindowSize Sets the size of the outer browser window. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. const sizeObject = web.getWindowSize(); ``` **Returns:** `Object` - Size object. Example: { height: 1056, width: 1936, x: -8, y: -8 } ## getXMLPageSource Gets the source of the currently active window which displays `text/xml` page. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. var src = web.getXMLPageSource();//Gets the source of currently active window which displays `text/xml` page. ``` **Returns:** `String` - The XML page source. ## init Initializes new Selenium session. **Parameters:** | Name | Type | Description | | ------------- | -------- | --------------------------------------------------------------------------------------------------- | | `caps` | `String` | `optional` Desired capabilities. If not specified capabilities will be taken from suite definition. | | `seleniumUrl` | `String` | `optional` Remote server URL (default: ). | ## isAlertPresent Return true if alert dialog is currently present on the screen. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. var alertPresent = web.isAlertPresent();//Returns true if the alert dialog is displayed. ``` **Returns:** `Boolean` - True if alert is present, false otherwise. ## isChecked ***deprecated*** Use isSelected instead. Determines if checkbox or radio element is checked. \*\* Usage example:\*\* ```javascript web.init(caps); var checked = web.isChecked("id=checkBox"); ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `Boolean` - true if element is checked. false otherwise. **Supported On**: ![](/files/-LzMCnYgv7H6u3PgSgCn) ## isExist Checks if element is present in the DOM. Returns false if element was not found within the specified timeout. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.isExist("id=SaveButton");// Returns true if the element exists in page. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds to wait for element to appear. Default is 60 seconds. | **Returns:** `Boolean` - True if element was found. False otherwise. ## isInteractable Returns true if the selected element is interactable. Element is considered interactable only if it exists, is visible, is within viewport (if not try scroll to it), its center is not overlapped with another element, and is not disabled. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. if (web.isInteractable("id=SaveButton")) { // the element is interactable } ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds to wait for element to appear. Default is 60 seconds. | **Returns:** `Boolean` - True if element is interactable. False otherwise. ## isSelected Determines whether an `option` or `input` element of type checkbox or radio is currently selected or not. \*\* Usage example:\*\* ```javascript web.init(); web.open('http://www.wikipedia.org'); var a = web.isSelected("id=Selection"); if (a) { ... } else { ... } ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `Boolean` - true if element is selected. false otherwise. ## isVisible Checks if element is present and visible. Returns false if element was not found or wasn't visible within the specified timeout. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.isVisible("id=SaveButton");// Returns true if the element is displayed in page. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds to wait for element to appear. Default is 60 seconds. | **Returns:** `Boolean` - True if element was found and it was visible. False otherwise. ## makeVisible Makes hidden element visible. This a workaround command for situations which require manipulation of hiddenelements, such as when using `web.type` command for file input fields which tend to be hidden.\ Specifically `makeVisible` will apply following styles to the specified element and all theparent elements: * visibility = 'visible' if set to 'hidden' * opacity = 1 if set to 0 * display = 'block' if set to 'none' * width/height = 1px if set to 0. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.makeVisible("id=SaveButton");// Makes an invisible/hidden element to become visible. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ----------------------------------------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. If multiple elements match the locator, visibility is applied to all. | ## maximizeWindow Maximize Window. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.maximizeWindow(); ``` ## minimizeWindow Minimize Window. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.minimizeWindow(); ``` ## mock Allows to mock the response of a request. Note: This method can be used in Chromium based browser only. **Parameters:** | Name | Type | Description | | ------------------------------- | -------------------- | -------------------------------------------------------- | | `url` | `String`\|`RegExp` | URL pattern to mock. | | `filterOptions` | `MockFilterOptions` | `optional` mock filter options (see below). | | `filterOptions.method` | `String`\|`Function` | `optional` filter resource by HTTP method. | | `filterOptions.headers` | `Object`\|`Function` | `optional` filter resource by specific request headers. | | `filterOptions.responseHeaders` | `Object`\|`Function` | `optional` filter resource by specific response headers. | | `filterOptions.postData` | `String`\|`Function` | `optional` filter resource by request postData | | `filterOptions.statusCode` | `Number`\|`Function` | `optional` filter resource by response statusCode | **Returns:** `Mock` - a mock object to modify the response ## mockClearAll Resets all mocks information stored in the session. Note: This method can be used in Chromium based browser only. ## mockRestoreAll Restores all mock information and behavior stored in the session. Note: This method can be used in Chromium based browser only. ## newWindow Opens new tab. The `newWindow` command waits for the page to load before proceeding. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.newWindow("www.yourwebsite.com");// Opens a website on new window. ``` **Parameters:** | Name | Type | Description | | ----- | -------- | --------------------------------------------- | | `url` | `String` | The URL to open; may be relative or absolute. | ## open Opens an URL. The `open` command waits for the page to load before proceeding. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. ``` **Parameters:** | Name | Type | Description | | ----- | -------- | --------------------------------------------- | | `url` | `String` | The URL to open; may be relative or absolute. | ## pause Pause test execution for the given amount of milliseconds. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.pause(10*1000);//Pauses the execution for 10 seconds (10000ms) ``` **Parameters:** | Name | Type | Description | | ---- | -------- | ---------------------------------------- | | `ms` | `Number` | Milliseconds to pause the execution for. | ## point Points the mouse cursor over the specified element. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.point("id=Selection");//Hovers a mouse over an element. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. If the element is not visible, it will be scrolled into view. | | `xOffset` | `Number` | `optional` X offset to move to, relative to the top-left corner of the element.If not specified, the mouse will move to the middle of the element. | | `yOffset` | `Number` | `optional` Y offset to move to, relative to the top-left corner of the element.If not specified, the mouse will move to the middle of the element. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## pointJS Points the mouse cursor over the specified element. This method is similar to `web.point`, however it simulates the action using JavaScript instead of using WebDriver's functionality which doesn't work in all cases. **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## refresh Causes the browser to reload the page. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.refresh();//Reloads the page ``` ## rightClick Perform right click on an element. \*\* Usage example:\*\* ```javascript web.init(); web.open("www.yourwebsite.com"); web.rightClick("id=someElement"); ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## rightClickActions Perform right click on an element. \*\* Usage example:\*\* ```javascript web.init(); web.open("www.yourwebsite.com"); web.rightClickActions("id=someElement", 10, -5); ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | | `xOffset` | `Number` | `optional` x offset in pixels. Default is 0. | | `yOffset` | `Number` | `optional` y offset in pixels. Default is 0. | ## scrollToElement Scrolls the page or a container element to the location of the specified element. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.scrollToElement("id=Button", true);// Scrolls to an element. ``` **Parameters:** | Name | Type | Description | | ------------ | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `locator` | `String`\|`Element` | An element locator. | | `alignToTop` | `Boolean` | `optional` If true, the top of the element will be aligned to the top of the visible area of the scrollable ancestor. This is the default. If false, the bottom of the element will be aligned to the bottom of the visible area of the scrollable ancestor. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## select Selects an option from a drop-down list using an option locator. This command works with multiple-choice lists as well. Option locator can be one of the following (No prefix is same as label matching):\ \- `label=STRING` - Matches option based on the visible text.\ \- `value=STRING` - Matches option based on its value.\ \- `index=STRING` - Matches option based on its index. The index is 0-based. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.select("id=Selection","label=United States");// Selects an option from a list. ``` **Parameters:** | Name | Type | Description | | --------------- | -------- | ---------------------------------------------------------- | | `selectLocator` | `String` | An element locator identifying a drop-down menu. | | `optionLocator` | `String` | An option locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## selectFrame Selects a frame or an iframe within the current window. Available frame locators:\ \- `'parent'` - Select parent frame.\ \- `'top'` - Select top window.\ \- `NUMBER` - Select frame by its 0-based index.\ \- `LOCATOR` - Locator identifying the frame (relative to the top window). Multiple locators can be passed in order to switch between nested frames. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com"); web.selectFrame("//iframe[@id='frame1']", "//iframe[@id='nested_frame']"); web.click("id=SaveButton");//Clicks on element that exists in the second iframe ``` **Parameters:** | Name | Type | Description | | -------------- | --------------------- | ------------------------------------------------------------------------------ | | `frameLocator` | `...String`\|`Number` | `optional` A locator identifying the frame or iframe. Or a series of locators. | ## selectWindow Selects window. Once window has been selected, all commands go to that window. `windowLocator` can be: * `title=TITLE` Switch to the first window which matches the specified title. `TITLE` can be any ofthe supported string matching patterns (see top of the page). When using title locator, this commandwill wait for the window to appear first similarly to `waitForWindow` command. * `url=URL` Switch to the first window which matches the specified URL. `URL` can be any ofthe supported string matching patterns (see top of the page). When using url locator, this commandwill wait for the window to appear first similarly to `waitForWindow` command. * `windowHandle` Switch to a window using its unique handle. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.selectWindow("title=Website");// Selects and focus a window. ``` **Parameters:** | Name | Type | Description | | --------------- | -------- | ------------------------------------------------------------------------------------------------------ | | `windowLocator` | `String` | `optional` Window locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds when using 'title' window locating strategy. Default is 60 seconds. | **Returns:** `String` - windowHandle of the previously selected window. ## sendKeys Send a sequence of keyboard strokes to the active window or element. Refer to [Key Codes](https://w3c.github.io/webdriver/#keyboard-actions) for the list of supported raw keyboard key codes. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.sendKeys("Hello World"); web.sendKeys(["Backspace", "Backspace", "Enter"]); // send two Backspace key codes and Enter. // Unicode representation can be used directly as well: web.sendKeys("Hello World\uE003\uE003\uE007"); ``` **Parameters:** | Name | Type | Description | | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------- | | `value` | `String`\|`Array.` | Sequence of key strokes to send. Can be either a string or an array of strings for sending raw key codes. | ## setAutoWaitForAngular Wait for Angular based app will be loaded \*\* Usage example:\*\* ```javascript web.init(); web.open("www.yourwebsite.com"); web.setAutoWaitForAngular(true); ``` **Parameters:** | Name | Type | Description | | -------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `autoWaitForAngular` | `Boolean` | true to enable auto-wait. false to disable. | | `rootSelector` | `String` | `optional` Selector for root element, needed only for AngularJS (v1). In Angular (v2) first available root node will be selected automatically. | | `softWait` | `Boolean` | `optional` If true then do not produce error if stability cannot be attained. Default is false. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## setTimeout Specifies the amount of time that Oxygen will wait for actions to complete. This includes the `open` command, `waitFor*` commands, and commands which wait for elements to appear in DOM or become visible before operating on them.\ If command wasn't able to complete within the specified period it will fail the test.\ The default time-out is 60 seconds. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.setTimeout(60000);//Sets the time out to amount of milliseconds . ``` **Parameters:** | Name | Type | Description | | --------- | -------- | --------------------------- | | `timeout` | `Number` | A time-out in milliseconds. | ## setWindowSize Sets the size of the outer browser window. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.setWindowSize(100,40);//Sets the window size (width and height) in pixels. ``` **Parameters:** | Name | Type | Description | | -------- | -------- | ----------------- | | `width` | `Number` | Width in pixels. | | `height` | `Number` | Height in pixels. | ## takeScreenshot Take a screenshot of the current page or screen and return it as base64 encoded string. \*\* Usage example:\*\* ```javascript web.init(); web.open("www.yourwebsite.com"); var ss = web.takeScreenshot(); require("fs").writeFileSync("c:\\screenshot.png", ss, 'base64'); ``` **Returns:** `String` - Screenshot image encoded as a base64 string. ## transaction Opens new transaction. The transaction will persist till a new one is opened. Transaction names must be unique. **Parameters:** | Name | Type | Description | | ------ | -------- | --------------------- | | `name` | `String` | The transaction name. | ## type Send a sequence of key strokes to an element (clears value before). Refer to [Key Codes](https://w3c.github.io/webdriver/#keyboard-actions) for the list of supported raw keyboard key codes. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.type("id=UserName","User1");//Types a string to field. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `value` | `String` | The value to type. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## verifyAlert Verifies whether alert matches the specified pattern and dismisses it. Text pattern can be any of the supported string matching patterns (on the top of page). If alert is not present then NO\_ALERT\_OPEN\_ERROR error will be thrown and the test terminated. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session web.open("www.yourwebsite.com");// Opens a website. web.click("id=SaveButton");//Clicks on save – an alert would pop up web.verifyAlert("Your Alert's text");//Verifies the alert's text. ``` **Parameters:** | Name | Type | Description | | --------- | -------- | ---------------------------------------------------------- | | `pattern` | `String` | Text pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## verifyExist Verifies whether element exists in the DOM. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session web.open("www.yourwebsite.com");// Opens a website. web.verifyExist ("id=Username");// Verifies if an element exists in the DOM. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## verifySelectedLabel Verifies text of the currently selected option in a drop-down list. Assertion pattern can be any of the supported string matching patterns (on the top of page).If element is not present then ELEMENT\_NOT\_FOUND error will be thrown and the test terminated. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session web.open("www.yourwebsite.com");// Opens a website. web.verifySelectedLabel("id=Selection", "United States");// Verifies if an element's label is selected in the drop down list. ``` **Parameters:** | Name | Type | Description | | ---------------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `pattern` | `String` | The assertion pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | | `waitForVisible` | `Boolean` | `optional` Wait for visible. | ## verifySelectedValue Verifies value of the currently selected option in a drop-down list. Assertion pattern can be any of the supported string matching patterns (on the top of page).If element is not present then ELEMENT\_NOT\_FOUND error will be thrown and the test terminated. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session web.open("www.yourwebsite.com");// Opens a website. web.verifySelectedValue("id=Selection", "3");// Verifies if an element's value is selected in the drop down list. ``` **Parameters:** | Name | Type | Description | | ---------------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `pattern` | `String` | The assertion pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | | `waitForVisible` | `Boolean` | `optional` Wait for visible. | ## verifyText Verifies element's inner text. Text pattern can be any of the supported string matching patterns (on the top of page). If the element is not interactable, then it will allways return empty string as its text. If element is not present then ELEMENT\_NOT\_FOUND error will be thrown and the test terminated. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session web.open("www.yourwebsite.com");// Opens a website. web.verifyText ("id=UserName","John Doe");// Verifies if an element's text is as expected. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `pattern` | `String` | Text pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## verifyTextNotPresent Verifies whether the given text is *not* present on the page. That is, whether there are no elements containing this text on the page. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session web.open("www.yourwebsite.com");// Opens a website. web.verifyTextNotPresent("John Doe");// Verifies if a text is not presented somewhere on the page. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `text` | `String`\|`Element` | Text. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## verifyTextPresent Verifies whether the given text is present somewhere on the page. That is whether an element containing this text exists on the page. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session web.open("www.yourwebsite.com");// Opens a website. web.verifyTextPresent("John Doe");// Verifies if a text is presented somewhere on the page. ``` **Parameters:** | Name | Type | Description | | --------- | -------- | ---------------------------------------------------------- | | `text` | `String` | Text. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## verifyTitle Verifies the page title. Assertion pattern can be any of the supported string matching patterns(on the top of page). \*\* Usage example:\*\* ```javascript web.init();//Opens browser session web.open("www.yourwebsite.com");// Opens a website. web.verifyTitle("Your websites title!");// Verifies the title of the page. ``` **Parameters:** | Name | Type | Description | | --------- | -------- | ---------------------------------------------------------- | | `pattern` | `String` | The assertion pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## verifyValue Verifies element's value. Value pattern can be any of the supported string matching patterns (on the top of page).If element is not present then ELEMENT\_NOT\_FOUND error will be thrown and the test terminated. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session web.open("www.yourwebsite.com");// Opens a website. web.verifyValue("id=UserName", "John Doe");// Verifies the value of an element. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `pattern` | `String` | Value pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## waitForAngular Wait for Angular based app will be loaded \*\* Usage example:\*\* ```javascript web.init(); web.open("www.yourwebsite.com"); web.waitForAngular(); ``` **Parameters:** | Name | Type | Description | | -------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `rootSelector` | `String` | `optional` Selector for root element, needed only for AngularJS (v1). In Angular (v2) first available root node will be selected automatically. | | `softWait` | `Boolean` | `optional` If true then do not produce error if stability cannot be attained. Default is false. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## waitForExist Waits for element to become available in the DOM. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.waitForExist("id=UserName");//Waits for an element to exist in DOM. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## waitForInteractable Waits for element to become interactable. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.waitForInteractable("id=UserName");//Waits for an element is clickable in DOM. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## waitForNotExist Waits for element to become unavailable in the DOM. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.waitForNotExist("id=UserName");//Waits for an element to not exist in DOM. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## waitForNotText Waits for inner text of the given element to stop matching the specified pattern. Text pattern can be any of the supported string matching patterns(on the top of page). \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.waitForNotText("id=Title","Website");//Waits for an element’s text to not match to expected string. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `pattern` | `String` | Text pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## waitForNotValue Waits for input element's value to stop matching the specified pattern. Value pattern can be any of the supported string matching patterns(on the top of page). \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.waitForNotValue("id=UserName","User");//Waits for an element’s value to not match to expected string. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `pattern` | `String` | Value pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## waitForText Waits for inner text of the given element to match the specified pattern. Text pattern can be any of the supported string matching patterns(on the top of page). \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.waitForText("id=Title","Website");//Waits for an element’s text to match to expected string. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `pattern` | `String` | Text pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## waitForValue Waits for input element's value to match the specified pattern. Value pattern can be any of the supported string matching patterns(on the top of page). \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.waitForValue("id=Title","Website");//Waits for an element’s value to match to expected string. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `pattern` | `String` | Value pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## waitForVisible Waits for element to become visible. \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.waitForVisible("id=Title", 45*1000);//Waits for an element to be visible. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## waitForWindow Waits for a window to appear, but doesn't actually switches to it. `windowLocator` can be: * `title=TITLE` Wait for the first window which matches the specified title. `TITLE` can be any of the supported string matching patterns(see top of the page). * `url=URL` Wait for the first window which matches the specified URL. `URL` can be any of the supported string matching patterns(see top of the page). \*\* Usage example:\*\* ```javascript web.init();//Opens browser session. web.open("www.yourwebsite.com");// Opens a website. web.waitForWindow("title=Website");//Waits for a window to appear. ``` **Parameters:** | Name | Type | Description | | --------------- | -------- | ---------------------------------------------------------- | | `windowLocator` | `String` | A window locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | # win Provides methods for Windows native applications automation. **Locators:** * `/XPATH` - Locates element using an XPath 1.0 expression. * `~AccessibilityId` - Locates element by its Accessibility ID. Attribute name in inspect.exe - AutomationId. * `name=NAME` - Locates element by its name. Attribute name in inspect.exe - Name. * `id=ID` - Locates element by its ID. Attribute name in inspect.exe - RuntimeID. **Pattern arguments:** Commands which expect a string matching pattern in their arguments, support following patterns unless specified otherwise: * `regex:PATTERN` - Match using regular expression. * `PATTERN` - Verbatim matching. ## assertText Asserts element's inner text. Text pattern can be any of the supported string matching patterns(on the top of page). If the element is not interactable, then it will allways return empty string as its text. **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `pattern` | `String` | Assertion text or pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## assertTitle Asserts the page title. Assertion pattern can be any of the supported string matching patterns(on the top of page). **Parameters:** | Name | Type | Description | | --------- | -------- | ---------------------------------------------------------- | | `pattern` | `String` | Assertion text or pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## assertValue Asserts element's value. **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `pattern` | `String` | Value pattern. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## back Navigate backwards in the browser history or simulates back button on Android device. ## clear Clears element's value or content **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## click Clicks on an element. **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## clickLong Performs a long click/touch on an element. **Parameters:** | Name | Type | Description | | ---------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `duration` | `Number` | Touch duration in milliseconds. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## clickMultipleTimes Performs tap on an element multiple times in quick succession. **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `taps` | `Number` | Number of taps. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## dispose Ends the current session. ## findElement Finds an element. **Parameters:** | Name | Type | Description | | --------- | --------- | ---------------------------------------------------------- | | `locator` | `String` | Element locator. | | `parent` | `Element` | `optional` Optional parent element for relative search. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `Element` - A Element object. ## findElements Finds elements. **Parameters:** | Name | Type | Description | | --------- | --------- | ---------------------------------------------------------- | | `locator` | `String` | Element locator. | | `parent` | `Element` | `optional` Optional parent element for relative search. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `Array.` - Collection of Element objects. ## getAppiumLogs Collects logs from the Appium server. **Returns:** `Array.` - A list of logs. ## getCapabilities Returns currently defined capabilities. **Returns:** `Object` - Current capabilities object. ## getCurrentWindowHandle Gets current window handle. \*\* Usage example:\*\* ```javascript win.init(); win.getCurrentWindowHandle(); ``` **Returns:** `String` - A window handle. ## getDriver Returns the underlying WDIO driver. **Returns:** `Object` - WDIO driver. ## getLocation Get element's location. **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `Object` - X and Y location of the element relative to top-left page corner. ## getSource Gets the source code of the page. **Returns:** `String` - HTML in case of web or hybrid application or XML in case of native. ## getText Returns the text (rendered text shown to the user; whitespace-trimmed) of an element. **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `String` - Element's text. ## getValue Gets element's value (whitespace-trimmed). **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `String` - Element's value. ## getWindowHandles Gets handles of currently open windows. \*\* Usage example:\*\* ```javascript win.init();//Opens WinAppDriver session. win.getWindowHandles();//Gets the window handles of currently open application. ``` **Returns:** `Array.` - Array of all available window handles. ## init Initializes a new Appium session. **Parameters:** | Name | Type | Description | | ----------- | -------- | --------------------------------------------------------------------------------------------------- | | `caps` | `String` | `optional` Desired capabilities. If not specified capabilities will be taken from suite definition. | | `appiumUrl` | `String` | `optional` Remote Appium server URL (default: ). | ## isCheckable Determines if checkbox or radio element is checkable. **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `Boolean` - true if element is checkable. false otherwise. ## isChecked Determines if checkbox or radio element is checked. **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `Boolean` - true if element is checked. false otherwise. ## isClickable Determines if an element is clickable. **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `Boolean` - true if element is clickable. false otherwise. ## isExist Wait for an element to become available. The element is not necessary needs to be visible. **Parameters:** | Name | Type | Description | | --------- | ------------------- | ------------------------------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Time in milliseconds to wait for the element. Default is 60 seconds. | **Returns:** `Boolean` - true if the element exists. false otherwise. ## isSelected Determines if an element is selected. **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | **Returns:** `Boolean` - true if element is selected. false otherwise. ## isVisible Checks if element is present and visible. Returns false if element was not found or wasn't visible within the specified timeout. **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds to wait for element to appear. Default is 60 seconds. | **Returns:** `Boolean` - True if element was found and it was visible. False otherwise. ## open Opens an URL. The `open` command waits for the page to load before proceeding. **Parameters:** | Name | Type | Description | | ----- | -------- | --------------------------------------------- | | `url` | `String` | The URL to open; may be relative or absolute. | ## pause Pause test execution for the given amount of milliseconds. **Parameters:** | Name | Type | Description | | ---- | -------- | ---------------------------------------- | | `ms` | `Number` | Milliseconds to pause the execution for. | ## rightClick Perform right click on an element. **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## selectWindow Selects window. Once window has been selected, all commands go to that window. `windowLocator` can be: * `title=TITLE` Switch to the first window which matches the specified title. `TITLE` can be any ofthe supported string matching patterns (see top of the page). When using title locator, this commandwill wait for the window to appear first similarly to `waitForWindow` command. * `windowHandle` Switch to a window using its unique handle. \*\* Usage example:\*\* ```javascript win.init(); win.selectWindow("title=FolderName");// Selects and focus a window. ``` **Parameters:** | Name | Type | Description | | --------------- | -------- | ------------------------------------------------------------------------------------------------------ | | `windowLocator` | `String` | `optional` Window locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds when using 'title' window locating strategy. Default is 60 seconds. | **Returns:** `String` - windowHandle of the previously selected window. ## sendKeys Send a sequence of keyboard strokes to the active window or element. Refer to [Key Codes](https://w3c.github.io/webdriver/#keyboard-actions) for the list of supported raw keyboard key codes. \*\* Usage example:\*\* ```javascript win.init();//Opens browser session. win.open("www.yourwebsite.com");// Opens a website. win.sendKeys("Hello World"); win.sendKeys(["Backspace", "Backspace", "Enter"]); // send two Backspace key codes and Enter. // Unicode representation can be used directly as well: win.sendKeys("Hello World\uE003\uE003\uE007"); ``` **Parameters:** | Name | Type | Description | | ------- | -------------------------- | --------------------------------------------------------------------------------------------------------- | | `value` | `String`\|`Array.` | Sequence of key strokes to send. Can be either a string or an array of strings for sending raw key codes. | ## setTimeout Specifies the amount of time that Oxygen will wait for actions to complete. This includes the `open` command, `waitFor*` commands, and commands which wait for elements to appear in DOM or become visible before operating on them.\ If command wasn't able to complete within the specified period it will fail the test.\ The default time-out is 60 seconds. **Parameters:** | Name | Type | Description | | --------- | -------- | --------------------------- | | `timeout` | `Number` | A time-out in milliseconds. | ## takeScreenshot Take a screenshot of the current page or screen and return it as base64 encoded string. \*\* Usage example:\*\* ```javascript win.init(caps); var ss = win.takeScreenshot();//Take a screenshot and return it as base64 encoded string. require("fs").writeFileSync("c:\\screenshot.png", ss, 'base64'); ``` **Returns:** `String` - Screenshot image encoded as a base64 string. ## tap Perform tap at the specified coordinate. **Parameters:** | Name | Type | Description | | ---- | -------- | ----------- | | `x` | `Number` | x offset. | | `y` | `Number` | y offset. | ## transaction Opens new transaction. The transaction will persist till a new one is opened. Transaction names must be unique. **Parameters:** | Name | Type | Description | | ------ | -------- | --------------------- | | `name` | `String` | The transaction name. | ## type Send a sequence of key strokes to an element (clears value before). Refer to [Key Codes](https://w3c.github.io/webdriver/#keyboard-actions) for the list of supported raw keyboard key codes. **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `value` | `String` | The value to type. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## waitForExist Wait for an element for the provided amount of milliseconds to exist in DOM. The element is not necessary needs to be visible. **Parameters:** | Name | Type | Description | | --------- | ------------------- | ------------------------------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Time in milliseconds to wait for the element. Default is 60 seconds. | ## waitForInteractable Waits for element to become interactable. \*\* Usage example:\*\* ```javascript win.init();//Opens browser session. win.waitForInteractable("id=UserName");//Waits for an element is clickable in DOM. ``` **Parameters:** | Name | Type | Description | | --------- | ------------------- | ---------------------------------------------------------- | | `locator` | `String`\|`Element` | An element locator. | | `timeout` | `Number` | `optional` Timeout in milliseconds. Default is 60 seconds. | ## waitForVisible Waits for element to become visible. **Parameters:** | Name | Type | Description | | --------- | ------------------- | ------------------------------------------------------------------------------- | | `locator` | `String`\|`Element` | Element locator. | | `timeout` | `Number` | `optional` Time in milliseconds to wait for the element. Default is 60 seconds. | # Test Parameters ## Parameterization Using variety of test data is crucial for a successful automation testing. Let's see how simple it's to add parameters to your test case file. All you need to do is to replace inline values with parameter names and create a CSV or XLSX file with the same name as the test case (script) file and corresponding columns with parameter names. Let's take the second step from the script we have built in "Getting Started - Desktop" tutorial and parameterize it: {% hint style="info" %} Here is the CSV file for example: {% endhint %} | name, | phone, | | | -------- | ----------- | - | | Tony, | 0523539924, | | | Josh, | 0548819925, | | | Tiffany, | 0518853395, | | Original ```javascript web.type('name=search', 'Tony'); ``` Parameterized ```javascript web.type('name=search', '${name}'); ``` ```bash web.type('name=search', params.name); ``` We replaced "Tony" value with "${name}". `${}` syntax is used to define external parameters. First row defines columns for each parameter. This row must include comma separated parameter names. Parameter name can include white-space. We will save the CSV file in the same directory as our test case file as `wikipedia.csv`. Now we have two files: * wikipedia.js * wikipedia.csv All we need to do now is to use the `-p` switch to specify the parameters file: ```bash oxygen -p=wikipedia.csv wikipedia.js ``` To use parameters when executing from within the IDE; click Settings icon and specify the parameterization CSV. ### Multiple Iterations You probably noticed that we have defined three different values under `name` parameter. If we would run the test as before, Oxygen will pick the first value, e.g. "Tony" and will use it in the test. Ideally we would like to iterate over multiple values. This can be done using the `-i` switch specifying number of iterations. For example, if we wanted to run the test three times: ```bash oxygen -p=wikipedia.csv -i=3 --pm=seq wikipedia.js ``` This will run three iterations of the test, each time using the next value which will be selected either randomly or sequentially depending on the setting of `--pm` switch. `random` and `seq` specify random and sequential modes respectively. Similarly, number of iterations in the IDE can be defined using the settings screen. # Sauce Labs In order to run tests on Sauce Labs provider, you'll need to configure Oxygen IDE with your Username and Access Token. \ Both of these values can be obtained from your Sauce Labs profile page: ![](/files/-M4fG8AADvOOXOjag7sx) Go to Run Settings ("cogwheel" icon on the toolbar), switch to Cloud Providers tab, select Sauce Labs, fill up the necessary information and click Save & Close: ![](/files/-M4fGdzaA5JKGvQj_vtT) Once this has been done, a "Location" selection box will appear on the toolbar. Select Sauce Labs. Once the location is selected, browser list will be populated with available target browsers. Select the browser (and optionally, the browser version and/or OS) you wish to run your test on. ![](/files/-M4JfTL43nyxEBwHYutK) # Lambda Test In order to run tests on LambdaTest provider, you'll need to configure Oxygen IDE with your Username and Access Token. \ Both of these values can be obtained from your LambdaTest profile page:
Go to Run Settings ("cogwheel" icon on the toolbar), switch to Cloud Providers tab, select Lambda Test, fill up the necessary information and click Save & Close: ![](/files/-M-xVBRgvau1D_dWYTKy) Once this has been done, a "Location" selection box will appear on the toolbar. Select Lambda Test. Once the location is selected, browser list will be populated with available target browsers. Select the browser (and optionally, the browser version and/or OS) you wish to run your test on. ![](/files/-M4JiLqbqUMT5bT5yNii) # TestObject under construction ## TestObject TestObject is a cloud hosted service that provides mobile devices running Android and iOS for application testing. It supports a number of testing frameworks, such as Appium, Robotium, and Espresso, and can also be used for manual testing ![TestObject - a part of SauceLabs](/files/-M4uHKxkjYy-Kog5rbmm) To enable TestObject, go to Settings - Cloud Providers and expand the TestObject item by enabling it. Enter the username, API key from TestObject and select your region from the drop-down. ![](/files/-M4uG9QE5gUA9BJ8h-8A) Username and API key can be obtained from your TestObject profile page: ![](/files/-M4wUFhQZ5MogBnpwNgm) # Project Configuration Project-level configuration files - oxygen.conf.js Starting from version 1.0, `oxygen-cli` no longer supports suite definitions using JSON files, and instead supports only project level configuration via a file named `oxygen.conf.js` . An example configuration file is listed below. Please note, that the file should be named exactly `oxygen.conf.js` and located in the project directory along with all the test scripts, in order for oxygen-cli to recognize it. To launch a project using configuration file, execute: `oxygen oxygen.conf.js`\ Pass full path to the configuration file if necessary. ``` module.exports = { // ============ // Suites // ============ // // For example, here we have two suites defined, with first suite having two cases // and second suite having only a single case. // suites: [ { name: 'Selenium', // suite name cases: [ // cases inside this suite { path: './tests/selenium-with-po.js' }, { path: './tests/pdf.js' } ] },{ name: 'Visual', cases: [ { path: './tests/visual.js' } ] } ], // ============ // Capabilities // ============ // // If "concurrency" value is greater than 1, // tests with different capabilities will be executed in parallel. // concurrency: 1, capabilities: [ { browserName: 'chrome', // execute on Chrome }, { browserName: 'firefox', // execute on Firefox } ], // ============ // Parameters // ============ // parameters : { file: '', mode: 'seq', // can be 'random' or 'all' as well }, // ============ // Iterations // ============ // // Tests will run only once if iterations number is not explicitly specified. // iterations: 1, // ============ // Selenium & Appium server URLs // ============ // // If not specified, the default URLs will be used // seleniumUrl: 'http://localhost:4444/wd/hub', appiumUrl: 'http://localhost:4723/wd/hub', // ============ // Services // ============ // // List services you want to enable during the test execution. // Available services: selenium-standalone | devtools // selenium-standalone needs to be installed with `npm i @wdio/selenium-standalone-service` first. // services: ['selenium-standalone', 'devtools'], // ============ // Modules // ============ // List modules you want to enable during the test execution. // Loading unnecessary modules might slow down your test execution, // so only load modules that are used in the test. // See here https://docs.oxygenhq.org for a list of available modules. // modules: ['web', 'db', 'log', 'assert', 'pdf', 'http', 'email'], // ============ // Framework // ============ // Define a testing framework for this project. // Available frameworks: oxygen | cucumber // framework: 'oxygen', // ============ // Reporting // ============ // Define test reporter format and corresponding options. // Multiple reporter formats can be specified. // Available reporters: json | html | junit | excel | pdf | xml // reporting: { reporters: ['json'], }, // ========== // Applitools // ========== // Define your Applitools service API key. // This is only for when using the `eyes` module. // applitoolsOpts: { key: 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX' }, // ========== // Hooks // ========== // Oxygen provides several hooks that can be used to interfere with the test // execution process. // hooks: { // // Hook that gets executed before the test starts. // At this point, Oxygen has been already initialized, so you // can access Oxygen functionality via relevant modules. // beforeTest: function(runId, options, caps) { }, beforeSuite: function(suiteDef) { }, beforeCase: function(caseDef) { log.info('Hey there! Case is about to start.'); }, beforeCommand: function(cmdDef) { }, afterCommand: function(cmdResult) { }, afterCase: function(caseDef, caseResult) { }, afterSuite: function(suiteDef, suiteResult) { }, afterTest: function(runId, testResult) { } } }; ``` Please see the [Sample Project](https://docs.oxygenhq.org/getting-started-web/getting-started-web/sample-project-web-test) for an example of a project configuration file. # Locating Elements ## Locating UI Elements Automated UI tests (either web or mobile), are mostly focused on performing certain actions on page's or screen's elements. One of the key challenges in writing UI tests is correctly identifying elements on the screen. Accurate element identification is very important to have stable automation tests. If the elements are incorrectly identified, the test will misbehave and perform actions on wrong elements or just fail, not able to find any. This is called test flakiness. To prevent or minimize flaky tests, you have to make sure the UI elements are uniquely identified. Selenium and Oxygen use `locators` to identify UI elements. Most of Oxygen commands in `web` and `mob` modules require a locator to perform various actions on the element (such as find an element, assert element's value, etc.). Oxygen provides a wide variety of locator types (strategies) which help to identify elements by different attributes and hierarchical position. Oxygen allows you to either generate locators automatically or write them manually using various element inspection tools. Here is what you can do: * **Use Oxygen IDE Recorder** - Oxygen IDE can record Chrome browser based user interactions and generate all possible locators for the selected element. Oxygen IDE will also pre-select the most suitable locator for the specific object. See [Web Recording Guide](/download-installation-start/start-working-with-oxygen/getting-started-web/recording-web-tests) for more details. * **Insert Locators Manually** - choose and insert element locators manually in your Oxygen script, using UI element inspection tools like [Chrome DevTools](https://developers.google.com/web/tools/chrome-devtools/), Appium Desktop, etc. **Note:** In order to record mobile application actions and locators, you will need to use a special version of Appium Desktop that supports generating Oxygen code. See [Mobile Recording Guide](/download-installation-start/start-working-with-oxygen/getting-started-mobile/recording-mobile-tests) for more details. ### Locator Types Oxygen provides different locator types to help to identify UI elements of web and mobile applications. To indicate which locator type to use, the `locator` parameter shall start with type `prefix`. Below are various locator types and prefixes for web and mobile applications. #### Web Locator Types | Locator | Prefix | Usage | | ------------ | -------- | -------------------------------------------------------------------- | | ID | `id=` | Locates elements by the value of the `id` attribute. | | Name | `name=` | Locates elements by the value of the `name` attribute. | | Link | `link=` | Locates elements by the text in A (anchor) HTML tag. | | CSS Selector | `css=` | Locates elements via the driver’s underlying W3 CSS Selector engine. | | XPath | `xpath=` | Locates elements by XPath. | See [Web Module (web)](/download-installation-start/modules/module-web) for more locator types and additional details. #### Mobile Locator Types | Locator | Prefix | Usage | | ------- | -------- | --------------------------------------------------------------------------------------------------------------- | | ID | `id=` | Locates elements by their unique identifier - `resource-id` attribute for android and `name` attribute for iOS. | | Class | `class=` | Locates elements by the full name of UI element's class. | | Text | `text=` | Locates elements by their visible text. | | XPath | `xpath=` | Locates elements by XPath. | See [Mobile Module (mob)](/download-installation-start/modules/module-mob) for more locator types and additional details. {% hint style="info" %} Here are some usage examples: {% endhint %} ``` web.click('id=submit') // ID web.type('name=firstNameInput', 'first name') // Name web.click('https://link.com') // Link web.click('div > button.login') // CSS Selector web.select('//select[@id="selectGender"]', 'label=female') // XPath ``` # Page Objects Page Objects (PO) provides means for abstracting element locators behind human friendly *objects*. This makes scripts more readable, reduces duplicate code, and simplifies maintenance since locators are defined in a single location and any updates due to UI changes for example will need to be done only once in one place. Page objects will be stored in a special file called oxygen.po.js **Hardcoded locators:** ```javascript web.init(); web.open('https://www.wikipedia.org/'); web.type('id=searchInput', 'selenium'); web.select('id=searchLanguage', 'label=English'); web.click('//*[@id="search-form"]/fieldset/button'); web.assertText('id=firstHeading', 'Selenium'); ``` **Using Page Objects:** {% hint style="info" %} Using require is no longer needed, but still supported. {% endhint %} ```javascript var po = require('./po.js'); web.init(); web.open('https://www.wikipedia.org/'); web.type(po.homePage.searchInput, 'selenium'); web.select(po.homePage.languageSelect, 'label=English'); web.click(po.homePage.goButton); web.assertText(po.searchResultScreen.mainTitle, 'Selenium'); ``` ### This will work the same without require ```javascript web.init(); web.open('https://www.wikipedia.org/'); web.type(po.homePage.searchInput, 'selenium'); web.select(po.homePage.languageSelect, 'label=English'); web.click(po.homePage.goButton); web.assertText(po.searchResultScreen.mainTitle, 'Selenium'); ``` Each object can be a part of a certain screen inside the "oxygen.po.js" file. The objects themselves are separated with ',' similar to a json file. Here is an example of how the file is built: ```javascript module.exports = { homePage: { searchInput: 'id=searchInput', languageSelect: 'id=searchLanguage', goButton: '//*[@id="search-form"]/fieldset/button', }, searchResultScreen: { mainTitle: 'id=firstHeading', } } ``` In the above example search input box, language drop-down list, and the "Go" button are all located on the homepage and the header which we assert in the last step is located on a separate page. Hence we have defined two pages "Homepage" and "Search Result" (the names are arbitrary) each containing the relevant objects. ## Page object video tutorial The following video will show you step by step how to create your own Page Object file and use it step by step in your Oxygen IDE tests! {% embed url="" %} # Environments Similarly to page objects, environments can be set up to properly organize your desired environments. They may include different URLs and different users for each environment. They will be stored in a special file called oxygen.env.js #### setting up our environments: ``` module.exports = { TEST: { url: 'https://test.app.com', con_string: 'Driver={SQL Server};Server=DESKTOP\\SQLEXPRESS;Database=test;', username: 'testuser', password: 'test123' }, PREP: { url: 'https://prep.app.com', con_string: 'Driver={SQL Server};Server=DESKTOP\\SQLEXPRESS;Database=prep;', username: 'prepuser', password: 'prep123' } } ``` now that we've set them up, we can choose them by clicking on the settings icon on the top right ![](/files/-MVMfJUNyvjqLph-rDLY) ![](/files/-MVMfZVbCdOXAtBZGv_q) let's choose the PREP environment and use it in our script: ``` web.init() web.open(env.url) // https://prep.app.com db.setConnectionString(env.con_string) web.type('id=username', env.username) web.type('id=password', env.password) ``` # Code Components Re-using code is a very useful working method, saves time and energy when it comes to performing the same actions or any common action on each test, therefore when it needs an update or a fix, you only need to fix it in the script file itself. Scripts can call the functions in the file using the `po` object statement. **Functions file:** ```javascript module.exports = { Login: function(username, password) { web.type('id=userName',username); web.type('id=password',password); web.click('name=login'); web.assertText('id=firstHeading', 'Welcome ' + username); } } ``` {% hint style="info" %} **it's also possible to use the ES6 arrow function and template literals** {% endhint %} ```javascript module.exports = { Login: (username, password) => { web.type('id=userName', username); web.type('id=password', password); web.click('name=login'); web.assertText('id=firstHeading', `Welcome ${username}`); } } ``` **Script to run:** ```javascript web.transaction('Opening browser and web-page'); web.init(); web.open('https://oxygenhq.org'); web.transaction('Logging in'); po.Login('User1', 'Password123'); web.click('id=button1'); ``` In the above example , the script shall use the code it has inherited from a file called **oxygen.po.js**, it can contain many functions as you want and call it from any script you are running.