Skip to content

WebDriver for testing HTML applications

License

Notifications You must be signed in to change notification settings

dlenroc/appium-html-driver

Repository files navigation

Appium HTML Driver · NPM Version Node.js Version

Appium HTML Driver is a WebDriver that allows controlling applications written using web technologies, regardless of the device they are running on.

Installation

appium driver install --source npm @dlenroc/appium-html-driver

Connection

DevTools Protocol

If target supports the devtools protocol, then we can connect to it via chrome-remote-interface.

  1. Get the DevTools target address (sample with Google Chrome)

    $ "<browser.path>" --user-data-dir="$(mktemp -d)" --remote-debugging-port="9222"
    
    DevTools listening on ws://127.0.0.1:9222/devtools/browser/c8f3b64d-aa40-4c56-b1d4-b4796fb24eae
  2. Attach and run test

    await driver = await remote({
      'capabilities': {
        'platformName': 'html',
        'appium:automationName': 'html',
        'appium:debuggingAddress': 'ws://127.0.0.1:9222/devtools/browser/c8f3b64d-aa40-4c56-b1d4-b4796fb24eae'
      },
    });
    
    // Attach to target
    const handles = await driver.getWindowHandles();
    await driver.switchToWindow(handles[0]);
    
    // Conduct testing
    await driver.getUrl()
      .should.eventually.be.fulfilled;

On-Device Component

If target doesn't support DevTools Protocol or you need access to pages it can't access, then ODC may be what you need.

  1. Instrumentation

    Inject the following code in every HTML file that belongs to your application.

    <script src="{origin}/appium-html-driver/js/{udid}/{handle}"></script>

    Where:

    • origin - address of the Appium server, for example: http://192.168.0.2:4723.
    • udid - identifier that represent your device, for > example: {device-name}-{serial-number}.
    • handle (optional) - identifier that will represent the window handle.
  2. Attach and run test

    await driver = await remote({
      'capabilities': {
        'platformName': 'html',
        'appium:automationName': 'html',
        'appium:debuggingAddress': `odc://${udid}/${handle}`
      },
    });
    
    /**
     * Load instrumented page manually, via cli or in any other way
     *
     * NOTE: that is not driver's responsibility
     */
    
    // Attach to target
    const handles = await driver.getWindowHandles();
    await driver.switchToWindow(handles[0]);
    
    // Conduct testing
    await driver.getUrl()
      .should.eventually.be.fulfilled;

NOTE: Because of how the instrumentation process works, the test session should start first, and then the application.

If this is a problem, you can initialize the driver yourself once and then not care about the mentioned limitation:

curl 'http://localhost:4723/session' \
  -H 'content-type: application/json;charset=utf-8' \
  -d '{ "capabilities": { "alwaysMatch": { "platformName": "html", "appium:automationName": "html", "appium:debuggingAddress": "odc://init" } } }'

Capabilities

Capability Required Type Description
platformName + string Must be html
appium:automationName + string Must be html
appium:debuggingAddress + string See Connection

Commands

Command Description
active Get active element
back Back
clear Element clear
click Element click
closeWindow Close window
createSession New session
createNewWindow New window
deleteCookie Delete cookie
deleteCookies Delete all cookies
elementDisplayed Is element displayed
elementEnabled Is element enabled
elementSelected Is element selected
execute Execute script
executeAsync Execute async script
findElement Find element
findElementFromElement Find element form element
findElements Find elements
findElementsFromElement Find elements from element
forward Forward
getAttribute Get element attribute
getCookie Get named cookie
getCookies Get all cookies
getCssProperty Get element CSS value
getElementRect Get element rect
getName Get element tag name
getPageSource Get page source
getProperty Get element property
getText Get element text
getTimeouts Get timeouts
getUrl Get current URL
getWindowHandle Get window handle
getWindowHandles Get window handles
getWindowRect Get window rect
maximizeWindow Maximize window
refresh Refresh
setCookie Add cookie
setFrame Switch to frame
setParentFrame Switch to parent frame
setUrl Navigate to URL
setValue Element send keys
setWindow Switch to window
setWindowRect Set window rect
timeouts Set timeouts
title Get title