appium-mac2-driver 4.5.0 → 4.6.0

package/node_modules/@appium/base-driver/lib/protocol/routes/w3c.ts

@@ -0,0 +1,253 @@
+import type {Driver, MethodMap} from '@appium/types';
+
+/**
+ * Standard W3C WebDriver routes.
+ * @see https://www.w3.org/TR/webdriver2/
+ */
+export const W3C_ROUTES = {
+  // Sessions
+  '/session': {
+    POST: {
+      command: 'createSession',
+      payloadParams: {
+        // Deliberately sent 3 times: this array is spread directly into any plugin hooking
+        // 'createSession' (see AppiumDriver#wrapCommandWithPlugins), so changing its shape here
+        // would be a wire-level breaking change for third-party plugins, not just drivers. Keep
+        // this in sync with the deprecated multi-argument overload of `createSession`.
+        optional: ['capabilities', 'capabilities', 'capabilities'],
+      },
+    },
+  },
+  '/session/:sessionId': {
+    // TODO: JSONWP route, remove in the future
+    GET: {command: 'getSession', deprecated: true},
+    DELETE: {command: 'deleteSession'},
+  },
+  '/status': {
+    GET: {command: 'getStatus'},
+  },
+
+  // Timeouts
+  '/session/:sessionId/timeouts': {
+    GET: {command: 'getTimeouts'},
+    POST: {
+      command: 'timeouts',
+      payloadParams: {
+        optional: ['type', 'ms', 'script', 'pageLoad', 'implicit'],
+      },
+    },
+  },
+
+  // Navigation
+  '/session/:sessionId/url': {
+    GET: {command: 'getUrl'},
+    POST: {command: 'setUrl', payloadParams: {required: ['url']}},
+  },
+  '/session/:sessionId/forward': {
+    POST: {command: 'forward'},
+  },
+  '/session/:sessionId/back': {
+    POST: {command: 'back'},
+  },
+  '/session/:sessionId/refresh': {
+    POST: {command: 'refresh'},
+  },
+  '/session/:sessionId/title': {
+    GET: {command: 'title'},
+  },
+
+  // Contexts (windows and frames)
+  '/session/:sessionId/window': {
+    GET: {command: 'getWindowHandle'},
+    POST: {
+      command: 'setWindow',
+      payloadParams: {
+        required: ['handle'],
+      },
+    },
+    DELETE: {command: 'closeWindow'},
+  },
+  '/session/:sessionId/window/handles': {
+    GET: {command: 'getWindowHandles'},
+  },
+  '/session/:sessionId/window/new': {
+    POST: {command: 'createNewWindow', payloadParams: {optional: ['type']}},
+  },
+  '/session/:sessionId/frame': {
+    POST: {command: 'setFrame', payloadParams: {required: ['id']}},
+  },
+  '/session/:sessionId/frame/parent': {
+    POST: {command: 'switchToParentFrame'},
+  },
+  '/session/:sessionId/window/rect': {
+    GET: {command: 'getWindowRect'},
+    POST: {
+      command: 'setWindowRect',
+      payloadParams: {optional: ['x', 'y', 'width', 'height']},
+    },
+  },
+  '/session/:sessionId/window/maximize': {
+    POST: {command: 'maximizeWindow'},
+  },
+  '/session/:sessionId/window/minimize': {
+    POST: {command: 'minimizeWindow'},
+  },
+  '/session/:sessionId/window/fullscreen': {
+    POST: {command: 'fullScreenWindow'},
+  },
+
+  // Elements
+  '/session/:sessionId/element/active': {
+    GET: {command: 'active'},
+  },
+  '/session/:sessionId/element/:elementId/shadow': {
+    GET: {command: 'elementShadowRoot'},
+  },
+  '/session/:sessionId/element': {
+    POST: {
+      command: 'findElement',
+      payloadParams: {required: ['using', 'value']},
+    },
+  },
+  '/session/:sessionId/elements': {
+    POST: {
+      command: 'findElements',
+      payloadParams: {required: ['using', 'value']},
+    },
+  },
+  '/session/:sessionId/element/:elementId/element': {
+    POST: {
+      command: 'findElementFromElement',
+      payloadParams: {required: ['using', 'value']},
+    },
+  },
+  '/session/:sessionId/element/:elementId/elements': {
+    POST: {
+      command: 'findElementsFromElement',
+      payloadParams: {required: ['using', 'value']},
+    },
+  },
+  '/session/:sessionId/shadow/:shadowId/element': {
+    POST: {
+      command: 'findElementFromShadowRoot',
+      payloadParams: {required: ['using', 'value']},
+    },
+  },
+  '/session/:sessionId/shadow/:shadowId/elements': {
+    POST: {
+      command: 'findElementsFromShadowRoot',
+      payloadParams: {required: ['using', 'value']},
+    },
+  },
+  '/session/:sessionId/element/:elementId/selected': {
+    GET: {command: 'elementSelected'},
+  },
+  '/session/:sessionId/element/:elementId/displayed': {
+    GET: {command: 'elementDisplayed'},
+  },
+  '/session/:sessionId/element/:elementId/attribute/:name': {
+    GET: {command: 'getAttribute'},
+  },
+  '/session/:sessionId/element/:elementId/property/:name': {
+    GET: {command: 'getProperty'},
+  },
+  '/session/:sessionId/element/:elementId/css/:propertyName': {
+    GET: {command: 'getCssProperty'},
+  },
+  '/session/:sessionId/element/:elementId/text': {
+    GET: {command: 'getText'},
+  },
+  '/session/:sessionId/element/:elementId/name': {
+    GET: {command: 'getName'},
+  },
+  '/session/:sessionId/element/:elementId/rect': {
+    GET: {command: 'getElementRect'},
+  },
+  '/session/:sessionId/element/:elementId/enabled': {
+    GET: {command: 'elementEnabled'},
+  },
+  '/session/:sessionId/element/:elementId/computedrole': {
+    GET: {command: 'getComputedRole'},
+  },
+  '/session/:sessionId/element/:elementId/computedlabel': {
+    GET: {command: 'getComputedLabel'},
+  },
+  '/session/:sessionId/element/:elementId/click': {
+    POST: {command: 'click'},
+  },
+  '/session/:sessionId/element/:elementId/clear': {
+    POST: {command: 'clear'},
+  },
+  '/session/:sessionId/element/:elementId/value': {
+    POST: {
+      command: 'setValue',
+      payloadParams: {
+        required: ['text'],
+      },
+    },
+  },
+
+  // Document
+  '/session/:sessionId/source': {
+    GET: {command: 'getPageSource'},
+  },
+  '/session/:sessionId/execute/sync': {
+    POST: {command: 'execute', payloadParams: {required: ['script', 'args']}},
+  },
+  '/session/:sessionId/execute/async': {
+    POST: {
+      command: 'executeAsync',
+      payloadParams: {required: ['script', 'args']},
+    },
+  },
+
+  // Cookies
+  '/session/:sessionId/cookie': {
+    GET: {command: 'getCookies'},
+    POST: {command: 'setCookie', payloadParams: {required: ['cookie']}},
+    DELETE: {command: 'deleteCookies'},
+  },
+  '/session/:sessionId/cookie/:name': {
+    GET: {command: 'getCookie'},
+    DELETE: {command: 'deleteCookie'},
+  },
+
+  // Actions
+  '/session/:sessionId/actions': {
+    POST: {command: 'performActions', payloadParams: {required: ['actions']}},
+    DELETE: {command: 'releaseActions'},
+  },
+
+  // User prompts (alerts)
+  '/session/:sessionId/alert/dismiss': {
+    POST: {command: 'postDismissAlert'},
+  },
+  '/session/:sessionId/alert/accept': {
+    POST: {command: 'postAcceptAlert'},
+  },
+  '/session/:sessionId/alert/text': {
+    GET: {command: 'getAlertText'},
+    POST: {
+      command: 'setAlertText',
+      payloadParams: {
+        required: ['text'],
+      },
+    },
+  },
+
+  // Screen capture and printing
+  '/session/:sessionId/screenshot': {
+    GET: {command: 'getScreenshot'},
+  },
+  '/session/:sessionId/element/:elementId/screenshot': {
+    GET: {command: 'getElementScreenshot'},
+  },
+  '/session/:sessionId/print': {
+    POST: {
+      command: 'printPage',
+      payloadParams: {
+        optional: ['orientation', 'scale', 'background', 'page', 'margin', 'shrinkToFit', 'pageRanges'],
+      },
+    },
+  },
+} as const satisfies MethodMap<Driver>;

package/node_modules/@appium/base-driver/lib/protocol/validators.ts

@@ -0,0 +1,20 @@
+import {util} from '@appium/support';
+
+const MAX_URL_ERROR_LENGTH = 100;
+
+export const validators = {
+  setUrl: (url: any) => {
+    if (!URL.canParse(url)) {
+      throw new Error(`'${util.truncateString(String(url), {length: MAX_URL_ERROR_LENGTH})}' must be a valid URL`);
+    }
+  },
+  setNetworkConnection: (type: any) => {
+    if (!isNumber(type) || [0, 1, 2, 4, 6].indexOf(type) === -1) {
+      throw new Error('Network type must be one of 0, 1, 2, 4, 6');
+    }
+  },
+};
+
+function isNumber(o: any): o is number {
+  return typeof o === 'number' || !Number.isNaN(parseInt(o, 10)) || !Number.isNaN(parseFloat(o));
+}

package/node_modules/@appium/base-driver/lib/test-pages/crash.ts

@@ -0,0 +1,15 @@
+import {errors} from '../protocol';
+
+/**
+ * Route handler that throws {@link errors.UnknownCommandError} for testing.
+ */
+export function produceError(): never {
+  throw new errors.UnknownCommandError('Produced generic error for testing');
+}
+
+/**
+ * Route handler that throws a generic Error for testing (e.g. crash scenarios).
+ */
+export function produceCrash(): never {
+  throw new Error('We just tried to crash Appium!');
+}

package/node_modules/@appium/base-driver/lib/test-pages/env.ts

@@ -0,0 +1,9 @@
+/** Environment variable that opts into deprecated built-in test pages on the Appium server. */
+export const LEGACY_TEST_PAGES_ENV = 'APPIUM_ENABLE_LEGACY_TEST_PAGES';
+
+const TRUTHY = new Set(['1', 'true', 'yes']);
+
+/** @returns Whether built-in legacy test pages should be mounted on the Appium server. */
+export function isLegacyTestPagesEnabled(): boolean {
+  return TRUTHY.has(String(process.env[LEGACY_TEST_PAGES_ENV] ?? '').toLowerCase());
+}

package/node_modules/@appium/base-driver/lib/test-pages/handlers.ts

@@ -0,0 +1,67 @@
+import path from 'node:path';
+
+import {fs} from '@appium/support';
+import {sleep} from 'asyncbox';
+import type {Request, Response} from 'express';
+
+import {log} from '../express/logger';
+import {TEST_FIXTURES_DIR} from './static-dir';
+import {compileLodashTemplate} from './template';
+
+type TemplateParams = Record<string, unknown>;
+
+/** Dynamic page mapped to /test/guinea-pig */
+export async function guineaPig(req: Request, res: Response): Promise<void> {
+  await guineaPigTemplate(req, res, 'guinea-pig.html');
+}
+
+/** Dynamic page mapped to /test/guinea-pig-scrollable */
+export async function guineaPigScrollable(req: Request, res: Response): Promise<void> {
+  await guineaPigTemplate(req, res, 'guinea-pig-scrollable.html');
+}
+
+/** Dynamic page mapped to /test/guinea-pig-app-banner */
+export async function guineaPigAppBanner(req: Request, res: Response): Promise<void> {
+  await guineaPigTemplate(req, res, 'guinea-pig-app-banner.html');
+}
+
+/** Dynamic page mapped to /welcome */
+export async function welcome(req: Request, res: Response): Promise<void> {
+  const params: TemplateParams = {message: "Let's browse!"};
+  log.debug(`Sending welcome response with params: ${JSON.stringify(params)}`);
+  const template = await getTemplate('welcome.html');
+  res.send(template(params));
+}
+
+async function guineaPigTemplate(req: Request, res: Response, page: string): Promise<void> {
+  const delay = parseInt(String(req.params.delay ?? req.query?.delay ?? 0), 10);
+  const throwError = String(req.params.throwError ?? req.query?.throwError ?? '');
+  const params: TemplateParams = {
+    throwError,
+    serverTime: new Date(),
+    userAgent: req.headers['user-agent'],
+    comment: 'None',
+  };
+  if (req.method === 'POST' && req.body && typeof req.body === 'object' && 'comments' in req.body) {
+    params.comment = String((req.body as {comments?: string}).comments ?? params.comment);
+  }
+  log.debug(`Sending guinea pig response with params: ${JSON.stringify(params)}`);
+  if (delay) {
+    log.debug(`Waiting ${delay}ms before responding`);
+    await sleep(delay);
+  }
+  res.set('content-type', 'text/html');
+  res.cookie('guineacookie1', 'i am a cookie value', {path: '/'});
+  res.cookie('guineacookie2', 'cookié2', {path: '/'});
+  res.cookie('guineacookie3', 'cant access this', {
+    domain: '.blargimarg.com',
+    path: '/',
+  });
+  const template = await getTemplate(page);
+  res.send(template(params));
+}
+
+async function getTemplate(templateName: string): Promise<(params: TemplateParams) => string> {
+  const content = await fs.readFile(path.resolve(TEST_FIXTURES_DIR, 'test', templateName));
+  return compileLodashTemplate(content.toString());
+}

package/node_modules/@appium/base-driver/lib/test-pages/index.ts

@@ -0,0 +1,36 @@
+import path from 'node:path';
+
+import express from 'express';
+import type {Express} from 'express';
+import favicon from 'serve-favicon';
+
+import {produceCrash, produceError} from './crash';
+import {guineaPig, guineaPigAppBanner, guineaPigScrollable, welcome} from './handlers';
+import {TEST_FIXTURES_DIR} from './static-dir';
+
+export interface RegisterTestPagesOpts {
+  basePath: string;
+}
+
+/**
+ * Mount deprecated built-in test pages and crash routes on an Express app.
+ *
+ * @deprecated Built-in test pages on the Appium server are deprecated and will be removed in
+ * Appium 4. Driver CI should hard-copy needed fixtures and run a local test HTTP server.
+ * @internal
+ */
+export function registerTestPages(app: Express, {basePath}: RegisterTestPagesOpts): void {
+  app.use(favicon(path.resolve(TEST_FIXTURES_DIR, 'favicon.ico')));
+  app.use(express.static(TEST_FIXTURES_DIR));
+
+  app.use(`${basePath}/produce_error`, produceError);
+  app.use(`${basePath}/crash`, produceCrash);
+
+  app.all('/welcome', welcome);
+  app.all('/test/guinea-pig', guineaPig);
+  app.all('/test/guinea-pig-scrollable', guineaPigScrollable);
+  app.all('/test/guinea-pig-app-banner', guineaPigAppBanner);
+}
+
+export {isLegacyTestPagesEnabled} from './env';
+export {TEST_FIXTURES_DIR} from './static-dir';

package/node_modules/@appium/base-driver/lib/test-pages/static-dir.ts

@@ -0,0 +1,19 @@
+import path from 'node:path';
+
+import {node} from '@appium/support';
+
+/**
+ * Absolute path to bundled legacy test fixture static files.
+ *
+ * @deprecated Removed in Appium 4. Test fixture files will live in the appium/test-fixtures
+ * repository. Do not depend on this path in driver CI — hard-copy needed files locally.
+ */
+export const TEST_FIXTURES_DIR = resolveTestFixturesDir();
+
+function resolveTestFixturesDir(): string {
+  const packageRoot = node.getModuleRootSync('@appium/base-driver', __filename);
+  if (!packageRoot) {
+    throw new Error(`Could not find the module root folder for @appium/base-driver from ${__filename}`);
+  }
+  return path.join(packageRoot, 'test-fixtures', 'static');
+}

package/node_modules/@appium/base-driver/lib/test-pages/template.ts

@@ -0,0 +1,15 @@
+/** Compile a lodash-style template string (`<%= expression %>`) into a render function. */
+export function compileLodashTemplate(template: string): (params: Record<string, unknown>) => string {
+  const parts: string[] = [];
+  let lastIndex = 0;
+  const re = /<%=\s*([\s\S]+?)\s*%>/g;
+  let match;
+  while ((match = re.exec(template)) !== null) {
+    parts.push(JSON.stringify(template.slice(lastIndex, match.index)));
+    parts.push(`String(${match[1]})`);
+    lastIndex = match.index + match[0].length;
+  }
+  parts.push(JSON.stringify(template.slice(lastIndex)));
+  const fn = new Function('obj', `with (obj) { return ${parts.join(' + ')}; }`);
+  return (params) => fn(params) as string;
+}

package/node_modules/@appium/base-driver/lib/utils.ts

@@ -0,0 +1,62 @@
+import {util} from '@appium/support';
+
+/**
+ * Deep-merge plain objects into a clone of `target`. Skips null/undefined sources.
+ * Non-plain values on a key replace the previous value (same as lodash merge for objects).
+ */
+export function mergePlainObjects<T extends Record<string, unknown>>(
+  target: T,
+  ...sources: Array<Partial<T> | undefined>
+): T {
+  const result = structuredClone(target);
+  for (const source of sources) {
+    if (source == null) {
+      continue;
+    }
+    for (const [key, value] of Object.entries(source)) {
+      const existing = result[key as keyof T];
+      if (util.isPlainObject(existing) && util.isPlainObject(value)) {
+        result[key as keyof T] = mergePlainObjects(
+          existing as Record<string, unknown>,
+          value as Record<string, unknown>,
+        ) as T[keyof T];
+      } else if (value !== undefined) {
+        result[key as keyof T] = value as T[keyof T];
+      }
+    }
+  }
+  return result;
+}
+
+/** Return a shallow copy of `obj` without `key`. Non-objects are returned unchanged. */
+export function omit<T extends Record<string, unknown>>(obj: T, key: string): T {
+  if (!util.isPlainObject(obj)) {
+    return obj;
+  }
+  return Object.fromEntries(Object.entries(obj).filter(([k]) => k !== key)) as T;
+}
+
+/** Return a shallow copy of `obj` without any of `keys`. */
+export function omitKeys<T extends Record<string, unknown>>(obj: T, keys: readonly string[]): T {
+  if (!util.isPlainObject(obj) || keys.length === 0) {
+    return obj;
+  }
+  const keysToOmit = new Set(keys);
+  return Object.fromEntries(Object.entries(obj).filter(([k]) => !keysToOmit.has(k))) as T;
+}
+
+/** Return a shallow copy of `obj` containing only listed keys. */
+export function pick<T extends Record<string, unknown>>(obj: T, keys: readonly string[]): Partial<T> {
+  const keysToPick = new Set(keys);
+  return Object.fromEntries(Object.entries(obj).filter(([k]) => keysToPick.has(k))) as Partial<T>;
+}
+
+/** Return a shallow copy of `obj` whose entries pass `predicate`. */
+export function pickBy<T extends Record<string, unknown>>(
+  obj: T,
+  predicate: (value: T[keyof T], key: keyof T) => boolean,
+): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([key, value]) => predicate(value as T[keyof T], key as keyof T)),
+  ) as Partial<T>;
+}