appium-android-driver/lib/commands/system-bars.ts

Android UiAutomator and Chrome support for Appium

import {errors} from 'appium/driver';
import _ from 'lodash';
import type {StringRecord} from '@appium/types';
import type {AndroidDriver} from '../driver';
import type {StatusBarCommand, WindowProperties} from './types';

const WINDOW_TITLE_PATTERN = /^\s+Window\s#\d+\sWindow\{[0-9a-f]+\s\w+\s([\w-]+)\}:$/;
const FRAME_PATTERN = /\bm?[Ff]rame=\[([0-9.-]+),([0-9.-]+)\]\[([0-9.-]+),([0-9.-]+)\]/;
// https://github.com/appium/appium-uiautomator2-driver/issues/904
const STATUS_BAR_TYPE_PATTERN = /\bty=STATUS_BAR\b/;
const NAVIGATION_BAR_TYPE_PATTERN = /\bty=NAVIGATION_BAR\b/;
const VIEW_VISIBILITY_PATTERN = /\bmViewVisibility=(0x[0-9a-fA-F]+)/;
// https://developer.android.com/reference/android/view/View#VISIBLE
const VIEW_VISIBLE = 0x0;
const STATUS_BAR_WINDOW_NAME_PREFIX = 'StatusBar';
const NAVIGATION_BAR_WINDOW_NAME_PREFIX = 'NavigationBar';
const DEFAULT_WINDOW_PROPERTIES: WindowProperties = {
  visible: false,
  x: 0,
  y: 0,
  width: 0,
  height: 0,
};

/**
 * Gets the system bars (status bar and navigation bar) properties.
 *
 * @returns Promise that resolves to an object containing statusBar and navigationBar properties.
 * @throws {Error} If system bars details cannot be retrieved or parsed.
 */
export async function getSystemBars(
  this: AndroidDriver,
): Promise<StringRecord> {
  let stdout: string;
  try {
    stdout = await this.adb.shell(['dumpsys', 'window', 'windows']);
  } catch (e) {
    throw new Error(
      `Cannot retrieve system bars details. Original error: ${(e as Error).message}`,
    );
  }
  return parseWindows.bind(this)(stdout);
}

/**
 * Performs a status bar command.
 *
 * @param command The status bar command to perform.
 * @param component The name of the tile component.
 * It is only required for `(add|remove|click)Tile` commands.
 * Example value: `com.package.name/.service.QuickSettingsTileComponent`
 * @returns Promise that resolves to the command output string.
 * @throws {errors.InvalidArgumentError} If the command is unknown.
 */
export async function mobilePerformStatusBarCommand(
  this: AndroidDriver,
  command: StatusBarCommand,
  component?: string,
): Promise<string> {
  const toStatusBarCommandCallable = (
    cmd: string,
    argsCallable?: () => string[] | string,
  ) => async (): Promise<string> =>
    await this.adb.shell([
      'cmd',
      'statusbar',
      cmd,
      ...(argsCallable ? _.castArray(argsCallable()) : []),
    ]);
  const tileCommandArgsCallable = () => component as string;
  const statusBarCommands = _.fromPairs(
    ([
      ['expandNotifications', ['expand-notifications']],
      ['expandSettings', ['expand-settings']],
      ['collapse', ['collapse']],
      ['addTile', ['add-tile', tileCommandArgsCallable]],
      ['removeTile', ['remove-tile', tileCommandArgsCallable]],
      ['clickTile', ['click-tile', tileCommandArgsCallable]],
      ['getStatusIcons', ['get-status-icons']],
    ] as const).map(([name, args]) => [name, toStatusBarCommandCallable(args[0], args[1])]),
  ) as Record<StatusBarCommand, () => Promise<string>>;

  const action = statusBarCommands[command];
  if (!action) {
    throw new errors.InvalidArgumentError(
      `The '${command}' status bar command is unknown. Only the following commands ` +
        `are supported: ${_.keys(statusBarCommands)}`,
    );
  }
  return await action();
}

// #region Internal helpers

/**
 * Parses window properties from adb dumpsys output
 *
 * @param name The name of the window whose properties are being parsed
 * @param props The list of particular window property lines.
 * Check the corresponding unit tests for more details on the input format.
 * @returns Parsed properties object
 * @throws {Error} If there was an issue while parsing the properties string
 */
export function parseWindowProperties(
  this: AndroidDriver,
  name: string,
  props: string[],
): WindowProperties {
  const result = _.cloneDeep(DEFAULT_WINDOW_PROPERTIES);
  const propLines = props.join('\n');
  const frameMatch = FRAME_PATTERN.exec(propLines);
  if (!frameMatch) {
    this.log.debug(propLines);
    throw new Error(`Cannot parse the frame size from '${name}' window properties`);
  }
  result.x = parseFloat(frameMatch[1]);
  result.y = parseFloat(frameMatch[2]);
  result.width = parseFloat(frameMatch[3]) - result.x;
  result.height = parseFloat(frameMatch[4]) - result.y;
  const visibilityMatch = VIEW_VISIBILITY_PATTERN.exec(propLines);
  if (!visibilityMatch) {
    this.log.debug(propLines);
    throw new Error(`Cannot parse the visibility value from '${name}' window properties`);
  }
  result.visible = parseInt(visibilityMatch[1], 16) === VIEW_VISIBLE;
  return result;
}

/**
 * Extracts status and navigation bar information from the window manager output.
 *
 * @param lines Output from dumpsys command.
 * Check the corresponding unit tests for more details on the input format.
 * @return An object containing two items where keys are statusBar and navigationBar,
 * and values are corresponding WindowProperties objects
 * @throws {Error} If no window properties could be parsed
 */
export function parseWindows(
  this: AndroidDriver,
  lines: string,
): SystemBarsResult {
  const windows: StringRecord<string[]> = {};
  let currentWindowName: string | null = null;
  for (const line of lines.split('\n').map(_.trimEnd)) {
    const match = WINDOW_TITLE_PATTERN.exec(line);
    if (match) {
      currentWindowName = match[1];
      windows[currentWindowName] = [];
      continue;
    }
    if (_.trim(line).length === 0) {
      currentWindowName = null;
      continue;
    }

    if (currentWindowName && _.isArray(windows[currentWindowName])) {
      windows[currentWindowName].push(line);
    }
  }
  if (_.isEmpty(windows)) {
    this.log.debug(lines);
    throw new Error('Cannot parse any window information from the dumpsys output');
  }

  const result: SystemBarsResult = {};
  for (const [name, props] of _.toPairs(windows)) {
    if (
      name.startsWith(STATUS_BAR_WINDOW_NAME_PREFIX)
      || props.some((line: string) => STATUS_BAR_TYPE_PATTERN.test(line))
    ) {
      result.statusBar = parseWindowProperties.bind(this)(name, props);
    } else if (
      name.startsWith(NAVIGATION_BAR_WINDOW_NAME_PREFIX)
      || props.some((line: string) => NAVIGATION_BAR_TYPE_PATTERN.test(line))
    ) {
      result.navigationBar = parseWindowProperties.bind(this)(name, props);
    }
  }
  const unmatchedWindows = ([
    ['statusBar', STATUS_BAR_WINDOW_NAME_PREFIX],
    ['navigationBar', NAVIGATION_BAR_WINDOW_NAME_PREFIX],
  ] as const).filter(([name]) => _.isNil(result[name as keyof SystemBarsResult]));
  for (const [window, namePrefix] of unmatchedWindows) {
    this.log.info(
      `No windows have been found whose title matches to ` +
        `'${namePrefix}'. Assuming it is invisible. ` +
        `Only the following windows are available: ${_.keys(windows)}`,
    );
    result[window as keyof SystemBarsResult] = _.cloneDeep(DEFAULT_WINDOW_PROPERTIES);
  }
  return result;
}

// #endregion

interface SystemBarsResult {
  statusBar?: WindowProperties;
  navigationBar?: WindowProperties;
}