selenium-appium

selenium-appium is selenium-webdriver extension to make selenium-webdriver to drive Appium to run automation for native, hybrid and mobile web and desktop apps.

Break changes

1. selenium-appium@1.0.0 The default URL is changed from http://localhost:4723/wd/hub to http://localhost:4723. The goal is to remove appium from the project and use winappdriver to launch and stop WinAppDriver

Features

1. A bridge to make selenium-webdriver to drive appium for native app automation. Implement Mobile JSON Wire Protocol Specification locator which selenium-webdriver doesn't support.
2. Supports PageObject Pattern for selenium-webdriver
3. Supports iOS, Andriod, Windows which Appium supports.
4. Supports Typescript
5. Avoid webdriver.wait(until.elementLocated()).click() pattern and replaced it with By2.click()

Installation

npm i selenium-appium --save-dev

By2 example

• By2 is a subclass of selenium-webdriver.By. So you can use it anywhere which selenium-webdriver provides.
• Also By2 implements the WebElement interface, so you can call click and other element operation directly.
• No webdriver.wait needed. Instead of findElement, By2 itself loop until element is located before actual click happens.

    test("By2 used in selenium-webdriver.WebDriver", async () => {
        const webdriver = await new Builder()
            .usingServer(url)
            .withCapabilities(capabilities)
            .build();
        const element = await webdriver.wait(until.elementLocated(By2.nativeName('One')));
        await element.click();
        await webdriver.quit();
    });

    test("By2 Supports multiple webdriver2", async () => {
        const webdriver = new WebDriver2();
        await webdriver.startWithCapabilities(capabilities)
        await By2.nativeName('One', webdriver).click();
        await webdriver.quit();
    });


    test("By2 deduced WebDriver2 for single WebDriver2", async () => {
        await driver.startWithCapabilities(capabilities)
        await By2.nativeName('One').click();
        await driver.quit();
    });

driver example

• driver is a wrapper of WebDriver which selenium-webdriver provides.
• Implements all functions of WebDriver of selenium-webdriver.
• It provides the default driver for By2.
• It delayed the creation of WebDriver, and implement the interface of WebDriver.

There are two ways to initialize the driver: startWithWebDriver or startWithWebDriver.

startWithWebDriver allows you to attach the driver to existing WebDriver if capability is not enough for your testing.

    test("simple webdriver2, and driver create from WebDriver", async () => {
        const webdriver = await new Builder()
            .usingServer(url)
            .withCapabilities(capabilities)
            .build();
        await driver.startWithWebDriver(webdriver);
        await By2.nativeName('One').click();
        await webdriver.quit();
    });

    test("Multiple webdriver2", async () => {
        const webdriver = new WebDriver2();
        await webdriver.startWithCapabilities(capabilities)
        await By2.nativeName('One', webdriver).click();
        await webdriver.quit();
    });


    test("Simple Webdriver2, and Driver create from capabilities", async () => {
        await driver.startWithCapabilities(capabilities)
        await By2.nativeName('One').click();
        await driver.quit();
    });

PageObject example

PageObject reduces the amount of duplicated code and easy to maintain.

1. get in typescript would make you always get new instance of By2. For example, get resultTextBox()
2. waitForPageLoaded pairs with isPageLoaded. You only need to overload isPageLoaded. waitForPageLoaded would poll until isPageLoaded is true or timeout.
3. In practice, we only need simple instance of PageObject since it doesn't save state, and all state could be query by By2 from remote app.

PageObject

import { PageObject, By2 } from "selenium-appium";

class CalculatorPage extends PageObject {
  isPageLoaded() {
    return this.minusButton.isDisplayed();
  }

  get resultTextBox() { return By2.nativeAccessibilityId('CalculatorResults');}
  get equalButton() { return By2.nativeAccessibilityId('equalButton'); }
  get clearButton() { return By2.nativeName('Clear'); }
  get plusButton() { return By2.nativeName('Plus'); }
  get divideButton() { return By2.nativeAccessibilityId('divideButton'); }
  get multiplyButton() { return By2.nativeXpath("//Button[@Name='Multiply by']") }
  get minusButton() { return By2.nativeXpath("//Button[@AutomationId=\"minusButton\"]"); }
 

  private async pressKeys(keys: string) {
    for (var key of keys) {
      await By2.nativeAccessibilityId('num' + key + 'Button').click();
    }
  }
  async divid(a: string, b: string): Promise<string> {
    await this.pressKeys(a);
    await this.divideButton.click();
    await this.pressKeys(b);
    await this.equalButton.click();
    return await this.getCalculatorResultText();
  }

  async multiply(a: string, b: string): Promise<string> {
    await this.pressKeys(a);
    await this.multiplyButton.click();
    await this.pressKeys(b);
    await this.equalButton.click();
    return await this.getCalculatorResultText();
  }

  async plus(a: string, b: string): Promise<string> {
    await this.pressKeys(a);
    await this.plusButton.click();
    await this.pressKeys(b);
    await this.equalButton.click();
    return await this.getCalculatorResultText();
  }

  async minus(a: string, b: string): Promise<string> {
    await this.pressKeys(a);
    await this.minusButton.click();
    await this.pressKeys(b);
    await this.equalButton.click();
    return await this.getCalculatorResultText();
  }

  private async getCalculatorResultText(): Promise<string> {
    return (await this.resultTextBox.getText()).replace('Display is', '').trim();
  } 
}

export default new CalculatorPage();

use the PageObject

  beforeEach(async () => {
    await CalculatorPage.waitForPageLoaded();
    await CalculatorPage.clearButton.clear();
  });
  test('Addition', async () => {
    // Find the buttons by their names and click them in sequence to perform 1 + 7 = 8
    expect(await CalculatorPage.plus('1', '7')).toBe('8');
  });

  test('Division', async () => {
    // Find the buttons by their accessibility ids and click them in sequence to perform 88 / 11 = 8
    expect(await CalculatorPage.divid('88', '11')).toBe('8');
  });

  test('Multiplication', async () => {
    // Find the buttons by their names using XPath and click them in sequence to perform 9 x 9 = 81
    expect(await CalculatorPage.multiply('9', '9')).toBe('81');
  });

  test('Subtraction', async () => {
    // Find the buttons by their accessibility ids using XPath and click them in sequence to perform 9 - 1 = 8
    expect(await CalculatorPage.minus('9', '1')).toBe('8');
  });

Configuration example

There are two global timers: waitforPageTimeout and waitforTimeout.

waitforTimeout is used by By2. When call any WebElement function of By2, it loops until the element is located

waitforPageTimeout is used by PageObject. It defined the default timeout for waitForPageLoaded.

    Config.setWaitForPageTimeout(100);
    expect(Config.getWaitForPageTimeout()).toBe(100);

Config.setWaitForTimeout(100);
expect(Config.getWaitForTimeout()).toBe(100);

driver.seleniumDriver

driver.seleniumDriver returns the instance of actual WebDriver.

Note

Because of typescript error, unlike By.name, By2 only replaced it with By2.name2.

Why selenium-appium

selenium-appium projected is created when I prototype automation for react-native Windows testing. Appium is an open source, cross-platform test automation tool for native, hybrid and mobile web and desktop apps. We support simulators (iOS), emulators (Android), and real devices (iOS, Android, Windows, Mac).

Selenium is a browser automation library. Most often used for testing web-applications.

selenium-webdriver is the offical WebDriver Javascript binding from selenium project.

Although WebDriverIO provides webdriver for Appium, it has some restrictions:

1. Selenium has very large user base in browser automation, but WebDriverIO API is different from selenium javascript API
2. [Already fixed] WebDriverIO has problem to support WinAppDriver, for example, https://github.com/webdriverio/webdriverio/pull/4369

Unfortunately selenium-webdriver doesn't support Mobile JSON Wire Protocol Specification. And that's why selenium-appium project is created.

Note

To know more about how to integrate JavaScript test runner and WinAppDriver for UI automation, please refer to:

• WinAppDriver + WebDriverIO example. Example to demostrate WinAppDriver and WebDriver integration without appium dependency

• E2E test on React Native for Windows. MoreAboutE2ETest.md provides some background why React Native Windows choose WinAppDriver and node test runner for E2E testing.

• winappdriver-js-webdriver-example, Which includes:

1. Jest + selenium-webdriver + WinAppDriver
2. Jasmine + WebDriverIO + WinAppDriver. This part is obselete, please refer to WinAppDriver + WebDriverIO example for newer change.

• selenium-webdriver-winappdriver-example. An example of jest, selenium-webdriver and winappdriver integration

• selenium-appium. selenium-appium is selenium-webdriver extension to make selenium-webdriver to drive Appium to run automation for native, hybrid and mobile web and desktop apps.

• Choose the right E2E automation framework for React Native Windows

• How to: Use Jest + selenium-webdriver + WinAppDriver to do Windows UI testing

• Automated Windows UI testing by Jest + selenium-appium + selenium-webdriver + WinAppDriver

• Inspecting UI Elements for WinAppDriver automation using Appium Desktop

License

The selenium-appium and all newly contributed code is provided under the MIT License.