fix: align options with the current driver capabilities

.github/workflows/ci.yml

@@ -71,7 +71,7 @@ jobs:
     - name: Resolve Selenium snapshot version
       if: matrix.selenium == 'snapshot'
       run: |
-        latest_snapshot=$(curl -sf https://raw.githubusercontent.com/SeleniumHQ/selenium/refs/heads/trunk/java/version.bzl | grep 'SE_VERSION' | sed 's/.*"\(.*\)".*/\1/')
+        latest_snapshot=$(curl -sf https://raw.githubusercontent.com/SeleniumHQ/selenium/refs/heads/trunk/version.bzl | grep '"java"' | sed 's/.*"java": *"\([^"]*\)".*/\1/')
         echo ">>> $latest_snapshot"
         echo "latest_snapshot=$latest_snapshot" >> "$GITHUB_ENV"
 

src/main/java/io/appium/java_client/android/options/EspressoOptions.java

@@ -98,27 +98,29 @@
 import io.appium.java_client.remote.options.SupportsUdidOption;
 import org.openqa.selenium.Capabilities;
 
+import java.net.URL;
 import java.util.Map;
+import java.util.Optional;
 
 /**
  * Provides options specific to the Espresso Driver.
  *
  * <p>For more details, refer to the
- * <a href="https://github.com/appium/appium-espresso-driver#capabilities">capabilities documentation</a></p>
+ * <a href="https://appium.github.io/appium-espresso-driver/latest/reference/capabilities/">capabilities documentation</a></p>
  */
 public class EspressoOptions extends BaseOptions<EspressoOptions> implements
-        // General options: https://github.com/appium/appium-uiautomator2-driver#general
+        // General options: https://appium.github.io/appium-espresso-driver/latest/reference/capabilities/#general
         SupportsDeviceNameOption<EspressoOptions>,
         SupportsUdidOption<EspressoOptions>,
-        // Driver/Server options: https://github.com/appium/appium-uiautomator2-driver#driverserver
+        // Driver/Server options: https://appium.github.io/appium-espresso-driver/latest/reference/capabilities/#espresso-server
         SupportsSystemPortOption<EspressoOptions>,
         SupportsSkipServerInstallationOption<EspressoOptions>,
         SupportsEspressoServerLaunchTimeoutOption<EspressoOptions>,
         SupportsForceEspressoRebuildOption<EspressoOptions>,
         SupportsShowGradleLogOption<EspressoOptions>,
         SupportsOrientationOption<EspressoOptions>,
         SupportsEspressoBuildConfigOption<EspressoOptions>,
-        // App options: https://github.com/appium/appium-uiautomator2-driver#app
+        // App options: https://appium.github.io/appium-espresso-driver/latest/reference/capabilities/#app-management
         SupportsAppOption<EspressoOptions>,
         SupportsAppPackageOption<EspressoOptions>,
         SupportsAppActivityOption<EspressoOptions>,
@@ -134,12 +136,12 @@ public class EspressoOptions extends BaseOptions<EspressoOptions> implements
         SupportsAllowTestPackagesOption<EspressoOptions>,
         SupportsRemoteAppsCacheLimitOption<EspressoOptions>,
         SupportsEnforceAppInstallOption<EspressoOptions>,
-        // App localization options: https://github.com/appium/appium-uiautomator2-driver#app-localization
+        // App localization options: https://appium.github.io/appium-espresso-driver/latest/reference/capabilities/#app-localization
         SupportsLocaleScriptOption<EspressoOptions>,
         SupportsLanguageOption<EspressoOptions>,
         SupportsLocaleOption<EspressoOptions>,
         SupportsAppLocaleOption<EspressoOptions>,
-        // ADB options: https://github.com/appium/appium-uiautomator2-driver#adb
+        // ADB options: https://appium.github.io/appium-espresso-driver/latest/reference/capabilities/#adb
         SupportsAdbPortOption<EspressoOptions>,
         SupportsRemoteAdbHostOption<EspressoOptions>,
         SupportsAdbExecTimeoutOption<EspressoOptions>,
@@ -152,7 +154,7 @@ public class EspressoOptions extends BaseOptions<EspressoOptions> implements
         SupportsLogcatFormatOption<EspressoOptions>,
         SupportsLogcatFilterSpecsOption<EspressoOptions>,
         SupportsAllowDelayAdbOption<EspressoOptions>,
-        // AVD options: https://github.com/appium/appium-uiautomator2-driver#emulator-android-virtual-device
+        // AVD options: https://appium.github.io/appium-espresso-driver/latest/reference/capabilities/#emulator-avd
         SupportsAvdOption<EspressoOptions>,
         SupportsAvdLaunchTimeoutOption<EspressoOptions>,
         SupportsAvdReadyTimeoutOption<EspressoOptions>,
@@ -161,19 +163,19 @@ public class EspressoOptions extends BaseOptions<EspressoOptions> implements
         SupportsNetworkSpeedOption<EspressoOptions>,
         SupportsGpsEnabledOption<EspressoOptions>,
         SupportsIsHeadlessOption<EspressoOptions>,
-        // App signing options: https://github.com/appium/appium-uiautomator2-driver#app-signing
+        // App signing options: https://appium.github.io/appium-espresso-driver/latest/reference/capabilities/#app-signing
         SupportsKeystoreOptions<EspressoOptions>,
         SupportsNoSignOption<EspressoOptions>,
-        // Device locking options: https://github.com/appium/appium-uiautomator2-driver#device-locking
+        // Device locking options: https://appium.github.io/appium-espresso-driver/latest/reference/capabilities/#device-under-test
         SupportsSkipUnlockOption<EspressoOptions>,
         SupportsUnlockTypeOption<EspressoOptions>,
         SupportsUnlockKeyOption<EspressoOptions>,
         SupportsUnlockStrategyOption<EspressoOptions>,
         SupportsUnlockSuccessTimeoutOption<EspressoOptions>,
-        // MJPEG options: https://github.com/appium/appium-uiautomator2-driver#mjpeg
+        // MJPEG options (not defined by the Espresso driver, deprecated)
         SupportsMjpegServerPortOption<EspressoOptions>,
         SupportsMjpegScreenshotUrlOption<EspressoOptions>,
-        // Web Context options: https://github.com/appium/appium-uiautomator2-driver#web-context
+        // Web Context options: https://appium.github.io/appium-espresso-driver/latest/reference/capabilities/#web-context
         SupportsAutoWebViewOption<EspressoOptions>,
         SupportsWebviewDevtoolsPortOption<EspressoOptions>,
         SupportsEnsureWebviewsHavePagesOption<EspressoOptions>,
@@ -192,7 +194,7 @@ public class EspressoOptions extends BaseOptions<EspressoOptions> implements
         SupportsShowChromedriverLogOption<EspressoOptions>,
         SupportsChromeOptionsOption<EspressoOptions>,
         SupportsChromeLoggingPrefsOption<EspressoOptions>,
-        // Other options: https://github.com/appium/appium-uiautomator2-driver#other
+        // Other options: https://appium.github.io/appium-espresso-driver/latest/reference/capabilities/#device-under-test
         SupportsDisableSuppressAccessibilityServiceOption<EspressoOptions>,
         SupportsSkipLogCaptureOption<EspressoOptions> {
     /**
@@ -228,4 +230,104 @@ private void setCommonOptions() {
         setPlatformName(MobilePlatform.ANDROID);
         setAutomationName(AutomationName.ESPRESSO);
     }
+
+    /**
+     * Skips capturing system logs (iOS only).
+     *
+     * @return self instance for chaining.
+     * @deprecated Not an Android capability, use {@code skipLogcatCapture} instead.
+     */
+    @Override
+    @Deprecated
+    public EspressoOptions skipLogCapture() {
+        return SupportsSkipLogCaptureOption.super.skipLogCapture();
+    }
+
+    /**
+     * Sets whether to skip capturing system logs (iOS only).
+     *
+     * @param value Capability value.
+     * @return self instance for chaining.
+     * @deprecated Not an Android capability, use {@code skipLogcatCapture} instead.
+     */
+    @Override
+    @Deprecated
+    public EspressoOptions setSkipLogCapture(boolean value) {
+        return SupportsSkipLogCaptureOption.super.setSkipLogCapture(value);
+    }
+
+    /**
+     * Gets whether to skip capturing system logs (iOS only).
+     *
+     * @return the value.
+     * @deprecated Not an Android capability, use {@code skipLogcatCapture} instead.
+     */
+    @Override
+    @Deprecated
+    public Optional<Boolean> doesSkipLogCapture() {
+        return SupportsSkipLogCaptureOption.super.doesSkipLogCapture();
+    }
+
+    /**
+     * Sets the MJPEG server port.
+     *
+     * @param port Port number.
+     * @return self instance for chaining.
+     * @deprecated Not defined by the Espresso driver.
+     */
+    @Override
+    @Deprecated
+    public EspressoOptions setMjpegServerPort(int port) {
+        return SupportsMjpegServerPortOption.super.setMjpegServerPort(port);
+    }
+
+    /**
+     * Gets the MJPEG server port.
+     *
+     * @return the value.
+     * @deprecated Not defined by the Espresso driver.
+     */
+    @Override
+    @Deprecated
+    public Optional<Integer> getMjpegServerPort() {
+        return SupportsMjpegServerPortOption.super.getMjpegServerPort();
+    }
+
+    /**
+     * Sets the MJPEG screenshot URL.
+     *
+     * @param url Screenshot URL.
+     * @return self instance for chaining.
+     * @deprecated Not defined by the Espresso driver.
+     */
+    @Override
+    @Deprecated
+    public EspressoOptions setMjpegScreenshotUrl(URL url) {
+        return SupportsMjpegScreenshotUrlOption.super.setMjpegScreenshotUrl(url);
+    }
+
+    /**
+     * Sets the MJPEG screenshot URL.
+     *
+     * @param url Screenshot URL.
+     * @return self instance for chaining.
+     * @deprecated Not defined by the Espresso driver.
+     */
+    @Override
+    @Deprecated
+    public EspressoOptions setMjpegScreenshotUrl(String url) {
+        return SupportsMjpegScreenshotUrlOption.super.setMjpegScreenshotUrl(url);
+    }
+
+    /**
+     * Gets the MJPEG screenshot URL.
+     *
+     * @return the value.
+     * @deprecated Not defined by the Espresso driver.
+     */
+    @Override
+    @Deprecated
+    public Optional<URL> getMjpegScreenshotUrl() {
+        return SupportsMjpegScreenshotUrlOption.super.getMjpegScreenshotUrl();
+    }
 }

src/main/java/io/appium/java_client/android/options/UiAutomator2Options.java

@@ -105,6 +105,7 @@
 import org.openqa.selenium.Capabilities;
 
 import java.util.Map;
+import java.util.Optional;
 
 /**
  * Provides options specific to the UiAutomator2 Driver.
@@ -240,4 +241,115 @@ private void setCommonOptions() {
         setPlatformName(MobilePlatform.ANDROID);
         setAutomationName(AutomationName.ANDROID_UIAUTOMATOR2);
     }
+
+    /**
+     * Skips capturing system logs (iOS only).
+     *
+     * @return self instance for chaining.
+     * @deprecated Not an Android capability, use {@code skipLogcatCapture} instead.
+     */
+    @Override
+    @Deprecated
+    public UiAutomator2Options skipLogCapture() {
+        return SupportsSkipLogCaptureOption.super.skipLogCapture();
+    }
+
+    /**
+     * Sets whether to skip capturing system logs (iOS only).
+     *
+     * @param value Capability value.
+     * @return self instance for chaining.
+     * @deprecated Not an Android capability, use {@code skipLogcatCapture} instead.
+     */
+    @Override
+    @Deprecated
+    public UiAutomator2Options setSkipLogCapture(boolean value) {
+        return SupportsSkipLogCaptureOption.super.setSkipLogCapture(value);
+    }
+
+    /**
+     * Gets whether to skip capturing system logs (iOS only).
+     *
+     * @return the value.
+     * @deprecated Not an Android capability, use {@code skipLogcatCapture} instead.
+     */
+    @Override
+    @Deprecated
+    public Optional<Boolean> doesSkipLogCapture() {
+        return SupportsSkipLogCaptureOption.super.doesSkipLogCapture();
+    }
+
+    /**
+     * Clears system files (iOS only).
+     *
+     * @return self instance for chaining.
+     * @deprecated The Android drivers never read this capability.
+     */
+    @Override
+    @Deprecated
+    public UiAutomator2Options clearSystemFiles() {
+        return SupportsClearSystemFilesOption.super.clearSystemFiles();
+    }
+
+    /**
+     * Sets whether to clear system files (iOS only).
+     *
+     * @param bool Capability value.
+     * @return self instance for chaining.
+     * @deprecated The Android drivers never read this capability.
+     */
+    @Override
+    @Deprecated
+    public UiAutomator2Options setClearSystemFiles(boolean bool) {
+        return SupportsClearSystemFilesOption.super.setClearSystemFiles(bool);
+    }
+
+    /**
+     * Gets whether to clear system files (iOS only).
+     *
+     * @return the value.
+     * @deprecated The Android drivers never read this capability.
+     */
+    @Override
+    @Deprecated
+    public Optional<Boolean> doesClearSystemFiles() {
+        return SupportsClearSystemFilesOption.super.doesClearSystemFiles();
+    }
+
+    /**
+     * Enables performance logging.
+     *
+     * @return self instance for chaining.
+     * @deprecated Deprecated by the Android driver, use {@code chromeLoggingPrefs} with {@code performance: ALL}.
+     */
+    @Override
+    @Deprecated
+    public UiAutomator2Options enablePerformanceLogging() {
+        return SupportsEnablePerformanceLoggingOption.super.enablePerformanceLogging();
+    }
+
+    /**
+     * Sets whether to enable performance logging.
+     *
+     * @param bool Capability value.
+     * @return self instance for chaining.
+     * @deprecated Deprecated by the Android driver, use {@code chromeLoggingPrefs} with {@code performance: ALL}.
+     */
+    @Override
+    @Deprecated
+    public UiAutomator2Options setEnablePerformanceLogging(boolean bool) {
+        return SupportsEnablePerformanceLoggingOption.super.setEnablePerformanceLogging(bool);
+    }
+
+    /**
+     * Gets whether performance logging is enabled.
+     *
+     * @return the value.
+     * @deprecated Deprecated by the Android driver, use {@code chromeLoggingPrefs} with {@code performance: ALL}.
+     */
+    @Override
+    @Deprecated
+    public Optional<Boolean> isEnablePerformanceLogging() {
+        return SupportsEnablePerformanceLoggingOption.super.isEnablePerformanceLogging();
+    }
 }

src/main/java/io/appium/java_client/android/options/adb/SupportsBuildToolsVersionOption.java

@@ -35,7 +35,7 @@ public interface SupportsBuildToolsVersionOption<T extends BaseOptions<T>> exten
     String BUILD_TOOLS_VERSION_OPTION = "buildToolsVersion";
 
     /**
-     * The version of Android build tools to use. By default, UiAutomator2
+     * The version of Android build tools to use. By default, the
      * driver uses the most recent version of build tools installed on
      * the machine, but sometimes it might be necessary to give it a hint
      * (let say if there is a known bug in the most recent tools version).

src/main/java/io/appium/java_client/android/options/adb/SupportsClearDeviceLogsOnStartOption.java

@@ -37,7 +37,7 @@ public interface SupportsClearDeviceLogsOnStartOption<T extends BaseOptions<T>>
     String CLEAR_DEVICE_LOGS_ON_START_OPTION = "clearDeviceLogsOnStart";
 
     /**
-     * Makes UiAutomator2 to delete all the existing logs in the
+     * Makes the driver delete all the existing logs in the
      * device buffer before starting a new test.
      *
      * @return self instance for chaining.
@@ -48,10 +48,10 @@ default T clearDeviceLogsOnStart() {
 
 
     /**
-     * If set to true then UiAutomator2 deletes all the existing logs in the
+     * If set to true then the driver deletes all the existing logs in the
      * device buffer before starting a new test.
      *
-     * @param value Set to false if you don't want to wait for the app to finish its launch.
+     * @param value Whether to delete all the existing device logs before starting a new test.
      * @return self instance for chaining.
      */
     default T setClearDeviceLogsOnStart(boolean value) {

src/main/java/io/appium/java_client/android/options/adb/SupportsIgnoreHiddenApiPolicyErrorOption.java

@@ -37,7 +37,7 @@ public interface SupportsIgnoreHiddenApiPolicyErrorOption<T extends BaseOptions<
     String IGNORE_HIDDEN_API_POLICY_ERROR_OPTION = "ignoreHiddenApiPolicyError";
 
     /**
-     * Prevents the driver from ever killing the ADB server explicitl.
+     * Ignores a failure while changing hidden API access policies.
      *
      * @return self instance for chaining.
      */

src/main/java/io/appium/java_client/android/options/adb/SupportsMockLocationAppOption.java

@@ -37,9 +37,9 @@ public interface SupportsMockLocationAppOption<T extends BaseOptions<T>> extends
     /**
      * Sets the package identifier of the app, which is used as a system mock location
      * provider since Appium 1.18.0+. This capability has no effect on emulators.
-     * If the value is set to null or an empty string, then Appium will skip the mocked
-     * location provider setup procedure. Defaults to Appium Setting package
-     * identifier (io.appium.settings).
+     * If the value is set to null or an empty string, then the driver will reset the mocked
+     * location provider instead. Defaults to Appium Setting package
+     * identifier (io.appium.settings) only if the capability is not set at all.
      *
      * @param appIdentifier The identifier of the mock location provider app.
      * @return self instance for chaining.

src/main/java/io/appium/java_client/android/options/adb/SupportsRemoteAdbHostOption.java

@@ -36,7 +36,7 @@ public interface SupportsRemoteAdbHostOption<T extends BaseOptions<T>> extends
 
     /**
      * Address of the host where ADB is running (the value of -H ADB command line option).
-     * Localhost by default.
+     * Unset by default, which makes the driver fall back to localhost.
      *
      * @param host The name host where ADB server is running.
      * @return self instance for chaining.