@limrun/appium-xcuitest-driver 10.4.3-lim.1

package/lib/device-log/ios-simulator-log.ts

@@ -0,0 +1,202 @@
+import _ from 'lodash';
+import {SubProcess, exec} from 'teen_process';
+import {util} from 'appium/support';
+import { LineConsumingLog } from './line-consuming-log';
+import { transports, createLogger, format, Logger } from 'winston';
+import type { Simulator } from '@limrun/appium-ios-simulator';
+import type { AppiumLogger } from '@appium/types';
+import fs from 'node:fs/promises';
+
+const EXECVP_ERROR_PATTERN = /execvp\(\)/;
+const LOG_STREAMING_PROCESS_NAME_PATTERN = /^com\.apple\.xpc\.launchd\.oneshot\.0x[0-f]+\.log$/;
+
+const START_TIMEOUT = 10000;
+
+export interface IOSSimulatorLogOptions {
+  sim: Simulator;
+  showLogs?: boolean;
+  iosSimulatorLogsPredicate?: string;
+  simulatorLogLevel?: string;
+  log: AppiumLogger;
+  iosSyslogFile?: string;
+}
+
+export class IOSSimulatorLog extends LineConsumingLog {
+  private readonly sim: Simulator;
+  private readonly showLogs: boolean;
+  private readonly predicate?: string;
+  private readonly logLevel?: string;
+  private proc: SubProcess | null;
+  private readonly iosSyslogFile?: string;
+  private syslogLogger: Logger | null;
+
+  constructor(opts: IOSSimulatorLogOptions) {
+    super({log: opts.log});
+    this.sim = opts.sim;
+    this.showLogs = !!opts.showLogs;
+    this.predicate = opts.iosSimulatorLogsPredicate;
+    this.logLevel = opts.simulatorLogLevel;
+    this.proc = null;
+    this.iosSyslogFile = opts.iosSyslogFile;
+    this.syslogLogger = null;
+  }
+
+  override async startCapture(): Promise<void> {
+    if (_.isUndefined(this.sim.udid)) {
+      throw new Error(`Log capture requires a sim udid`);
+    }
+    if (!(await this.sim.isRunning())) {
+      throw new Error(`iOS Simulator with udid '${this.sim.udid}' is not running`);
+    }
+    if (this.iosSyslogFile && this.showLogs) {
+      await this.clearExistingSyslog();
+      try {
+        this.syslogLogger = createLogger({
+          level: 'info',
+          format: format.combine(format.timestamp(), format.simple()),
+          transports: [new transports.File({filename: this.iosSyslogFile})],
+          exitOnError: false
+        });
+        this.log.debug(`iOS syslog will be written to: '${this.iosSyslogFile}'`);
+      } catch (e) {
+        this.log.warn(`Could not set up iOS syslog logger for '${this.iosSyslogFile}': ${e.message}`);
+        this.syslogLogger = null;
+      }
+    }
+    const spawnArgs = ['log', 'stream', '--style', 'compact'];
+    if (this.predicate) {
+      spawnArgs.push('--predicate', this.predicate);
+    }
+    if (this.logLevel) {
+      spawnArgs.push('--level', this.logLevel);
+    }
+    this.log.debug(
+      `Starting log capture for iOS Simulator with udid '${this.sim.udid}' ` +
+      `via simctl using the following arguments '${util.quote(spawnArgs)}'`
+    );
+    await this.cleanupObsoleteLogStreams();
+    try {
+      this.proc = await this.sim.simctl.spawnSubProcess(spawnArgs);
+      await this.finishStartingLogCapture();
+    } catch (e) {
+      this.shutdownSyslogger();
+      throw new Error(`Simulator log capture failed. Original error: ${e.message}`);
+    }
+  }
+
+  override async stopCapture(): Promise<void> {
+    if (!this.proc) {
+      return;
+    }
+    await this.killLogSubProcess();
+    this.proc = null;
+    this.shutdownSyslogger();
+  }
+
+  override get isCapturing(): boolean {
+    return Boolean(this.proc?.isRunning);
+  }
+
+  private async clearExistingSyslog(): Promise<void> {
+    if (this.iosSyslogFile === undefined) {
+      this.log.debug('iOS Syslog file path is not defined, skipping deletion.');
+      return;
+    }
+    try {
+      await fs.unlink(this.iosSyslogFile);
+      this.log.debug(`Existing iOS Syslog file: '${this.iosSyslogFile}' deleted.`);
+    } catch (unlinkErr) {
+      if (unlinkErr.code !== 'ENOENT') {
+        this.log.warn(`Could not delete existing syslog file '${this.iosSyslogFile}': ${unlinkErr.message}`);
+      }
+    }
+  }
+
+  private shutdownSyslogger(): void {
+    if (this.syslogLogger) {
+      this.log.debug(`Closing iOS syslog file: '${this.iosSyslogFile}'`);
+      const fileTransport = this.syslogLogger.transports.find(
+        (t) => (t instanceof transports.File) && (t.filename === this.iosSyslogFile)
+      );
+      if (fileTransport) {
+        fileTransport.end?.();
+        this.syslogLogger.remove(fileTransport);
+      }
+      this.syslogLogger = null;
+    }
+  }
+
+  private onOutput(logRow: string, prefix: string = ''): void {
+    this.broadcast(logRow);
+    const space = prefix.length > 0 ? ' ' : '';
+    if (this.showLogs && !this.iosSyslogFile) {
+      this.log.info(`[IOS_SYSLOG_ROW${space}${prefix}] ${logRow}`);
+    } else if (this.iosSyslogFile && this.showLogs) {
+      this.writeToSyslogFile(`[IOS_SYSLOG_ROW${space}${prefix}] ${logRow}`);
+    }
+  }
+
+  /**
+   * Writes the given log row to the dedicated iOS syslog file if the logger is active.
+   * @param {string} logRow - The log line to write.
+   * @private
+   */
+  private writeToSyslogFile(logRow: string): void {
+    if (this.syslogLogger && this.showLogs) {
+      this.syslogLogger.info(logRow);
+    }
+  }
+
+  private async killLogSubProcess(): Promise<void> {
+    if (!this.proc?.isRunning) {
+      return;
+    }
+    this.log.debug('Stopping iOS log capture');
+    try {
+      await this.proc.stop('SIGTERM', 1000);
+    } catch {
+      if (!this.proc.isRunning) {
+        return;
+      }
+      this.log.warn('Cannot stop log capture process. Sending SIGKILL');
+      await this.proc.stop('SIGKILL');
+    }
+  }
+
+  private async finishStartingLogCapture(): Promise<void> {
+    if (!this.proc) {
+      throw this.log.errorWithException('Could not capture simulator log');
+    }
+    for (const streamName of ['stdout', 'stderr']) {
+      this.proc.on(`line-${streamName}`, (line: string) => {
+        this.onOutput(line, ...(streamName === 'stderr' ? ['STDERR'] : []));
+      });
+    }
+    const startDetector = (stdout: string, stderr: string) => {
+      if (EXECVP_ERROR_PATTERN.test(stderr)) {
+        throw new Error('iOS log capture process failed to start');
+      }
+      return Boolean(stdout || stderr);
+    };
+    await this.proc.start(startDetector, START_TIMEOUT);
+  }
+
+  private async cleanupObsoleteLogStreams(): Promise<void> {
+    const processes = await this.sim.ps();
+    const pids = processes
+      .filter(({name}) => LOG_STREAMING_PROCESS_NAME_PATTERN.test(name))
+      .map(({pid}) => pid);
+    if (_.isEmpty(pids)) {
+      return;
+    }
+    try {
+      await exec('kill', pids.map(String));
+    } catch (e) {
+      this.log.warn(
+        `Could not terminate one or more obsolete log streams: ${e.stderr || e.message}`
+      );
+    }
+  }
+}
+
+export default IOSSimulatorLog;

package/lib/device-log/line-consuming-log.ts

@@ -0,0 +1,16 @@
+import {IOSLog} from './ios-log';
+import { toLogEntry } from './helpers';
+import type { LogEntry } from '../commands/types';
+
+type TSerializedEntry = [string, number];
+
+export abstract class LineConsumingLog extends IOSLog<string, TSerializedEntry> {
+  protected override _serializeEntry(value: string): TSerializedEntry {
+    return [value, Date.now()];
+  }
+
+  protected override _deserializeEntry(value: TSerializedEntry): LogEntry {
+    const [message, timestamp] = value;
+    return toLogEntry(message, timestamp);
+  }
+}

package/lib/device-log/safari-console-log.ts

@@ -0,0 +1,117 @@
+import _ from 'lodash';
+import type { AppiumLogger } from '@appium/types';
+import {
+  toLogEntry,
+  DEFAULT_LOG_LEVEL,
+  MAX_JSON_LOG_LENGTH,
+  MAX_BUFFERED_EVENTS_COUNT
+} from './helpers';
+import { IOSLog } from './ios-log';
+import type { LogEntry } from '../commands/types';
+
+const LOG_LEVELS_MAP = {
+  error: 'SEVERE',
+  warning: 'WARNING',
+  log: 'FINE',
+};
+
+export interface SafariConsoleLogOptions {
+  showLogs: boolean;
+  log: AppiumLogger;
+}
+
+export interface SafariConsoleStacktraceEntry {
+  functionName: string;
+  url: string;
+  scriptId: number;
+  lineNumber: number;
+  columnNumber: number;
+}
+
+export interface SafariConsoleEntry {
+  source: string;
+  level: string;
+  text: string;
+  type: string;
+  line: number;
+  column: number;
+  url?: string;
+  repeatCount: number;
+  stackTrace: SafariConsoleStacktraceEntry[];
+}
+
+type TSerializedEntry = [SafariConsoleEntry, number];
+
+export class SafariConsoleLog extends IOSLog<SafariConsoleEntry, TSerializedEntry> {
+  private readonly _showLogs: boolean;
+
+  constructor(opts: SafariConsoleLogOptions) {
+    super({
+      log: opts.log,
+      maxBufferSize: MAX_BUFFERED_EVENTS_COUNT,
+    });
+    this._showLogs = opts.showLogs;
+  }
+
+  override async startCapture(): Promise<void> {}
+  override async stopCapture(): Promise<void> {}
+  override get isCapturing(): boolean {
+    return true;
+  }
+
+  /**
+   *
+   * @param err
+   * @param entry The output will be like:
+   *   {
+   *     "source": "javascript",
+   *     "level":"error",
+   *     "text":"ReferenceError: Can't find variable: s_account",
+   *     "type":"log",
+   *     "line":2,
+   *     "column":21,
+   *     "url":"https://assets.adobedtm.com/b46e318d845250834eda10c5a20827c045a4d76f/scripts/satellite-57866f8b64746d53a8000104-staging.js",
+   *     "repeatCount":1,
+   *     "stackTrace":[{
+   *       "functionName":"global code",
+   *       "url":"https://assets.adobedtm.com/b46e318d845250834eda10c5a20827c045a4d76f/scripts/satellite-57866f8b64746d53a8000104-staging.js",
+   *       "scriptId":"6",
+   *       "lineNumber":2,
+   *       "columnNumber":21
+   *     }]
+   *  }
+   *
+   * we need, at least, `level` (in accordance with Java levels
+   * (https://docs.oracle.com/javase/7/docs/api/java/util/logging/Level.html)),
+   * `timestamp`, and `message` to satisfy the java client. In order to
+   * provide all the information to the client, `message` is the full
+   * object, stringified.
+   *
+   */
+  onConsoleLogEvent(err?: Error, entry?: SafariConsoleEntry): void {
+    if (!entry) {
+      this.log.debug(`[SafariConsole] Ignoring empty console log entry: ${err?.message}`);
+      return;
+    }
+
+    this.broadcast(entry);
+    if (this._showLogs) {
+      this.log.info(`[SafariConsole] ${_.truncate(JSON.stringify(entry), {length: MAX_JSON_LOG_LENGTH})}`);
+    }
+  }
+
+  protected override _serializeEntry(value: SafariConsoleEntry): TSerializedEntry {
+    return [value, Date.now()];
+  }
+
+  protected override _deserializeEntry(value: TSerializedEntry): LogEntry {
+    const [entry, timestamp] = value;
+    return toLogEntry(JSON.stringify(entry), timestamp, mapLogLevel(entry.level));
+  }
+}
+
+function mapLogLevel(originalLevel: string): string {
+  return LOG_LEVELS_MAP[originalLevel] ?? DEFAULT_LOG_LEVEL;
+}
+
+export default SafariConsoleLog;

package/lib/device-log/safari-network-log.ts

@@ -0,0 +1,120 @@
+import _ from 'lodash';
+import { LineConsumingLog } from './line-consuming-log';
+import { MAX_JSON_LOG_LENGTH, MAX_BUFFERED_EVENTS_COUNT } from './helpers';
+import type { AppiumLogger, StringRecord } from '@appium/types';
+
+const EVENTS_TO_LOG = [
+  'Network.loadingFinished',
+  'Network.loadingFailed',
+];
+const MONITORED_EVENTS = [
+  'Network.requestWillBeSent',
+  'Network.responseReceived',
+  ...EVENTS_TO_LOG,
+];
+
+export interface SafariConsoleLogOptions {
+  showLogs: boolean;
+  log: AppiumLogger;
+}
+
+export interface SafariNetworkResponseTiming {
+  startTime: number;
+  redirectStart: number;
+  redirectEnd: number;
+  fetchStart: number;
+  domainLookupStart: number;
+  domainLookupEnd: number;
+  connectStart: number;
+  connectEnd: number;
+  secureConnectionStart: number;
+  requestStart: number;
+  responseStart: number;
+  responseEnd: number;
+}
+
+export interface SafariNetworkResponse {
+  url: string;
+  status: number;
+  statusText: string;
+  headers: Record<string, string>;
+  mimeType: string;
+  timing: SafariNetworkResponseTiming;
+  source: string;
+  security: StringRecord
+}
+
+export interface SafariNetworkLogEntryMetrics {
+  requestHeaderBytesSent: number;
+  requestBodyBytesSent: number;
+  responseHeaderBytesReceived: number;
+  isProxyConnection: boolean;
+  responseBodyBytesReceived: number;
+  responseBodyDecodedSize: number;
+  securityConnection: StringRecord;
+}
+
+export interface SafariNetworkRequest {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  rereferrerPolicy: string;
+}
+
+export interface SafariNetworkRequestInitiator {
+  type: string;
+}
+
+export interface SafariNetworkLogEntry {
+  requestId: string;
+  frameId?: string;
+  loaderId?: string;
+  documentURL?: string;
+  request?: SafariNetworkRequest
+  timestamp?: number;
+  walltime?: number;
+  inititator?: SafariNetworkRequestInitiator;
+  response?: SafariNetworkResponse;
+  type?: string;
+  initiator?: string;
+  // Safari has a `metrics` object on it's `Network.loadingFinished` event
+  metrics?: SafariNetworkLogEntryMetrics;
+  errorText?: string;
+  // When a network call is cancelled, Safari returns `cancelled` as error text
+  // but has a boolean `canceled`.
+  canceled?: boolean;
+  [key: string]: any; // Allow additional properties
+}
+
+export class SafariNetworkLog extends LineConsumingLog {
+  private readonly _showLogs: boolean;
+
+  constructor(opts: SafariConsoleLogOptions) {
+    super({
+      log: opts.log,
+      maxBufferSize: MAX_BUFFERED_EVENTS_COUNT,
+    });
+    this._showLogs = opts.showLogs;
+  }
+
+  override async startCapture(): Promise<void> {}
+  override async stopCapture(): Promise<void> {}
+  override get isCapturing(): boolean {
+    return true;
+  }
+
+  onNetworkEvent(err?: Error, entry?: SafariNetworkLogEntry, method?: string): void {
+    if (!_.includes(MONITORED_EVENTS, method)) {
+      this.log.debug(`[SafariNetwork] Ignoring unmonitored event: ${method}`);
+      return;
+    }
+
+    const serializedEntry = JSON.stringify({method, event: entry});
+    this.broadcast(serializedEntry);
+    if (this._showLogs && _.includes(EVENTS_TO_LOG, method)) {
+      this.log.info(`[SafariNetwork] ${_.truncate(serializedEntry, {length: MAX_JSON_LOG_LENGTH})}`);
+    }
+  }
+}
+
+export default SafariNetworkLog;

package/lib/doctor/checks.ts

@@ -0,0 +1,3 @@
+export * as required from './required-checks';
+export * as optional from './optional-checks';
+

package/lib/doctor/optional-checks.ts

@@ -0,0 +1,173 @@
+import {resolveExecutablePath} from './utils';
+import {doctor} from 'appium/support';
+import type {IDoctorCheck, AppiumLogger, DoctorCheckResult} from '@appium/types';
+import '@colors/colors';
+import {exec} from 'teen_process';
+
+export class OptionalIdbCommandCheck implements IDoctorCheck {
+  log!: AppiumLogger;
+  static readonly IDB_README_URL = 'https://git.io/JnxQc';
+
+  async diagnose(): Promise<DoctorCheckResult> {
+    const fbIdbPath = await resolveExecutablePath('idb');
+    const fbCompanionIdbPath = await resolveExecutablePath('idb_companion');
+    if (fbIdbPath && fbCompanionIdbPath) {
+      return doctor.okOptional('idb and idb_companion are installed');
+    }
+
+    if (!fbIdbPath && fbCompanionIdbPath) {
+      return doctor.nokOptional('idb is not installed');
+    } else if (fbIdbPath && !fbCompanionIdbPath) {
+      return doctor.nokOptional('idb_companion is not installed');
+    }
+    return doctor.nokOptional('idb and idb_companion are not installed');
+  }
+
+  async fix(): Promise<string> {
+    return `Why ${'idb'.bold} is needed and how to install it: ${OptionalIdbCommandCheck.IDB_README_URL}`;
+  }
+
+  hasAutofix(): boolean {
+    return false;
+  }
+
+  isOptional(): boolean {
+    return true;
+  }
+}
+export const optionalIdbCheck = new OptionalIdbCommandCheck();
+
+export class OptionalSimulatorCheck implements IDoctorCheck {
+  log!: AppiumLogger;
+  static readonly SUPPORTED_SIMULATOR_PLATFORMS: SimulatorPlatform[] = [
+    {
+      displayName: 'iOS',
+      name: 'iphonesimulator'
+    },
+    {
+      displayName: 'tvOS',
+      name: 'appletvsimulator'
+    }
+  ];
+
+  async diagnose(): Promise<DoctorCheckResult> {
+    try {
+      // https://github.com/appium/appium/issues/12093#issuecomment-459358120
+      await exec('xcrun', ['simctl', 'help']);
+    } catch (err) {
+      return doctor.nokOptional(
+        `Testing on Simulator is not possible. Cannot run 'xcrun simctl': ${(err as any).stderr || (err as Error).message}`
+      );
+    }
+
+    const sdks = await this._listInstalledSdks();
+    for (const {displayName, name} of OptionalSimulatorCheck.SUPPORTED_SIMULATOR_PLATFORMS) {
+      const errorPrefix = `Testing on ${displayName} Simulator is not possible`;
+      if (!sdks.some(({platform}) => platform === name)) {
+        return doctor.nokOptional(`${errorPrefix}: SDK is not installed`);
+      }
+    }
+
+    return doctor.okOptional(
+      `The following Simulator SDKs are installed:\n` +
+      sdks
+        .filter(({platform}) => OptionalSimulatorCheck.SUPPORTED_SIMULATOR_PLATFORMS.some(({name}) => name === platform))
+        .map(({displayName}) => `\t→ ${displayName}`).join('\n')
+    );
+  }
+
+  async fix(): Promise<string> {
+    return `Install the desired Simulator SDK from Xcode's Settings -> Components`;
+  }
+
+  hasAutofix(): boolean {
+    return false;
+  }
+
+  isOptional(): boolean {
+    return true;
+  }
+
+  private async _listInstalledSdks(): Promise<InstalledSdk[]> {
+    const {stdout} = await exec('xcodebuild', ['-json', '-showsdks']);
+    return JSON.parse(stdout);
+  }
+}
+export const optionalSimulatorCheck = new OptionalSimulatorCheck();
+
+export class OptionalApplesimutilsCommandCheck implements IDoctorCheck {
+  log!: AppiumLogger;
+  static readonly README_LINK = 'https://github.com/appium/appium-xcuitest-driver/blob/master/docs/reference/execute-methods.md#mobile-setpermission';
+
+  async diagnose(): Promise<DoctorCheckResult> {
+    const applesimutilsPath = await resolveExecutablePath('applesimutils');
+    return applesimutilsPath
+      ? doctor.okOptional(`applesimutils is installed at: ${applesimutilsPath}`)
+      : doctor.nokOptional('applesimutils are not installed');
+  }
+
+  async fix(): Promise<string> {
+    return `Why ${'applesimutils'.bold} is needed and how to install it: ${OptionalApplesimutilsCommandCheck.README_LINK}`;
+  }
+
+  hasAutofix(): boolean {
+    return false;
+  }
+
+  isOptional(): boolean {
+    return true;
+  }
+}
+export const optionalApplesimutilsCheck = new OptionalApplesimutilsCommandCheck();
+
+
+export class OptionalFfmpegCheck implements IDoctorCheck {
+  log!: AppiumLogger;
+  static readonly FFMPEG_BINARY = 'ffmpeg';
+  static readonly FFMPEG_INSTALL_LINK = 'https://www.ffmpeg.org/download.html';
+
+  async diagnose(): Promise<DoctorCheckResult> {
+    const ffmpegPath = await resolveExecutablePath(OptionalFfmpegCheck.FFMPEG_BINARY);
+
+    return ffmpegPath
+      ? doctor.okOptional(`${OptionalFfmpegCheck.FFMPEG_BINARY} exists at '${ffmpegPath}'`)
+      : doctor.nokOptional(`${OptionalFfmpegCheck.FFMPEG_BINARY} cannot be found`);
+  }
+
+  async fix(): Promise<string> {
+    return (
+      `${`${OptionalFfmpegCheck.FFMPEG_BINARY}`.bold} is used to capture screen recordings from the device under test. ` +
+      `Please read ${OptionalFfmpegCheck.FFMPEG_INSTALL_LINK}.`
+    );
+  }
+
+  hasAutofix(): boolean {
+    return false;
+  }
+
+  isOptional(): boolean {
+    return true;
+  }
+}
+export const optionalFfmpegCheck = new OptionalFfmpegCheck();
+
+interface SimulatorPlatform {
+  displayName: string;
+  name: string;
+}
+
+interface InstalledSdk {
+  buildID?: string;
+  canonicalName: string;
+  displayName: string;
+  isBaseSdk: boolean;
+  platform: string;
+  platformPath: string;
+  platformVersion: string;
+  productBuildVersion?: string;
+  productCopyright?: string;
+  productName?: string;
+  productVersion?: string;
+  sdkPath: string;
+  sdkVersion: string;
+}