Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 21 additions & 6 deletions .github/scripts/resolve-appium-versions.mjs
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
// Resolves the versions of the Appium server and of a driver to install in e2e jobs.
// Usage: node resolve-appium-versions.mjs [--stable] <server package> <driver package>
// Usage: node resolve-appium-versions.mjs [--stable] [--skip-if-unsupported] <server package> <driver package>
// The beta server is used if it is newer than the latest stable one and some driver version supports it,
// otherwise the latest stable server is used. The driver is the newest version whose `appium` peer range
// accepts the chosen server (stable only, unless a beta server is used). With --stable the stable server is forced.
// The result is written to the step outputs `server` and `driver`.
// If no driver version supports the server, the script fails, unless --skip-if-unsupported is set: then it
// only reports `supported=false`. The result is written to the step outputs `server`, `driver` and `supported`.
import {execFile} from 'node:child_process';
import {appendFile} from 'node:fs/promises';
import {createRequire} from 'node:module';
Expand Down Expand Up @@ -44,9 +45,12 @@ function pickDriver(driverVersions, server, includePrereleases) {

async function main(args) {
const stableOnly = args.includes('--stable');
const [serverPackage, driverPackage] = args.filter((arg) => arg !== '--stable');
const skipIfUnsupported = args.includes('--skip-if-unsupported');
const [serverPackage, driverPackage] = args.filter((arg) => !arg.startsWith('--'));
if (!serverPackage || !driverPackage) {
throw new Error('Usage: resolve-appium-versions.mjs [--stable] <server package> <driver package>');
throw new Error(
'Usage: resolve-appium-versions.mjs [--stable] [--skip-if-unsupported] <server package> <driver package>',
);
}

const [{latest, beta}, driverTags, driverVersions] = await Promise.all([
Expand All @@ -61,7 +65,18 @@ async function main(args) {
const server = betaDriver ? beta : latest;
const driver = betaDriver ?? pickDriver(driverVersions, latest, false);
if (!driver) {
throw new Error(`No ${driverPackage} version supports ${serverPackage}@${server}`);
const message = `No ${driverPackage} version supports ${serverPackage}@${server}`;
if (!skipIfUnsupported) {
throw new Error(message);
}
console.log(`::warning::${message}, the dependent steps are skipped`);
if (process.env.GITHUB_STEP_SUMMARY) {
await appendFile(process.env.GITHUB_STEP_SUMMARY, `${message}, the dependent steps are skipped\n`);
}
if (process.env.GITHUB_OUTPUT) {
await appendFile(process.env.GITHUB_OUTPUT, `server=${server}\nsupported=false\n`);
}
return;
}

const summary = [
Expand All @@ -74,7 +89,7 @@ async function main(args) {
await appendFile(process.env.GITHUB_STEP_SUMMARY, `${summary}\n`);
}
if (process.env.GITHUB_OUTPUT) {
await appendFile(process.env.GITHUB_OUTPUT, `server=${server}\ndriver=${driver}\n`);
await appendFile(process.env.GITHUB_OUTPUT, `server=${server}\ndriver=${driver}\nsupported=true\n`);
}
}

Expand Down
24 changes: 15 additions & 9 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -137,16 +137,22 @@ jobs:
appium
${{ (matrix.e2e-tests == 'android' || matrix.e2e-tests == 'flutter-android') && 'appium-uiautomator2-driver' || 'appium-xcuitest-driver' }}

# The Flutter driver may not support the stable server yet, the Flutter tests are skipped then
- name: Resolve Flutter Integration driver version
id: flutter-driver
if: startsWith(matrix.e2e-tests, 'flutter')
run: node .github/scripts/resolve-appium-versions.mjs --stable --skip-if-unsupported appium appium-flutter-integration-driver

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Both Flutter jobs passed on this PR with e2eFlutterTest skipped. When the Flutter driver lags behind a new Appium major, every subsequent PR can pass without exercising either Flutter platform. Could the Flutter jobs fall back to the newest stable Appium release supported by both the Flutter and platform drivers, or pin a compatible major until the Flutter driver catches up?

@mykola-mokhnach mykola-mokhnach Nov 21, 2026 •

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Flutter Integration driver is third-party, so we cannot influence its release lifecycle or when it adds support for a new Appium major. Falling back to an older Appium or pinning a major would run the Flutter jobs against a server that the rest of the CI has already moved off, so they would not reflect what users get with the current Appium either. Skipping is the honest outcome: it is visible in the job log, and the Flutter jobs start running again automatically once the driver publishes a compatible release. If the gap ever turns out to be long-lived, we can revisit and add a dedicated pin then.


- name: Install Appium
run: npm install --location=global appium@${{ steps.appium-versions.outputs.server }}

- name: Install UIA2 driver
if: matrix.e2e-tests == 'android' || matrix.e2e-tests == 'flutter-android'
if: (matrix.e2e-tests == 'android' || matrix.e2e-tests == 'flutter-android') && steps.flutter-driver.outputs.supported != 'false'
run: appium driver install uiautomator2@${{ steps.appium-versions.outputs.driver }}

- name: Install Flutter Integration driver
if: matrix.e2e-tests == 'flutter-android' || matrix.e2e-tests == 'flutter-ios'
run: appium driver install appium-flutter-integration-driver --source npm
if: (matrix.e2e-tests == 'flutter-android' || matrix.e2e-tests == 'flutter-ios') && steps.flutter-driver.outputs.supported != 'false'
run: appium driver install appium-flutter-integration-driver@${{ steps.flutter-driver.outputs.driver }} --source npm

- name: Run Android E2E tests
if: matrix.e2e-tests == 'android'
Expand All @@ -160,7 +166,7 @@ jobs:
target: ${{ env.ANDROID_EMU_TARGET }}

- name: Run Flutter Android E2E tests
if: matrix.e2e-tests == 'flutter-android'
if: matrix.e2e-tests == 'flutter-android' && steps.flutter-driver.outputs.supported != 'false'
uses: reactivecircus/android-emulator-runner@v2
with:
script: ./gradlew e2eFlutterTest -Pplatform="android" -PflutterApp=${{ env.FLUTTER_ANDROID_APP }}
Expand All @@ -171,13 +177,13 @@ jobs:
target: ${{ env.ANDROID_EMU_TARGET }}

- name: Select Xcode
if: matrix.e2e-tests == 'ios' || matrix.e2e-tests == 'flutter-ios'
if: (matrix.e2e-tests == 'ios' || matrix.e2e-tests == 'flutter-ios') && steps.flutter-driver.outputs.supported != 'false'
uses: maxim-lobanov/setup-xcode@v1
with:
xcode-version: "${{ env.XCODE_VERSION }}"

- name: Prepare iOS simulator
if: matrix.e2e-tests == 'ios' || matrix.e2e-tests == 'flutter-ios'
if: (matrix.e2e-tests == 'ios' || matrix.e2e-tests == 'flutter-ios') && steps.flutter-driver.outputs.supported != 'false'
uses: futureware-tech/simulator-action@v6
with:
model: "${{ env.IOS_DEVICE_NAME }}"
Expand All @@ -187,17 +193,17 @@ jobs:
shutdown_after_job: false

- name: Install XCUITest driver
if: matrix.e2e-tests == 'ios' || matrix.e2e-tests == 'flutter-ios'
if: (matrix.e2e-tests == 'ios' || matrix.e2e-tests == 'flutter-ios') && steps.flutter-driver.outputs.supported != 'false'
run: appium driver install xcuitest@${{ steps.appium-versions.outputs.driver }}

- name: Download prebuilt WDA
if: matrix.e2e-tests == 'ios' || matrix.e2e-tests == 'flutter-ios'
if: (matrix.e2e-tests == 'ios' || matrix.e2e-tests == 'flutter-ios') && steps.flutter-driver.outputs.supported != 'false'
run: appium driver run xcuitest download-wda -- --platform=ios --kind=sim --outdir=$(dirname "$PREBUILT_WDA_PATH")

- name: Run iOS E2E tests
if: matrix.e2e-tests == 'ios'
run: ./gradlew e2eIosTest

- name: Run Flutter iOS E2E tests
if: matrix.e2e-tests == 'flutter-ios'
if: matrix.e2e-tests == 'flutter-ios' && steps.flutter-driver.outputs.supported != 'false'
run: ./gradlew e2eFlutterTest -Pplatform="ios" -PflutterApp=${{ env.FLUTTER_IOS_APP }}
26 changes: 26 additions & 0 deletions docs/selenium-bridge.md
Original file line number Diff line number Diff line change
Expand Up @@ -54,3 +54,29 @@ The next `asRemoteWebDriver` call opens a new connection.

To customize the HTTP client that opens the WebSocket connection, use the `asRemoteWebDriver` overload that takes
a Selenium `HttpClient.Factory`. It creates a new Selenium driver with its own connection on every call.

### Migrating from the logs broadcast

`ListensToLogcatMessages` (Android) and `ListensToSyslogMessages` (iOS), together with the `StringWebSocketClient`
they are based on, are deprecated, as the Appium drivers deprecated the `mobile: startLogsBroadcast` and
`mobile: stopLogsBroadcast` extensions. Subscribe to the BiDi `log.entryAdded` event instead. It is delivered over the
connection of the session, so there is no need to know the host and the port of the Appium server.

```java
var driver = new AndroidDriver(serverUrl, options.enableBiDi());
var selenium = SeleniumBridge.asRemoteWebDriver(driver);
try (var logInspector = new LogInspector(selenium)) {
logInspector.onGenericLog(entry -> {
if ("syslog".equals(entry.getType())) {
System.out.println(entry.getText());
}
});
// ...
} finally {
selenium.closeBiDi();
}
```

The `type` of a log entry tells the source of the log. Filter by `syslog` (used for both the Android logcat
and the iOS syslog) to get the device log, as other types, like `crashlog`, are delivered to the same listener.
The level is one of `debug`, `info`, `warn` and `error`.
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,8 @@
/**
* Android driver implementation.
*/
// The deprecated logs broadcasting API is removed in the next major release
@SuppressWarnings("removal")
public class AndroidDriver extends AppiumDriver implements
PressesKey,
SupportsRotation,
Expand Down Expand Up @@ -224,6 +226,7 @@ public AndroidBatteryInfo getBatteryInfo() {
}

@Override
@Deprecated(since = "11.1.0", forRemoval = true)
public synchronized StringWebSocketClient getLogcatClient() {
if (logcatClient == null) {
logcatClient = new StringWebSocketClient(getHttpClient());
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,20 +29,31 @@

import static io.appium.java_client.service.local.AppiumServiceBuilder.DEFAULT_APPIUM_PORT;

/** Provides listening to logcat messages broadcast via web socket. */
/**
* Provides listening to logcat messages broadcast via web socket.
*
* @deprecated The logs broadcasting web socket of the Appium drivers is deprecated and will be removed
* together with this API. Subscribe to the BiDi {@code log.entryAdded} event instead, see the
* <a href="https://github.com/appium/java-client/blob/master/docs/selenium-bridge.md#bidi">Selenium
* bridge documentation</a>.
*/
@Deprecated(since = "11.1.0", forRemoval = true)
Comment thread
Copilot marked this conversation as resolved.
Resolved
@SuppressWarnings("removal")
public interface ListensToLogcatMessages extends ExecutesMethod {
/**
* Gets the web socket client used for receiving logcat messages.
*
* @return the logcat web socket client.
*/
@Deprecated(since = "11.1.0", forRemoval = true)
StringWebSocketClient getLogcatClient();

/**
* Start logcat messages broadcast via web socket.
* This method assumes that Appium server is running on localhost and
* is assigned to the default port (4723).
*/
@Deprecated(since = "11.1.0", forRemoval = true)
default void startLogcatBroadcast() {
startLogcatBroadcast("127.0.0.1");
}
Expand All @@ -53,6 +64,7 @@ default void startLogcatBroadcast() {
*
* @param host the name of the host where Appium server is running
*/
@Deprecated(since = "11.1.0", forRemoval = true)
default void startLogcatBroadcast(String host) {
startLogcatBroadcast(host, DEFAULT_APPIUM_PORT);
}
Expand All @@ -63,6 +75,7 @@ default void startLogcatBroadcast(String host) {
* @param host the name of the host where Appium server is running
* @param port the port of the host where Appium server is running
*/
@Deprecated(since = "11.1.0", forRemoval = true)
default void startLogcatBroadcast(String host, int port) {
var remoteWebDriver = (AppiumRemoteWebDriver) this;
URL serverUrl = ((AppiumCommandExecutor) remoteWebDriver.getCommandExecutor()).getAddressOfRemoteServer();
Expand All @@ -81,6 +94,7 @@ default void startLogcatBroadcast(String host, int port) {
*
* @param handler a function, which accepts a single argument, which is the actual log message
*/
@Deprecated(since = "11.1.0", forRemoval = true)
default void addLogcatMessagesListener(Consumer<String> handler) {
getLogcatClient().addMessageHandler(handler);
}
Expand All @@ -93,6 +107,7 @@ default void addLogcatMessagesListener(Consumer<String> handler) {
*
* @param handler a function, which accepts a single argument, which is the actual exception instance
*/
@Deprecated(since = "11.1.0", forRemoval = true)
default void addLogcatErrorsListener(Consumer<Throwable> handler) {
getLogcatClient().addErrorHandler(handler);
}
Expand All @@ -106,6 +121,7 @@ default void addLogcatErrorsListener(Consumer<Throwable> handler) {
* @param handler a function, which is executed as soon as the client is successfully
* connected to the web socket
*/
@Deprecated(since = "11.1.0", forRemoval = true)
default void addLogcatConnectionListener(Runnable handler) {
getLogcatClient().addConnectionHandler(handler);
}
Expand All @@ -119,20 +135,23 @@ default void addLogcatConnectionListener(Runnable handler) {
* @param handler a function, which is executed as soon as the client is successfully
* disconnected from the web socket
*/
@Deprecated(since = "11.1.0", forRemoval = true)
default void addLogcatDisconnectionListener(Runnable handler) {
getLogcatClient().addDisconnectionHandler(handler);
}

/**
* Removes all existing logcat handlers.
*/
@Deprecated(since = "11.1.0", forRemoval = true)
default void removeAllLogcatListeners() {
getLogcatClient().removeAllHandlers();
}

/**
* Stops logcat messages broadcast via web socket.
*/
@Deprecated(since = "11.1.0", forRemoval = true)
default void stopLogcatBroadcast() {
removeAllLogcatListeners();
CommandExecutionHelper.executeScript(this, "mobile: stopLogsBroadcast");
Expand Down
3 changes: 3 additions & 0 deletions src/main/java/io/appium/java_client/ios/IOSDriver.java
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,8 @@
/**
* iOS driver implementation.
*/
// The deprecated logs broadcasting API is removed in the next major release
@SuppressWarnings("removal")
public class IOSDriver extends AppiumDriver implements
SupportsContextSwitching,
SupportsRotation,
Expand Down Expand Up @@ -252,6 +254,7 @@ class IOSAlert implements Alert {
}

@Override
@Deprecated(since = "11.1.0", forRemoval = true)
public synchronized StringWebSocketClient getSyslogClient() {
if (syslogClient == null) {
syslogClient = new StringWebSocketClient(getHttpClient());
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,21 +29,32 @@

import static io.appium.java_client.service.local.AppiumServiceBuilder.DEFAULT_APPIUM_PORT;

/** Provides the ability to listen to syslog messages broadcast by the Appium server via web socket. */
/**
* Provides the ability to listen to syslog messages broadcast by the Appium server via web socket.
*
* @deprecated The logs broadcasting web socket of the Appium drivers is deprecated and will be removed
* together with this API. Subscribe to the BiDi {@code log.entryAdded} event instead, see the
* <a href="https://github.com/appium/java-client/blob/master/docs/selenium-bridge.md#bidi">Selenium
* bridge documentation</a>.
*/
@Deprecated(since = "11.1.0", forRemoval = true)
Comment thread
Copilot marked this conversation as resolved.
Resolved
@SuppressWarnings("removal")
public interface ListensToSyslogMessages extends ExecutesMethod {

/**
* Returns the web socket client used to receive syslog messages.
*
* @return the syslog web socket client
*/
@Deprecated(since = "11.1.0", forRemoval = true)
StringWebSocketClient getSyslogClient();

/**
* Start syslog messages broadcast via web socket.
* This method assumes that Appium server is running on localhost and
* is assigned to the default port (4723).
*/
@Deprecated(since = "11.1.0", forRemoval = true)
default void startSyslogBroadcast() {
startSyslogBroadcast("localhost");
}
Expand All @@ -54,6 +65,7 @@ default void startSyslogBroadcast() {
*
* @param host the name of the host where Appium server is running
*/
@Deprecated(since = "11.1.0", forRemoval = true)
default void startSyslogBroadcast(String host) {
startSyslogBroadcast(host, DEFAULT_APPIUM_PORT);
}
Expand All @@ -64,6 +76,7 @@ default void startSyslogBroadcast(String host) {
* @param host the name of the host where Appium server is running
* @param port the port of the host where Appium server is running
*/
@Deprecated(since = "11.1.0", forRemoval = true)
default void startSyslogBroadcast(String host, int port) {
var remoteWebDriver = (AppiumRemoteWebDriver) this;
URL serverUrl = ((AppiumCommandExecutor) remoteWebDriver.getCommandExecutor()).getAddressOfRemoteServer();
Expand All @@ -82,6 +95,7 @@ default void startSyslogBroadcast(String host, int port) {
*
* @param handler a function, which accepts a single argument, which is the actual log message
*/
@Deprecated(since = "11.1.0", forRemoval = true)
default void addSyslogMessagesListener(Consumer<String> handler) {
getSyslogClient().addMessageHandler(handler);
}
Expand All @@ -94,6 +108,7 @@ default void addSyslogMessagesListener(Consumer<String> handler) {
*
* @param handler a function, which accepts a single argument, which is the actual exception instance
*/
@Deprecated(since = "11.1.0", forRemoval = true)
default void addSyslogErrorsListener(Consumer<Throwable> handler) {
getSyslogClient().addErrorHandler(handler);
}
Expand All @@ -107,6 +122,7 @@ default void addSyslogErrorsListener(Consumer<Throwable> handler) {
* @param handler a function, which is executed as soon as the client is successfully
* connected to the web socket
*/
@Deprecated(since = "11.1.0", forRemoval = true)
default void addSyslogConnectionListener(Runnable handler) {
getSyslogClient().addConnectionHandler(handler);
}
Expand All @@ -120,20 +136,23 @@ default void addSyslogConnectionListener(Runnable handler) {
* @param handler a function, which is executed as soon as the client is successfully
* disconnected from the web socket
*/
@Deprecated(since = "11.1.0", forRemoval = true)
default void addSyslogDisconnectionListener(Runnable handler) {
getSyslogClient().addDisconnectionHandler(handler);
}

/**
* Removes all existing syslog handlers.
*/
@Deprecated(since = "11.1.0", forRemoval = true)
default void removeAllSyslogListeners() {
getSyslogClient().removeAllHandlers();
}

/**
* Stops syslog messages broadcast via web socket.
*/
@Deprecated(since = "11.1.0", forRemoval = true)
default void stopSyslogBroadcast() {
CommandExecutionHelper.executeScript(this, "mobile: stopLogsBroadcast");
}
Expand Down
Loading
Loading