Appium HTML Driver ·

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