feat(deps)!: target Appium 4 beta

Targets the recently released Appium 4 beta (4.0.0-beta.1). Bumps the
appium peer dependency and all lockstep @appium/* packages to their
Appium 4 beta releases, and updates driver code for the resulting API
removals/changes described in the Appium 3-to-4 migration guide
(appium/appium#22790).

- @appium/strongbox, @appium/types, @appium/docutils, @appium/oxc-config,
  @appium/semantic-release-config, @appium/tsconfig bumped to their
  Appium 4 lockstep beta releases (engine/ESM-only bumps, verified
  byte-identical source vs. master where diffable, not API changes)
- Removed the driverData mechanism and the legacy 4-argument
  createSession override (both removed upstream); createSession now
  takes the single w3cCapabilities argument
- Removed the already-deprecated reset API (driver.reset() /
  POST /session/:sessionId/appium/app/reset), which only ever threw a
  deprecation error
- Fixed a real regression in the W3C timeouts command: BaseDriver's
  generic timeouts() handler no longer dispatches through
  scriptTimeoutW3C/pageLoadTimeoutW3C/implicitWaitW3C - it now calls
  setScriptTimeout/setPageLoadTimeout/setImplicitWait directly for both
  the legacy and W3C timeout forms. Renamed setAsyncScriptTimeout to
  setScriptTimeout to match, dropped the now-unreachable W3C/MJSONWP
  wrapper methods, and made sure BaseDriver's own scriptTimeoutMs/
  pageLoadTimeoutMs stay in sync too, since GET /timeouts now reports
  them on Appium 4 (it never did on Appium 3)
- Replaced the Location type (removed from @appium/types along with the
  legacy geolocation endpoint) with a local LocationWithAltitude
  interface
- Narrowed fs.glob()'s now-widened overloaded return type at the
  handful of call sites that don't use its withFileTypes/lazy options
- Made getStrings's language parameter optional in its type signature,
  matching its actual (always-optional) runtime/wire behavior - caught
  by the new compile-time execute-method-map param checking
- Bridged two known upstream typing lags (appium-webdriveragent and
  appium-ios-simulator still resolve AppiumLogger from pre-Appium4
  @appium/types copies) with documented `as any` casts; confirmed
  neither package's compiled output actually calls the removed
  errorAndThrow, so this is a type-only gap, not a runtime one
- Dropped @colors/colors and the local isEmpty/escapeRegExp/
  isPlainObject/truncateString/memoize shims in lib/utils, now that the
  appium peerDependency bump makes their appium/support equivalents
  available (both were carrying "replace once this driver declares
  that minimum" TODOs)
- Replaced the pem devDependency in the Safari SSL e2e test with a
  direct `openssl req -x509` invocation
- Bumped commander to v15

BREAKING CHANGE: requires Appium >=4.0.0-beta.0 and drops Node 20
support (minimum is now ^22.22.2 || ^24.15.0 || >=26.0.0), matching
Appium 4's own minimum supported Node engine. The appium/app/reset
endpoint is also gone; use the corresponding 'mobile:' extensions to
manage app state instead.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: mykola-mokhnach

docs/reference/commands.md

@@ -405,11 +405,11 @@ Trigger a touch/fingerprint match or match failure
 
 !!! warning "Deprecated"
 
-    This method is deprecated. Please use `scriptTimeoutW3C` instead
+    This method is deprecated. Please use `setScriptTimeout` instead
 
 `POST` **`/session/:sessionId/timeouts/async_script`**
 
-Alias for XCUITestDriver.scriptTimeoutW3C.
+Alias for XCUITestDriver.setScriptTimeout.
 
 #### Arguments
 

lib/commands/app-strings.ts

@@ -131,7 +131,7 @@ export async function parseLocalizableStrings(
  */
 export async function getStrings(
   this: XCUITestDriver,
-  language: string,
+  language?: string,
   stringFile: string | null = null,
 ): Promise<StringRecord<string>> {
   this.log.debug(`Gettings strings for language '${language}' and string file '${stringFile}'`);

lib/commands/automation-session.ts

@@ -13,7 +13,7 @@ import {requireSimulator, requireWebContext} from './helpers/index.js';
  * Seeded with the driver's current page-load/script/implicit-wait timeouts - the session's own
  * defaults (in particular a `0` implicit wait) otherwise differ from what the client configured,
  * silently changing WebDriver timeout behavior on session start. Later timeout updates are kept
- * in sync too, by {@linkcode setPageLoadTimeout}/{@linkcode setAsyncScriptTimeout}/
+ * in sync too, by {@linkcode setPageLoadTimeout}/{@linkcode setScriptTimeout}/
  * {@linkcode setImplicitWait}.
  *
  * @group Mobile Web Only

lib/commands/helpers/app.ts

@@ -166,9 +166,9 @@ export function buildSafariPreferences(opts: SafariPreferencesOpts & StringRecor
 export async function findApps(appPath: string, appExtensions: string[]): Promise<string[]> {
   const globPattern = `**/*.+(${appExtensions.map((ext) => ext.replace(/^\./, '')).join('|')})`;
   const sortedBundleItems = (
-    await fs.glob(globPattern, {
+    (await fs.glob(globPattern, {
       cwd: appPath,
-    })
+    })) as string[]
   ).sort((a, b) => a.split(path.sep).length - b.split(path.sep).length);
   return sortedBundleItems;
 }
@@ -334,7 +334,7 @@ export async function onPostConfigureApp(
     ) {
       const nestedItemsCountInCache = (appInfo.integrity as any)?.folder;
       if (nestedItemsCountInCache !== undefined) {
-        return (await fs.glob('**/*', {cwd: cachedPath})).length >= nestedItemsCountInCache;
+        return ((await fs.glob('**/*', {cwd: cachedPath})) as string[]).length >= nestedItemsCountInCache;
       }
     }
 

lib/commands/location.ts

@@ -1,4 +1,3 @@
-import type {Location} from '@appium/types';
 import type {Simulator} from 'appium-ios-simulator';
 import {errors} from 'appium/driver.js';
 import {util} from 'appium/support.js';
@@ -68,7 +67,10 @@ export async function getGeoLocation(this: XCUITestDriver): Promise<LocationWith
  *
  * @param location - Must include `latitude` and `longitude` (each coerced with `Number()`).
  */
-export async function setGeoLocation(this: XCUITestDriver, location: Partial<Location>): Promise<Location> {
+export async function setGeoLocation(
+  this: XCUITestDriver,
+  location: Partial<LocationWithAltitude>,
+): Promise<LocationWithAltitude> {
   for (const name of ['latitude', 'longitude']) {
     if (!util.hasValue(location[name as keyof typeof location])) {
       throw new errors.InvalidArgumentError(`${name} should be set`);

lib/commands/timeouts.ts

@@ -2,82 +2,60 @@ import {BaseDriver} from 'appium/driver.js';
 
 import type {XCUITestDriver} from '../driver.js';
 
-/**
- * Sets the page load timeout using W3C protocol.
- *
- * @param ms - Timeout in milliseconds
- */
-export async function pageLoadTimeoutW3C(this: XCUITestDriver, ms: number): Promise<void> {
-  await this.setPageLoadTimeout(this.parseTimeoutArgument(ms));
-}
-
-/**
- * Sets the page load timeout using MJSONWP protocol.
- *
- * @param ms - Timeout in milliseconds
- */
-export async function pageLoadTimeoutMJSONWP(this: XCUITestDriver, ms: number): Promise<void> {
-  await this.setPageLoadTimeout(this.parseTimeoutArgument(ms));
-}
-
-/**
- * Sets the async script timeout using W3C protocol.
- *
- * @param ms - Timeout in milliseconds
- */
-export async function scriptTimeoutW3C(this: XCUITestDriver, ms: number): Promise<void> {
-  // XXX: this is synchronous
-  await this.setAsyncScriptTimeout(this.parseTimeoutArgument(ms));
-}
-
-/**
- * Alias for {@linkcode XCUITestDriver.scriptTimeoutW3C}.
- *
- * @param ms - The timeout in milliseconds
- * @deprecated Use {@linkcode XCUITestDriver.scriptTimeoutW3C} instead
- */
-export async function scriptTimeoutMJSONWP(this: XCUITestDriver, ms: number): Promise<void> {
-  await this.asyncScriptTimeout(ms);
+/** Keeps an already-started automation session's timeout in sync with the driver's own. */
+function syncAutomationSessionTimeout(
+  driver: XCUITestDriver,
+  field: 'pageLoadTimeoutMs' | 'scriptTimeoutMs' | 'implicitWaitTimeoutMs',
+  ms: number,
+): void {
+  if (driver._remote?.automationSession?.isStarted) {
+    driver._remote.automationSession[field] = ms;
+  }
 }
 
 /**
- * Alias for {@linkcode XCUITestDriver.scriptTimeoutW3C}.
+ * Alias for {@linkcode XCUITestDriver.setScriptTimeout}, kept for the deprecated
+ * `/timeouts/async_script` route.
  *
  * @param ms - The timeout in milliseconds
- * @deprecated Use {@linkcode XCUITestDriver.scriptTimeoutW3C} instead
+ * @deprecated Use {@linkcode XCUITestDriver.setScriptTimeout} instead
  */
 export async function asyncScriptTimeout(this: XCUITestDriver, ms: number): Promise<void> {
-  await this.scriptTimeoutW3C(ms);
+  this.setScriptTimeout(this.parseTimeoutArgument(ms));
 }
 
 /**
  * Sets the page load timeout.
  *
+ * Defers to `BaseDriver`'s own `setPageLoadTimeout` to keep `pageLoadTimeoutMs` (what
+ * `GET /timeouts` reports) in sync, additionally tracking our own `pageLoadMs` and the active
+ * automation session (if any), neither of which the base implementation knows about.
+ *
  * @param ms - Timeout in milliseconds
  */
 export function setPageLoadTimeout(this: XCUITestDriver, ms: number): void {
   ms = parseInt(String(ms), 10);
+  BaseDriver.prototype.setPageLoadTimeout.call(this, ms);
   this.pageLoadMs = ms;
   if (this._remote) {
     this.remote.pageLoadMs = ms;
-    if (this._remote.automationSession?.isStarted) {
-      this._remote.automationSession.pageLoadTimeoutMs = ms;
-    }
   }
-  this.log.debug(`Set page load timeout to ${ms}ms`);
+  syncAutomationSessionTimeout(this, 'pageLoadTimeoutMs', ms);
 }
 
 /**
  * Sets the async script timeout.
  *
+ * Defers to `BaseDriver`'s own `setScriptTimeout` to keep `scriptTimeoutMs` (what
+ * `GET /timeouts` reports) in sync, additionally tracking our own `asyncWaitMs` and the active
+ * automation session (if any), neither of which the base implementation knows about.
+ *
  * @param ms - Timeout in milliseconds
  */
-export function setAsyncScriptTimeout(this: XCUITestDriver, ms: number): void {
+export function setScriptTimeout(this: XCUITestDriver, ms: number): void {
+  BaseDriver.prototype.setScriptTimeout.call(this, ms);
   this.asyncWaitMs = ms;
-  if (this._remote?.automationSession?.isStarted) {
-    this._remote.automationSession.scriptTimeoutMs = ms;
-  }
-  this.log.debug(`Set async script timeout to ${ms}ms`);
+  syncAutomationSessionTimeout(this, 'scriptTimeoutMs', ms);
 }
 
 /**
@@ -91,7 +69,5 @@ export function setAsyncScriptTimeout(this: XCUITestDriver, ms: number): void {
  */
 export function setImplicitWait(this: XCUITestDriver, ms: number): void {
   BaseDriver.prototype.setImplicitWait.call(this, ms);
-  if (this._remote?.automationSession?.isStarted) {
-    this._remote.automationSession.implicitWaitTimeoutMs = ms;
-  }
+  syncAutomationSessionTimeout(this, 'implicitWaitTimeoutMs', ms);
 }

lib/commands/types.ts

@@ -1,14 +1,18 @@
 import type {EventEmitter} from 'node:events';
 
-import type {AnyCase, Element, HTTPHeaders, Location, Size, StringRecord} from '@appium/types';
+import type {AnyCase, Element, HTTPHeaders, Size, StringRecord} from '@appium/types';
 
 import type {XCUITestDriverOpts} from '../driver.js';
 import type {Page} from '../types.js';
 import type {AuthorizationStatus, BatteryState, ThermalState} from './enum.js';
 
 export type Direction = 'up' | 'down' | 'left' | 'right';
 
-export type LocationWithAltitude = Location & {altitude: number};
+export interface LocationWithAltitude {
+  latitude: number;
+  longitude: number;
+  altitude: number;
+}
 
 export type AutInstallationStateOptions = Pick<
   XCUITestDriverOpts,

lib/commands/wda/cleanup.ts

@@ -55,7 +55,7 @@ export async function clearSystemFiles(retrieveDerivedDataPath: RetrieveDerivedD
 
   // Cleaning up big temporary files created by XCTest: https://github.com/appium/appium/issues/9410
   const globPattern = `${os.tmpdir()}/${XCTEST_LOGS_CACHE_FOLDER_PREFIX}*/`;
-  const dstFolders = await fs.glob(globPattern);
+  const dstFolders = (await fs.glob(globPattern)) as string[];
   if (isEmpty(dstFolders)) {
     log.debug(`Did not find the temporary XCTest logs root at '${globPattern}'`);
   } else {

lib/commands/xctest-record-screen.ts

@@ -51,10 +51,10 @@ class SimulatorXcTestScreenRecordingRetriever extends XcTestScreenRecordingRetri
     // e.g. .../CoreSimulator/Devices/<udid>/data/Containers/Data/InternalDaemon/<daemon-id>/Attachments/<uuid>
     // or .../InternalDaemon/<daemon-id>/tmp/Attachments/<uuid> (Xcode 26.5+)
     const internalDaemonRoot = path.resolve(dataRoot, 'Containers', 'Data', 'InternalDaemon');
-    const attachmentPaths = await fs.glob(SIMULATOR_XCTEST_RECORDING_ATTACHMENT_GLOB, {
+    const attachmentPaths = (await fs.glob(SIMULATOR_XCTEST_RECORDING_ATTACHMENT_GLOB, {
       cwd: internalDaemonRoot,
       absolute: true,
-    });
+    })) as string[];
     const videoPath = attachmentPaths.find((fp) =>
       XcTestScreenRecordingRetriever.nameMatchesUuid(path.basename(fp), uuid),
     );

lib/device/device-discovery.ts

@@ -188,7 +188,7 @@ export class DeviceDiscovery {
       const canonicalUdid = (await findSimulatorUdidCase(udid, devicesSetPath, platform)) ?? udid;
       const device = await getSimulator(canonicalUdid, {
         devicesSetPath,
-        logger: this.log,
+        logger: this.log as any,
       });
       await this.ensurePlatformVersion(device);
       return this.toResult({device, realDevice: false, udid});