tgdevice

Helpers for running Appium/WebdriverIO tests against a TestGrid Appium hub for mobile device automation (Android/iOS).

Install

npm install tgdevice
# For WebdriverIO integration (optional)
npm install webdriverio @wdio/cli

The package automatically builds on install and will print setup instructions.

Quick Start

1. Set your TestGrid Appium endpoint (place in .env, shell profile, or CI secrets):

   APPIUM_REMOTE_URL=http://your-grid-host/appium_XXXXX/wd/hub
   TESTGRID_USER_TOKEN=...
   TESTGRID_UDID=...
   TESTGRID_PLATFORM_NAME=android         # or ios
   TESTGRID_PLATFORM_VERSION=12
   TESTGRID_DEVICE_NAME="Galaxy Note10"
   TESTGRID_AUTOMATION_NAME=UiAutomator2  # or XCUITest for iOS
   TESTGRID_SYSTEM_PORT=4002
   TESTGRID_UIAUTOMATOR2_TIMEOUT=90000

   Supplying APPIUM_REMOTE_URL automatically flips the helpers into remote mode.

2. Use in your tests:

   import { TestGridDevice, withTestGridDevice } from 'tgdevice';
   
   // Manual lifecycle
   const device = await TestGridDevice.connect();
   console.log('Session:', device.getSessionId());
      
   // Access WebdriverIO driver if installed
   if (device.driver) {
     await device.driver.$('~button').click();
   }
      
   await device.dispose();
   
   // Or use the convenience helper
   await withTestGridDevice(async (device) => {
     if (device.driver) {
       const element = await device.driver.$('~button');
       await element.click();
     }
   });

3. For WebdriverIO projects, copy sample-wdio.config.js (or .ts) from node_modules/tgdevice/ to your project root and rename to wdio.conf.js (or .ts).

Environment Variables

| Variable | Purpose | Default | | --- | --- | --- | | APPIUM_REMOTE_URL | TestGrid Appium Hub URL | Required for remote | | TESTGRID_USER_TOKEN | TestGrid auth token | Required | | TESTGRID_UDID | Device identifier | Required | | TESTGRID_PLATFORM_NAME | android or ios | android | | TESTGRID_PLATFORM_VERSION | OS version | 12 | | TESTGRID_DEVICE_NAME | Device model name | Galaxy Note10 | | TESTGRID_AUTOMATION_NAME | UiAutomator2 or XCUITest | UiAutomator2 | | TESTGRID_SYSTEM_PORT | Appium system port | 4002 | | TESTGRID_UIAUTOMATOR2_TIMEOUT | Launch timeout (ms) | 90000 | | DEBUG_TESTGRID | Set to 1 for verbose logging | Optional |

If APPIUM_REMOTE_URL is unset or blank, the library defaults to local Appium execution.

API

TestGridDevice

• TestGridDevice.connect(options?): Creates a new device session on the TestGrid Appium hub
• device.getSessionId(): Returns the Appium session ID
• device.getCapabilities(): Returns the session capabilities
• device.driver: WebdriverIO browser instance (if webdriverio is installed)
• device.dispose(): Closes the session

Helpers

• withTestGridDevice(callback, options?): Convenience wrapper that handles session lifecycle
• resolveTestGridDeviceConfig(): Returns current configuration based on environment
• createTestGridDeviceSession(config): Low-level session creation
• deleteTestGridDeviceSession(config, sessionId): Low-level session deletion

Development

This repository uses npm workspaces:

npm install
npm run build --workspace=tgdevice

To publish a new version:

cd packages/tgdevice
npm version patch    # or minor/major
npm publish --access public

Support

Issues and feature requests: open a ticket or contact the TestGrid team.