js_tgdevice/index.js

Helpers for launching Android and iOS Appium sessions on TestGrid

const { Builder } = require('selenium-webdriver');

function parseCapabilities(raw, label) {
  if (!raw) {
    return {};
  }
  if (typeof raw === 'object') {
    return { ...raw };
  }
  try {
    return JSON.parse(raw);
  } catch (error) {
    throw new Error(`Failed to parse ${label || 'capabilities'}: ${error.message}`);
  }
}

function withAppiumPrefix(caps) {
  const result = {};
  for (const [key, value] of Object.entries(caps)) {
    result[key] = value;
    if (!key.includes(':')) {
      result[`appium:${key}`] = value;
    }
  }
  return result;
}

function buildAndroidCapabilities(overrides = {}) {
  const envCaps = parseCapabilities(process.env.TG_ANDROID_CAPABILITIES, 'TG_ANDROID_CAPABILITIES');
  const shared = parseCapabilities(
    process.env.APPIUM_REMOTE_CAPABILITIES || process.env.SELENIUM_REMOTE_CAPABILITIES,
    'APPIUM_REMOTE_CAPABILITIES'
  );
  const base = {
    platformName: 'android',
    automationName: 'UiAutomator2',
    browserName: 'chrome',
    ...shared,
    ...envCaps,
    ...overrides
  };
  return withAppiumPrefix(base);
}

function buildIosCapabilities(overrides = {}) {
  const envCaps = parseCapabilities(process.env.TG_IOS_CAPABILITIES, 'TG_IOS_CAPABILITIES');
  const shared = parseCapabilities(
    process.env.APPIUM_REMOTE_CAPABILITIES || process.env.SELENIUM_REMOTE_CAPABILITIES,
    'APPIUM_REMOTE_CAPABILITIES'
  );
  const base = {
    platformName: 'iOS',
    automationName: 'XCUITest',
    browserName: 'safari',
    ...shared,
    ...envCaps,
    ...overrides
  };
  return withAppiumPrefix(base);
}

function resolveRemoteUrl(options, fallbackEnv) {
  return (
    options?.remoteUrl ||
    process.env[fallbackEnv] ||
    process.env.APPIUM_REMOTE_URL ||
    process.env.SELENIUM_REMOTE_URL ||
    process.env.TG_DEVICE_REMOTE_URL
  );
}

async function createAndroidDriver(options = {}) {
  const remoteUrl = resolveRemoteUrl(options, 'TG_ANDROID_REMOTE_URL');
  if (!remoteUrl) {
    throw new Error('Android driver requires remoteUrl (set TG_ANDROID_REMOTE_URL or APPIUM_REMOTE_URL).');
  }
  const capabilities = buildAndroidCapabilities(options.capabilities);
  const builder = new Builder().usingServer(remoteUrl).withCapabilities(capabilities);
  const browserName = capabilities['appium:browserName'] || capabilities.browserName;
  if (browserName) {
    builder.forBrowser(browserName);
  }
  return builder.build();
}

async function createIosDriver(options = {}) {
  const remoteUrl = resolveRemoteUrl(options, 'TG_IOS_REMOTE_URL');
  if (!remoteUrl) {
    throw new Error('iOS driver requires remoteUrl (set TG_IOS_REMOTE_URL or APPIUM_REMOTE_URL).');
  }
  const capabilities = buildIosCapabilities(options.capabilities);
  const builder = new Builder().usingServer(remoteUrl).withCapabilities(capabilities);
  const browserName = capabilities['appium:browserName'] || capabilities.browserName;
  if (browserName) {
    builder.forBrowser(browserName);
  }
  return builder.build();
}

module.exports = {
  buildAndroidCapabilities,
  buildIosCapabilities,
  createAndroidDriver,
  createIosDriver
};