Compare commits

...
Author SHA1 Message Date
renovate[bot] 8b6482033e chore(deps): update dependency @tsconfig/node22 to v22.0.7 (#23182)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2026-11-17 14:45:46 +00:00
renovate[bot] 12afc85064 chore(docutils): update dependency mkdocs-git-revision-date-localized-plugin to v1.7.0 (#23181)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2026-11-17 12:59:02 +00:00
renovate[bot] 4f9fe05442 chore(docutils): update dependency mkdocs-material to v9.8.1 (#23179)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2026-11-17 04:42:29 +00:00
renovate[bot] 51cfc7b292 chore(workflows): update peter-evans/create-pull-request action to v8.1.3 (#23180)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2026-11-16 19:31:14 +00:00
github-actions[bot]andmykola-mokhnach e67a1980b0 docs(appium): Update documentation translations (#23174)
Co-authored-by: mykola-mokhnach <7767781+mykola-mokhnach@users.noreply.github.com>
2026-11-16 20:43:19 +02:00
renovate[bot] 8bd55ec338 chore(appium): update dependency argparse to v3.0.4 (#23178)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2026-11-16 19:26:19 +01:00
Lê Văn Xuân Hoàn aad17b1ba9 test(http-server): declare FakeDriver newMethodMap as const (#23176) 2026-11-16 09:58:12 +01:00
Mohamed Mostafa a8d646b6cc fix(support): apply case-only moves on macOS too (#23147) 2026-11-15 23:10:01 +01:00
Mykola Mokhnach 2b232adb2a feat(execute-driver-plugin)!: update webdriverio to v10 (#23170)
BREAKING CHANGE: webdriverio 10 requires Node.js ^22.23.4 || ^24.22.1 || >=26.12.1, so the plugin's minimum supported Node versions are raised accordingly.
2026-11-15 21:58:26 +01:00
Edgars Eglītis 2a6ef950f0 docs: update migration guide to remove beta references (#23173) 2026-11-15 22:12:13 +02:00
jimbob1414andClaude Opus 5.5 96bcc11ff4 docs: add BenchFleet Appium to Ecosystem tools document (#23171)
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 21:18:57 +02:00
Edgars Eglītis f7ccf0fb7c docs: link to Appium 4 migration guide + update aggregate changelog (#23172) 2026-11-15 20:57:21 +02:00
Mykola Mokhnach 5e1ec327c4 chore(deps): update dependency webdriverio to v10 (#23169) 2026-11-15 15:50:36 +01:00
Mykola Mokhnach 61bfbebe3c chore(deps): update dependency @types/node to v26 (#23168) 2026-11-15 15:23:37 +01:00
renovate[bot] 6447e97999 chore(http-server): update dependency path-to-regexp to v9 (#23113)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2026-11-15 15:23:05 +01:00
renovate[bot] 5cf9d9bba6 chore(support): update dependency teen_process to v5 (#23167)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2026-11-15 15:21:29 +01:00
renovate[bot] 0f5284f1f4 chore(support): update dependency asyncbox to v7 (#23166)
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
2026-11-15 15:11:51 +01:00
79 changed files with 3404 additions and 2547 deletions
@@ -29,7 +29,7 @@ jobs:
CROWDIN_PROJECT_ID: ${{ vars.CROWDIN_DOCS_PROJECT_ID }}
CROWDIN_TOKEN: ${{ secrets.CROWDIN_DOCS_TOKEN }}
- name: Create Pull Request
uses: peter-evans/create-pull-request@v8.1.1
uses: peter-evans/create-pull-request@v8.1.3
with:
token: ${{ github.token }}
commit-message: 'docs(appium): Update documentation translations'
+2 -1
View File
@@ -24,9 +24,9 @@ to driver/client documentation
* [base-plugin](packages/base-plugin/CHANGELOG.md)
* [docutils](packages/docutils/CHANGELOG.md)
* [driver-test-support](packages/driver-test-support/CHANGELOG.md)
* [eslint-config-appium-ts](packages/eslint-config-appium-ts/CHANGELOG.md)
* [fake-driver](packages/fake-driver/CHANGELOG.md)
* [fake-plugin](packages/fake-plugin/CHANGELOG.md)
* [http-server](packages/http-server/CHANGELOG.md)
* [logger](packages/logger/CHANGELOG.md)
* [opencv](packages/opencv/CHANGELOG.md)
* [oxc-config](packages/oxc-config/CHANGELOG.md)
@@ -42,6 +42,7 @@ to driver/client documentation
The changelog links used for these modules lead to the last version of their changelog file.
* [doctor](https://github.com/appium/appium/blob/8daf5e123ac14c8325acf504fb33eb28e1a3dd78/packages/doctor/CHANGELOG.md) ([removal PR](https://github.com/appium/appium/pull/20805))
* [eslint-config-appium](https://github.com/appium/appium/blob/4b3a8c2197a587ec5a2606b662e4e7667a7852cb/packages/eslint-config-appium/CHANGELOG.md) ([removal PR](https://github.com/appium/appium/pull/20856))
* [eslint-config-appium-ts](https://github.com/appium/appium/blob/31bc9f1f8cc99561135f4dd53c0e49637813d694/packages/eslint-config-appium-ts/CHANGELOG.md) ([removal PR](https://github.com/appium/appium/pull/22699))
* [gulp-plugins](https://github.com/appium/appium/blob/0823f0b60e40395cd1dc3b72cfa3c0092bc81302/packages/gulp-plugins/CHANGELOG.md) ([removal PR](https://github.com/appium/appium/pull/17943))
* [test-support](https://github.com/appium/appium/blob/1a46d7d61ee49c7e82a63687c5647c42ab69513d/packages/test-support/CHANGELOG.md) ([removal PR](https://github.com/appium/appium/pull/22351))
* [typedoc-plugin-appium](https://github.com/appium/appium/blob/d6204b6902074210943d7bbbf72d139b9b170a20/packages/typedoc-plugin-appium/CHANGELOG.md) ([removal PR](https://github.com/appium/appium/pull/19465))
+1
View File
@@ -43,6 +43,7 @@ programming languages, which means there is an entire ecosystem of related softw
The Appium team only provides support for the most recent version of Appium. If you wish to upgrade from
an older major Appium version, please refer to the migration guides:
* [Appium v3 to v4](https://appium.io/docs/en/latest/guides/migrating-3-to-4/)
* [Appium v2 to v3](https://appium.io/docs/en/latest/guides/migrating-2-to-3/)
* [Appium v1 to v2](https://appium.io/docs/en/latest/guides/migrating-1-to-2/)
+487 -1592
View File
File diff suppressed because it is too large Load Diff
+5 -5
View File
@@ -81,14 +81,14 @@
},
"devDependencies": {
"@appium/oxc-config": "2.0.0-beta.0",
"@tsconfig/node22": "22.0.0",
"@tsconfig/node22": "22.0.7",
"@types/express": "5.0.6",
"@types/json-schema": "7.0.15",
"@types/lockfile": "1.0.4",
"@types/method-override": "3.0.0",
"@types/mime-types": "3.0.1",
"@types/morgan": "1.9.10",
"@types/node": "24.19.2",
"@types/node": "26.6.6",
"@types/picomatch": "4.0.3",
"@types/pluralize": "0.0.33",
"@types/semver": "7.8.0",
@@ -97,7 +97,7 @@
"@types/which": "3.0.4",
"@types/ws": "8.18.1",
"@types/yargs": "17.0.35",
"asyncbox": "6.6.0",
"asyncbox": "7.0.0",
"axios": "1.20.0",
"conventional-changelog-conventionalcommits": "9.3.1",
"cross-env": "10.1.0",
@@ -105,10 +105,10 @@
"lerna": "10.1.1",
"npm-run-all2": "9.0.4",
"sinon": "22.1.0",
"teen_process": "4.2.1",
"teen_process": "5.0.1",
"tsd": "0.33.0",
"typescript": "6.0.3",
"webdriverio": "9.32.0",
"webdriverio": "10.2.0",
"ws": "8.22.0"
},
"overrides": {
@@ -105,6 +105,20 @@ Supported by: `@AppiumTestDistribution`
npm install -g appium-installer
```
### [BenchFleet Appium](https://github.com/benchfleet/benchfleet-appium)
BenchFleet Appium is a command-line tool for running existing Appium tests on real Android phones
connected to a [BenchFleet](https://benchfleet.com) Hub, a desktop app for managing many phones
(Pro or Team plan). For each phone, the Hub starts an Appium server with the UiAutomator2 driver.
The tool then runs your test command once per phone with that server's URL in `APPIUM_URL`, and
collects each phone's JUnit report. iOS and BenchFleet's cloud phones are not supported yet.
Supported by: `@benchfleet`
```sh title="Install This Tool"
npm install -g benchfleet-appium
```
### [Optics](https://github.com/mozarkai/optics-framework)
Optics is an open-source test automation framework that uses Appium to drive Android, iOS,
@@ -12,13 +12,12 @@ deprecated items not limited to endpoints, and general modernizing of the codeba
## Installation
Appium 4 is currently only available as a beta release, published under the `beta` npm dist-tag.
The installation method otherwise remains the same as for Appium 3. If you want to upgrade, you
The installation method for Appium 4 remains the same as for Appium 3. If you want to upgrade, you
can simply install Appium 4 on top of your existing installation:
```bash
# optional: `appium setup reset`
npm install -g appium@beta
npm install -g appium
```
## Breaking Changes
@@ -230,18 +230,6 @@ async createSession(w3cCaps) {
}
```
!!! warning "Deprecated"
```
Older drivers may still define `createSession` with up to four parameters, e.g.
`createSession(jwpCaps, reqCaps, w3cCaps, otherDriverData)`. This shape is a holdover from the
retired JSON Wire Protocol, which required desired and required caps as the first two
arguments; only the first W3C-shaped argument was ever used. The `otherDriverData` parameter is
likewise deprecated in favor of [IPC](#send-messages-to-plugins-running-on-the-same-session) for
coordinating with other concurrently-running sessions. New drivers should use the single-argument
form shown above.
```
You'll want to make sure to call `super.createSession` in order to get the session ID as well as
the processed capabilities (note that capabilities are also set on `this.caps`; modifying `caps`
locally here would have no effect other than changing what the user sees in the create session
@@ -730,6 +718,12 @@ A couple notes about this system:
mode!
3. The `executeMethod` helper will reject with an error if a script name doesn't match one of the
script names defined as a command in `executeMethodMap`, or if there are missing parameters.
4. If your driver is written in TypeScript, declare the map `as const satisfies
ExecuteMethodMap<MyDriver>` (with `ExecuteMethodMap` imported from `@appium/types`). The
compiler then checks that each `command` names a method of your driver, and that the
`required`/`optional` params are consistent with that method's signature: the method must not
require a parameter which is listed as `optional` (or not listed at all), and must accept all
of the listed parameters.
One of the nice things about the Execute Method strategy is that methods implemented in this way
will be available via the classic or BiDi interfaces (since they will result in the same Appium
@@ -796,6 +790,36 @@ this.eventEmitter.emit('bidiEvent', {
Now, if the client has subscribed to the `system.cpu` event, it will be notified with the load
whenever the driver emits it.
#### Slow clients and high-rate events
Appium does not buffer events indefinitely for a client that does not read them. A connection
that keeps more than `--bidi-max-buffered-bytes` unsent for longer than `--bidi-max-buffered-ms`
is closed with the code `1013`, and connections that do not answer WebSocket pings (see
`--bidi-heartbeat-interval`) are terminated. Both only affect the offending connection.
Drivers that emit events at a high rate (e.g. media streams) can let Appium skip events for a
connection that is falling behind, instead of waiting for it to be closed. Add a `delivery` hint
to the event (it is never sent to clients; older Appium versions ignore it):
```js
this.eventEmitter.emit('bidiEvent', {
method: 'appium:media.units',
params: {track: 'video', units},
delivery: {policy: 'droppable', chain: 'video', syncPoint: startsWithKeyframe},
})
```
- `policy`: `reliable` (default) events are always sent, `droppable` ones may be skipped.
- `chain`: events of the same chain depend on each other. After one is skipped for a connection,
the following ones are skipped for it too, until an event with `syncPoint: true` (e.g. a keyframe)
arrives and the connection has caught up. Every connection resynchronizes independently.
Subscriptions are per session, not per connection, so Appium decides by the state of each
connection's buffer. To react to dropped events (e.g. to request a keyframe or lower the bitrate),
listen to `bidiBackpressure` on the same emitter. Its payload is `{method, chain?, state, dropped}`,
where `state` is `dropping` once the first connection starts skipping events (and again whenever a
sync point is skipped, so that you can request a new one) and `recovered` once the last one stops, and `dropped` is the largest number of events skipped for a single connection.
### Make itself aware of resources other concurrent drivers are using
Let's say your driver uses up some system resources, like ports. There are a few ways to make sure
@@ -803,55 +827,35 @@ that multiple simultaneous sessions don't use the same resources:
1. Have your users specify resource IDs via capabilities (`appium:driverPort` etc)
2. Just always use free resources (find a new random port for each session)
3. Have each driver express what resources it is using, then examine currently-used resources from
other drivers when a new session begins.
3. Have each running instance of your driver publish and subscribe to messages on a shared IPC
channel, so sessions can coordinate directly with one another.
!!! warning "Deprecated"
```
The `driverData`-based mechanism described below is deprecated. Prefer
[IPC](#send-messages-to-plugins-running-on-the-same-session) for coordinating resources across
concurrently-running sessions instead.
```
To support this third strategy, you can implement `get driverData` in your driver to return what
sorts of resources your driver is currently using, for example:
```js
get driverData() {
return {specialPort: 1234, specialFile: /path/to/file}
}
```
Now, when a new session is started on your driver, the `driverData` response from any other
simultaneously running drivers (of the same type) will also be included, as the last parameter of
the deprecated, multi-argument form of the `createSession` method:
```js
async createSession(jwpCaps, reqCaps, w3cCaps, driverData)
```
You can dig into this `driverData` array to see what resources other drivers are using to help
determine which ones you want to use for this particular session.
The per-session IPC channel described in Send messages to plugins running on the same
session is isolated per session, so it
can't be used for this: it doesn't let you talk to _other_ sessions of your driver. Instead,
construct and hold on to your own `AppiumIpc` instance (exported from `appium/driver.js`) at
module scope in your driver's package, for example as a memoized singleton. Since Node.js caches
modules, every instance of your driver loaded within the same Appium server process will share
that one `AppiumIpc` object, and can use it to publish and subscribe to topics across sessions —
the same way the per-session channel works, just not scoped to a single session. See
[xcuitest-driver's `session-claim-handler.ts`](https://github.com/appium/appium-xcuitest-driver/blob/master/lib/session-claim-handler.ts)
for a real example, which uses this technique to detect and resolve conflicting sessions targeting
the same device UDID.
!!! warning
```
Be careful here, since `driverData` is only passed between sessions of a single running Appium
server. There's nothing to stop a user from running multiple Appium servers and requesting your
driver simultaneously on each of them. In this case, you won't be able to ensure independence
of resources via `driverData`, so you might consider using file-based locking mechanisms or
something similar.
This only works for sessions running within the same Node.js process (i.e. the same Appium
server). It cannot coordinate sessions running on different Appium server processes; for that,
consider file-based locking or a similar out-of-process mechanism.
```
!!! warning
```
It's also important to note you will only receive `driverData` for other instances of *your*
driver. So unrelated drivers also running may still be using some system resources. In general
Appium doesn't provide any features for ensuring unrelated drivers don't interfere with one
another, so it's up to the drivers to allow users to specify resource locations or addresses to
avoid clashes.
Appium also doesn't provide any features for ensuring unrelated drivers don't interfere with
one another, so it's up to the drivers to allow users to specify resource locations or
addresses to avoid clashes.
```
### Log events to the Appium event timeline
@@ -1002,10 +1006,15 @@ export type IpcMessage<T> = {
There are some important things to keep in mind when using Appium's IPC feature:
- IPC is only available once `onIpcInit` has been called, at the end of the `createSession` flow.
It cannot be used statically or in `createSession` hooks
- In sum, IPC is only for use during a session (this is also to prevent drivers/plugins from
accessing or reading data sent on IPC channels in other sessions.)
- The `ipcSubscribe` method (and the IPC channel it subscribes to) is only available once
`onIpcInit` has been called, at the end of the `createSession` flow. It cannot be used statically
or in `createSession` hooks
- The channel that `ipcSubscribe` gives you access to is scoped to the current session, and is
shared only with the plugins active in that same session (this is also to prevent drivers/plugins
from accessing or reading data sent on IPC channels in other sessions.) To coordinate across
multiple concurrent sessions of your own driver instead, see Make itself aware of resources
other concurrent drivers are
using.
- The default max size of an IPC message is 1MB. This can be configured by the server-admin by
using the `--max-ipc-data-size` arg (value is a number in bytes).
- If a message exceeds the configured size, any call to `publish` methods will throw, so be
@@ -261,7 +261,7 @@ throw new errors.NoSuchElementError();
### Log messages to the Appium log
You can always use `console.log`, of course, but Appium provides a nice logger for you as
`this.logger` (it has `.info`, `.debug`, `.log`, `.warn`, `.error` methods on it for differing log
`this.log` (it has `.info`, `.debug`, `.warn`, `.error` methods on it for differing log
levels). If you want to create an Appium logger outside of a plugin context (say in a script or
helper file), you can always construct your own too:
@@ -482,7 +482,7 @@ capability.
You probably don't normally need to update the Appium server object (which is an
[Express](https://expressjs.com/) server having already been
[configured](https://github.com/appium/appium/blob/master/packages/base-driver/lib/express/server.ts)
[configured](https://github.com/appium/appium/blob/master/packages/http-server/lib/server.ts)
in a variety of ways). But, for example, you could add new routes to the server to support your
plugin's requirements. To update the server you must implement the `static async updateServer`
method in your class. This method takes three parameters:
@@ -42,7 +42,7 @@ In order to get some value in logs replaced by a generic mask it is necessary:
[util.format](https://nodejs.org/api/util.html#utilformatformat-args) API.
- While sending the appropriate server request, where this log line is used and should be masked,
add the custom header `X-Appium-Is-Sensitive` with its value set to `1` or `true` (case-insensitive).
add the custom header `X-Appium-Is-Sensitive` with its value set to `1`, `true` or `yes` (case-insensitive).
Without such header the above log value is not going to be masked.
This way it is possible to conditionally mask log records depending on which
request is being handled by the extension if the log expression is used in the
+18 -16
View File
@@ -71,20 +71,13 @@ appium driver install safari
appium driver install uiautomator2
```
### [Windows](https://github.com/appium/appium-windows-driver)
!!! warning
```
Only the Node.js-based driver part is maintained by the Appium team. The server part
(WinAppDriver executable) is provided by Microsoft, but has not been maintained since 2022.
```
### [WinCore](https://appium.github.io/appium-wincore-driver)
- Target: Windows applications
- Mode: Native
```sh title="Install This Driver"
appium driver install windows
appium driver install wincore
```
### [XCUITest](https://appium.github.io/appium-xcuitest-driver/)
@@ -161,13 +154,6 @@ appium driver install --source=npm @itsmeaj/appium-linux-driver
### [NovaWindows](https://github.com/AutomateThePlanet/appium-novawindows-driver)
!!! info
```
This driver is recommended as a drop-in replacement for the partially unmaintained
[Windows driver](#windows)
```
- Target: Windows applications
- Mode: Native, Hybrid
- Supported by: Community / Automate The Planet
@@ -212,6 +198,22 @@ npm install appium-tizen-driver
appium driver install --source=npm appium-tizen-tv-driver
```
### [Windows (legacy)](https://github.com/appium/appium-windows-driver)
!!! warning
```
This driver relies on WinAppDriver, which has not been maintained since 2022, and is only
compatible with Appium 1-3. Use the [WinCore](#wincore) driver with Appium 4 and newer.
```
- Target: Windows applications
- Mode: Native
```sh title="Install This Driver"
appium driver install --source=npm appium-windows-driver
```
### [You.i Engine](https://github.com/YOU-i-Labs/appium-youiengine-driver)
!!! warning
@@ -114,6 +114,20 @@ Supported by: `@AppiumTestDistribution`
npm install -g appium-installer
```
### [BenchFleet Appium](https://github.com/benchfleet/benchfleet-appium)
BenchFleet Appium is a command-line tool for running existing Appium tests on real Android phones
connected to a [BenchFleet](https://benchfleet.com) Hub, a desktop app for managing many phones
(Pro or Team plan). For each phone, the Hub starts an Appium server with the UiAutomator2 driver.
The tool then runs your test command once per phone with that server's URL in `APPIUM_URL`, and
collects each phone's JUnit report. iOS and BenchFleet's cloud phones are not supported yet.
Supported by: `@benchfleet`
```sh title="Install This Tool"
npm install -g benchfleet-appium
```
### [Optics](https://github.com/mozarkai/optics-framework)
Optics is an open-source test automation framework that uses Appium to drive Android, iOS,
+1 -1
View File
@@ -99,4 +99,4 @@ The above configuration corresponds to the `--driver-xcuitest-webkit-debug-proxy
All properties are case-sensitive and will be in
[kebab-case](https://en.wikipedia.org/wiki/Naming_convention_(programming)#Delimiter-separated_words).
For example, `callback-port` is allowed, but `callbackPort` is not.
For example, `base-path` is allowed, but `basePath` is not.
+343
View File
@@ -0,0 +1,343 @@
---
title: Automating Gestures
---
Appium supports automating complex pointer, touch, key, and wheel interactions through the
W3C WebDriver [Perform Actions](../reference/api/webdriver.md#performactions) API
([W3C Specification](https://w3c.github.io/webdriver/#actions)). Alternatively, many drivers provide
platform-native gesture [Execute Methods](./execute-methods.md) for common interactions.
In the W3C Actions API, interactions are defined by creating one or more virtual input sources
(such as `pointer` with `pointerType: "touch"`, `key`, `wheel`, or `none`) and queuing a sequence
of synchronized ticks (`pointerMove`, `pointerDown`, `pointerUp`, `pause`). See the
[Selenium Actions API documentation](https://www.selenium.dev/documentation/webdriver/actions_api/)
for a general overview of input sources and tick synchronization.
Below are examples of common single-finger and multi-touch gestures implemented using the W3C
Actions API across client languages.
## Double Tap
Performs two quick touch taps at `(x, y)` with a short pause between them:
=== "JS (WebDriverIO)"
```js
await driver
.action('pointer', {parameters: {pointerType: 'touch'}})
.move({x: 200, y: 300, duration: 0})
.down()
.up()
.pause(100)
.down()
.up()
.perform();
```
=== "Java"
```java
PointerInput finger = new PointerInput(PointerInput.Kind.TOUCH, "finger");
Sequence doubleTap = new Sequence(finger, 1)
.addAction(finger.createPointerMove(Duration.ZERO, PointerInput.Origin.viewport(), 200, 300))
.addAction(finger.createPointerDown(PointerInput.MouseButton.LEFT.asArg()))
.addAction(finger.createPointerUp(PointerInput.MouseButton.LEFT.asArg()))
.addAction(new Pause(finger, Duration.ofMillis(100)))
.addAction(finger.createPointerDown(PointerInput.MouseButton.LEFT.asArg()))
.addAction(finger.createPointerUp(PointerInput.MouseButton.LEFT.asArg()));
driver.perform(Collections.singletonList(doubleTap));
```
=== "Python"
```py
actions = ActionChains(driver)
actions.w3c_actions = ActionBuilder(driver, mouse=PointerInput(interaction.POINTER_TOUCH, "finger"))
actions.w3c_actions.pointer_action.move_to_location(200, 300)
actions.w3c_actions.pointer_action.pointer_down()
actions.w3c_actions.pointer_action.pointer_up()
actions.w3c_actions.pointer_action.pause(0.1)
actions.w3c_actions.pointer_action.pointer_down()
actions.w3c_actions.pointer_action.pointer_up()
actions.perform()
```
=== "Ruby"
```rb
f1 = driver.action.add_pointer_input(:touch, 'finger')
f1.create_pointer_move(duration: 0, x: 200, y: 300, origin: :viewport)
f1.create_pointer_down(:left)
f1.create_pointer_up(:left)
f1.create_pause(0.1)
f1.create_pointer_down(:left)
f1.create_pointer_up(:left)
driver.perform_actions([f1])
```
=== "C#"
```csharp
var finger = new PointerInputDevice(PointerKind.Touch, "finger");
var doubleTap = new ActionSequence(finger, 0);
doubleTap.AddAction(finger.CreatePointerMove(CoordinateOrigin.Viewport, 200, 300, TimeSpan.Zero));
doubleTap.AddAction(finger.CreatePointerDown(MouseButton.Touch));
doubleTap.AddAction(finger.CreatePointerUp(MouseButton.Touch));
doubleTap.AddAction(finger.CreatePause(TimeSpan.FromMilliseconds(100)));
doubleTap.AddAction(finger.CreatePointerDown(MouseButton.Touch));
doubleTap.AddAction(finger.CreatePointerUp(MouseButton.Touch));
driver.PerformActions(new List<ActionSequence> { doubleTap });
```
## Long Press
Presses and holds a touch pointer at `(x, y)` for 1000ms before releasing:
=== "JS (WebDriverIO)"
```js
await driver
.action('pointer', {parameters: {pointerType: 'touch'}})
.move({x: 200, y: 300, duration: 0})
.down()
.pause(1000)
.up()
.perform();
```
=== "Java"
```java
PointerInput finger = new PointerInput(PointerInput.Kind.TOUCH, "finger");
Sequence longPress = new Sequence(finger, 1)
.addAction(finger.createPointerMove(Duration.ZERO, PointerInput.Origin.viewport(), 200, 300))
.addAction(finger.createPointerDown(PointerInput.MouseButton.LEFT.asArg()))
.addAction(new Pause(finger, Duration.ofMillis(1000)))
.addAction(finger.createPointerUp(PointerInput.MouseButton.LEFT.asArg()));
driver.perform(Collections.singletonList(longPress));
```
=== "Python"
```py
actions = ActionChains(driver)
actions.w3c_actions = ActionBuilder(driver, mouse=PointerInput(interaction.POINTER_TOUCH, "finger"))
actions.w3c_actions.pointer_action.move_to_location(200, 300)
actions.w3c_actions.pointer_action.pointer_down()
actions.w3c_actions.pointer_action.pause(1.0)
actions.w3c_actions.pointer_action.pointer_up()
actions.perform()
```
=== "Ruby"
```rb
f1 = driver.action.add_pointer_input(:touch, 'finger')
f1.create_pointer_move(duration: 0, x: 200, y: 300, origin: :viewport)
f1.create_pointer_down(:left)
f1.create_pause(1.0)
f1.create_pointer_up(:left)
driver.perform_actions([f1])
```
=== "C#"
```csharp
var finger = new PointerInputDevice(PointerKind.Touch, "finger");
var longPress = new ActionSequence(finger, 0);
longPress.AddAction(finger.CreatePointerMove(CoordinateOrigin.Viewport, 200, 300, TimeSpan.Zero));
longPress.AddAction(finger.CreatePointerDown(MouseButton.Touch));
longPress.AddAction(finger.CreatePause(TimeSpan.FromMilliseconds(1000)));
longPress.AddAction(finger.CreatePointerUp(MouseButton.Touch));
driver.PerformActions(new List<ActionSequence> { longPress });
```
## Drag and Drop / Swipe
Moves a touch pointer from `(200, 600)` to `(200, 200)` over 600ms:
=== "JS (WebDriverIO)"
```js
await driver
.action('pointer', {parameters: {pointerType: 'touch'}})
.move({x: 200, y: 600, duration: 0})
.down()
.pause(100)
.move({x: 200, y: 200, duration: 600})
.up()
.perform();
```
=== "Java"
```java
PointerInput finger = new PointerInput(PointerInput.Kind.TOUCH, "finger");
Sequence dragAndDrop = new Sequence(finger, 1)
.addAction(finger.createPointerMove(Duration.ZERO, PointerInput.Origin.viewport(), 200, 600))
.addAction(finger.createPointerDown(PointerInput.MouseButton.LEFT.asArg()))
.addAction(new Pause(finger, Duration.ofMillis(100)))
.addAction(finger.createPointerMove(Duration.ofMillis(600), PointerInput.Origin.viewport(), 200, 200))
.addAction(finger.createPointerUp(PointerInput.MouseButton.LEFT.asArg()));
driver.perform(Collections.singletonList(dragAndDrop));
```
=== "Python"
```py
actions = ActionChains(driver)
actions.w3c_actions = ActionBuilder(driver, mouse=PointerInput(interaction.POINTER_TOUCH, "finger"))
actions.w3c_actions.pointer_action.move_to_location(200, 600)
actions.w3c_actions.pointer_action.pointer_down()
actions.w3c_actions.pointer_action.pause(0.1)
actions.w3c_actions.pointer_action.move_to_location(200, 200)
actions.w3c_actions.pointer_action.pointer_up()
actions.perform()
```
=== "Ruby"
```rb
f1 = driver.action.add_pointer_input(:touch, 'finger')
f1.create_pointer_move(duration: 0, x: 200, y: 600, origin: :viewport)
f1.create_pointer_down(:left)
f1.create_pause(0.1)
f1.create_pointer_move(duration: 0.6, x: 200, y: 200, origin: :viewport)
f1.create_pointer_up(:left)
driver.perform_actions([f1])
```
=== "C#"
```csharp
var finger = new PointerInputDevice(PointerKind.Touch, "finger");
var dragAndDrop = new ActionSequence(finger, 0);
dragAndDrop.AddAction(finger.CreatePointerMove(CoordinateOrigin.Viewport, 200, 600, TimeSpan.Zero));
dragAndDrop.AddAction(finger.CreatePointerDown(MouseButton.Touch));
dragAndDrop.AddAction(finger.CreatePause(TimeSpan.FromMilliseconds(100)));
dragAndDrop.AddAction(finger.CreatePointerMove(CoordinateOrigin.Viewport, 200, 200, TimeSpan.FromMilliseconds(600)));
dragAndDrop.AddAction(finger.CreatePointerUp(MouseButton.Touch));
driver.PerformActions(new List<ActionSequence> { dragAndDrop });
```
## Pinch and Zoom (Multi-Touch)
Uses two concurrent `touch` pointer sequences (`finger1` and `finger2`) moving apart to zoom in (or toward each other to pinch):
=== "JS (WebDriverIO)"
```js
await driver.performActions([
{
type: 'pointer',
id: 'finger1',
parameters: {pointerType: 'touch'},
actions: [
{type: 'pointerMove', duration: 0, x: 200, y: 400},
{type: 'pointerDown', button: 0},
{type: 'pause', duration: 100},
{type: 'pointerMove', duration: 500, x: 200, y: 200},
{type: 'pointerUp', button: 0},
],
},
{
type: 'pointer',
id: 'finger2',
parameters: {pointerType: 'touch'},
actions: [
{type: 'pointerMove', duration: 0, x: 200, y: 450},
{type: 'pointerDown', button: 0},
{type: 'pause', duration: 100},
{type: 'pointerMove', duration: 500, x: 200, y: 650},
{type: 'pointerUp', button: 0},
],
},
]);
```
=== "Java"
```java
PointerInput finger1 = new PointerInput(PointerInput.Kind.TOUCH, "finger1");
Sequence seq1 = new Sequence(finger1, 1)
.addAction(finger1.createPointerMove(Duration.ZERO, PointerInput.Origin.viewport(), 200, 400))
.addAction(finger1.createPointerDown(PointerInput.MouseButton.LEFT.asArg()))
.addAction(new Pause(finger1, Duration.ofMillis(100)))
.addAction(finger1.createPointerMove(Duration.ofMillis(500), PointerInput.Origin.viewport(), 200, 200))
.addAction(finger1.createPointerUp(PointerInput.MouseButton.LEFT.asArg()));
PointerInput finger2 = new PointerInput(PointerInput.Kind.TOUCH, "finger2");
Sequence seq2 = new Sequence(finger2, 1)
.addAction(finger2.createPointerMove(Duration.ZERO, PointerInput.Origin.viewport(), 200, 450))
.addAction(finger2.createPointerDown(PointerInput.MouseButton.LEFT.asArg()))
.addAction(new Pause(finger2, Duration.ofMillis(100)))
.addAction(finger2.createPointerMove(Duration.ofMillis(500), PointerInput.Origin.viewport(), 200, 650))
.addAction(finger2.createPointerUp(PointerInput.MouseButton.LEFT.asArg()));
driver.perform(Arrays.asList(seq1, seq2));
```
=== "Python"
```py
action_builder = ActionBuilder(driver)
finger1 = action_builder.add_pointer_input(interaction.POINTER_TOUCH, "finger1")
finger2 = action_builder.add_pointer_input(interaction.POINTER_TOUCH, "finger2")
finger1.create_pointer_move(duration=0, x=200, y=400)
finger1.create_pointer_down(button=MouseButton.LEFT)
finger1.create_pause(0.1)
finger1.create_pointer_move(duration=500, x=200, y=200)
finger1.create_pointer_up(button=MouseButton.LEFT)
finger2.create_pointer_move(duration=0, x=200, y=450)
finger2.create_pointer_down(button=MouseButton.LEFT)
finger2.create_pause(0.1)
finger2.create_pointer_move(duration=500, x=200, y=650)
finger2.create_pointer_up(button=MouseButton.LEFT)
action_builder.perform()
```
=== "Ruby"
```rb
f1 = driver.action.add_pointer_input(:touch, 'finger1')
f1.create_pointer_move(duration: 0, x: 200, y: 400, origin: :viewport)
f1.create_pointer_down(:left)
f1.create_pause(0.1)
f1.create_pointer_move(duration: 0.5, x: 200, y: 200, origin: :viewport)
f1.create_pointer_up(:left)
f2 = driver.action.add_pointer_input(:touch, 'finger2')
f2.create_pointer_move(duration: 0, x: 200, y: 450, origin: :viewport)
f2.create_pointer_down(:left)
f2.create_pause(0.1)
f2.create_pointer_move(duration: 0.5, x: 200, y: 650, origin: :viewport)
f2.create_pointer_up(:left)
driver.perform_actions([f1, f2])
```
=== "C#"
```csharp
var finger1 = new PointerInputDevice(PointerKind.Touch, "finger1");
var seq1 = new ActionSequence(finger1, 0);
seq1.AddAction(finger1.CreatePointerMove(CoordinateOrigin.Viewport, 200, 400, TimeSpan.Zero));
seq1.AddAction(finger1.CreatePointerDown(MouseButton.Touch));
seq1.AddAction(finger1.CreatePause(TimeSpan.FromMilliseconds(100)));
seq1.AddAction(finger1.CreatePointerMove(CoordinateOrigin.Viewport, 200, 200, TimeSpan.FromMilliseconds(500)));
seq1.AddAction(finger1.CreatePointerUp(MouseButton.Touch));
var finger2 = new PointerInputDevice(PointerKind.Touch, "finger2");
var seq2 = new ActionSequence(finger2, 0);
seq2.AddAction(finger2.CreatePointerMove(CoordinateOrigin.Viewport, 200, 450, TimeSpan.Zero));
seq2.AddAction(finger2.CreatePointerDown(MouseButton.Touch));
seq2.AddAction(finger2.CreatePause(TimeSpan.FromMilliseconds(100)));
seq2.AddAction(finger2.CreatePointerMove(CoordinateOrigin.Viewport, 200, 650, TimeSpan.FromMilliseconds(500)));
seq2.AddAction(finger2.CreatePointerUp(MouseButton.Touch));
driver.PerformActions(new List<ActionSequence> { seq1, seq2 });
```
-59
View File
@@ -117,62 +117,3 @@ hub, you'll be able to send all your Appium traffic via the single hub endpoint
And of course, you're able to link up Appium servers and nodes running on different machines in
your network to form a larger grid.
## Using Selenium Grid 3
It is possible to register your Appium server with a local [Selenium Grid 3](https://www.selenium.dev/documentation/legacy/selenium_3/grid_3/)
([setup docs](https://www.selenium.dev/documentation/legacy/grid_3/setting_up_your_own_grid/)) instance by using the
`--nodeconfig` server argument.
```bash
appium server --nodeconfig /path/to/nodeconfig.json --base-path=/wd/hub
```
In the referenced config file you have to define the `browserName`, `version` and `platform`
capabilities and based on these parameters the grid will re-direct your test to the right device.
You will also need to configure your host details and the Selenium Grid details. For a full list of
all parameters and descriptions see
[here](https://www.selenium.dev/documentation/legacy/selenium_3/grid_setup/).
Once you start the Appium server it will register with the grid, and you will see your device on
the grid console page:
`http://**\<grid-ip-address\>**:**\<grid-port\>**/grid/console`
### Example Grid Node Configuration JSON
```json
{
"capabilities":
[
{
"browserName": "<e.g._iPhone5_or_iPad4>",
"version":"<version_of_iOS_e.g._7.1>",
"maxInstances": 1,
"platform":"<platform_e.g._MAC_or_ANDROID>"
}
],
"configuration":
{
"cleanUpCycle":2000,
"timeout":30000,
"proxy": "org.openqa.grid.selenium.proxy.DefaultRemoteProxy",
"url":"http://<host_name_appium_server_or_ip-address_appium_server>:<appium_port>/wd/hub",
"host": "<host_name_appium_server_or_ip-address_appium_server>",
"port": <appium_port>,
"maxSession": 1,
"register": true,
"registerCycle": 5000,
"hubPort": <grid_port>,
"hubHost": "<Grid_host_name_or_grid_ip-address>",
"hubProtocol": "<Protocol_of_Grid_defaults_to_http>"
}
}
```
If `url`, `host`, and `port` are not given, the config will be auto updated to point to
`localhost:<appium-port>`.
If your Appium server is running on a different machine to your Selenium Grid server, make sure you
use an external name/IP address in your `host` and `url` configuration; `localhost` and `127.0.0.1`
will prevent Selenium Grid from connecting correctly.
@@ -28,12 +28,6 @@ installing it only installs the core Appium server, without any drivers.
When it comes to installing Appium 2 drivers, there are several approaches you can take:
- Add the `--drivers` flag when installing Appium, for example:
```bash
npm i -g appium --drivers=xcuitest,uiautomator2
```
- Use the [Appium Extension CLI](../reference/cli/extensions.md), for example:
```bash
@@ -221,8 +215,12 @@ and [Mobile JSON Wire Protocol](https://github.com/SeleniumHQ/mobile-spec/blob/m
(MJSONWP) were used instead.
In Appium 1, all of these protocols were supported, so that older Selenium/Appium clients could
still communicate with newer Appium servers. Appium 2 removes support for JSONWP/MJSONWP and is now
only compatible with the W3C WebDriver Protocol.
still communicate with newer Appium servers. Appium 2 removes support for JSONWP/MJSONWP (including
legacy `TouchAction` and `MultiAction` endpoints) and is now only compatible with the W3C WebDriver
Protocol. Multi-touch and pointer gestures should be performed using the W3C
[Perform Actions](../reference/api/webdriver.md#performactions) API (see the
[Automating Gestures](./gestures.md) guide) or driver-specific
[Execute Methods](./execute-methods.md).
!!! info "Actions Needed"
@@ -0,0 +1,649 @@
---
title: Migrating to Appium 4
---
This document is a guide for those who are using Appium 3 and would like to upgrade to Appium 4.
It contains a list of breaking changes (including behavioral fixes), as well as suggestions for
handling them.
Appium 3 was largely focused on cleaning up old endpoints, whereas Appium 4 includes a wider range
of changes, including closer alignment to W3C WebDriver protocol requirements, removal of
deprecated items not limited to endpoints, and general modernizing of the codebase.
## Installation
The installation method for Appium 4 remains the same as for Appium 3. If you want to upgrade, you
can simply install Appium 4 on top of your existing installation:
```bash
# optional: `appium setup reset`
npm install -g appium
```
## Breaking Changes
### Node 22.22+ Required
Appium 3 required a Node.js version in the range `^20.19.0 || ^22.12.0 || >=24.0.0`. Appium 4 drops
Node 20 and bumps the required range to `^22.22.2 || ^24.15.0 || >=26.0.0`. The minimum `npm`
version remains unchanged.
!!! info "Actions Needed"
Upgrade Node.js to `v22.22.2` or newer
### ESM-Only
Every package in the Appium monorepo (`appium` and its dependents) is now published as ESM-only,
with no CommonJS build. `require()` no longer works for these packages.
!!! info "Actions Needed"
Import Appium packages using ESM `import` syntax, or use dynamic `import()` from CommonJS code
### JSONWP/MJSONWP Internals Removed
The release of Appium 2 removed general support for the obsolete JSONWP and MJSONWP protocols,
though some Appium-related packages using JSONWP/MJSONWP under the hood could still continue to
function.
Appium 4 removes most of the remaining internal code that supported these protocols, which means
that drivers that still relied on these protocols are no longer compatible with Appium 4. Most
notably, this includes the Windows driver ([see dedicated section below](#windows-driver-replaced-by-wincore-driver)). All other official drivers rely on the W3C protocol and are not affected by this change.
Despite this, Appium 4 does retain temporary support for a select few JSONWP/MJSONWP endpoints (see
[Deprecated Endpoints Removed](#deprecated-endpoints-removed)).
For extension developers, a more detailed breakdown is available in the Developer-Facing Changes
section below.
!!! info "Actions Needed"
Migrate to drivers that support the W3C WebDriver protocol
### Windows Driver Replaced by WinCore Driver
As part of [dropping support for the deprecated JSONWP and MJSONWP protocols](#jsonwpmjsonwp-support-fully-removed),
Appium 4 is no longer compatible with the Windows driver ([`appium-windows-driver`](https://github.com/appium/appium-windows-driver)),
since the driver cannot support the standard W3C WebDriver protocol. As a result, the
`appium driver install windows` CLI command also no longer works.
Its official replacement is the WinCore driver ([`appium-wincore-driver`](https://github.com/appium/appium-wincore-driver)),
which can be installed using the new `appium driver install wincore` command. Since the WinCore
driver is also compatible with Appium 3, you can safely migrate from the Windows driver while
remaining on Appium 3 - though note that the installation shortcut is only available since Appium 4.
!!! info "Actions Needed"
If you currently use the Windows driver with Appium 3, you can migrate as follows:
1. Install `appium-wincore-driver` v3: `appium driver install --source=npm appium-wincore-driver@3`
2. Migrate your tests to use the WinCore driver
3. Uninstall the Windows driver: `appium driver uninstall windows`
4. Upgrade to Appium 4
5. Update the WinCore driver to its Appium 4 version: `appium driver update wincore --unsafe`
### Deprecated Endpoints Removed
Similarly to Appium 3, Appium 4 also removes several previously deprecated server endpoints, all of
which belong to the obsolete JSONWP/MJSONWP protocols. Compared to Appium 3, this cleanup is much
smaller (12 removed endpoints total, compared to 98 for Appium 3).
All removed endpoints are listed below, along with their replacement endpoints or driver-specific
execute methods:
- `GET /session/:sessionId`
- :octicons-arrow-right-24: [`GET /session/:sessionId/appium/capabilities`](../reference/api/appium.md#getappiumsessioncapabilities) (for capabilities)
- :octicons-arrow-right-24: [`GET /session/:sessionId/appium/events`](../reference/api/appium.md#getlogevents) (for event timings)
- `POST /session/:sessionId/ime/activate`
- :octicons-check-24: Moved to [UiAutomator2](https://appium.github.io/appium-uiautomator2-driver/)/[Espresso](https://appium.github.io/appium-espresso-driver/) drivers
- `GET /session/:sessionId/ime/activated`
- :octicons-check-24: Moved to UiAutomator2/Espresso drivers
- `GET /session/:sessionId/ime/active_engine`
- :octicons-check-24: Moved to UiAutomator2/Espresso drivers
- `GET /session/:sessionId/ime/available_engines`
- :octicons-check-24: Moved to UiAutomator2/Espresso drivers
- `POST /session/:sessionId/ime/deactivate`
- :octicons-check-24: Moved to UiAutomator2/Espresso drivers
- `GET /session/:sessionId/location`
- :octicons-check-24: Moved to [XCUITest](https://appium.github.io/appium-xcuitest-driver/) driver
- :octicons-arrow-right-24: `mobile: getGeolocation` (UiAutomator2/Espresso drivers)
- :octicons-arrow-right-24: `mobile: getSimulatedLocation` (XCUITest driver)
- `POST /session/:sessionId/location`
- :octicons-check-24: Moved to UiAutomator2/Espresso/XCUITest drivers
- :octicons-arrow-right-24: `mobile: setGeolocation` (UiAutomator2/Espresso drivers)
- :octicons-arrow-right-24: `mobile: setSimulatedLocation` (XCUITest driver)
- `GET /session/:sessionId/network_connection`
- :octicons-check-24: Moved to UiAutomator2/Espresso drivers
- :octicons-arrow-right-24: `mobile: getConnectivity` (UiAutomator2/Espresso drivers)
- `POST /session/:sessionId/network_connection`
- :octicons-check-24: Moved to UiAutomator2/Espresso drivers
- :octicons-arrow-right-24: `mobile: setConnectivity` (UiAutomator2/Espresso drivers)
- `POST /session/:sessionId/receive_async_response`
- :octicons-arrow-right-24: [`POST /session/:sessionId/execute/async`](../reference/api/webdriver.md#executeasync)
- `GET /session/:sessionId/element/:elementId`
- :octicons-no-entry-24: JSONWP protocol command stub with no direct replacement
#### Remaining Deprecations
There are 7 more deprecated endpoints that are intentionally _not_ removed in Appium 4. They are
the last remaining JSONWP/MJSONWP endpoints supported by Appium, and are listed in the
[JSONWP](../reference/api/jsonwp.md) and [MJSONWP](../reference/api/mjsonwp.md) reference pages.
These endpoints are kept due to their common usage (for context management), and their deprecation
being somewhat recent. All of them are therefore planned to be removed in the next major Appium
version, in order to give users time to migrate to their replacements.
!!! info "Actions Needed"
Check your Appium client documentation for the affected methods, and adjust your code to use
their replacements
### `--allow-cors` Flag Renamed
In Appium 3, the `--allow-cors` server argument was the only feature flag not integrated with
Appium's default [insecure feature flag mechanism](./security.md). Appium 4 removes this argument
and replaces it with the `cors` insecure feature name. This means the feature can now be controlled
using the `--allow-insecure`, `--deny-insecure` and `--relaxed-security` flags.
Similarly to the `session_discovery` feature, the `cors` feature must also be prefixed with the
wildcard (`*`) symbol.
!!! info "Actions Needed"
Replace `--allow-cors` with `--allow-insecure=*:cors` or `--relaxed-security`
### Default Log Level Set to Info
The default logging level for server logs has been changed from `debug` to `info`. Debug-level
logging is very verbose and mostly only useful for troubleshooting.
!!! info "Actions Needed"
Pass `--log-level debug` explicitly if you rely on the previous verbosity
### CLI Command Output Streams Split
In Appium 3, all non-JSON output of Appium's CLI commands (`driver`/`plugin`/`setup`, but not
`server`) was written to `stderr`. Appium 4 now writes `log`/`ok`/`info`/`warn` level messages of
these commands to `stdout`, while `error` level output remains in `stderr`.
The log output of the server itself (the `server` command) is unaffected, since it already split
streams this way.
!!! info "Actions Needed"
If you use scripts that capture non-JSON output of `driver`/`plugin`/`setup` commands, make
sure they read from the correct stream
### SPDY/HTTP2 No Longer Supported
In Appium 3, the server could be launched with SSL/TLS, which enabled support for the SPDY and
HTTP/2 protocols. This functionality relied on the unmaintained `spdy` package. Appium 4 replaces
this package with Node's native `https` module, which only supports plain HTTPS (HTTP/1.1).
!!! info "Actions Needed"
Clients relying on SPDY or HTTP/2 multiplexing against Appium's TLS listener must switch to
plain HTTPS (HTTP/1.1) or use a proxy
### Selenium Grid 3 Support Removed
Support for Selenium Grid 3 hub has been removed, along with its `--nodeconfig` server
argument/config file property. Selenium Grid 4 remains supported.
!!! info "Actions Needed"
If you relied on Grid 3 registration, use the [Selenium Grid 4 relay feature](./grid.md) instead
### Post-Install Script Removed
Appium 2 and 3 supported a postinstall hook that allowed for installation of drivers/plugins
together with the Appium server itself:
```
npm install -g appium --drivers=... --plugins=...
```
Since postinstall hooks are a supply-chain security risk, and newer versions of `npm` disable them
by default, this hook has been removed in Appium 4.
!!! info "Actions Needed"
If you install drivers/plugins using the postinstall hook, migrate to Appium's
[`install`](../reference/cli/extensions.md#install) command, or declare extensions in your
project's `package.json` file
### Event Timings Capability Removed
In Appium 3, the `appium:eventTimings` capability could be set to `true` in order to include event
timing information in the response of the `GET /session/:sessionId` endpoint. Since Appium 4
removes this endpoint (see [Deprecated Endpoints Removed](#deprecated-endpoints-removed)), the
capability became obsolete, and has also been removed.
!!! info "Actions Needed"
Remove any instances of the `appium:eventTimings` capability, and instead use the [getLogEvents](../reference/api/appium.md#getlogevents) endpoint to retrieve event timings
### Unused Server Arguments Removed
The following server arguments have had no effect for a long time and have been removed, along with
their equivalents in the configuration file:
- `--callback-address` (`-ca`)
- `--callback-port` (`-cp`)
- `--debug-log-spacing`
- `--shell`
- `--strict-caps`
- `--trace-dir`
Passing any of them on the command line now fails with an unrecognized argument error (unless
[`--allow-unknown-args`](../reference/cli/server.md) is set), and config files containing them
fail schema validation.
!!! info "Actions Needed"
Remove these arguments from startup scripts and config files
## Behavior Fixes
This is a list of smaller changes that are positioned as fixes, rather than removal of existing
functionality, and may or may not be breaking depending on your usecase. The majority of changes
are related to alignment with the W3C WebDriver specification, and should not generally require
any user action.
### Session Lifecycle
- If a successfully created session fails initialization, Appium now attempts to delete the newly
created session and removes its registration while preserving the original initialization error
([#22873](https://github.com/appium/appium/pull/22873))
- The new command idle timeout (`appium:newCommandTimeout`) now only starts after finishing the
setup of initial settings and BiDi responses, preventing a session from expiring during
initialization ([#22881](https://github.com/appium/appium/pull/22881))
- If the new command idle timeout expires and the session deletion process starts, any driver
cleanup failures are now logged, instead of becoming an unhandled rejection that can terminate
the server and unrelated sessions ([#22964](https://github.com/appium/appium/pull/22964))
- Upon session deletion, any commands still waiting in the command queue are now rejected with HTTP
`404` / `invalid session id`, instead of remaining pending indefinitely
([#22874](https://github.com/appium/appium/pull/22874))
### Capabilities
- Names of standard WebDriver capabilities must now be case-sensitive (e.g. `platformName`, not
`PlatformName`). Handling of the _values_ of these capabilities, as well as names of prefixed
capabilities (e.g. `appium:app`), remains unchanged
([#22976](https://github.com/appium/appium/pull/22976))
- Malformed capability containers and parse failures now return HTTP `400` / `invalid argument`,
instead of HTTP `500` / `session not created`
([#22977](https://github.com/appium/appium/pull/22977))
- Top-level `null` capabilities are omitted before validation and merging, avoiding false
duplicate-key errors. Nested nulls, such as `timeouts: {script: null}`, are preserved
([#22975](https://github.com/appium/appium/pull/22975))
- Session settings provided inside `appium:options` are now honored
([#22882](https://github.com/appium/appium/pull/22882))
- The standard `timeouts` capability now correctly initializes BaseDriver's timeout state using
the same value checks as the [Set Timeouts](../reference/api/webdriver.md#timeouts) endpoint.
Backend handling remains driver-specific ([#22983](https://github.com/appium/appium/pull/22983))
- Setting both `appium:noReset` and `appium:fullReset` to `true` now returns HTTP `500` /
`session not created` instead of a generic error, and no longer leaves partially initialized
session state behind ([#22861](https://github.com/appium/appium/pull/22861),
[#22870](https://github.com/appium/appium/pull/22870))
- Setting `appium:newCommandTimeout` to `null`, a blank string, or a non-finite numeric value is
now ignored (keeping the default timeout value), instead of causing the timeout to be silently
disabled ([#22815](https://github.com/appium/appium/pull/22815),
[#23103](https://github.com/appium/appium/pull/23103)). Other invalid types, such as negative
numbers or nonnumeric strings, still fail capability validation
- Percent-encoded credentials in `appium:app` URLs are now decoded once before Basic authentication,
and complete HTTP-compressed downloads are no longer rejected if the decompressed file size
differs from `Content-Length` ([#22887](https://github.com/appium/appium/pull/22887),
[#22886](https://github.com/appium/appium/pull/22886))
- Setting `firstMatch` to an empty array (`[]`) is now rejected with HTTP `400` /
`invalid argument`, instead of being silently replaced with a single empty entry
([#22860](https://github.com/appium/appium/pull/22860))
- Every `firstMatch` candidate is now validated and merged before selection. Invalid supplied values
or duplicate keys in any candidate reject the request, even if another candidate could match;
missing required driver capabilities and unsupported platforms still allow matching to continue
([#22982](https://github.com/appium/appium/pull/22982))
- Default capabilities (which can be set using `--default-capabilities`) are now applied to each
individual `firstMatch` candidate separately. Values set in `alwaysMatch` or the current
candidate still take precedence ([#22988](https://github.com/appium/appium/pull/22988)). See
[Default Capabilities](../reference/cli/server.md#default-capabilities) for an example.
- Session settings are now applied from the selected `firstMatch` candidate, instead of potentially
being overridden by later unselected candidates. Defaults and `alwaysMatch` settings are still
applied first ([#22882](https://github.com/appium/appium/pull/22882))
- Values of the standard `timeouts` capability are now also validated in `alwaysMatch` and every
`firstMatch` candidate ([#23062](https://github.com/appium/appium/pull/23062)). A malformed
timeout object or invalid standard timeout value is rejected with HTTP `400` /
`invalid argument`, even if an earlier `firstMatch` candidate could match. Top-level
`timeouts: null` is still omitted, nested null timeout values are preserved, and unknown timeout
properties are ignored for validation
### HTTP Responses
- All WebDriver HTTP responses now include the `Cache-Control: no-cache` header. Caches must
revalidate these responses before reusing them
([#22971](https://github.com/appium/appium/pull/22971))
- Any WebDriver error `data` (e.g. alert text) is now preserved in driver and proxy responses
([#22974](https://github.com/appium/appium/pull/22974))
- The body of any `POST` command now has to be a JSON object; requests where the body is empty or
set to an empty JSON array (`[]`) return HTTP `400` with `invalid argument`
([#23007](https://github.com/appium/appium/pull/23007)). A value of `{}` is still accepted,
including commands that take no parameters. Routes that set `payloadParams.wrap` may still accept
an empty array
- `GET` requests to the server root route (e.g. `GET /` for a default server base path) now return
HTTP `404` / `unknown command`, instead of Express's HTML 404 page. Extensions can still register
their own root route ([#22969](https://github.com/appium/appium/pull/22969))
- `HEAD` requests to any `GET` command URL now return HTTP `405` without executing the `GET`
command. Custom server routes and `HEAD` request handlers retain their behavior
([#22992](https://github.com/appium/appium/pull/22992))
- Driver commands rejecting with `null` or `undefined` now return HTTP `500` / `unknown error`,
instead of causing the error handler itself to fail
([#22869](https://github.com/appium/appium/pull/22869))
- `TimeoutError` and `ScriptTimeoutError` now map to HTTP `500` instead of HTTP `408`
([#22686](https://github.com/appium/appium/pull/22686))
- A `detached shadow root` error is now preserved as HTTP `404`, instead of being converted to HTTP
`500` / `unknown error` ([#22968](https://github.com/appium/appium/pull/22968))
### Specific Endpoints
- [New Session](../reference/api/webdriver.md#createsession): now raises the `session not created`
error instead of `unknown error` if no installed driver matches the requested platform/automation
combination, or the matching driver cannot be loaded or does not export its class. Validation of
missing `platformName`/`appium:automationName` is unchanged
([#22970](https://github.com/appium/appium/pull/22970))
- [Get Timeouts](../reference/api/webdriver.md#gettimeouts): now returns `script` and `pageLoad` in
addition to the existing `implicit` and Appium-specific `command` values
([#22776](https://github.com/appium/appium/pull/22776))
- [Set Timeouts](../reference/api/webdriver.md#timeouts): `script`, `pageLoad`, and `implicit` now
only accept null or integer values; strings and fractions return HTTP `400` / `invalid argument`
([#22961](https://github.com/appium/appium/pull/22961))
- Set Timeouts: `null` values now correctly disable the specified timeout
([#22961](https://github.com/appium/appium/pull/22961))
- Set Timeouts: omitting `script`, `pageLoad`, or `implicit` no longer fails: omitted fields keep their
values and `{}` succeeds without changes. Invalid updates change no values
([#22960](https://github.com/appium/appium/pull/22960),
[#22961](https://github.com/appium/appium/pull/22961))
- Set Timeouts: unknown values for the legacy `type` argument now return HTTP `400` /
`invalid argument` instead of HTTP `500` / `unknown error`
([#22987](https://github.com/appium/appium/pull/22987))
- [getLog](../reference/api/others.md#getlog): unsupported `type` values now return HTTP `400` /
`invalid argument` instead of HTTP `500` / `unknown error`
([#22986](https://github.com/appium/appium/pull/22986))
### BiDi Protocol
- Subscriptions without `contexts` now receive events carrying a context, so that module
subscriptions such as `events: ["log"]` now match events such as `log.entryAdded`. Overlapping
subscriptions deliver each event only once ([#22883](https://github.com/appium/appium/pull/22883))
- The implementation of [`session.subscribe`](../reference/api/bidi.md#bidisubscribe) (which does
not yet support `userContexts`) now rejects `userContexts` with HTTP `500` /
`unsupported operation`, instead of silently creating an unscoped subscription. Malformed
`userContexts`, or supplying both `contexts` and `userContexts`, return HTTP `400` /
`invalid argument`. Drivers implementing user-context support can override `bidiSubscribe`
([#22877](https://github.com/appium/appium/pull/22877)).
- Any `sessionId` or `id` keys inside BiDi command parameters are now validated like any other
unknown parameter, instead of being silently accepted
([#22771](https://github.com/appium/appium/pull/22771))
### [Storage Plugin](https://github.com/appium/appium/tree/master/packages/storage-plugin)
- All [endpoints](../reference/api/plugins.md#storage-plugin) and stream/events WebSocket paths now
respect custom server `--base-path` values, instead of always being mounted at the server root
([#22906](https://github.com/appium/appium/pull/22906))
- File names starting with a dot or ending with `.filepart` are now rejected
([#22863](https://github.com/appium/appium/pull/22863),
[#22959](https://github.com/appium/appium/pull/22959))
- Concurrent WebSocket uploads of the same file are now rejected
([#22962](https://github.com/appium/appium/pull/22962))
- Pending upload WebSocket routes are now preserved across retries
([#22948](https://github.com/appium/appium/pull/22948))
- Errors on upload event sockets are now logged instead of potentially terminating the server
([#22963](https://github.com/appium/appium/pull/22963))
### Other Fixes
- The `appium driver`/`appium plugin` CLI commands now lock the extension manifest while running,
preventing any concurrent CLI commands from silently clobbering each other's changes
([#22767](https://github.com/appium/appium/pull/22767))
- IPv6 literals are now correctly bracketed during URL assembly, including BiDi WebSocket URLs and
[Execute Driver Plugin](https://github.com/appium/appium/tree/master/packages/execute-driver-plugin)
connections ([#22872](https://github.com/appium/appium/pull/22872),
[#22912](https://github.com/appium/appium/pull/22912),
[#22914](https://github.com/appium/appium/pull/22914))
## Developer-Facing Changes
The following changes primarily affect developers of Appium clients, drivers, plugins, or tools
that import Appium's internal packages directly. They do not affect most Appium end users.
### Extension Development
- When installing a locally available driver/plugin using Appium's CLI `install` command with the
`--source=local` flag, Appium now installs the extension directly from the supplied local
directory, without first creating an intermediate global `npm` link
([#23086](https://github.com/appium/appium/pull/23086)). Local installs still link to the source
directory, so source changes do not require reinstalling the extension. If you use tooling that
relies on the package being linked in `npm`'s global prefix, manage that global link separately.
- Extension manifests and `extensions.yaml` are now validated with `ajv`/JSON Schema; a corrupted
`extensions.yaml` now resets to an empty manifest with a warning, instead of crashing later with a
confusing error ([#22732](https://github.com/appium/appium/pull/22732))
- `ExecuteMethodMap` type declarations now check `params` against the target method's signature at
compile time, catching mismatched required/optional execute method parameters in driver code
([#22754](https://github.com/appium/appium/pull/22754))
- When a plugin intercepts a command that would otherwise be proxied downstream, Appium no longer
validates its fields or values ([#23060](https://github.com/appium/appium/pull/23060)). This
matches direct proxying, where the downstream remote end owns these checks. Plugins that
previously relied on Appium to validate these arguments can now receive missing or invalid
values (JSON-object request-body checks still remain in place before the plugin is called). If
your plugin handles such a command without calling `next()`, validate the inputs it uses.
Pass-through plugins can still call `next()` and delegate validation to the downstream remote end.
### `@appium/base-driver`
#### JSONWP/MJSONWP Removal
As listed [in the Breaking Changes section above](#jsonwpmjsonwp-internals-removed), the internal
code responsible for JSONWP/MJSONWP protocol support has been removed
([#22681](https://github.com/appium/appium/pull/22681)). This includes the following items:
- `ProtocolError` instances no longer carry a `jsonwpCode` property, and error responses no longer
include a legacy numeric `status` code (`errorFromMJSONWPStatusCode`, aliased as `errorFromCode`,
has been removed; use `errorFromW3CJsonCode`)
- Responses no longer duplicate element references under the legacy `ELEMENT` key; only the W3C
`element-6066-11e4-a52e-4f735466cecf` key is present
- `WebDriverProxy` (formerly `JWProxy`, now removed as a name) no longer converts responses from a
downstream automation server speaking legacy MJSONWP; downstream servers must speak W3C WebDriver
- `determineProtocol`, `DriverCore#setProtocolMJSONWP()`, and `DriverCore#isMjsonwpProtocol()` have
been removed; drivers can no longer produce the legacy `{sessionId, status, value}` response shape
- `statusCodes` and `getSummaryByCode` are no longer available (the `jsonwp-status` module has been
removed)
- A command result shaped like `{protocol, value}` is no longer unwrapped. It is sent to the
client as the command value, so a script returning `{protocol: 'W3C', value: 5}` gets that object
back. A result of `{protocol, error}` whose `protocol` is `W3C` or `MJSONWP` and whose `error`
is an `Error` is still thrown
#### HTTP Server Moved to Separate Package
The HTTP/Express server code has been extracted from `@appium/base-driver` into the new
`@appium/http-server` package ([#22800](https://github.com/appium/appium/pull/22800)). The
following items are therefore no longer exported from `@appium/base-driver` or `appium/driver.js`:
- Methods: `server`, `normalizeBasePath`, `configureServer`
- Types: `ServerOpts`, `ConfigureServerOpts`, `ConfigureHttpOpts`, `StartServerOpts`
If you use these items, import them from `@appium/http-server` instead.
#### Other Changes
- The default class export has been removed
([#22741](https://github.com/appium/appium/pull/22741)). Use the named `{BaseDriver}` export
instead
- The default export of `basedriver/helpers.js` has been removed
([#22741](https://github.com/appium/appium/pull/22741)). Use named exports instead
- `BaseDriver`'s constructor no longer takes command-mixin machinery into account
([#22741](https://github.com/appium/appium/pull/22741))
- `createSession()` no longer accepts the legacy multi-argument form
(`jwpCaps, reqCaps, w3cCaps`); only the single `w3cCapabilities` argument is supported now
([#22730](https://github.com/appium/appium/pull/22730))
- The deprecated `driverData` mechanism (`Core.driverData`, the `driverData` parameter on
`createSession`/`deleteSession`, and the `DriverData` type) has been removed
([#22716](https://github.com/appium/appium/pull/22716)). Migrate to `IAppiumIpc` instead
- The `server()` and `configureServer()` methods (now exported by `@appium/http-server`) now
default to `allowCors: false` ([#22990](https://github.com/appium/appium/pull/22990))
- Both `ipc.unsubscribe(topic, subscriber)` and `subscription.unsubscribe()` now finish waiting on
async iterators and notify observers once ([#22955](https://github.com/appium/appium/pull/22955)).
An observer that throws still propagates its error to the caller, but no longer prevents waiting
iterators from finishing
- The unused `reset()` method has been removed
([#22741](https://github.com/appium/appium/pull/22741))
- The `generateDriverLogPrefix()` helper no longer supports the deprecated `sessionId` argument
([#22764](https://github.com/appium/appium/pull/22764))
- The new command idle timeout now stays suspended through HTTP/BiDi plugin chains, including work
after `next()`, and while proxied BiDi commands await a response
([#22946](https://github.com/appium/appium/pull/22946),
[#22947](https://github.com/appium/appium/pull/22947)). Custom `startNewCommandTimeout`
implementations must delegate timer creation to `super.startNewCommandTimeout()` so they respect
shared activity, while custom command execution must delegate to `super.executeCommand()` or wrap
the full command in `runWithCommandTimeout`
- The `appium:autoLaunch`, `appium:locale`, `appium:language`, `appium:autoWebview`,
`appium:orientation`, and `appium:udid` capabilities are no longer validated as part of the
standard capability constraints ([#22950](https://github.com/appium/appium/pull/22950),
[#22952](https://github.com/appium/appium/pull/22952)). If you use them, declare them in your own
driver constraints
- The built-in test fixture routes (`/welcome`, `/test/guinea-pig*`, `/produce_error`, `/crash`),
the `STATIC_DIR` export, and the `APPIUM_ENABLE_LEGACY_TEST_PAGES` environment variable have been
removed ([#22680](https://github.com/appium/appium/pull/22680)). If you relied on these fixtures,
migrate to use your own local test server
### `@appium/base-plugin`
- The default class export has been removed ([#22718](https://github.com/appium/appium/pull/22718)).
Use the named `{BasePlugin}` export instead
- `Plugin#logger` has been removed in favor of `Plugin#log`
([#22718](https://github.com/appium/appium/pull/22718))
- `Plugin#name` and `Plugin#cliArgs` are now read-only
([#22718](https://github.com/appium/appium/pull/22718))
### `@appium/logger`
- The default class export has been removed ([#22719](https://github.com/appium/appium/pull/22719)).
Use the named `{log}` export instead
- The long-disabled, no-op progress/unicode methods (`enableProgress`, `disableProgress`,
`progressEnabled`, `enableUnicode`, `disableUnicode`) have been removed
([#22719](https://github.com/appium/appium/pull/22719))
### `@appium/support`
- `env`: the module has been integrated into the `appium` package as internal helpers
([#22708](https://github.com/appium/appium/pull/22708))
- `imageUtil`: the module has been removed ([#22678](https://github.com/appium/appium/pull/22678))
- `fs`: the following exports have been removed: `readPackageJsonFrom` and `findRoot` methods,
`F_OK`/`R_OK`/`W_OK`/`X_OK` constants, `CopyFileDescriptor` and `ReadFn` types
([#22678](https://github.com/appium/appium/pull/22678))
- `fs`: `glob()` now relies on Node's `fs.promises.glob` instead of the `glob` package, with a
narrower `GlobOptions` shape ([#22735](https://github.com/appium/appium/pull/22735))
- `fs`: `mv()` now preserves symlinks inside moved directories and moves source symlinks themselves
without moving their targets' contents. Dangling source links are supported, and Windows
case-only renames update the entry's spelling
([#22880](https://github.com/appium/appium/pull/22880),
[#22954](https://github.com/appium/appium/pull/22954),
[#22958](https://github.com/appium/appium/pull/22958))
- `fs`: `walkDir()` now continues after walker errors such as `EACCES` and `ELOOP` instead of
hanging. These errors are logged and affected entries are skipped; `ENOENT` still rejects the
returned promise ([#22956](https://github.com/appium/appium/pull/22956))
- `fs`: `write()` now relies on Node's `promisify`, which resolves to an object
(`{bytesWritten, buffer}`), instead of only `bytesWritten`
([#22704](https://github.com/appium/appium/pull/22704))
- `logger`: the default export has been removed. Use the named `{log}` export instead
([#22719](https://github.com/appium/appium/pull/22719))
- `logger`: `errorAndThrow` has been removed in favor of `errorWithException`
([#22719](https://github.com/appium/appium/pull/22719))
- `net`: support for FTP-based file uploads has been removed, along with the `FtpUploadOptions` and
`NotHttpUploadOptions` types ([#22678](https://github.com/appium/appium/pull/22678))
- `net`: the new `checkPortStatus()` and `getFreePort()` helpers replace the `portscanner` package
and custom free port lookups in drivers and plugins
([#23156](https://github.com/appium/appium/pull/23156)). Unlike `portscanner`, they accept an
options object instead of positional arguments. `getFreePort()` also covers `findAPortNotInUse()`:
pass `port` (a single port or a `[startPort, endPort]` range) to probe specific ports, in which
case it throws `NoFreePortError` if all of them are busy instead of resolving with `false`
- `mjpeg`: the module has been removed ([#22678](https://github.com/appium/appium/pull/22678))
- `mkdirp`: the module has been removed ([#22678](https://github.com/appium/appium/pull/22678)).
Import `mkdirp()` from the `fs` module instead
- `node`: `requirePackage()` has been removed
([#22684](https://github.com/appium/appium/pull/22684))
- `npm`: the module has been integrated into the `appium` package as internal helpers
([#22721](https://github.com/appium/appium/pull/22721))
- `process`: the module has been removed ([#22678](https://github.com/appium/appium/pull/22678))
- `system`: `macOsxVersion()` has been removed
([#22684](https://github.com/appium/appium/pull/22684))
- `util`: the following methods have been removed: `uuidV1`, `uuidV3`, `uuidV5`, `localIp`,
`cancellableDelay`, and `multiResolve` ([#22678](https://github.com/appium/appium/pull/22678))
- `zip`: `extractAllTo()` always uses the built-in JS extractor now, so the `useSystemUnzip` option
has been removed ([#23091](https://github.com/appium/appium/pull/23091)). The extractor supports
only stored and deflate entries and verifies the CRC32 of every entry. File names that are not
flagged as UTF-8 by the archive are decoded as `utf8` by default, and the legacy `cp437` decoding
is no longer supported. Other single-byte encodings supported by Node.js can be selected via
`fileNamesEncoding`. Archives with encrypted entries or other compression methods are rejected
with `ZipStreamUnsupportedError`
### `@appium/tsconfig`
- `noImplicitOverride` is now set to `true`, which means that TypeScript drivers and plugins that
extend the config must mark every member overriding a base class member (e.g. `BaseDriver` or
`BasePlugin` methods, and `static` fields such as `newMethodMap`) with the `override` modifier
([#23143](https://github.com/appium/appium/pull/23143)). Opt-out is also possible by setting
`noImplicitOverride` to `false` in your own `tsconfig.json`.
### Client Development
- State-changing HTTP requests with an `Origin` header now return HTTP `403`, unless the CORS
insecure feature is enabled on the Appium server
([#23102](https://github.com/appium/appium/pull/23102)). Remove the `Origin` header or instruct
users to enable CORS.
## New Features
### App URL Rules
The new `--app-url-rules` server CLI flag (and its equivalent configuration file property) allows
server hosts to restrict the host/IP values allowed in capabilities like `appium:app`. Configurable
properties include allow/deny lists, HTTPS-only, credentials, and redirect limits.
Refer to [the Security guide](./security.md#restricting-remote-app-urls) for more details.
### CLI Update Command Checks Server Requirement
As a follow-up to Appium 3.9, which changed the default behavior of the Appium CLI
[`install`](../reference/cli/extensions.md#install) command to install the newest extension version
that is compatible with the current server (as opposed to throwing an error if the server
requirement of the latest extension version is incompatible), Appium 4 adjusts the
[`update`](../reference/cli/extensions.md#update) command to now implement this behavior as well.
This makes default usage of both `install` and `update` safe even when future major extension
versions raise their server requirements.
### Commands Can Bypass Queue
Driver commands (endpoints) are now allowed to bypass the default command queue, which enables the
command to execute while another long-running command is in progress.
By default, only the standard [Status](../reference/api/webdriver.md#getstatus) endpoint is exempt
from the queue, but driver developers can also customize the list of exempt commands by overriding
the `queueExemptCommands` getter.
The behavior of the idle timer (set by `appium:newCommandTimeout`) has also been adjusted to only
reset once no commands are executing.
### New Set Timeouts Parameter
The standard [Set Timeouts](../reference/api/webdriver.md#timeouts) endpoint has been extended to
additionally accept the Appium-specific `command` parameter. This aligns its handling with
[Get Timeouts](../reference/api/webdriver.md#gettimeouts), which already returned this parameter.
The parameter itself is mapped to the `appium:newCommandTimeout` capability.
The non-standard `type`/`ms` parameters, which were previously the only way to change this timeout
mid-session, have been deprecated as a result.
### Universal XML Plugin Can Be Toggled
The [Universal XML plugin](https://github.com/appium/appium/tree/master/packages/universal-xml-plugin)
now provides the [`universalXml: setEnabled` and `universalXml: isEnabled` execute methods](../reference/api/plugins.md#universal-xml-plugin),
which allow toggling the translation during a session, e.g. to retrieve the original page source.
+123
View File
@@ -37,6 +37,10 @@ sessions the feature should apply. The prefix can be either the driver's `automa
wildcard (`*`) symbol, if the feature should be applied to all drivers. The prefix and feature name
are separated using the colon character (`:`).
Use the driver's `automationName`, which may differ from its install name. An install-name-only
prefix does not enable or disable a feature. When configuring a session, Appium warns about such
entries for that driver unless the prefix is another installed driver's `automationName`.
For example, `first:foo` refers to the `foo` feature for the `first` driver, whereas `*:bar` refers
to the `bar` feature for all drivers.
@@ -87,3 +91,122 @@ Turn on multiple insecure features for specific drivers:
```bash
appium --allow-insecure=uiautomator2:adb_shell,xcuitest:get_server_logs
```
## Restricting Remote App URLs
Several drivers accept a URL instead of a local path in capabilities such as `appium:app`, in which
case the Appium server downloads the application package from that URL before starting the session.
By default, any `http:` or `https:` URL is accepted. Server hosts who want to control which URLs
their server is allowed to download from can do so with the `--app-url-rules` argument (or the
`server.app-url-rules` property in a [configuration file](./config.md)). Its value is a JSON object
(or a path to a JSON file) with any of the following properties:
| <div style="width:10em">Rule</div> | Description | Default |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `allow` | List of hostname patterns, IP addresses, or CIDR subnets. If non-empty, a hostname or its resolved address must match _at least one_ | `[]` |
| `deny` | List of hostname patterns, IP addresses, or CIDR subnets. A matching hostname or resolved address is rejected, even if an `allow` rule also matches | `[]` |
| `httpsOnly` | Only accept `https:` URLs | `false` |
| `allowCredentials` | Accept URLs containing a username and/or password (e.g. `https://user:pass@host/app.apk`) | `true` |
| `maxRedirects` | Maximum number of HTTP redirects to follow while downloading. Set to `0` to reject any redirect | `21` |
Hostnames are normalized (lowercased, converted to Punycode, trailing dot removed) before matching
and resolved on every download. Address rules apply to literal addresses and all dynamically
resolved IPv4/IPv6 addresses. The rules are also applied to every redirect, so redirects cannot be
used to escape them. If a URL violates any rule, the session is not created and a generic error
is returned. The violated rule is deliberately neither reported to the client nor written to the
server log, since server logs are often handed over to clients as well. URL schemes, ports, paths,
queries, and fragments are not matched.
Hostname patterns use the [picomatch](https://github.com/micromatch/picomatch#globbing-features)
glob syntax and are matched against the whole hostname:
| Pattern | Matches |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `artifacts.example.com` | Exactly this hostname |
| `*.example.com` | Any subdomain of `example.com` (including nested ones, like `a.b.example.com`), but not `example.com` itself |
| `*example.com` | Any hostname ending with `example.com`, including `example.com` itself |
| `apps.{staging,prod}.example.com` | `apps.staging.example.com` and `apps.prod.example.com` |
| `build-?.example.com` | `build-1.example.com`, `build-a.example.com`, etc. |
| `node[0-9].example.com` | `node0.example.com` to `node9.example.com` |
IP address rules match a single address (`192.0.2.10`, `2001:db8::1`) or a whole subnet in CIDR
notation (`10.0.0.0/8`, `2001:db8::/32`). IPv4 rules also match IPv4-mapped IPv6 addresses
(e.g. `::ffff:10.1.2.3`).
!!! note
```
These rules only apply to URLs the server downloads via the standard app configuration helper,
which is used for `appium:app` and similar capabilities by all official drivers. Drivers may
define custom capabilities with URLs that are processed differently and thus are not covered.
```
!!! note
```
If the server downloads applications through an HTTP proxy (configured via the `HTTP_PROXY`,
`HTTPS_PROXY` and `NO_PROXY` environment variables), the proxy resolves the destination host
itself, so rules containing IP addresses or subnets cannot be enforced for proxied downloads.
Such downloads are rejected; either exclude the download hosts from proxying via `NO_PROXY`
or only use hostname-based rules.
```
### Examples
Only allow HTTPS downloads from an internal artifact server, without credentials in the URL and
without following redirects:
```bash
appium --app-url-rules='{"allow": ["artifacts.example.com", "10.0.0.0/8"], "httpsOnly": true, "allowCredentials": false, "maxRedirects": 0}'
```
The same configuration as part of a config file:
```yaml
server:
app-url-rules:
allow:
- 'artifacts.example.com'
- '10.0.0.0/8'
httpsOnly: true
allowCredentials: false
maxRedirects: 0
```
Allow downloads from any subdomain of `example.com` and from two IPv6 subnets, except from the
staging environment:
```yaml
server:
app-url-rules:
allow:
- '*.example.com'
- '2001:db8:1::/48'
- '2001:db8:2::/48'
deny:
- '*.staging.example.com'
```
Allow downloads from anywhere, except from the server itself, private networks, link-local
addresses (such as cloud metadata services), and any `.internal` hostname:
```yaml
server:
app-url-rules:
deny:
- 'localhost'
- '*.internal'
- '127.0.0.0/8'
- '10.0.0.0/8'
- '172.16.0.0/12'
- '192.168.0.0/16'
- '169.254.0.0/16'
- '::1/128'
- 'fc00::/7'
- 'fe80::/10'
```
The rules in the last example are applied to the addresses each hostname resolves to, so they
cannot be bypassed via DNS. Note that the `deny` list also blocks any download from the server's
own private network, so a private artifact server must be excluded from the `deny` rules in order
to work.
+6 -7
View File
@@ -2,7 +2,7 @@
hide:
- toc
title: SSL/TLS/SPDY Support
title: SSL/TLS Support
---
Appium 2.2 introduces the option to start the Appium server with SSL/TLS support.
@@ -20,15 +20,14 @@ Both arguments must be provided and should contain paths to a valid
[X509 PEM](https://www.ssl.com/guide/pem-der-crt-and-cer-x-509-encodings-and-conversions/)
certificate and its corresponding private key.
After the server is started use the `https` protocol and a client supporting SSL/TLS or
[SPDY](https://en.wikipedia.org/wiki/SPDY) to communicate to it.
After the server is started use the `https` protocol and a client supporting SSL/TLS to
communicate to it.
### Supported Features
Once a secure server socket is established it supports the following protocols:
`['h2', 'spdy/3.1', 'spdy/3', 'spdy/2', 'http/1.1', 'http/1.0']`. See
[the SPDY node module documentation](https://www.npmjs.com/package/spdy) to get more details about
its features. All insecure client connections will be rejected by the server.
Once a secure server socket is established it uses Node.js' native
[`https`](https://nodejs.org/api/https.html) module to serve connections. All insecure client
connections will be rejected by the server.
### Self-Signed Certificates
+12 -2
View File
@@ -41,6 +41,16 @@ So, for example, the `Find Element` command corresponds to an HTTP `POST` reques
endpoint `/session/:sessionid/element` (where in this case, `:sessionid` is a placeholder for the
unique session ID generated by the server in a previous call to `Create Session`).
If the client disconnects before Appium finishes sending a `Create Session` response and the
request has no `X-Idempotency-Key`, Appium deletes the new session once driver setup completes.
Setup is not interrupted. With an accepted idempotency key, a retry that arrives before setup
finishes waits for the same session ID, or the same error if setup failed. If the original client
and all waiting retries disconnect before setup finishes, Appium deletes the new session and
discards its cached result; a later retry starts a new session. Otherwise, Appium keeps the session
and caches its response for replay while it remains in the bounded, in-memory idempotency cache.
Disconnecting after a response was sent, or during a command in an existing session, does not
automatically end that session. Use `Delete Session` when you are done.
This information is primarily useful for people developing technology that works with the WebDriver
spec. It's not particularly useful for people trying to write Appium or Selenium tests. When you
write an Appium test, you want to use a programming language you're familiar with. Luckily, there
@@ -112,8 +122,8 @@ System.Console.WriteLine(driver.PageSource);
Each of these scripts, despite being in different languages, does the same thing under the hood:
1. Call `Find Element` with a `using` parameter of `xpath` and a `value` parameter expressing the
XPath query used to find an element. (If you're confused about these terms, you might find an
introduction to Appium or Selenium useful)
XPath query used to find an element. (If you're confused about these terms, you might find an
introduction to Appium or Selenium useful)
2. Call `Click Element` with the ID of the element found in the previous call.
3. Call `Get Element Text` with the ID of the same element, and print it to the console.
4. Call `Get Page Source` to retrieve the page/app source and print it to the console.
+1 -1
View File
@@ -19,7 +19,7 @@ Appium, called `BaseDriver`. You could have something very close to a "working"
very simple lines of code:
```js
import BaseDriver from '@appium/base-driver'
import {BaseDriver} from '@appium/base-driver'
class MyNewDriver extends BaseDriver {
}
@@ -8,15 +8,14 @@ title: Write a Test (.NET)
The [Appium .NET Client](https://github.com/appium/dotnet-client/) is
an official Appium client in C#. This driver is an extension of the Selenium C# client. It has all the functionalities of the regular driver, but add Appium-specific methods on top of this. The driver is available on the public NuGet Gallery as [Appium.WebDriver](https://www.nuget.org/packages/Appium.WebDriver/).
Now, we get inside the directory and create a new [NUnit](https://nunit.org/) project. We will also add the references to the Appium.Net driver, and other dependencies.
Now, create a new [NUnit](https://nunit.org/) project. We will also add the references to the Appium.Net driver, and other dependencies.
```bash
cd dotnet-client
dotnet new nunit --name appiumtest
cd appiumtest
# This will install the latest 5.x version
# This will install the latest version
dotnet add package Appium.WebDriver --prerelease
dotnet add package Newtonsoft.Json --version 13.0.3
```
@@ -47,7 +46,7 @@ public class Tests
driverOptions.AddAdditionalAppiumOption("appPackage", "com.android.settings");
driverOptions.AddAdditionalAppiumOption("appActivity", ".Settings");
// NoReset assumes the app com.google.android is preinstalled on the emulator
// NoReset assumes the app com.android.settings is preinstalled on the emulator
driverOptions.AddAdditionalAppiumOption("noReset", true);
_driver = new AndroidDriver(serverUri, driverOptions, TimeSpan.FromSeconds(180));
@@ -57,16 +57,17 @@ session.unsubscribe
> WebDriver BiDi documentation: [session.unsubscribe](https://w3c.github.io/webdriver-bidi/#command-session-unsubscribe)
Unsubscribes using either previously returned subscription IDs or event names.
Removing a subscription ID preserves any overlapping subscriptions.
Unsubscribes from one or more BiDi events using subscription IDs or event names. Event names can
also be scoped to contexts (legacy parameter). Removing a subscription ID preserves any overlapping
subscriptions.
#### Parameters
| Name | Description | Type | Default |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------- |
| `subscriptions?` | Non-empty list of subscription IDs returned by `session.subscribe`. Cannot be combined with `events` or `contexts`. | string[] | |
| `contexts?` | Non-standard, only together with `events`: contexts in which to unsubscribe from the specified events. By default, the global scope is applied. | string[] | `['']` |
| `events?` | Non-empty list of event names to unsubscribe from. Required when `subscriptions` is omitted. | string[] | |
| Name | Description | Type | Default |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | ------- |
| `subscriptions?` | Non-empty list of subscription IDs returned by `session.subscribe`. Cannot be combined with `events` or `contexts`. | string[] | |
| `events?` | Non-empty list of event names to unsubscribe from. Required when `subscriptions` is omitted. | string[] | |
| `contexts?` | Legacy parameter: contexts in which to unsubscribe from events specified in `events`. By default, the global scope is applied. | string[] | `['']` |
All subscription IDs must be known to the current session. An unknown ID causes an `invalid argument`
error without removing any subscriptions. Subscription IDs are cleared when the session is deleted.
@@ -11,125 +11,6 @@ title: JSON Wire Protocol
The following is a list of legacy [JSON Wire Protocol (JSONWP)](https://www.selenium.dev/documentation/legacy/json_wire_protocol/)
endpoints supported in Appium.
### getSession
```
GET /session/:sessionId
```
> JSONWP documentation: [/session/:sessionId](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionid)
Retrieves the capabilities of the current session.
Appium implements a modified version of this endpoint. If the `appium:eventTimings` capability is
set to `true`, the returned result will additionally include the `events` key, whose value contains
the event history and timings.
!!! warning "Deprecated"
For retrieving capabilities, please use [`getAppiumSessionCapabilities`](./appium.md#getappiumsessioncapabilities).<br />
For retrieving event history, please use [`getLogEvents`](./appium.md#getlogevents).
#### Response
`Capabilities` - an object containing the session capabilities, and the event history (if applicable)
### availableIMEEngines
```
GET /session/:sessionId/ime/available_engines
```
> JSONWP documentation: [/session/:sessionId/ime/available_engines](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidimeavailable_engines)
Retrieves all IME (input method editor) engines available on the device under test.
!!! warning "Deprecated"
In the future, this endpoint will be moved to the [UiAutomator2 and Espresso drivers](../../ecosystem/drivers.md)
#### Response
`string[]` - a list of available IME engines
### getActiveIMEEngine
```
GET /session/:sessionId/ime/active_engine
```
> JSONWP documentation: [/session/:sessionId/ime/active_engine](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidimeactive_engine)
Retrieves the name of the active IME engine.
!!! warning "Deprecated"
In the future, this endpoint will be moved to the UiAutomator2 and Espresso drivers
#### Response
`string` - the name of the active IME engine
### isIMEActivated
```
GET /session/:sessionId/ime/activated
```
> JSONWP documentation: [/session/:sessionId/ime/activated](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidimeactivated)
Determines if IME input is available and active.
!!! warning "Deprecated"
In the future, this endpoint will be moved to the UiAutomator2 and Espresso drivers
#### Response
`boolean` - `true` if IME is active, otherwise `false`
### deactivateIMEEngine
```
POST /session/:sessionId/ime/deactivate
```
> JSONWP documentation: [/session/:sessionId/ime/deactivate](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidimedeactivate)
Deactivates the currently active IME engine.
!!! warning "Deprecated"
In the future, this endpoint will be moved to the UiAutomator2 and Espresso drivers
#### Response
`null`
### activateIMEEngine
```
POST /session/:sessionId/ime/activate
```
> JSONWP documentation: [/session/:sessionId/ime/activate](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidimeactivate)
Activates an IME engine.
!!! warning "Deprecated"
In the future, this endpoint will be moved to the UiAutomator2 and Espresso drivers
#### Parameters
| Name | Description | Type |
| -------- | ---------------------------------- | ------ |
| `engine` | Name of the IME engine to activate | string |
#### Response
`null`
### getOrientation
```
@@ -171,53 +52,3 @@ Sets the orientation of the device under test.
#### Response
`null`
### getGeoLocation
```
GET /session/:sessionId/location
```
> JSONWP documentation: [/session/:sessionId/location](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidlocation)
Retrieves the current location of the device under test.
!!! warning "Deprecated"
Please use driver-specific extension methods such as `mobile: getGeoLocation` or
`mobile: getSimulatedLocation`
#### Response
`Location` - an object with the following properties:
| Name | Description | Type |
| ----------- | -------------------------------- | ------ |
| `altitude` | Altitude of the device location | number |
| `latitude` | Latitude of the device location | number |
| `longitude` | Longitude of the device location | number |
### setGeoLocation
```
POST /session/:sessionId/location
```
> JSONWP documentation: [/session/:sessionId/location](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidlocation)
Sets the current location of the device under test.
!!! warning "Deprecated"
Please use driver-specific extension methods such as `mobile: setGeoLocation` or
`mobile: setSimulatedLocation`
#### Parameters
| Name | Description | Type |
| ---------- | ------------------------------------------- | ------------------------- |
| `location` | New device latitude, longitude and altitude | [`Location`](#response_6) |
#### Response
`null`
@@ -120,53 +120,3 @@ Retrieves all available application contexts.
#### Response
`string[]` - the names of available contexts
### getNetworkConnection
```
GET /session/:sessionId/network_connection
```
> MJSONWP documentation: [Device Modes](https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md#device-modes)
Retrieves the current state of network types (data, Wi-Fi, airplane mode).
!!! warning "Deprecated"
Please use driver-specific extension methods such as `mobile: getConnectivity`
#### Response
`NetworkConnectionState` - a number indicating the current network state:
| Value | Data | Wi-Fi | Airplane Mode |
| ----- | ---- | ----- | ------------- |
| `0` | OFF | OFF | OFF |
| `1` | OFF | OFF | ON |
| `2` | OFF | ON | OFF |
| `4` | ON | OFF | OFF |
| `6` | ON | ON | OFF |
### setNetworkConnection
```
POST /session/:sessionId/network_connection
```
> MJSONWP documentation: [Device Modes](https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md#device-modes)
Sets the state of network types (data, Wi-Fi, airplane mode).
!!! warning "Deprecated"
Please use driver-specific extension methods such as `mobile: setConnectivity`
#### Parameters
| <div style="width:6em">Name</div> | Description | <div style="width:18em">Type</div> |
| --------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------- |
| `parameters` | Object containing the `type` key, whose value is the desired network state | `{"type": `[`NetworkConnectionState`](#response_5)`}` |
#### Response
[`NetworkConnectionState`](#response_5) - the new network state
@@ -267,6 +267,43 @@ preserved, and only the incomplete uploads will be stopped.
## Universal XML Plugin
Translation is on by default. It can be turned off and on during a session with the
[execute methods](../../guides/execute-methods.md) below, and applies only to the current session.
### execute
```
POST /session/:sessionId/execute/sync
```
Modifies the [`execute`](./webdriver.md#execute) endpoint:
- Adds the `universalXml: setEnabled` and `universalXml: isEnabled` execute methods. Any other
script is passed on unchanged
#### universalXml: setEnabled
Turns translation on or off for the current session. While it is off, `findElement`,
`findElements` and `getPageSource` are passed on unchanged.
##### Parameters
| Name | Description | Type |
| --------- | ------------------------------------------------- | ------- |
| `enabled` | Whether node/attribute names should be translated | boolean |
##### Response
`null`
#### universalXml: isEnabled
Returns whether translation is on for the current session.
##### Response
`boolean` - `true` if translation is on
### findElement
```
@@ -26,18 +26,11 @@ POST /session
Creates a new WebDriver session.
Appium implements a modified version of this endpoint for historical reasons. While the W3C
endpoint only accepts 1 parameter, Appium's implementation allows up to 3 parameters, as this was
required by the legacy JSON Wire Protocol (JSONWP). Since Appium 2, the JSONWP format is no longer
supported, and any of the 3 parameters can be used to specify the W3C capabilities.
#### Parameters
| Name | Description | Type |
| ------------------- | ----------------------------------------------------------------------------- | --------------- |
| `w3cCapabilities1?` | Capabilities of the new session | `W3CDriverCaps` |
| `w3cCapabilities2?` | Another location for the new session capabilities (legacy) | `W3CDriverCaps` |
| `w3cCapabilities?` | Another location for the new session capabilities (legacy) | `W3CDriverCaps` |
| Name | Description | Type |
| --------------- | ------------------------------- | --------------- |
| `capabilities?` | Capabilities of the new session | `W3CDriverCaps` |
#### Response
@@ -92,14 +85,19 @@ GET /session/:sessionId/timeouts
Retrieves the timeout values of the current session.
Appium implements a modified version of this endpoint, by also returning the value of the `command`
timeout for supported drivers and contexts.
#### Response
`GetTimeoutsResult` - an object with the following properties:
| Name | Description | Type |
| ---------- | --------------------- | ------ |
| `command` | Command timeout | number |
| `implicit` | Implicit wait timeout | number |
| Name | Description | Type |
| ---------- | ---------------------- | -------------- |
| `script` | Script timeout | number or null |
| `pageLoad` | Page load timeout | number or null |
| `implicit` | Implicit wait timeout | number or null |
| `command` | Appium command timeout | number |
### timeouts
@@ -111,13 +109,17 @@ POST /session/:sessionId/timeouts
Sets the timeout values of the current session.
Appium implements a modified version of this endpoint by adding the optional `command` parameter
for supported drivers and contexts.
#### Parameters
| Name | Description | Type |
| ----------- | ---------------------------------------------------------- | ------ |
| `implicit?` | Implicit wait timeout (in milliseconds) | number |
| `pageLoad?` | Page load timeout (in milliseconds) | number |
| `script?` | Script timeout (in milliseconds) | number |
| Name | Description | Type |
| ----------- | ----------------------------------------------------------- | -------------- |
| `script?` | Script timeout (in milliseconds) | number or null |
| `implicit?` | Implicit wait timeout (in milliseconds) | number or null |
| `pageLoad?` | Page load timeout (in milliseconds) | number or null |
| `command?` | Appium command timeout (in milliseconds) | number |
#### Response
@@ -954,7 +956,7 @@ POST /session/:sessionId/actions
> WebDriver documentation: [Perform Actions](https://w3c.github.io/webdriver/#perform-actions)
Performs a sequence of [actions](https://w3c.github.io/webdriver/#actions).
Performs a sequence of [actions](https://w3c.github.io/webdriver/#actions). See the [Automating Gestures](../../guides/gestures.md) guide for multi-language examples.
#### Parameters
@@ -14,6 +14,7 @@ they can only be enabled using the wildcard (`*`) prefix:
| Feature Name | Description |
| ------------------- | ------------------------------------------------------------------------------- |
| `session_discovery` | Allows retrieving the list of active server sessions via `GET /appium/sessions` |
| `cors` | Allows web browser connections to the server from any host |
Of course, Appium drivers and plugins are free to define additional insecure features of their own.
The following features are defined by official plugins:
+75 -42
View File
@@ -24,48 +24,81 @@ appium
All of these options can also be set via a [Configuration File](../../guides/config.md). Options
set on the command line will override any options found in a configuration file.
| <div style="width:15em">Argument</div> | Description | Type | <div style="width:7em">Default</div> |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -------------------------------------------------------- |
| `--address`, `-a` | IPv4/IPv6 address or a hostname to listen on | string | `0.0.0.0` |
| `--allow-cors` | Allow web browser connections from any host | boolean | `false` |
| `--allow-insecure` | List of [insecure features](../../guides/security.md) that should be allowed in this server's sessions. Individual features can be overridden by `--deny-insecure`. Has no effect in combination with `--relaxed-security`. | array<string> | `[]` |
| `--allow-unknown-args` | Do not exit if unrecognized command-line arguments are passed to the server; ignore them instead. Useful when the Appium CLI is wrapped by external tooling that appends extra flags. | boolean | `false` |
| `--base-path`, `-pa` | Base path to use as the prefix for all webdriver routes running on the server | string | `""` |
| `--callback-address`, `-ca` | Callback IP address | string | same as `--address` |
| `--callback-port`, `-cp` | Callback port | integer | `4723` |
| `--config` | Path to an [Appium configuration JSON file](../../guides/config.md) | string | |
| `--debug-log-spacing` | Add exaggerated spacing in logs to help with visual inspection | boolean | `false` |
| `--default-capabilities`, `-dc` | Capabilities that will be used for each session, unless overridden by received capabilities | object | |
| `--deny-insecure` | List of [insecure features](../../guides/security.md) that should be disabled in this server's sessions. Since all insecure features are disabled by default, this argument has no effect without either `--allow-insecure` or `--relaxed-security`, and is applied after both. | array<string> | `[]` |
| `--driver` | Driver-specific configuration. Keys should correspond to driver package names | object | |
| `--drivers-import-chunk-size` | Maximum number of drivers that can be imported in parallel on server startup | number | `3` |
| `--keep-alive-timeout`, `-ka` | Timeout (in seconds) to use as both the keep-alive timeout and the connection timeout for all client requests. Disabled if set to `0`. | integer | `600` |
| `--request-timeout` | Timeout (in seconds) for waiting to receive the entire HTTP request from the client. Disabled if set to `0`. Requests exceeding this timeout will be rejected with the code `HTTP 408`. | integer | `3600` |
| `--local-timezone` | Use local timezone for log timestamps | boolean | `false` |
| `--log`, `-g` | Path to a file where the server logs should be output. This does not affect output on the console. | string | |
| `--log-filters` | List of log filtering rules. See the [log filtering guide](../../guides/log-filters.md) for details. | array | |
| `--log-level` | The log level for the server logs. Supported values are `debug`, `info`, `warn`, or `error`. Combining two supported values using a colon (e.g. `warn:debug`) allows to set separate log levels for the console and file outputs, respectively. | string | `debug` |
| `--log-format` | The log format of the server logs. Supported values are `text`, `json`, or `pretty_json`. Setting the value to `json` disables colors. | string | `text` |
| `--log-no-colors` | Disable colors in the server log | boolean | `false` |
| `--log-timestamp` | Show timestamps in the server log | boolean | `false` |
| `--long-stacktrace` | Add long stack traces to log entries. Recommended for debugging only. | boolean | `false` |
| `--max-ipc-data-size` | Maximum byte size of IPC message objects. | integer | `1048576` (1MB) |
| `--max-ipc-topics` | Maximum number of IPC topics per session. | integer | `1000` |
| `--no-perms-check` | Skip various permission checks on the server startup | boolean | `false` |
| `--nodeconfig` | JSON configuration for registering Appium as a node with Selenium Grid 3 | object | |
| `--plugin` | Plugin-specific configuration. Keys should correspond to plugin package names | object | |
| `--plugins-import-chunk-size` | Maximum number of plugins that can be imported in parallel on server startup | number | `7` |
| `--port`, `-p` | Port to listen on | integer | `4723` |
| `--relaxed-security` | Allow all [insecure features](../../guides/security.md). Only use this if all clients are in a trusted network and could not potentially break out of the session sandbox. Specific features can be overridden by using `--deny-insecure`. | boolean | `false` |
| `--session-override` | Enable session override (clobbering) | boolean | `false` |
| `--shutdown-timeout` | Timeout (in milliseconds) for waiting on all active connections to close, when shutting down the server | number | `5000` |
| `--ssl-cert-path` | Absolute path to the `.cert` file if TLS is used. Must be provided together with `--ssl-key-path`. See the [SSL/TLS/SPDY Support guide](../../guides/tls.md) for details. | string | |
| `--ssl-key-path` | Absolute path to the `.key` file if TLS is used. Must be provided together with `--ssl-cert-path`. See the [SSL/TLS/SPDY Support guide](../../guides/tls.md) for details. | string | |
| `--strict-caps` | Prevent creation of new client sessions that use unsupported capabilities | boolean | `false` |
| `--tmp` | Absolute path to the directory used for temporary files | string | [`os.tmpdir()`](https://nodejs.org/api/os.html#ostmpdir) |
| `--use-drivers` | List of drivers to activate. By default, all installed drivers are activated. | array<string> | `[]` |
| `--use-plugins` | List of plugins to activate. By default, no plugins are activated. Set to `["all"]` to activate all installed plugins. | array<string> | `[]` |
| `--webhook`, `-G` | URL for an HTTP listener where the server logs should be output. This does not affect output on the console. A bare `host:port` is also accepted, which posts the logs to the root path over plain http; a value having neither a scheme nor a port falls back to `127.0.0.1:9003`. | string | |
| <div style="width:15em">Argument</div> | Description | Type | <div style="width:7em">Default</div> |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -------------------------------------------------------- |
| `--address`, `-a` | IPv4/IPv6 address or a hostname to listen on | string | `0.0.0.0` |
| `--allow-cors` | Allow web browser connections from any host | boolean | `false` |
| `--allow-insecure` | List of [insecure features](../../guides/security.md) that should be allowed in this server's sessions. Individual features can be overridden by `--deny-insecure`. Has no effect in combination with `--relaxed-security`. | array<string> | `[]` |
| `--allow-unknown-args` | Do not exit if unrecognized command-line arguments are passed to the server; ignore them instead. Useful when the Appium CLI is wrapped by external tooling that appends extra flags. | boolean | `false` |
| `--app-url-rules` | Rules that remote application URLs (e.g. in the `appium:app` capability) must satisfy before the server downloads them. See the [Restricting Remote App URLs](../../guides/security.md#restricting-remote-app-urls) guide for details. Can be a path to a JSON file or raw JSON. | object | |
| `--base-path`, `-pa` | Base path to use as the prefix for all webdriver routes running on the server | string | `""` |
| `--config` | Path to an [Appium configuration JSON file](../../guides/config.md) | string | |
| `--bidi-heartbeat-interval` | Interval (in seconds) between WebSocket pings sent to each [BiDi](../api/bidi.md) client. A connection that misses two consecutive pongs is terminated. Disabled if set to `0`. | integer | `15` |
| `--bidi-max-buffered-bytes` | Maximum number of bytes the server may keep buffered for a BiDi connection whose client is not reading fast enough. A connection that stays above the limit for longer than `--bidi-max-buffered-ms`, or exceeds twice the limit, is closed with the code `1013`. Disabled if set to `0`, which also turns off skipping of droppable events. | integer | `33554432` |
| `--bidi-max-buffered-ms` | Time (in milliseconds) a BiDi connection may stay above `--bidi-max-buffered-bytes` before it is closed. If set to `0`, the connection is closed as soon as the limit is exceeded. | integer | `30000` |
| `--default-capabilities`, `-dc` | Capabilities that will be used for each session, unless overridden by received capabilities. See [Default Capabilities](#default-capabilities) for how they are applied. | object | |
| `--deny-insecure` | List of [insecure features](../../guides/security.md) that should be disabled in this server's sessions. Since all insecure features are disabled by default, this argument has no effect without either `--allow-insecure` or `--relaxed-security`, and is applied after both. | array<string> | `[]` |
| `--driver` | Driver-specific configuration. Keys should correspond to driver package names | object | |
| `--drivers-import-chunk-size` | Maximum number of drivers that can be imported in parallel on server startup | number | `3` |
| `--keep-alive-timeout`, `-ka` | Timeout (in seconds) to use as both the keep-alive timeout and the connection timeout for all client requests. Disabled if set to `0`. | integer | `600` |
| `--request-timeout` | Timeout (in seconds) for waiting to receive the entire HTTP request from the client. Disabled if set to `0`. Requests exceeding this timeout will be rejected with the code `HTTP 408`. | integer | `3600` |
| `--local-timezone` | Use local timezone for log timestamps | boolean | `false` |
| `--log`, `-g` | Path to a file where the server logs should be output. This does not affect output on the console. | string | |
| `--log-filters` | List of log filtering rules. See the [log filtering guide](../../guides/log-filters.md) for details. | array | |
| `--log-level` | The log level for the server logs. Supported values are `debug`, `info`, `warn`, or `error`. Combining two supported values using a colon (e.g. `warn:debug`) allows to set separate log levels for the console and file outputs, respectively. | string | `info` |
| `--log-format` | The log format of the server logs. Supported values are `text`, `json`, or `pretty_json`. Setting the value to `json` disables colors. | string | `text` |
| `--log-no-colors` | Disable colors in the server log | boolean | `false` |
| `--log-timestamp` | Show timestamps in the server log | boolean | `false` |
| `--long-stacktrace` | Add long stack traces to log entries. Recommended for debugging only. | boolean | `false` |
| `--max-ipc-data-size` | Maximum byte size of IPC message objects. | integer | `1048576` (1MB) |
| `--max-ipc-topics` | Maximum number of IPC topics per session. | integer | `1000` |
| `--no-perms-check` | Skip various permission checks on the server startup | boolean | `false` |
| `--plugin` | Plugin-specific configuration. Keys should correspond to plugin package names | object | |
| `--plugins-import-chunk-size` | Maximum number of plugins that can be imported in parallel on server startup | number | `7` |
| `--port`, `-p` | Port to listen on | integer | `4723` |
| `--relaxed-security` | Allow all [insecure features](../../guides/security.md). Only use this if all clients are in a trusted network and could not potentially break out of the session sandbox. Specific features can be overridden by using `--deny-insecure`. | boolean | `false` |
| `--session-override` | Enable session override (clobbering) | boolean | `false` |
| `--shutdown-timeout` | Timeout (in milliseconds) for waiting on all active connections to close, when shutting down the server | number | `5000` |
| `--ssl-cert-path` | Absolute path to the `.cert` file if TLS is used. Must be provided together with `--ssl-key-path`. See the [SSL/TLS/SPDY Support guide](../../guides/tls.md) for details. | string | |
| `--ssl-key-path` | Absolute path to the `.key` file if TLS is used. Must be provided together with `--ssl-cert-path`. See the [SSL/TLS/SPDY Support guide](../../guides/tls.md) for details. | string | |
| `--tmp` | Absolute path to the directory used for temporary files | string | [`os.tmpdir()`](https://nodejs.org/api/os.html#ostmpdir) |
| `--use-drivers` | List of drivers to activate. By default, all installed drivers are activated. | array<string> | `[]` |
| `--use-plugins` | List of plugins to activate. By default, no plugins are activated. Set to `["all"]` to activate all installed plugins. | array<string> | `[]` |
| `--webhook`, `-G` | URL for an HTTP listener where the server logs should be output. This does not affect output on the console. A bare `host:port` is also accepted, which posts the logs to the root path over plain http; a value having neither a scheme nor a port falls back to `127.0.0.1:9003`. | string | |
### Default Capabilities
Capabilities set with `--default-capabilities` are added to the received capabilities before a
driver is matched. This is Appium's own defaulting behavior, not something defined by the W3C
WebDriver specification.
- A value the client sends in `alwaysMatch`, or in a given `firstMatch` candidate, takes precedence
over the server default
- Defaults fill missing keys in each `firstMatch` candidate separately. A value in one candidate
does not stop the default from being applied to another candidate
- A key sent in both `alwaysMatch` and `firstMatch` is still rejected by the usual capability
validation. Server defaults do not change that
For example, with these server defaults:
```json
{"appium:newCommandTimeout": 60}
```
and these received capabilities:
```json
{
"alwaysMatch": {"appium:deviceName": "Pixel"},
"firstMatch": [
{"platformName": "iOS", "appium:newCommandTimeout": 120},
{"platformName": "Android"}
]
}
```
the iOS candidate keeps `appium:newCommandTimeout` of `120`, and the Android candidate gets the
default `60`. The session uses the value from whichever candidate it is created with.
### Info Options
@@ -33,7 +33,7 @@ appium setup browser
Installs the following extensions for desktop application testing:
- Drivers: `mac2`[^1], `windows`[^2]
- Drivers: `mac2`[^1], `wincore`[^2]
- Plugins: `images`, `inspector`
#### Usage
@@ -29,12 +29,11 @@ Appium sessions.
These capabilities are used in the Appium server/base driver, but are optional, and may have a
default value.
| <div style="width:19em">Capability</div> | Description | Type | Default |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `webSocketUrl` | Toggle support of the WebDriver BiDi protocol | `boolean` | |
| `appium:eventTimings` (deprecated) | Toggle collection of [Event Timings](../../guides/event-timing.md). This capability is deprecated - please use the [`getLogEvents`](../api/appium.md#getlogevents) endpoint instead. | `boolean` | |
| `appium:newCommandTimeout` | Number of seconds the Appium server should wait for clients to send commands before stopping the session. A value of `0` disables the timeout. | `number` | `60` |
| `appium:printPageSourceOnFindFailure` | Toggle retrieval of the page source and its printing to the Appium log, whenever a request to find an element fails | `boolean` | |
| <div style="width:19em">Capability</div> | Description | Type | Default |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- |
| `webSocketUrl` | Toggle support of the WebDriver BiDi protocol | `boolean` | |
| `appium:newCommandTimeout` | Number of seconds the Appium server should wait for clients to send commands before stopping the session. A value of `0` disables the timeout. | `number` | `60` |
| `appium:printPageSourceOnFindFailure` | Toggle retrieval of the page source and its printing to the Appium log, whenever a request to find an element fails | `boolean` | |
### Validated Capabilities
@@ -42,9 +41,9 @@ These capabilities are not directly used in the Appium server/base driver, but a
validation checks due to their relevance in other drivers. The actual handling of these
capabilities is optional and entirely driver-dependent.
| Capability | Validation |
| --------------------------------------------------- | ------------------------------------------------------------- |
| `platformVersion` | Must be `string` |
| `appium:app` | Must be `string`; empty values are ignored |
| `appium:fullReset` | Must be `boolean`; mutually exclusive with `appium:noReset` |
| `appium:noReset` | Must be `boolean`; mutually exclusive with `appium:fullReset` |
| Capability | Validation |
| ------------------------ | ------------------------------------------------------------- |
| `appium:platformVersion` | Must be `string` |
| `appium:app` | Must be `string`; empty values are ignored |
| `appium:fullReset` | Must be `boolean`; mutually exclusive with `appium:noReset` |
| `appium:noReset` | Must be `boolean`; mutually exclusive with `appium:fullReset` |
+2
View File
@@ -57,6 +57,7 @@ nav:
- reference/api/plugins.md
- ガイド:
- 移行:
- guides/migrating-3-to-4.md
- guides/migrating-2-to-3.md
- guides/migrating-1-to-2.md
- サーバ/ドライバの設定:
@@ -73,6 +74,7 @@ nav:
- guides/caps.md
- guides/settings.md
- guides/execute-methods.md
- guides/gestures.md
- guides/context.md
- guides/event-timing.md
- More Resources:
+2
View File
@@ -57,6 +57,7 @@ nav:
- reference/api/plugins.md
- 指南:
- 迁移:
- guides/migrating-3-to-4.md
- guides/migrating-2-to-3.md
- guides/migrating-1-to-2.md
- 服务器/驱动程序配置:
@@ -73,6 +74,7 @@ nav:
- guides/caps.md
- guides/settings.md
- guides/execute-methods.md
- guides/gestures.md
- guides/context.md
- guides/event-timing.md
- 更多资源:
@@ -169,12 +169,6 @@ async createSession(w3cCaps) {
}
```
!!! 警告 “已废弃”
```
较老的驱动可能仍以最多四个参数定义 createSession,例如createSession(jwpCaps, reqCaps, w3cCaps, otherDriverData)。这种形式是已退役的 JSON Wire Protocol 的遗留产物——它要求前两个参数是期望能力和必须能力,而实际上只有第一个W3C 形式的参数被使用过。otherDriverData 参数同样已被废弃,与其他并行运行会话的协调请改用IPC(见下文"向同一会话中的插件发送消息")。新驱动应使用上面所示的单参数形式。
```
你要确保调用 `super.createSession`,以拿到会话 ID 以及处理过的能力(注意:能力同时也被设置在`this.caps` 上;此处仅修改局部变量 `caps`,这只改变用户在创建会话响应中看到的内容,没有其他效果)。
就是这样!中间的空白部分由你的驱动所需的启动逻辑来填充。
@@ -608,6 +602,12 @@ A couple notes about this system:
mode!
3. The `executeMethod` helper will reject with an error if a script name doesn't match one of the
script names defined as a command in `executeMethodMap`, or if there are missing parameters.
4. If your driver is written in TypeScript, declare the map `as const satisfies
ExecuteMethodMap<MyDriver>` (with `ExecuteMethodMap` imported from `@appium/types`). The
compiler then checks that each `command` names a method of your driver, and that the
`required`/`optional` params are consistent with that method's signature: the method must not
require a parameter which is listed as `optional` (or not listed at all), and must accept all
of the listed parameters.
One of the nice things about the Execute Method strategy is that methods implemented in this way
will be available via the classic or BiDi interfaces (since they will result in the same Appium
@@ -674,6 +674,36 @@ this.eventEmitter.emit('bidiEvent', {
Now, if the client has subscribed to the `system.cpu` event, it will be notified with the load
whenever the driver emits it.
#### Slow clients and high-rate events
Appium does not buffer events indefinitely for a client that does not read them. A connection
that keeps more than `--bidi-max-buffered-bytes` unsent for longer than `--bidi-max-buffered-ms`
is closed with the code `1013`, and connections that do not answer WebSocket pings (see
`--bidi-heartbeat-interval`) are terminated. Both only affect the offending connection.
Drivers that emit events at a high rate (e.g. media streams) can let Appium skip events for a
connection that is falling behind, instead of waiting for it to be closed. Add a `delivery` hint
to the event (it is never sent to clients; older Appium versions ignore it):
```js
this.eventEmitter.emit('bidiEvent', {
method: 'appium:media.units',
params: {track: 'video', units},
delivery: {policy: 'droppable', chain: 'video', syncPoint: startsWithKeyframe},
})
```
- `policy`: `reliable` (default) events are always sent, `droppable` ones may be skipped.
- `chain`: events of the same chain depend on each other. After one is skipped for a connection,
the following ones are skipped for it too, until an event with `syncPoint: true` (e.g. a keyframe)
arrives and the connection has caught up. Every connection resynchronizes independently.
Subscriptions are per session, not per connection, so Appium decides by the state of each
connection's buffer. To react to dropped events (e.g. to request a keyframe or lower the bitrate),
listen to `bidiBackpressure` on the same emitter. Its payload is `{method, chain?, state, dropped}`,
where `state` is `dropping` once the first connection starts skipping events (and again whenever a
sync point is skipped, so that you can request a new one) and `recovered` once the last one stops, and `dropped` is the largest number of events skipped for a single connection.
### Make itself aware of resources other concurrent drivers are using
Let's say your driver uses up some system resources, like ports. There are a few ways to make sure
@@ -681,55 +711,35 @@ that multiple simultaneous sessions don't use the same resources:
1. Have your users specify resource IDs via capabilities (`appium:driverPort` etc)
2. Just always use free resources (find a new random port for each session)
3. Have each driver express what resources it is using, then examine currently-used resources from
other drivers when a new session begins.
3. Have each running instance of your driver publish and subscribe to messages on a shared IPC
channel, so sessions can coordinate directly with one another.
!!! warning "Deprecated"
```
The `driverData`-based mechanism described below is deprecated. Prefer
[IPC](#send-messages-to-plugins-running-on-the-same-session) for coordinating resources across
concurrently-running sessions instead.
```
To support this third strategy, you can implement `get driverData` in your driver to return what
sorts of resources your driver is currently using, for example:
```js
get driverData() {
return {specialPort: 1234, specialFile: /path/to/file}
}
```
Now, when a new session is started on your driver, the `driverData` response from any other
simultaneously running drivers (of the same type) will also be included, as the last parameter of
the deprecated, multi-argument form of the `createSession` method:
```js
async createSession(jwpCaps, reqCaps, w3cCaps, driverData)
```
You can dig into this `driverData` array to see what resources other drivers are using to help
determine which ones you want to use for this particular session.
The per-session IPC channel described in Send messages to plugins running on the same
session is isolated per session, so it
can't be used for this: it doesn't let you talk to _other_ sessions of your driver. Instead,
construct and hold on to your own `AppiumIpc` instance (exported from `appium/driver.js`) at
module scope in your driver's package, for example as a memoized singleton. Since Node.js caches
modules, every instance of your driver loaded within the same Appium server process will share
that one `AppiumIpc` object, and can use it to publish and subscribe to topics across sessions —
the same way the per-session channel works, just not scoped to a single session. See
[xcuitest-driver's `session-claim-handler.ts`](https://github.com/appium/appium-xcuitest-driver/blob/master/lib/session-claim-handler.ts)
for a real example, which uses this technique to detect and resolve conflicting sessions targeting
the same device UDID.
!!! warning
```
Be careful here, since `driverData` is only passed between sessions of a single running Appium
server. There's nothing to stop a user from running multiple Appium servers and requesting your
driver simultaneously on each of them. In this case, you won't be able to ensure independence
of resources via `driverData`, so you might consider using file-based locking mechanisms or
something similar.
This only works for sessions running within the same Node.js process (i.e. the same Appium
server). It cannot coordinate sessions running on different Appium server processes; for that,
consider file-based locking or a similar out-of-process mechanism.
```
!!! warning
```
It's also important to note you will only receive `driverData` for other instances of *your*
driver. So unrelated drivers also running may still be using some system resources. In general
Appium doesn't provide any features for ensuring unrelated drivers don't interfere with one
another, so it's up to the drivers to allow users to specify resource locations or addresses to
avoid clashes.
Appium also doesn't provide any features for ensuring unrelated drivers don't interfere with
one another, so it's up to the drivers to allow users to specify resource locations or
addresses to avoid clashes.
```
### Log events to the Appium event timeline
@@ -880,10 +890,15 @@ export type IpcMessage<T> = {
There are some important things to keep in mind when using Appium's IPC feature:
- IPC is only available once `onIpcInit` has been called, at the end of the `createSession` flow.
It cannot be used statically or in `createSession` hooks
- In sum, IPC is only for use during a session (this is also to prevent drivers/plugins from
accessing or reading data sent on IPC channels in other sessions.)
- The `ipcSubscribe` method (and the IPC channel it subscribes to) is only available once
`onIpcInit` has been called, at the end of the `createSession` flow. It cannot be used statically
or in `createSession` hooks
- The channel that `ipcSubscribe` gives you access to is scoped to the current session, and is
shared only with the plugins active in that same session (this is also to prevent drivers/plugins
from accessing or reading data sent on IPC channels in other sessions.) To coordinate across
multiple concurrent sessions of your own driver instead, see Make itself aware of resources
other concurrent drivers are
using.
- The default max size of an IPC message is 1MB. This can be configured by the server-admin by
using the `--max-ipc-data-size` arg (value is a number in bytes).
- If a message exceeds the configured size, any call to `publish` methods will throw, so be
@@ -190,7 +190,9 @@ throw new errors.NoSuchElementError();
### 向 Appium 日志写消息
你当然可以随时用 `console.log`,但 Appium 为你提供了一个更贴心的日志器 `this.logger`(它有 `.info`、`.debug`、`.log`、`.warn`、`.error` 等不同日志级别的方法)。如果你想在插件上下文之外(比如脚本或辅助文件中)创建 Appium 日志器,也可以自行构造:
You can always use `console.log`, of course, but Appium provides a nice logger for you as
`this.log` (it has `.info`, `.debug`, `.warn`, `.error` methods on it for differing log
levels). 如果你想在插件上下文之外(比如脚本或辅助文件中)创建 Appium 日志器,也可以自行构造:
```js
import {logging} from 'appium/support';
@@ -354,7 +356,7 @@ async execute(next, driver, script, args) {
You probably don't normally need to update the Appium server object (which is an
[Express](https://expressjs.com/) server having already been
[configured](https://github.com/appium/appium/blob/master/packages/base-driver/lib/express/server.ts)
[configured](https://github.com/appium/appium/blob/master/packages/http-server/lib/server.ts)
in a variety of ways). 但你可以为服务器添加新的路由来支撑你的插件的需求。要更新服务器,你必须在类中实现 `static async updateServer` 方法。该方法接收三个参数:
- `expressApp`:Express app 对象
@@ -32,4 +32,6 @@ Appium server 已经提供了一种通过 [过滤](../guides/log-filters.md) 来
格式化过程会通过标准的 Node.js [util.format](https://nodejs.org/api/util.html#utilformatformat-args) API 完成。
- 在发送相应的服务器请求时,如果这个日志行被使用并且应该被掩码处理,请额外添加自定义请求头 `X-Appium-Is-Sensitive`,其值为 `1` 或 `true`(大小写不敏感)。如果没有这个请求头,上述日志值将不会被掩码处理。这样就可以根据扩展处理的具体请求来有条件地屏蔽日志记录;如果日志表达式位于公共部分,就可以在这里统一控制。
- While sending the appropriate server request, where this log line is used and should be masked,
add the custom header `X-Appium-Is-Sensitive` with its value set to `1`, `true` or `yes` (case-insensitive).
如果没有这个请求头,上述日志值将不会被掩码处理。这样就可以根据扩展处理的具体请求来有条件地屏蔽日志记录;如果日志表达式位于公共部分,就可以在这里统一控制。
+18 -16
View File
@@ -71,20 +71,13 @@ appium driver install safari
appium driver install uiautomator2
```
### [Windows](https://github.com/appium/appium-windows-driver)
!!! warning
```
Only the Node.js-based driver part is maintained by the Appium team. The server part
(WinAppDriver executable) is provided by Microsoft, but has not been maintained since 2022.
```
### [WinCore](https://appium.github.io/appium-wincore-driver)
- Target: Windows applications
- Mode: Native
```sh title="Install This Driver"
appium driver install windows
appium driver install wincore
```
### [XCUITest](https://appium.github.io/appium-xcuitest-driver/)
@@ -161,13 +154,6 @@ appium driver install --source=npm @itsmeaj/appium-linux-driver
### [NovaWindows](https://github.com/AutomateThePlanet/appium-novawindows-driver)
!!! info
```
This driver is recommended as a drop-in replacement for the partially unmaintained
[Windows driver](#windows)
```
- Target: Windows applications
- Mode: Native, Hybrid
- Supported by: Community / Automate The Planet
@@ -212,6 +198,22 @@ npm install appium-tizen-driver
appium driver install --source=npm appium-tizen-tv-driver
```
### [Windows (legacy)](https://github.com/appium/appium-windows-driver)
!!! warning
```
This driver relies on WinAppDriver, which has not been maintained since 2022, and is only
compatible with Appium 1-3. Use the [WinCore](#wincore) driver with Appium 4 and newer.
```
- Target: Windows applications
- Mode: Native
```sh title="Install This Driver"
appium driver install --source=npm appium-windows-driver
```
### [You.i Engine](https://github.com/YOU-i-Labs/appium-youiengine-driver)
!!! warning
@@ -114,6 +114,20 @@ Supported by: `@AppiumTestDistribution`
npm install -g appium-installer
```
### [BenchFleet Appium](https://github.com/benchfleet/benchfleet-appium)
BenchFleet Appium is a command-line tool for running existing Appium tests on real Android phones
connected to a [BenchFleet](https://benchfleet.com) Hub, a desktop app for managing many phones
(Pro or Team plan). For each phone, the Hub starts an Appium server with the UiAutomator2 driver.
The tool then runs your test command once per phone with that server's URL in `APPIUM_URL`, and
collects each phone's JUnit report. iOS and BenchFleet's cloud phones are not supported yet.
Supported by: `@benchfleet`
```sh title="Install This Tool"
npm install -g benchfleet-appium
```
### [Optics](https://github.com/mozarkai/optics-framework)
Optics is an open-source test automation framework that uses Appium to drive Android, iOS,
+1 -1
View File
@@ -99,4 +99,4 @@ The above configuration corresponds to the `--driver-xcuitest-webkit-debug-proxy
All properties are case-sensitive and will be in
[kebab-case](https://en.wikipedia.org/wiki/Naming_convention_(programming)#Delimiter-separated_words).
For example, `callback-port` is allowed, but `callbackPort` is not.
For example, `base-path` is allowed, but `basePath` is not.
+343
View File
@@ -0,0 +1,343 @@
---
title: Automating Gestures
---
Appium supports automating complex pointer, touch, key, and wheel interactions through the
W3C WebDriver [Perform Actions](../reference/api/webdriver.md#performactions) API
([W3C Specification](https://w3c.github.io/webdriver/#actions)). Alternatively, many drivers provide
platform-native gesture [Execute Methods](./execute-methods.md) for common interactions.
In the W3C Actions API, interactions are defined by creating one or more virtual input sources
(such as `pointer` with `pointerType: "touch"`, `key`, `wheel`, or `none`) and queuing a sequence
of synchronized ticks (`pointerMove`, `pointerDown`, `pointerUp`, `pause`). See the
[Selenium Actions API documentation](https://www.selenium.dev/documentation/webdriver/actions_api/)
for a general overview of input sources and tick synchronization.
Below are examples of common single-finger and multi-touch gestures implemented using the W3C
Actions API across client languages.
## Double Tap
Performs two quick touch taps at `(x, y)` with a short pause between them:
=== "JS (WebDriverIO)"
```js
await driver
.action('pointer', {parameters: {pointerType: 'touch'}})
.move({x: 200, y: 300, duration: 0})
.down()
.up()
.pause(100)
.down()
.up()
.perform();
```
=== "Java"
```java
PointerInput finger = new PointerInput(PointerInput.Kind.TOUCH, "finger");
Sequence doubleTap = new Sequence(finger, 1)
.addAction(finger.createPointerMove(Duration.ZERO, PointerInput.Origin.viewport(), 200, 300))
.addAction(finger.createPointerDown(PointerInput.MouseButton.LEFT.asArg()))
.addAction(finger.createPointerUp(PointerInput.MouseButton.LEFT.asArg()))
.addAction(new Pause(finger, Duration.ofMillis(100)))
.addAction(finger.createPointerDown(PointerInput.MouseButton.LEFT.asArg()))
.addAction(finger.createPointerUp(PointerInput.MouseButton.LEFT.asArg()));
driver.perform(Collections.singletonList(doubleTap));
```
=== "Python"
```py
actions = ActionChains(driver)
actions.w3c_actions = ActionBuilder(driver, mouse=PointerInput(interaction.POINTER_TOUCH, "finger"))
actions.w3c_actions.pointer_action.move_to_location(200, 300)
actions.w3c_actions.pointer_action.pointer_down()
actions.w3c_actions.pointer_action.pointer_up()
actions.w3c_actions.pointer_action.pause(0.1)
actions.w3c_actions.pointer_action.pointer_down()
actions.w3c_actions.pointer_action.pointer_up()
actions.perform()
```
=== "Ruby"
```rb
f1 = driver.action.add_pointer_input(:touch, 'finger')
f1.create_pointer_move(duration: 0, x: 200, y: 300, origin: :viewport)
f1.create_pointer_down(:left)
f1.create_pointer_up(:left)
f1.create_pause(0.1)
f1.create_pointer_down(:left)
f1.create_pointer_up(:left)
driver.perform_actions([f1])
```
=== "C#"
```csharp
var finger = new PointerInputDevice(PointerKind.Touch, "finger");
var doubleTap = new ActionSequence(finger, 0);
doubleTap.AddAction(finger.CreatePointerMove(CoordinateOrigin.Viewport, 200, 300, TimeSpan.Zero));
doubleTap.AddAction(finger.CreatePointerDown(MouseButton.Touch));
doubleTap.AddAction(finger.CreatePointerUp(MouseButton.Touch));
doubleTap.AddAction(finger.CreatePause(TimeSpan.FromMilliseconds(100)));
doubleTap.AddAction(finger.CreatePointerDown(MouseButton.Touch));
doubleTap.AddAction(finger.CreatePointerUp(MouseButton.Touch));
driver.PerformActions(new List<ActionSequence> { doubleTap });
```
## Long Press
Presses and holds a touch pointer at `(x, y)` for 1000ms before releasing:
=== "JS (WebDriverIO)"
```js
await driver
.action('pointer', {parameters: {pointerType: 'touch'}})
.move({x: 200, y: 300, duration: 0})
.down()
.pause(1000)
.up()
.perform();
```
=== "Java"
```java
PointerInput finger = new PointerInput(PointerInput.Kind.TOUCH, "finger");
Sequence longPress = new Sequence(finger, 1)
.addAction(finger.createPointerMove(Duration.ZERO, PointerInput.Origin.viewport(), 200, 300))
.addAction(finger.createPointerDown(PointerInput.MouseButton.LEFT.asArg()))
.addAction(new Pause(finger, Duration.ofMillis(1000)))
.addAction(finger.createPointerUp(PointerInput.MouseButton.LEFT.asArg()));
driver.perform(Collections.singletonList(longPress));
```
=== "Python"
```py
actions = ActionChains(driver)
actions.w3c_actions = ActionBuilder(driver, mouse=PointerInput(interaction.POINTER_TOUCH, "finger"))
actions.w3c_actions.pointer_action.move_to_location(200, 300)
actions.w3c_actions.pointer_action.pointer_down()
actions.w3c_actions.pointer_action.pause(1.0)
actions.w3c_actions.pointer_action.pointer_up()
actions.perform()
```
=== "Ruby"
```rb
f1 = driver.action.add_pointer_input(:touch, 'finger')
f1.create_pointer_move(duration: 0, x: 200, y: 300, origin: :viewport)
f1.create_pointer_down(:left)
f1.create_pause(1.0)
f1.create_pointer_up(:left)
driver.perform_actions([f1])
```
=== "C#"
```csharp
var finger = new PointerInputDevice(PointerKind.Touch, "finger");
var longPress = new ActionSequence(finger, 0);
longPress.AddAction(finger.CreatePointerMove(CoordinateOrigin.Viewport, 200, 300, TimeSpan.Zero));
longPress.AddAction(finger.CreatePointerDown(MouseButton.Touch));
longPress.AddAction(finger.CreatePause(TimeSpan.FromMilliseconds(1000)));
longPress.AddAction(finger.CreatePointerUp(MouseButton.Touch));
driver.PerformActions(new List<ActionSequence> { longPress });
```
## Drag and Drop / Swipe
Moves a touch pointer from `(200, 600)` to `(200, 200)` over 600ms:
=== "JS (WebDriverIO)"
```js
await driver
.action('pointer', {parameters: {pointerType: 'touch'}})
.move({x: 200, y: 600, duration: 0})
.down()
.pause(100)
.move({x: 200, y: 200, duration: 600})
.up()
.perform();
```
=== "Java"
```java
PointerInput finger = new PointerInput(PointerInput.Kind.TOUCH, "finger");
Sequence dragAndDrop = new Sequence(finger, 1)
.addAction(finger.createPointerMove(Duration.ZERO, PointerInput.Origin.viewport(), 200, 600))
.addAction(finger.createPointerDown(PointerInput.MouseButton.LEFT.asArg()))
.addAction(new Pause(finger, Duration.ofMillis(100)))
.addAction(finger.createPointerMove(Duration.ofMillis(600), PointerInput.Origin.viewport(), 200, 200))
.addAction(finger.createPointerUp(PointerInput.MouseButton.LEFT.asArg()));
driver.perform(Collections.singletonList(dragAndDrop));
```
=== "Python"
```py
actions = ActionChains(driver)
actions.w3c_actions = ActionBuilder(driver, mouse=PointerInput(interaction.POINTER_TOUCH, "finger"))
actions.w3c_actions.pointer_action.move_to_location(200, 600)
actions.w3c_actions.pointer_action.pointer_down()
actions.w3c_actions.pointer_action.pause(0.1)
actions.w3c_actions.pointer_action.move_to_location(200, 200)
actions.w3c_actions.pointer_action.pointer_up()
actions.perform()
```
=== "Ruby"
```rb
f1 = driver.action.add_pointer_input(:touch, 'finger')
f1.create_pointer_move(duration: 0, x: 200, y: 600, origin: :viewport)
f1.create_pointer_down(:left)
f1.create_pause(0.1)
f1.create_pointer_move(duration: 0.6, x: 200, y: 200, origin: :viewport)
f1.create_pointer_up(:left)
driver.perform_actions([f1])
```
=== "C#"
```csharp
var finger = new PointerInputDevice(PointerKind.Touch, "finger");
var dragAndDrop = new ActionSequence(finger, 0);
dragAndDrop.AddAction(finger.CreatePointerMove(CoordinateOrigin.Viewport, 200, 600, TimeSpan.Zero));
dragAndDrop.AddAction(finger.CreatePointerDown(MouseButton.Touch));
dragAndDrop.AddAction(finger.CreatePause(TimeSpan.FromMilliseconds(100)));
dragAndDrop.AddAction(finger.CreatePointerMove(CoordinateOrigin.Viewport, 200, 200, TimeSpan.FromMilliseconds(600)));
dragAndDrop.AddAction(finger.CreatePointerUp(MouseButton.Touch));
driver.PerformActions(new List<ActionSequence> { dragAndDrop });
```
## Pinch and Zoom (Multi-Touch)
Uses two concurrent `touch` pointer sequences (`finger1` and `finger2`) moving apart to zoom in (or toward each other to pinch):
=== "JS (WebDriverIO)"
```js
await driver.performActions([
{
type: 'pointer',
id: 'finger1',
parameters: {pointerType: 'touch'},
actions: [
{type: 'pointerMove', duration: 0, x: 200, y: 400},
{type: 'pointerDown', button: 0},
{type: 'pause', duration: 100},
{type: 'pointerMove', duration: 500, x: 200, y: 200},
{type: 'pointerUp', button: 0},
],
},
{
type: 'pointer',
id: 'finger2',
parameters: {pointerType: 'touch'},
actions: [
{type: 'pointerMove', duration: 0, x: 200, y: 450},
{type: 'pointerDown', button: 0},
{type: 'pause', duration: 100},
{type: 'pointerMove', duration: 500, x: 200, y: 650},
{type: 'pointerUp', button: 0},
],
},
]);
```
=== "Java"
```java
PointerInput finger1 = new PointerInput(PointerInput.Kind.TOUCH, "finger1");
Sequence seq1 = new Sequence(finger1, 1)
.addAction(finger1.createPointerMove(Duration.ZERO, PointerInput.Origin.viewport(), 200, 400))
.addAction(finger1.createPointerDown(PointerInput.MouseButton.LEFT.asArg()))
.addAction(new Pause(finger1, Duration.ofMillis(100)))
.addAction(finger1.createPointerMove(Duration.ofMillis(500), PointerInput.Origin.viewport(), 200, 200))
.addAction(finger1.createPointerUp(PointerInput.MouseButton.LEFT.asArg()));
PointerInput finger2 = new PointerInput(PointerInput.Kind.TOUCH, "finger2");
Sequence seq2 = new Sequence(finger2, 1)
.addAction(finger2.createPointerMove(Duration.ZERO, PointerInput.Origin.viewport(), 200, 450))
.addAction(finger2.createPointerDown(PointerInput.MouseButton.LEFT.asArg()))
.addAction(new Pause(finger2, Duration.ofMillis(100)))
.addAction(finger2.createPointerMove(Duration.ofMillis(500), PointerInput.Origin.viewport(), 200, 650))
.addAction(finger2.createPointerUp(PointerInput.MouseButton.LEFT.asArg()));
driver.perform(Arrays.asList(seq1, seq2));
```
=== "Python"
```py
action_builder = ActionBuilder(driver)
finger1 = action_builder.add_pointer_input(interaction.POINTER_TOUCH, "finger1")
finger2 = action_builder.add_pointer_input(interaction.POINTER_TOUCH, "finger2")
finger1.create_pointer_move(duration=0, x=200, y=400)
finger1.create_pointer_down(button=MouseButton.LEFT)
finger1.create_pause(0.1)
finger1.create_pointer_move(duration=500, x=200, y=200)
finger1.create_pointer_up(button=MouseButton.LEFT)
finger2.create_pointer_move(duration=0, x=200, y=450)
finger2.create_pointer_down(button=MouseButton.LEFT)
finger2.create_pause(0.1)
finger2.create_pointer_move(duration=500, x=200, y=650)
finger2.create_pointer_up(button=MouseButton.LEFT)
action_builder.perform()
```
=== "Ruby"
```rb
f1 = driver.action.add_pointer_input(:touch, 'finger1')
f1.create_pointer_move(duration: 0, x: 200, y: 400, origin: :viewport)
f1.create_pointer_down(:left)
f1.create_pause(0.1)
f1.create_pointer_move(duration: 0.5, x: 200, y: 200, origin: :viewport)
f1.create_pointer_up(:left)
f2 = driver.action.add_pointer_input(:touch, 'finger2')
f2.create_pointer_move(duration: 0, x: 200, y: 450, origin: :viewport)
f2.create_pointer_down(:left)
f2.create_pause(0.1)
f2.create_pointer_move(duration: 0.5, x: 200, y: 650, origin: :viewport)
f2.create_pointer_up(:left)
driver.perform_actions([f1, f2])
```
=== "C#"
```csharp
var finger1 = new PointerInputDevice(PointerKind.Touch, "finger1");
var seq1 = new ActionSequence(finger1, 0);
seq1.AddAction(finger1.CreatePointerMove(CoordinateOrigin.Viewport, 200, 400, TimeSpan.Zero));
seq1.AddAction(finger1.CreatePointerDown(MouseButton.Touch));
seq1.AddAction(finger1.CreatePause(TimeSpan.FromMilliseconds(100)));
seq1.AddAction(finger1.CreatePointerMove(CoordinateOrigin.Viewport, 200, 200, TimeSpan.FromMilliseconds(500)));
seq1.AddAction(finger1.CreatePointerUp(MouseButton.Touch));
var finger2 = new PointerInputDevice(PointerKind.Touch, "finger2");
var seq2 = new ActionSequence(finger2, 0);
seq2.AddAction(finger2.CreatePointerMove(CoordinateOrigin.Viewport, 200, 450, TimeSpan.Zero));
seq2.AddAction(finger2.CreatePointerDown(MouseButton.Touch));
seq2.AddAction(finger2.CreatePause(TimeSpan.FromMilliseconds(100)));
seq2.AddAction(finger2.CreatePointerMove(CoordinateOrigin.Viewport, 200, 650, TimeSpan.FromMilliseconds(500)));
seq2.AddAction(finger2.CreatePointerUp(MouseButton.Touch));
driver.PerformActions(new List<ActionSequence> { seq1, seq2 });
```
-59
View File
@@ -117,62 +117,3 @@ hub, you'll be able to send all your Appium traffic via the single hub endpoint
And of course, you're able to link up Appium servers and nodes running on different machines in
your network to form a larger grid.
## Using Selenium Grid 3
It is possible to register your Appium server with a local [Selenium Grid 3](https://www.selenium.dev/documentation/legacy/selenium_3/grid_3/)
([setup docs](https://www.selenium.dev/documentation/legacy/grid_3/setting_up_your_own_grid/)) instance by using the
`--nodeconfig` server argument.
```bash
appium server --nodeconfig /path/to/nodeconfig.json --base-path=/wd/hub
```
In the referenced config file you have to define the `browserName`, `version` and `platform`
capabilities and based on these parameters the grid will re-direct your test to the right device.
You will also need to configure your host details and the Selenium Grid details. For a full list of
all parameters and descriptions see
[here](https://www.selenium.dev/documentation/legacy/selenium_3/grid_setup/).
Once you start the Appium server it will register with the grid, and you will see your device on
the grid console page:
`http://**\<grid-ip-address\>**:**\<grid-port\>**/grid/console`
### Example Grid Node Configuration JSON
```json
{
"capabilities":
[
{
"browserName": "<e.g._iPhone5_or_iPad4>",
"version":"<version_of_iOS_e.g._7.1>",
"maxInstances": 1,
"platform":"<platform_e.g._MAC_or_ANDROID>"
}
],
"configuration":
{
"cleanUpCycle":2000,
"timeout":30000,
"proxy": "org.openqa.grid.selenium.proxy.DefaultRemoteProxy",
"url":"http://<host_name_appium_server_or_ip-address_appium_server>:<appium_port>/wd/hub",
"host": "<host_name_appium_server_or_ip-address_appium_server>",
"port": <appium_port>,
"maxSession": 1,
"register": true,
"registerCycle": 5000,
"hubPort": <grid_port>,
"hubHost": "<Grid_host_name_or_grid_ip-address>",
"hubProtocol": "<Protocol_of_Grid_defaults_to_http>"
}
}
```
If `url`, `host`, and `port` are not given, the config will be auto updated to point to
`localhost:<appium-port>`.
If your Appium server is running on a different machine to your Selenium Grid server, make sure you
use an external name/IP address in your `host` and `url` configuration; `localhost` and `127.0.0.1`
will prevent Selenium Grid from connecting correctly.
@@ -31,12 +31,6 @@ installing it only installs the core Appium server, without any drivers.
When it comes to installing Appium 2 drivers, there are several approaches you can take:
- Add the `--drivers` flag when installing Appium, for example:
```bash
npm i -g appium --drivers=xcuitest,uiautomator2
```
- Use the [Appium Extension CLI](../reference/cli/extensions.md), for example:
```bash
@@ -227,8 +221,12 @@ and [Mobile JSON Wire Protocol](https://github.com/SeleniumHQ/mobile-spec/blob/m
(MJSONWP) were used instead.
In Appium 1, all of these protocols were supported, so that older Selenium/Appium clients could
still communicate with newer Appium servers. Appium 2 removes support for JSONWP/MJSONWP and is now
only compatible with the W3C WebDriver Protocol.
still communicate with newer Appium servers. Appium 2 removes support for JSONWP/MJSONWP (including
legacy `TouchAction` and `MultiAction` endpoints) and is now only compatible with the W3C WebDriver
Protocol. Multi-touch and pointer gestures should be performed using the W3C
[Perform Actions](../reference/api/webdriver.md#performactions) API (see the
[Automating Gestures](./gestures.md) guide) or driver-specific
[Execute Methods](./execute-methods.md).
!!! info "Actions Needed"
@@ -0,0 +1,649 @@
---
title: Migrating to Appium 4
---
This document is a guide for those who are using Appium 3 and would like to upgrade to Appium 4.
It contains a list of breaking changes (including behavioral fixes), as well as suggestions for
handling them.
Appium 3 was largely focused on cleaning up old endpoints, whereas Appium 4 includes a wider range
of changes, including closer alignment to W3C WebDriver protocol requirements, removal of
deprecated items not limited to endpoints, and general modernizing of the codebase.
## Installation
The installation method for Appium 4 remains the same as for Appium 3. If you want to upgrade, you
can simply install Appium 4 on top of your existing installation:
```bash
# optional: `appium setup reset`
npm install -g appium
```
## Breaking Changes
### Node 22.22+ Required
Appium 3 required a Node.js version in the range `^20.19.0 || ^22.12.0 || >=24.0.0`. Appium 4 drops
Node 20 and bumps the required range to `^22.22.2 || ^24.15.0 || >=26.0.0`. The minimum `npm`
version remains unchanged.
!!! info "Actions Needed"
Upgrade Node.js to `v22.22.2` or newer
### ESM-Only
Every package in the Appium monorepo (`appium` and its dependents) is now published as ESM-only,
with no CommonJS build. `require()` no longer works for these packages.
!!! info "Actions Needed"
Import Appium packages using ESM `import` syntax, or use dynamic `import()` from CommonJS code
### JSONWP/MJSONWP Internals Removed
The release of Appium 2 removed general support for the obsolete JSONWP and MJSONWP protocols,
though some Appium-related packages using JSONWP/MJSONWP under the hood could still continue to
function.
Appium 4 removes most of the remaining internal code that supported these protocols, which means
that drivers that still relied on these protocols are no longer compatible with Appium 4. Most
notably, this includes the Windows driver ([see dedicated section below](#windows-driver-replaced-by-wincore-driver)). All other official drivers rely on the W3C protocol and are not affected by this change.
Despite this, Appium 4 does retain temporary support for a select few JSONWP/MJSONWP endpoints (see
[Deprecated Endpoints Removed](#deprecated-endpoints-removed)).
For extension developers, a more detailed breakdown is available in the Developer-Facing Changes
section below.
!!! info "Actions Needed"
Migrate to drivers that support the W3C WebDriver protocol
### Windows Driver Replaced by WinCore Driver
As part of [dropping support for the deprecated JSONWP and MJSONWP protocols](#jsonwpmjsonwp-support-fully-removed),
Appium 4 is no longer compatible with the Windows driver ([`appium-windows-driver`](https://github.com/appium/appium-windows-driver)),
since the driver cannot support the standard W3C WebDriver protocol. As a result, the
`appium driver install windows` CLI command also no longer works.
Its official replacement is the WinCore driver ([`appium-wincore-driver`](https://github.com/appium/appium-wincore-driver)),
which can be installed using the new `appium driver install wincore` command. Since the WinCore
driver is also compatible with Appium 3, you can safely migrate from the Windows driver while
remaining on Appium 3 - though note that the installation shortcut is only available since Appium 4.
!!! info "Actions Needed"
If you currently use the Windows driver with Appium 3, you can migrate as follows:
1. Install `appium-wincore-driver` v3: `appium driver install --source=npm appium-wincore-driver@3`
2. Migrate your tests to use the WinCore driver
3. Uninstall the Windows driver: `appium driver uninstall windows`
4. Upgrade to Appium 4
5. Update the WinCore driver to its Appium 4 version: `appium driver update wincore --unsafe`
### Deprecated Endpoints Removed
Similarly to Appium 3, Appium 4 also removes several previously deprecated server endpoints, all of
which belong to the obsolete JSONWP/MJSONWP protocols. Compared to Appium 3, this cleanup is much
smaller (12 removed endpoints total, compared to 98 for Appium 3).
All removed endpoints are listed below, along with their replacement endpoints or driver-specific
execute methods:
- `GET /session/:sessionId`
- :octicons-arrow-right-24: [`GET /session/:sessionId/appium/capabilities`](../reference/api/appium.md#getappiumsessioncapabilities) (for capabilities)
- :octicons-arrow-right-24: [`GET /session/:sessionId/appium/events`](../reference/api/appium.md#getlogevents) (for event timings)
- `POST /session/:sessionId/ime/activate`
- :octicons-check-24: Moved to [UiAutomator2](https://appium.github.io/appium-uiautomator2-driver/)/[Espresso](https://appium.github.io/appium-espresso-driver/) drivers
- `GET /session/:sessionId/ime/activated`
- :octicons-check-24: Moved to UiAutomator2/Espresso drivers
- `GET /session/:sessionId/ime/active_engine`
- :octicons-check-24: Moved to UiAutomator2/Espresso drivers
- `GET /session/:sessionId/ime/available_engines`
- :octicons-check-24: Moved to UiAutomator2/Espresso drivers
- `POST /session/:sessionId/ime/deactivate`
- :octicons-check-24: Moved to UiAutomator2/Espresso drivers
- `GET /session/:sessionId/location`
- :octicons-check-24: Moved to [XCUITest](https://appium.github.io/appium-xcuitest-driver/) driver
- :octicons-arrow-right-24: `mobile: getGeolocation` (UiAutomator2/Espresso drivers)
- :octicons-arrow-right-24: `mobile: getSimulatedLocation` (XCUITest driver)
- `POST /session/:sessionId/location`
- :octicons-check-24: Moved to UiAutomator2/Espresso/XCUITest drivers
- :octicons-arrow-right-24: `mobile: setGeolocation` (UiAutomator2/Espresso drivers)
- :octicons-arrow-right-24: `mobile: setSimulatedLocation` (XCUITest driver)
- `GET /session/:sessionId/network_connection`
- :octicons-check-24: Moved to UiAutomator2/Espresso drivers
- :octicons-arrow-right-24: `mobile: getConnectivity` (UiAutomator2/Espresso drivers)
- `POST /session/:sessionId/network_connection`
- :octicons-check-24: Moved to UiAutomator2/Espresso drivers
- :octicons-arrow-right-24: `mobile: setConnectivity` (UiAutomator2/Espresso drivers)
- `POST /session/:sessionId/receive_async_response`
- :octicons-arrow-right-24: [`POST /session/:sessionId/execute/async`](../reference/api/webdriver.md#executeasync)
- `GET /session/:sessionId/element/:elementId`
- :octicons-no-entry-24: JSONWP protocol command stub with no direct replacement
#### Remaining Deprecations
There are 7 more deprecated endpoints that are intentionally _not_ removed in Appium 4. They are
the last remaining JSONWP/MJSONWP endpoints supported by Appium, and are listed in the
[JSONWP](../reference/api/jsonwp.md) and [MJSONWP](../reference/api/mjsonwp.md) reference pages.
These endpoints are kept due to their common usage (for context management), and their deprecation
being somewhat recent. All of them are therefore planned to be removed in the next major Appium
version, in order to give users time to migrate to their replacements.
!!! info "Actions Needed"
Check your Appium client documentation for the affected methods, and adjust your code to use
their replacements
### `--allow-cors` Flag Renamed
In Appium 3, the `--allow-cors` server argument was the only feature flag not integrated with
Appium's default [insecure feature flag mechanism](./security.md). Appium 4 removes this argument
and replaces it with the `cors` insecure feature name. This means the feature can now be controlled
using the `--allow-insecure`, `--deny-insecure` and `--relaxed-security` flags.
Similarly to the `session_discovery` feature, the `cors` feature must also be prefixed with the
wildcard (`*`) symbol.
!!! info "Actions Needed"
Replace `--allow-cors` with `--allow-insecure=*:cors` or `--relaxed-security`
### Default Log Level Set to Info
The default logging level for server logs has been changed from `debug` to `info`. Debug-level
logging is very verbose and mostly only useful for troubleshooting.
!!! info "Actions Needed"
Pass `--log-level debug` explicitly if you rely on the previous verbosity
### CLI Command Output Streams Split
In Appium 3, all non-JSON output of Appium's CLI commands (`driver`/`plugin`/`setup`, but not
`server`) was written to `stderr`. Appium 4 now writes `log`/`ok`/`info`/`warn` level messages of
these commands to `stdout`, while `error` level output remains in `stderr`.
The log output of the server itself (the `server` command) is unaffected, since it already split
streams this way.
!!! info "Actions Needed"
If you use scripts that capture non-JSON output of `driver`/`plugin`/`setup` commands, make
sure they read from the correct stream
### SPDY/HTTP2 No Longer Supported
In Appium 3, the server could be launched with SSL/TLS, which enabled support for the SPDY and
HTTP/2 protocols. This functionality relied on the unmaintained `spdy` package. Appium 4 replaces
this package with Node's native `https` module, which only supports plain HTTPS (HTTP/1.1).
!!! info "Actions Needed"
Clients relying on SPDY or HTTP/2 multiplexing against Appium's TLS listener must switch to
plain HTTPS (HTTP/1.1) or use a proxy
### Selenium Grid 3 Support Removed
Support for Selenium Grid 3 hub has been removed, along with its `--nodeconfig` server
argument/config file property. Selenium Grid 4 remains supported.
!!! info "Actions Needed"
If you relied on Grid 3 registration, use the [Selenium Grid 4 relay feature](./grid.md) instead
### Post-Install Script Removed
Appium 2 and 3 supported a postinstall hook that allowed for installation of drivers/plugins
together with the Appium server itself:
```
npm install -g appium --drivers=... --plugins=...
```
Since postinstall hooks are a supply-chain security risk, and newer versions of `npm` disable them
by default, this hook has been removed in Appium 4.
!!! info "Actions Needed"
If you install drivers/plugins using the postinstall hook, migrate to Appium's
[`install`](../reference/cli/extensions.md#install) command, or declare extensions in your
project's `package.json` file
### Event Timings Capability Removed
In Appium 3, the `appium:eventTimings` capability could be set to `true` in order to include event
timing information in the response of the `GET /session/:sessionId` endpoint. Since Appium 4
removes this endpoint (see [Deprecated Endpoints Removed](#deprecated-endpoints-removed)), the
capability became obsolete, and has also been removed.
!!! info "Actions Needed"
Remove any instances of the `appium:eventTimings` capability, and instead use the [getLogEvents](../reference/api/appium.md#getlogevents) endpoint to retrieve event timings
### Unused Server Arguments Removed
The following server arguments have had no effect for a long time and have been removed, along with
their equivalents in the configuration file:
- `--callback-address` (`-ca`)
- `--callback-port` (`-cp`)
- `--debug-log-spacing`
- `--shell`
- `--strict-caps`
- `--trace-dir`
Passing any of them on the command line now fails with an unrecognized argument error (unless
[`--allow-unknown-args`](../reference/cli/server.md) is set), and config files containing them
fail schema validation.
!!! info "Actions Needed"
Remove these arguments from startup scripts and config files
## Behavior Fixes
This is a list of smaller changes that are positioned as fixes, rather than removal of existing
functionality, and may or may not be breaking depending on your usecase. The majority of changes
are related to alignment with the W3C WebDriver specification, and should not generally require
any user action.
### Session Lifecycle
- If a successfully created session fails initialization, Appium now attempts to delete the newly
created session and removes its registration while preserving the original initialization error
([#22873](https://github.com/appium/appium/pull/22873))
- The new command idle timeout (`appium:newCommandTimeout`) now only starts after finishing the
setup of initial settings and BiDi responses, preventing a session from expiring during
initialization ([#22881](https://github.com/appium/appium/pull/22881))
- If the new command idle timeout expires and the session deletion process starts, any driver
cleanup failures are now logged, instead of becoming an unhandled rejection that can terminate
the server and unrelated sessions ([#22964](https://github.com/appium/appium/pull/22964))
- Upon session deletion, any commands still waiting in the command queue are now rejected with HTTP
`404` / `invalid session id`, instead of remaining pending indefinitely
([#22874](https://github.com/appium/appium/pull/22874))
### Capabilities
- Names of standard WebDriver capabilities must now be case-sensitive (e.g. `platformName`, not
`PlatformName`). Handling of the _values_ of these capabilities, as well as names of prefixed
capabilities (e.g. `appium:app`), remains unchanged
([#22976](https://github.com/appium/appium/pull/22976))
- Malformed capability containers and parse failures now return HTTP `400` / `invalid argument`,
instead of HTTP `500` / `session not created`
([#22977](https://github.com/appium/appium/pull/22977))
- Top-level `null` capabilities are omitted before validation and merging, avoiding false
duplicate-key errors. Nested nulls, such as `timeouts: {script: null}`, are preserved
([#22975](https://github.com/appium/appium/pull/22975))
- Session settings provided inside `appium:options` are now honored
([#22882](https://github.com/appium/appium/pull/22882))
- The standard `timeouts` capability now correctly initializes BaseDriver's timeout state using
the same value checks as the [Set Timeouts](../reference/api/webdriver.md#timeouts) endpoint.
Backend handling remains driver-specific ([#22983](https://github.com/appium/appium/pull/22983))
- Setting both `appium:noReset` and `appium:fullReset` to `true` now returns HTTP `500` /
`session not created` instead of a generic error, and no longer leaves partially initialized
session state behind ([#22861](https://github.com/appium/appium/pull/22861),
[#22870](https://github.com/appium/appium/pull/22870))
- Setting `appium:newCommandTimeout` to `null`, a blank string, or a non-finite numeric value is
now ignored (keeping the default timeout value), instead of causing the timeout to be silently
disabled ([#22815](https://github.com/appium/appium/pull/22815),
[#23103](https://github.com/appium/appium/pull/23103)). Other invalid types, such as negative
numbers or nonnumeric strings, still fail capability validation
- Percent-encoded credentials in `appium:app` URLs are now decoded once before Basic authentication,
and complete HTTP-compressed downloads are no longer rejected if the decompressed file size
differs from `Content-Length` ([#22887](https://github.com/appium/appium/pull/22887),
[#22886](https://github.com/appium/appium/pull/22886))
- Setting `firstMatch` to an empty array (`[]`) is now rejected with HTTP `400` /
`invalid argument`, instead of being silently replaced with a single empty entry
([#22860](https://github.com/appium/appium/pull/22860))
- Every `firstMatch` candidate is now validated and merged before selection. Invalid supplied values
or duplicate keys in any candidate reject the request, even if another candidate could match;
missing required driver capabilities and unsupported platforms still allow matching to continue
([#22982](https://github.com/appium/appium/pull/22982))
- Default capabilities (which can be set using `--default-capabilities`) are now applied to each
individual `firstMatch` candidate separately. Values set in `alwaysMatch` or the current
candidate still take precedence ([#22988](https://github.com/appium/appium/pull/22988)). See
[Default Capabilities](../reference/cli/server.md#default-capabilities) for an example.
- Session settings are now applied from the selected `firstMatch` candidate, instead of potentially
being overridden by later unselected candidates. Defaults and `alwaysMatch` settings are still
applied first ([#22882](https://github.com/appium/appium/pull/22882))
- Values of the standard `timeouts` capability are now also validated in `alwaysMatch` and every
`firstMatch` candidate ([#23062](https://github.com/appium/appium/pull/23062)). A malformed
timeout object or invalid standard timeout value is rejected with HTTP `400` /
`invalid argument`, even if an earlier `firstMatch` candidate could match. Top-level
`timeouts: null` is still omitted, nested null timeout values are preserved, and unknown timeout
properties are ignored for validation
### HTTP Responses
- All WebDriver HTTP responses now include the `Cache-Control: no-cache` header. Caches must
revalidate these responses before reusing them
([#22971](https://github.com/appium/appium/pull/22971))
- Any WebDriver error `data` (e.g. alert text) is now preserved in driver and proxy responses
([#22974](https://github.com/appium/appium/pull/22974))
- The body of any `POST` command now has to be a JSON object; requests where the body is empty or
set to an empty JSON array (`[]`) return HTTP `400` with `invalid argument`
([#23007](https://github.com/appium/appium/pull/23007)). A value of `{}` is still accepted,
including commands that take no parameters. Routes that set `payloadParams.wrap` may still accept
an empty array
- `GET` requests to the server root route (e.g. `GET /` for a default server base path) now return
HTTP `404` / `unknown command`, instead of Express's HTML 404 page. Extensions can still register
their own root route ([#22969](https://github.com/appium/appium/pull/22969))
- `HEAD` requests to any `GET` command URL now return HTTP `405` without executing the `GET`
command. Custom server routes and `HEAD` request handlers retain their behavior
([#22992](https://github.com/appium/appium/pull/22992))
- Driver commands rejecting with `null` or `undefined` now return HTTP `500` / `unknown error`,
instead of causing the error handler itself to fail
([#22869](https://github.com/appium/appium/pull/22869))
- `TimeoutError` and `ScriptTimeoutError` now map to HTTP `500` instead of HTTP `408`
([#22686](https://github.com/appium/appium/pull/22686))
- A `detached shadow root` error is now preserved as HTTP `404`, instead of being converted to HTTP
`500` / `unknown error` ([#22968](https://github.com/appium/appium/pull/22968))
### Specific Endpoints
- [New Session](../reference/api/webdriver.md#createsession): now raises the `session not created`
error instead of `unknown error` if no installed driver matches the requested platform/automation
combination, or the matching driver cannot be loaded or does not export its class. Validation of
missing `platformName`/`appium:automationName` is unchanged
([#22970](https://github.com/appium/appium/pull/22970))
- [Get Timeouts](../reference/api/webdriver.md#gettimeouts): now returns `script` and `pageLoad` in
addition to the existing `implicit` and Appium-specific `command` values
([#22776](https://github.com/appium/appium/pull/22776))
- [Set Timeouts](../reference/api/webdriver.md#timeouts): `script`, `pageLoad`, and `implicit` now
only accept null or integer values; strings and fractions return HTTP `400` / `invalid argument`
([#22961](https://github.com/appium/appium/pull/22961))
- Set Timeouts: `null` values now correctly disable the specified timeout
([#22961](https://github.com/appium/appium/pull/22961))
- Set Timeouts: omitting `script`, `pageLoad`, or `implicit` no longer fails: omitted fields keep their
values and `{}` succeeds without changes. Invalid updates change no values
([#22960](https://github.com/appium/appium/pull/22960),
[#22961](https://github.com/appium/appium/pull/22961))
- Set Timeouts: unknown values for the legacy `type` argument now return HTTP `400` /
`invalid argument` instead of HTTP `500` / `unknown error`
([#22987](https://github.com/appium/appium/pull/22987))
- [getLog](../reference/api/others.md#getlog): unsupported `type` values now return HTTP `400` /
`invalid argument` instead of HTTP `500` / `unknown error`
([#22986](https://github.com/appium/appium/pull/22986))
### BiDi Protocol
- Subscriptions without `contexts` now receive events carrying a context, so that module
subscriptions such as `events: ["log"]` now match events such as `log.entryAdded`. Overlapping
subscriptions deliver each event only once ([#22883](https://github.com/appium/appium/pull/22883))
- The implementation of [`session.subscribe`](../reference/api/bidi.md#bidisubscribe) (which does
not yet support `userContexts`) now rejects `userContexts` with HTTP `500` /
`unsupported operation`, instead of silently creating an unscoped subscription. Malformed
`userContexts`, or supplying both `contexts` and `userContexts`, return HTTP `400` /
`invalid argument`. Drivers implementing user-context support can override `bidiSubscribe`
([#22877](https://github.com/appium/appium/pull/22877)).
- Any `sessionId` or `id` keys inside BiDi command parameters are now validated like any other
unknown parameter, instead of being silently accepted
([#22771](https://github.com/appium/appium/pull/22771))
### [Storage Plugin](https://github.com/appium/appium/tree/master/packages/storage-plugin)
- All [endpoints](../reference/api/plugins.md#storage-plugin) and stream/events WebSocket paths now
respect custom server `--base-path` values, instead of always being mounted at the server root
([#22906](https://github.com/appium/appium/pull/22906))
- File names starting with a dot or ending with `.filepart` are now rejected
([#22863](https://github.com/appium/appium/pull/22863),
[#22959](https://github.com/appium/appium/pull/22959))
- Concurrent WebSocket uploads of the same file are now rejected
([#22962](https://github.com/appium/appium/pull/22962))
- Pending upload WebSocket routes are now preserved across retries
([#22948](https://github.com/appium/appium/pull/22948))
- Errors on upload event sockets are now logged instead of potentially terminating the server
([#22963](https://github.com/appium/appium/pull/22963))
### Other Fixes
- The `appium driver`/`appium plugin` CLI commands now lock the extension manifest while running,
preventing any concurrent CLI commands from silently clobbering each other's changes
([#22767](https://github.com/appium/appium/pull/22767))
- IPv6 literals are now correctly bracketed during URL assembly, including BiDi WebSocket URLs and
[Execute Driver Plugin](https://github.com/appium/appium/tree/master/packages/execute-driver-plugin)
connections ([#22872](https://github.com/appium/appium/pull/22872),
[#22912](https://github.com/appium/appium/pull/22912),
[#22914](https://github.com/appium/appium/pull/22914))
## Developer-Facing Changes
The following changes primarily affect developers of Appium clients, drivers, plugins, or tools
that import Appium's internal packages directly. They do not affect most Appium end users.
### Extension Development
- When installing a locally available driver/plugin using Appium's CLI `install` command with the
`--source=local` flag, Appium now installs the extension directly from the supplied local
directory, without first creating an intermediate global `npm` link
([#23086](https://github.com/appium/appium/pull/23086)). Local installs still link to the source
directory, so source changes do not require reinstalling the extension. If you use tooling that
relies on the package being linked in `npm`'s global prefix, manage that global link separately.
- Extension manifests and `extensions.yaml` are now validated with `ajv`/JSON Schema; a corrupted
`extensions.yaml` now resets to an empty manifest with a warning, instead of crashing later with a
confusing error ([#22732](https://github.com/appium/appium/pull/22732))
- `ExecuteMethodMap` type declarations now check `params` against the target method's signature at
compile time, catching mismatched required/optional execute method parameters in driver code
([#22754](https://github.com/appium/appium/pull/22754))
- When a plugin intercepts a command that would otherwise be proxied downstream, Appium no longer
validates its fields or values ([#23060](https://github.com/appium/appium/pull/23060)). This
matches direct proxying, where the downstream remote end owns these checks. Plugins that
previously relied on Appium to validate these arguments can now receive missing or invalid
values (JSON-object request-body checks still remain in place before the plugin is called). If
your plugin handles such a command without calling `next()`, validate the inputs it uses.
Pass-through plugins can still call `next()` and delegate validation to the downstream remote end.
### `@appium/base-driver`
#### JSONWP/MJSONWP Removal
As listed [in the Breaking Changes section above](#jsonwpmjsonwp-internals-removed), the internal
code responsible for JSONWP/MJSONWP protocol support has been removed
([#22681](https://github.com/appium/appium/pull/22681)). This includes the following items:
- `ProtocolError` instances no longer carry a `jsonwpCode` property, and error responses no longer
include a legacy numeric `status` code (`errorFromMJSONWPStatusCode`, aliased as `errorFromCode`,
has been removed; use `errorFromW3CJsonCode`)
- Responses no longer duplicate element references under the legacy `ELEMENT` key; only the W3C
`element-6066-11e4-a52e-4f735466cecf` key is present
- `WebDriverProxy` (formerly `JWProxy`, now removed as a name) no longer converts responses from a
downstream automation server speaking legacy MJSONWP; downstream servers must speak W3C WebDriver
- `determineProtocol`, `DriverCore#setProtocolMJSONWP()`, and `DriverCore#isMjsonwpProtocol()` have
been removed; drivers can no longer produce the legacy `{sessionId, status, value}` response shape
- `statusCodes` and `getSummaryByCode` are no longer available (the `jsonwp-status` module has been
removed)
- A command result shaped like `{protocol, value}` is no longer unwrapped. It is sent to the
client as the command value, so a script returning `{protocol: 'W3C', value: 5}` gets that object
back. A result of `{protocol, error}` whose `protocol` is `W3C` or `MJSONWP` and whose `error`
is an `Error` is still thrown
#### HTTP Server Moved to Separate Package
The HTTP/Express server code has been extracted from `@appium/base-driver` into the new
`@appium/http-server` package ([#22800](https://github.com/appium/appium/pull/22800)). The
following items are therefore no longer exported from `@appium/base-driver` or `appium/driver.js`:
- Methods: `server`, `normalizeBasePath`, `configureServer`
- Types: `ServerOpts`, `ConfigureServerOpts`, `ConfigureHttpOpts`, `StartServerOpts`
If you use these items, import them from `@appium/http-server` instead.
#### Other Changes
- The default class export has been removed
([#22741](https://github.com/appium/appium/pull/22741)). Use the named `{BaseDriver}` export
instead
- The default export of `basedriver/helpers.js` has been removed
([#22741](https://github.com/appium/appium/pull/22741)). Use named exports instead
- `BaseDriver`'s constructor no longer takes command-mixin machinery into account
([#22741](https://github.com/appium/appium/pull/22741))
- `createSession()` no longer accepts the legacy multi-argument form
(`jwpCaps, reqCaps, w3cCaps`); only the single `w3cCapabilities` argument is supported now
([#22730](https://github.com/appium/appium/pull/22730))
- The deprecated `driverData` mechanism (`Core.driverData`, the `driverData` parameter on
`createSession`/`deleteSession`, and the `DriverData` type) has been removed
([#22716](https://github.com/appium/appium/pull/22716)). Migrate to `IAppiumIpc` instead
- The `server()` and `configureServer()` methods (now exported by `@appium/http-server`) now
default to `allowCors: false` ([#22990](https://github.com/appium/appium/pull/22990))
- Both `ipc.unsubscribe(topic, subscriber)` and `subscription.unsubscribe()` now finish waiting on
async iterators and notify observers once ([#22955](https://github.com/appium/appium/pull/22955)).
An observer that throws still propagates its error to the caller, but no longer prevents waiting
iterators from finishing
- The unused `reset()` method has been removed
([#22741](https://github.com/appium/appium/pull/22741))
- The `generateDriverLogPrefix()` helper no longer supports the deprecated `sessionId` argument
([#22764](https://github.com/appium/appium/pull/22764))
- The new command idle timeout now stays suspended through HTTP/BiDi plugin chains, including work
after `next()`, and while proxied BiDi commands await a response
([#22946](https://github.com/appium/appium/pull/22946),
[#22947](https://github.com/appium/appium/pull/22947)). Custom `startNewCommandTimeout`
implementations must delegate timer creation to `super.startNewCommandTimeout()` so they respect
shared activity, while custom command execution must delegate to `super.executeCommand()` or wrap
the full command in `runWithCommandTimeout`
- The `appium:autoLaunch`, `appium:locale`, `appium:language`, `appium:autoWebview`,
`appium:orientation`, and `appium:udid` capabilities are no longer validated as part of the
standard capability constraints ([#22950](https://github.com/appium/appium/pull/22950),
[#22952](https://github.com/appium/appium/pull/22952)). If you use them, declare them in your own
driver constraints
- The built-in test fixture routes (`/welcome`, `/test/guinea-pig*`, `/produce_error`, `/crash`),
the `STATIC_DIR` export, and the `APPIUM_ENABLE_LEGACY_TEST_PAGES` environment variable have been
removed ([#22680](https://github.com/appium/appium/pull/22680)). If you relied on these fixtures,
migrate to use your own local test server
### `@appium/base-plugin`
- The default class export has been removed ([#22718](https://github.com/appium/appium/pull/22718)).
Use the named `{BasePlugin}` export instead
- `Plugin#logger` has been removed in favor of `Plugin#log`
([#22718](https://github.com/appium/appium/pull/22718))
- `Plugin#name` and `Plugin#cliArgs` are now read-only
([#22718](https://github.com/appium/appium/pull/22718))
### `@appium/logger`
- The default class export has been removed ([#22719](https://github.com/appium/appium/pull/22719)).
Use the named `{log}` export instead
- The long-disabled, no-op progress/unicode methods (`enableProgress`, `disableProgress`,
`progressEnabled`, `enableUnicode`, `disableUnicode`) have been removed
([#22719](https://github.com/appium/appium/pull/22719))
### `@appium/support`
- `env`: the module has been integrated into the `appium` package as internal helpers
([#22708](https://github.com/appium/appium/pull/22708))
- `imageUtil`: the module has been removed ([#22678](https://github.com/appium/appium/pull/22678))
- `fs`: the following exports have been removed: `readPackageJsonFrom` and `findRoot` methods,
`F_OK`/`R_OK`/`W_OK`/`X_OK` constants, `CopyFileDescriptor` and `ReadFn` types
([#22678](https://github.com/appium/appium/pull/22678))
- `fs`: `glob()` now relies on Node's `fs.promises.glob` instead of the `glob` package, with a
narrower `GlobOptions` shape ([#22735](https://github.com/appium/appium/pull/22735))
- `fs`: `mv()` now preserves symlinks inside moved directories and moves source symlinks themselves
without moving their targets' contents. Dangling source links are supported, and Windows
case-only renames update the entry's spelling
([#22880](https://github.com/appium/appium/pull/22880),
[#22954](https://github.com/appium/appium/pull/22954),
[#22958](https://github.com/appium/appium/pull/22958))
- `fs`: `walkDir()` now continues after walker errors such as `EACCES` and `ELOOP` instead of
hanging. These errors are logged and affected entries are skipped; `ENOENT` still rejects the
returned promise ([#22956](https://github.com/appium/appium/pull/22956))
- `fs`: `write()` now relies on Node's `promisify`, which resolves to an object
(`{bytesWritten, buffer}`), instead of only `bytesWritten`
([#22704](https://github.com/appium/appium/pull/22704))
- `logger`: the default export has been removed. Use the named `{log}` export instead
([#22719](https://github.com/appium/appium/pull/22719))
- `logger`: `errorAndThrow` has been removed in favor of `errorWithException`
([#22719](https://github.com/appium/appium/pull/22719))
- `net`: support for FTP-based file uploads has been removed, along with the `FtpUploadOptions` and
`NotHttpUploadOptions` types ([#22678](https://github.com/appium/appium/pull/22678))
- `net`: the new `checkPortStatus()` and `getFreePort()` helpers replace the `portscanner` package
and custom free port lookups in drivers and plugins
([#23156](https://github.com/appium/appium/pull/23156)). Unlike `portscanner`, they accept an
options object instead of positional arguments. `getFreePort()` also covers `findAPortNotInUse()`:
pass `port` (a single port or a `[startPort, endPort]` range) to probe specific ports, in which
case it throws `NoFreePortError` if all of them are busy instead of resolving with `false`
- `mjpeg`: the module has been removed ([#22678](https://github.com/appium/appium/pull/22678))
- `mkdirp`: the module has been removed ([#22678](https://github.com/appium/appium/pull/22678)).
Import `mkdirp()` from the `fs` module instead
- `node`: `requirePackage()` has been removed
([#22684](https://github.com/appium/appium/pull/22684))
- `npm`: the module has been integrated into the `appium` package as internal helpers
([#22721](https://github.com/appium/appium/pull/22721))
- `process`: the module has been removed ([#22678](https://github.com/appium/appium/pull/22678))
- `system`: `macOsxVersion()` has been removed
([#22684](https://github.com/appium/appium/pull/22684))
- `util`: the following methods have been removed: `uuidV1`, `uuidV3`, `uuidV5`, `localIp`,
`cancellableDelay`, and `multiResolve` ([#22678](https://github.com/appium/appium/pull/22678))
- `zip`: `extractAllTo()` always uses the built-in JS extractor now, so the `useSystemUnzip` option
has been removed ([#23091](https://github.com/appium/appium/pull/23091)). The extractor supports
only stored and deflate entries and verifies the CRC32 of every entry. File names that are not
flagged as UTF-8 by the archive are decoded as `utf8` by default, and the legacy `cp437` decoding
is no longer supported. Other single-byte encodings supported by Node.js can be selected via
`fileNamesEncoding`. Archives with encrypted entries or other compression methods are rejected
with `ZipStreamUnsupportedError`
### `@appium/tsconfig`
- `noImplicitOverride` is now set to `true`, which means that TypeScript drivers and plugins that
extend the config must mark every member overriding a base class member (e.g. `BaseDriver` or
`BasePlugin` methods, and `static` fields such as `newMethodMap`) with the `override` modifier
([#23143](https://github.com/appium/appium/pull/23143)). Opt-out is also possible by setting
`noImplicitOverride` to `false` in your own `tsconfig.json`.
### Client Development
- State-changing HTTP requests with an `Origin` header now return HTTP `403`, unless the CORS
insecure feature is enabled on the Appium server
([#23102](https://github.com/appium/appium/pull/23102)). Remove the `Origin` header or instruct
users to enable CORS.
## New Features
### App URL Rules
The new `--app-url-rules` server CLI flag (and its equivalent configuration file property) allows
server hosts to restrict the host/IP values allowed in capabilities like `appium:app`. Configurable
properties include allow/deny lists, HTTPS-only, credentials, and redirect limits.
Refer to [the Security guide](./security.md#restricting-remote-app-urls) for more details.
### CLI Update Command Checks Server Requirement
As a follow-up to Appium 3.9, which changed the default behavior of the Appium CLI
[`install`](../reference/cli/extensions.md#install) command to install the newest extension version
that is compatible with the current server (as opposed to throwing an error if the server
requirement of the latest extension version is incompatible), Appium 4 adjusts the
[`update`](../reference/cli/extensions.md#update) command to now implement this behavior as well.
This makes default usage of both `install` and `update` safe even when future major extension
versions raise their server requirements.
### Commands Can Bypass Queue
Driver commands (endpoints) are now allowed to bypass the default command queue, which enables the
command to execute while another long-running command is in progress.
By default, only the standard [Status](../reference/api/webdriver.md#getstatus) endpoint is exempt
from the queue, but driver developers can also customize the list of exempt commands by overriding
the `queueExemptCommands` getter.
The behavior of the idle timer (set by `appium:newCommandTimeout`) has also been adjusted to only
reset once no commands are executing.
### New Set Timeouts Parameter
The standard [Set Timeouts](../reference/api/webdriver.md#timeouts) endpoint has been extended to
additionally accept the Appium-specific `command` parameter. This aligns its handling with
[Get Timeouts](../reference/api/webdriver.md#gettimeouts), which already returned this parameter.
The parameter itself is mapped to the `appium:newCommandTimeout` capability.
The non-standard `type`/`ms` parameters, which were previously the only way to change this timeout
mid-session, have been deprecated as a result.
### Universal XML Plugin Can Be Toggled
The [Universal XML plugin](https://github.com/appium/appium/tree/master/packages/universal-xml-plugin)
now provides the [`universalXml: setEnabled` and `universalXml: isEnabled` execute methods](../reference/api/plugins.md#universal-xml-plugin),
which allow toggling the translation during a session, e.g. to retrieve the original page source.
+123
View File
@@ -37,6 +37,10 @@ sessions the feature should apply. The prefix can be either the driver's `automa
wildcard (`*`) symbol, if the feature should be applied to all drivers. The prefix and feature name
are separated using the colon character (`:`).
Use the driver's `automationName`, which may differ from its install name. An install-name-only
prefix does not enable or disable a feature. When configuring a session, Appium warns about such
entries for that driver unless the prefix is another installed driver's `automationName`.
For example, `first:foo` refers to the `foo` feature for the `first` driver, whereas `*:bar` refers
to the `bar` feature for all drivers.
@@ -87,3 +91,122 @@ Turn on multiple insecure features for specific drivers:
```bash
appium --allow-insecure=uiautomator2:adb_shell,xcuitest:get_server_logs
```
## Restricting Remote App URLs
Several drivers accept a URL instead of a local path in capabilities such as `appium:app`, in which
case the Appium server downloads the application package from that URL before starting the session.
By default, any `http:` or `https:` URL is accepted. Server hosts who want to control which URLs
their server is allowed to download from can do so with the `--app-url-rules` argument (or the
`server.app-url-rules` property in a [configuration file](./config.md)). Its value is a JSON object
(or a path to a JSON file) with any of the following properties:
| <div style="width:10em">Rule</div> | Description | Default |
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `allow` | List of hostname patterns, IP addresses, or CIDR subnets. If non-empty, a hostname or its resolved address must match _at least one_ | `[]` |
| `deny` | List of hostname patterns, IP addresses, or CIDR subnets. A matching hostname or resolved address is rejected, even if an `allow` rule also matches | `[]` |
| `httpsOnly` | Only accept `https:` URLs | `false` |
| `allowCredentials` | Accept URLs containing a username and/or password (e.g. `https://user:pass@host/app.apk`) | `true` |
| `maxRedirects` | Maximum number of HTTP redirects to follow while downloading. Set to `0` to reject any redirect | `21` |
Hostnames are normalized (lowercased, converted to Punycode, trailing dot removed) before matching
and resolved on every download. Address rules apply to literal addresses and all dynamically
resolved IPv4/IPv6 addresses. The rules are also applied to every redirect, so redirects cannot be
used to escape them. If a URL violates any rule, the session is not created and a generic error
is returned. The violated rule is deliberately neither reported to the client nor written to the
server log, since server logs are often handed over to clients as well. URL schemes, ports, paths,
queries, and fragments are not matched.
Hostname patterns use the [picomatch](https://github.com/micromatch/picomatch#globbing-features)
glob syntax and are matched against the whole hostname:
| Pattern | Matches |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `artifacts.example.com` | Exactly this hostname |
| `*.example.com` | Any subdomain of `example.com` (including nested ones, like `a.b.example.com`), but not `example.com` itself |
| `*example.com` | Any hostname ending with `example.com`, including `example.com` itself |
| `apps.{staging,prod}.example.com` | `apps.staging.example.com` and `apps.prod.example.com` |
| `build-?.example.com` | `build-1.example.com`, `build-a.example.com`, etc. |
| `node[0-9].example.com` | `node0.example.com` to `node9.example.com` |
IP address rules match a single address (`192.0.2.10`, `2001:db8::1`) or a whole subnet in CIDR
notation (`10.0.0.0/8`, `2001:db8::/32`). IPv4 rules also match IPv4-mapped IPv6 addresses
(e.g. `::ffff:10.1.2.3`).
!!! note
```
These rules only apply to URLs the server downloads via the standard app configuration helper,
which is used for `appium:app` and similar capabilities by all official drivers. Drivers may
define custom capabilities with URLs that are processed differently and thus are not covered.
```
!!! note
```
If the server downloads applications through an HTTP proxy (configured via the `HTTP_PROXY`,
`HTTPS_PROXY` and `NO_PROXY` environment variables), the proxy resolves the destination host
itself, so rules containing IP addresses or subnets cannot be enforced for proxied downloads.
Such downloads are rejected; either exclude the download hosts from proxying via `NO_PROXY`
or only use hostname-based rules.
```
### Examples
Only allow HTTPS downloads from an internal artifact server, without credentials in the URL and
without following redirects:
```bash
appium --app-url-rules='{"allow": ["artifacts.example.com", "10.0.0.0/8"], "httpsOnly": true, "allowCredentials": false, "maxRedirects": 0}'
```
The same configuration as part of a config file:
```yaml
server:
app-url-rules:
allow:
- 'artifacts.example.com'
- '10.0.0.0/8'
httpsOnly: true
allowCredentials: false
maxRedirects: 0
```
Allow downloads from any subdomain of `example.com` and from two IPv6 subnets, except from the
staging environment:
```yaml
server:
app-url-rules:
allow:
- '*.example.com'
- '2001:db8:1::/48'
- '2001:db8:2::/48'
deny:
- '*.staging.example.com'
```
Allow downloads from anywhere, except from the server itself, private networks, link-local
addresses (such as cloud metadata services), and any `.internal` hostname:
```yaml
server:
app-url-rules:
deny:
- 'localhost'
- '*.internal'
- '127.0.0.0/8'
- '10.0.0.0/8'
- '172.16.0.0/12'
- '192.168.0.0/16'
- '169.254.0.0/16'
- '::1/128'
- 'fc00::/7'
- 'fe80::/10'
```
The rules in the last example are applied to the addresses each hostname resolves to, so they
cannot be bypassed via DNS. Note that the `deny` list also blocks any download from the server's
own private network, so a private artifact server must be excluded from the `deny` rules in order
to work.
+6 -7
View File
@@ -2,7 +2,7 @@
hide:
- toc
title: SSL/TLS/SPDY Support
title: SSL/TLS Support
---
Appium 2.2 introduces the option to start the Appium server with SSL/TLS support.
@@ -20,15 +20,14 @@ Both arguments must be provided and should contain paths to a valid
[X509 PEM](https://www.ssl.com/guide/pem-der-crt-and-cer-x-509-encodings-and-conversions/)
certificate and its corresponding private key.
After the server is started use the `https` protocol and a client supporting SSL/TLS or
[SPDY](https://en.wikipedia.org/wiki/SPDY) to communicate to it.
After the server is started use the `https` protocol and a client supporting SSL/TLS to
communicate to it.
### Supported Features
Once a secure server socket is established it supports the following protocols:
`['h2', 'spdy/3.1', 'spdy/3', 'spdy/2', 'http/1.1', 'http/1.0']`. See
[the SPDY node module documentation](https://www.npmjs.com/package/spdy) to get more details about
its features. All insecure client connections will be rejected by the server.
Once a secure server socket is established it uses Node.js' native
[`https`](https://nodejs.org/api/https.html) module to serve connections. All insecure client
connections will be rejected by the server.
### Self-Signed Certificates
+10
View File
@@ -24,6 +24,16 @@ title: Appium 客户端简介
例如,`查找元素`命令对应于发送到 HTTP 端点 `/session/:sessionid/element` 的 HTTP `POST` 请求(其中`:sessionid` 是服务器在之前 `创建会话` 调用中生成的唯一会话 ID 的占位符)。
If the client disconnects before Appium finishes sending a `Create Session` response and the
request has no `X-Idempotency-Key`, Appium deletes the new session once driver setup completes.
Setup is not interrupted. With an accepted idempotency key, a retry that arrives before setup
finishes waits for the same session ID, or the same error if setup failed. If the original client
and all waiting retries disconnect before setup finishes, Appium deletes the new session and
discards its cached result; a later retry starts a new session. Otherwise, Appium keeps the session
and caches its response for replay while it remains in the bounded, in-memory idempotency cache.
Disconnecting after a response was sent, or during a command in an existing session, does not
automatically end that session. Use `Delete Session` when you are done.
此信息主要对开发与 WebDriver 规范一起工作的技术的人有用。它对试图编写 Appium 或 Selenium 测试的人不是特别有用。当您编写 Appium 测试时,您希望使用您熟悉的编程语言。幸运的是,存在一组 [Appium 客户端库](../ecosystem/clients.md)[^1],它们负责向 Appium 服务器发起HTTP 的请求。它们为特定编程语言公开了一组“原生”命令,以便对测试作者来说,它就像您在编写 Python、JavaScript 或 Java。
以下是使用 Appium 客户端在五种不同编程语言中实现相同的 Appium 命令集的示例(注意,这不是包含所有导入的工作示例代码;请参阅每个客户端库的设置和命令参考说明):
+1 -1
View File
@@ -11,7 +11,7 @@ title: Appium 驱动程序介绍
在最基本的层面上,驱动程序只是扩展了 Appium 中包含的一个特殊类的 Node.js 类,这个类叫做 `BaseDriver`。你可以用以下非常简单的几行代码就拥有一个非常接近"可工作"的驱动程序:
```js
import BaseDriver from '@appium/base-driver'
import {BaseDriver} from '@appium/base-driver'
class MyNewDriver extends BaseDriver {
}
@@ -8,15 +8,14 @@ title: 编写测试 (.NET)
[Appium .NET Client](https://github.com/appium/dotnet-client/) 是
官方的 Appium C# 客户端。这个驱动程序是 Selenium C# 客户端的扩展。它具有常规驱动程序的所有功能,但在之上添加了 Appium 特定的方法。该驱动程序在公共 NuGet Gallery 上作为 [Appium.WebDriver](https://www.nuget.org/packages/Appium.WebDriver/) 提供。
现在,我们进入目录并创建一个新的 [NUnit](https://nunit.org/) 项目。我们还将添加对 Appium.Net 驱动程序和其他依赖项的引用。
Now, create a new [NUnit](https://nunit.org/) project. 我们还将添加对 Appium.Net 驱动程序和其他依赖项的引用。
```bash
cd dotnet-client
dotnet new nunit --name appiumtest
cd appiumtest
# 这将安装最新的 5.x 版本
# This will install the latest version
dotnet add package Appium.WebDriver --prerelease
dotnet add package Newtonsoft.Json --version 13.0.3
```
@@ -47,7 +46,7 @@ public class Tests
driverOptions.AddAdditionalAppiumOption("appPackage", "com.android.settings");
driverOptions.AddAdditionalAppiumOption("appActivity", ".Settings");
// NoReset assumes the app com.google.android is preinstalled on the emulator
// NoReset assumes the app com.android.settings is preinstalled on the emulator
driverOptions.AddAdditionalAppiumOption("noReset", true);
_driver = new AndroidDriver(serverUri, driverOptions, TimeSpan.FromSeconds(180));
@@ -57,16 +57,17 @@ session.unsubscribe
> WebDriver BiDi documentation: [session.unsubscribe](https://w3c.github.io/webdriver-bidi/#command-session-unsubscribe)
Unsubscribes using either previously returned subscription IDs or event names.
Removing a subscription ID preserves any overlapping subscriptions.
Unsubscribes from one or more BiDi events using subscription IDs or event names. Event names can
also be scoped to contexts (legacy parameter). Removing a subscription ID preserves any overlapping
subscriptions.
#### Parameters
| Name | Description | Type | Default |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------- |
| `subscriptions?` | Non-empty list of subscription IDs returned by `session.subscribe`. Cannot be combined with `events` or `contexts`. | string[] | |
| `contexts?` | Non-standard, only together with `events`: contexts in which to unsubscribe from the specified events. By default, the global scope is applied. | string[] | `['']` |
| `events?` | Non-empty list of event names to unsubscribe from. Required when `subscriptions` is omitted. | string[] | |
| Name | Description | Type | Default |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | ------- |
| `subscriptions?` | Non-empty list of subscription IDs returned by `session.subscribe`. Cannot be combined with `events` or `contexts`. | string[] | |
| `events?` | Non-empty list of event names to unsubscribe from. Required when `subscriptions` is omitted. | string[] | |
| `contexts?` | Legacy parameter: contexts in which to unsubscribe from events specified in `events`. By default, the global scope is applied. | string[] | `['']` |
All subscription IDs must be known to the current session. An unknown ID causes an `invalid argument`
error without removing any subscriptions. Subscription IDs are cleared when the session is deleted.
@@ -11,125 +11,6 @@ title: JSON Wire Protocol
The following is a list of legacy [JSON Wire Protocol (JSONWP)](https://www.selenium.dev/documentation/legacy/json_wire_protocol/)
endpoints supported in Appium.
### getSession
```
GET /session/:sessionId
```
> JSONWP documentation: [/session/:sessionId](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionid)
Retrieves the capabilities of the current session.
Appium implements a modified version of this endpoint. If the `appium:eventTimings` capability is
set to `true`, the returned result will additionally include the `events` key, whose value contains
the event history and timings.
!!! warning "Deprecated"
For retrieving capabilities, please use [`getAppiumSessionCapabilities`](./appium.md#getappiumsessioncapabilities).<br />
For retrieving event history, please use [`getLogEvents`](./appium.md#getlogevents).
#### Response
`Capabilities` - an object containing the session capabilities, and the event history (if applicable)
### availableIMEEngines
```
GET /session/:sessionId/ime/available_engines
```
> JSONWP documentation: [/session/:sessionId/ime/available_engines](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidimeavailable_engines)
Retrieves all IME (input method editor) engines available on the device under test.
!!! warning "Deprecated"
In the future, this endpoint will be moved to the [UiAutomator2 and Espresso drivers](../../ecosystem/drivers.md)
#### Response
`string[]` - a list of available IME engines
### getActiveIMEEngine
```
GET /session/:sessionId/ime/active_engine
```
> JSONWP documentation: [/session/:sessionId/ime/active_engine](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidimeactive_engine)
Retrieves the name of the active IME engine.
!!! warning "Deprecated"
In the future, this endpoint will be moved to the UiAutomator2 and Espresso drivers
#### Response
`string` - the name of the active IME engine
### isIMEActivated
```
GET /session/:sessionId/ime/activated
```
> JSONWP documentation: [/session/:sessionId/ime/activated](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidimeactivated)
Determines if IME input is available and active.
!!! warning "Deprecated"
In the future, this endpoint will be moved to the UiAutomator2 and Espresso drivers
#### Response
`boolean` - `true` if IME is active, otherwise `false`
### deactivateIMEEngine
```
POST /session/:sessionId/ime/deactivate
```
> JSONWP documentation: [/session/:sessionId/ime/deactivate](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidimedeactivate)
Deactivates the currently active IME engine.
!!! warning "Deprecated"
In the future, this endpoint will be moved to the UiAutomator2 and Espresso drivers
#### Response
`null`
### activateIMEEngine
```
POST /session/:sessionId/ime/activate
```
> JSONWP documentation: [/session/:sessionId/ime/activate](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidimeactivate)
Activates an IME engine.
!!! warning "Deprecated"
In the future, this endpoint will be moved to the UiAutomator2 and Espresso drivers
#### Parameters
| Name | Description | Type |
| -------- | ---------------------------------- | ------ |
| `engine` | Name of the IME engine to activate | string |
#### Response
`null`
### getOrientation
```
@@ -171,53 +52,3 @@ Sets the orientation of the device under test.
#### Response
`null`
### getGeoLocation
```
GET /session/:sessionId/location
```
> JSONWP documentation: [/session/:sessionId/location](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidlocation)
Retrieves the current location of the device under test.
!!! warning "Deprecated"
Please use driver-specific extension methods such as `mobile: getGeoLocation` or
`mobile: getSimulatedLocation`
#### Response
`Location` - an object with the following properties:
| Name | Description | Type |
| ----------- | -------------------------------- | ------ |
| `altitude` | Altitude of the device location | number |
| `latitude` | Latitude of the device location | number |
| `longitude` | Longitude of the device location | number |
### setGeoLocation
```
POST /session/:sessionId/location
```
> JSONWP documentation: [/session/:sessionId/location](https://www.selenium.dev/documentation/legacy/json_wire_protocol/#sessionsessionidlocation)
Sets the current location of the device under test.
!!! warning "Deprecated"
Please use driver-specific extension methods such as `mobile: setGeoLocation` or
`mobile: setSimulatedLocation`
#### Parameters
| Name | Description | Type |
| ---------- | ------------------------------------------- | ------------------------- |
| `location` | New device latitude, longitude and altitude | [`Location`](#response_6) |
#### Response
`null`
@@ -120,53 +120,3 @@ Retrieves all available application contexts.
#### Response
`string[]` - the names of available contexts
### getNetworkConnection
```
GET /session/:sessionId/network_connection
```
> MJSONWP documentation: [Device Modes](https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md#device-modes)
Retrieves the current state of network types (data, Wi-Fi, airplane mode).
!!! warning "Deprecated"
Please use driver-specific extension methods such as `mobile: getConnectivity`
#### Response
`NetworkConnectionState` - a number indicating the current network state:
| Value | Data | Wi-Fi | Airplane Mode |
| ----- | ---- | ----- | ------------- |
| `0` | OFF | OFF | OFF |
| `1` | OFF | OFF | ON |
| `2` | OFF | ON | OFF |
| `4` | ON | OFF | OFF |
| `6` | ON | ON | OFF |
### setNetworkConnection
```
POST /session/:sessionId/network_connection
```
> MJSONWP documentation: [Device Modes](https://github.com/SeleniumHQ/mobile-spec/blob/master/spec-draft.md#device-modes)
Sets the state of network types (data, Wi-Fi, airplane mode).
!!! warning "Deprecated"
Please use driver-specific extension methods such as `mobile: setConnectivity`
#### Parameters
| <div style="width:6em">Name</div> | Description | <div style="width:18em">Type</div> |
| --------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------- |
| `parameters` | Object containing the `type` key, whose value is the desired network state | `{"type": `[`NetworkConnectionState`](#response_5)`}` |
#### Response
[`NetworkConnectionState`](#response_5) - the new network state
@@ -267,6 +267,43 @@ preserved, and only the incomplete uploads will be stopped.
## Universal XML Plugin
Translation is on by default. It can be turned off and on during a session with the
[execute methods](../../guides/execute-methods.md) below, and applies only to the current session.
### execute
```
POST /session/:sessionId/execute/sync
```
Modifies the [`execute`](./webdriver.md#execute) endpoint:
- Adds the `universalXml: setEnabled` and `universalXml: isEnabled` execute methods. Any other
script is passed on unchanged
#### universalXml: setEnabled
Turns translation on or off for the current session. While it is off, `findElement`,
`findElements` and `getPageSource` are passed on unchanged.
##### Parameters
| Name | Description | Type |
| --------- | ------------------------------------------------- | ------- |
| `enabled` | Whether node/attribute names should be translated | boolean |
##### Response
`null`
#### universalXml: isEnabled
Returns whether translation is on for the current session.
##### Response
`boolean` - `true` if translation is on
### findElement
```
@@ -26,18 +26,11 @@ POST /session
Creates a new WebDriver session.
Appium implements a modified version of this endpoint for historical reasons. While the W3C
endpoint only accepts 1 parameter, Appium's implementation allows up to 3 parameters, as this was
required by the legacy JSON Wire Protocol (JSONWP). Since Appium 2, the JSONWP format is no longer
supported, and any of the 3 parameters can be used to specify the W3C capabilities.
#### Parameters
| Name | Description | Type |
| ------------------- | ----------------------------------------------------------------------------- | --------------- |
| `w3cCapabilities1?` | Capabilities of the new session | `W3CDriverCaps` |
| `w3cCapabilities2?` | Another location for the new session capabilities (legacy) | `W3CDriverCaps` |
| `w3cCapabilities?` | Another location for the new session capabilities (legacy) | `W3CDriverCaps` |
| Name | Description | Type |
| --------------- | ------------------------------- | --------------- |
| `capabilities?` | Capabilities of the new session | `W3CDriverCaps` |
#### Response
@@ -92,14 +85,19 @@ GET /session/:sessionId/timeouts
Retrieves the timeout values of the current session.
Appium implements a modified version of this endpoint, by also returning the value of the `command`
timeout for supported drivers and contexts.
#### Response
`GetTimeoutsResult` - an object with the following properties:
| Name | Description | Type |
| ---------- | --------------------- | ------ |
| `command` | Command timeout | number |
| `implicit` | Implicit wait timeout | number |
| Name | Description | Type |
| ---------- | ---------------------- | -------------- |
| `script` | Script timeout | number or null |
| `pageLoad` | Page load timeout | number or null |
| `implicit` | Implicit wait timeout | number or null |
| `command` | Appium command timeout | number |
### timeouts
@@ -111,13 +109,17 @@ POST /session/:sessionId/timeouts
Sets the timeout values of the current session.
Appium implements a modified version of this endpoint by adding the optional `command` parameter
for supported drivers and contexts.
#### Parameters
| Name | Description | Type |
| ----------- | ---------------------------------------------------------- | ------ |
| `implicit?` | Implicit wait timeout (in milliseconds) | number |
| `pageLoad?` | Page load timeout (in milliseconds) | number |
| `script?` | Script timeout (in milliseconds) | number |
| Name | Description | Type |
| ----------- | ----------------------------------------------------------- | -------------- |
| `script?` | Script timeout (in milliseconds) | number or null |
| `implicit?` | Implicit wait timeout (in milliseconds) | number or null |
| `pageLoad?` | Page load timeout (in milliseconds) | number or null |
| `command?` | Appium command timeout (in milliseconds) | number |
#### Response
@@ -954,7 +956,7 @@ POST /session/:sessionId/actions
> WebDriver documentation: [Perform Actions](https://w3c.github.io/webdriver/#perform-actions)
Performs a sequence of [actions](https://w3c.github.io/webdriver/#actions).
Performs a sequence of [actions](https://w3c.github.io/webdriver/#actions). See the [Automating Gestures](../../guides/gestures.md) guide for multi-language examples.
#### Parameters
@@ -14,6 +14,7 @@ they can only be enabled using the wildcard (`*`) prefix:
| Feature Name | Description |
| ------------------- | ------------------------------------------------------------------------------- |
| `session_discovery` | Allows retrieving the list of active server sessions via `GET /appium/sessions` |
| `cors` | Allows web browser connections to the server from any host |
Of course, Appium drivers and plugins are free to define additional insecure features of their own.
The following features are defined by official plugins:
+75 -42
View File
@@ -24,48 +24,81 @@ appium
All of these options can also be set via a [Configuration File](../../guides/config.md). Options
set on the command line will override any options found in a configuration file.
| <div style="width:15em">Argument</div> | Description | Type | <div style="width:7em">Default</div> |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -------------------------------------------------------- |
| `--address`, `-a` | IPv4/IPv6 address or a hostname to listen on | string | `0.0.0.0` |
| `--allow-cors` | Allow web browser connections from any host | boolean | `false` |
| `--allow-insecure` | List of [insecure features](../../guides/security.md) that should be allowed in this server's sessions. Individual features can be overridden by `--deny-insecure`. Has no effect in combination with `--relaxed-security`. | array<string> | `[]` |
| `--allow-unknown-args` | Do not exit if unrecognized command-line arguments are passed to the server; ignore them instead. Useful when the Appium CLI is wrapped by external tooling that appends extra flags. | boolean | `false` |
| `--base-path`, `-pa` | Base path to use as the prefix for all webdriver routes running on the server | string | `""` |
| `--callback-address`, `-ca` | Callback IP address | string | same as `--address` |
| `--callback-port`, `-cp` | Callback port | integer | `4723` |
| `--config` | Path to an [Appium configuration JSON file](../../guides/config.md) | string | |
| `--debug-log-spacing` | Add exaggerated spacing in logs to help with visual inspection | boolean | `false` |
| `--default-capabilities`, `-dc` | Capabilities that will be used for each session, unless overridden by received capabilities | object | |
| `--deny-insecure` | List of [insecure features](../../guides/security.md) that should be disabled in this server's sessions. Since all insecure features are disabled by default, this argument has no effect without either `--allow-insecure` or `--relaxed-security`, and is applied after both. | array<string> | `[]` |
| `--driver` | Driver-specific configuration. Keys should correspond to driver package names | object | |
| `--drivers-import-chunk-size` | Maximum number of drivers that can be imported in parallel on server startup | number | `3` |
| `--keep-alive-timeout`, `-ka` | Timeout (in seconds) to use as both the keep-alive timeout and the connection timeout for all client requests. Disabled if set to `0`. | integer | `600` |
| `--request-timeout` | Timeout (in seconds) for waiting to receive the entire HTTP request from the client. Disabled if set to `0`. Requests exceeding this timeout will be rejected with the code `HTTP 408`. | integer | `3600` |
| `--local-timezone` | Use local timezone for log timestamps | boolean | `false` |
| `--log`, `-g` | Path to a file where the server logs should be output. This does not affect output on the console. | string | |
| `--log-filters` | List of log filtering rules. See the [log filtering guide](../../guides/log-filters.md) for details. | array | |
| `--log-level` | The log level for the server logs. Supported values are `debug`, `info`, `warn`, or `error`. Combining two supported values using a colon (e.g. `warn:debug`) allows to set separate log levels for the console and file outputs, respectively. | string | `debug` |
| `--log-format` | The log format of the server logs. Supported values are `text`, `json`, or `pretty_json`. Setting the value to `json` disables colors. | string | `text` |
| `--log-no-colors` | Disable colors in the server log | boolean | `false` |
| `--log-timestamp` | Show timestamps in the server log | boolean | `false` |
| `--long-stacktrace` | Add long stack traces to log entries. Recommended for debugging only. | boolean | `false` |
| `--max-ipc-data-size` | Maximum byte size of IPC message objects. | integer | `1048576` (1MB) |
| `--max-ipc-topics` | Maximum number of IPC topics per session. | integer | `1000` |
| `--no-perms-check` | Skip various permission checks on the server startup | boolean | `false` |
| `--nodeconfig` | JSON configuration for registering Appium as a node with Selenium Grid 3 | object | |
| `--plugin` | Plugin-specific configuration. Keys should correspond to plugin package names | object | |
| `--plugins-import-chunk-size` | Maximum number of plugins that can be imported in parallel on server startup | number | `7` |
| `--port`, `-p` | Port to listen on | integer | `4723` |
| `--relaxed-security` | Allow all [insecure features](../../guides/security.md). Only use this if all clients are in a trusted network and could not potentially break out of the session sandbox. Specific features can be overridden by using `--deny-insecure`. | boolean | `false` |
| `--session-override` | Enable session override (clobbering) | boolean | `false` |
| `--shutdown-timeout` | Timeout (in milliseconds) for waiting on all active connections to close, when shutting down the server | number | `5000` |
| `--ssl-cert-path` | Absolute path to the `.cert` file if TLS is used. Must be provided together with `--ssl-key-path`. See the [SSL/TLS/SPDY Support guide](../../guides/tls.md) for details. | string | |
| `--ssl-key-path` | Absolute path to the `.key` file if TLS is used. Must be provided together with `--ssl-cert-path`. See the [SSL/TLS/SPDY Support guide](../../guides/tls.md) for details. | string | |
| `--strict-caps` | Prevent creation of new client sessions that use unsupported capabilities | boolean | `false` |
| `--tmp` | Absolute path to the directory used for temporary files | string | [`os.tmpdir()`](https://nodejs.org/api/os.html#ostmpdir) |
| `--use-drivers` | List of drivers to activate. By default, all installed drivers are activated. | array<string> | `[]` |
| `--use-plugins` | List of plugins to activate. By default, no plugins are activated. Set to `["all"]` to activate all installed plugins. | array<string> | `[]` |
| `--webhook`, `-G` | URL for an HTTP listener where the server logs should be output. This does not affect output on the console. A bare `host:port` is also accepted, which posts the logs to the root path over plain http; a value having neither a scheme nor a port falls back to `127.0.0.1:9003`. | string | |
| <div style="width:15em">Argument</div> | Description | Type | <div style="width:7em">Default</div> |
| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | -------------------------------------------------------- |
| `--address`, `-a` | IPv4/IPv6 address or a hostname to listen on | string | `0.0.0.0` |
| `--allow-cors` | Allow web browser connections from any host | boolean | `false` |
| `--allow-insecure` | List of [insecure features](../../guides/security.md) that should be allowed in this server's sessions. Individual features can be overridden by `--deny-insecure`. Has no effect in combination with `--relaxed-security`. | array<string> | `[]` |
| `--allow-unknown-args` | Do not exit if unrecognized command-line arguments are passed to the server; ignore them instead. Useful when the Appium CLI is wrapped by external tooling that appends extra flags. | boolean | `false` |
| `--app-url-rules` | Rules that remote application URLs (e.g. in the `appium:app` capability) must satisfy before the server downloads them. See the [Restricting Remote App URLs](../../guides/security.md#restricting-remote-app-urls) guide for details. Can be a path to a JSON file or raw JSON. | object | |
| `--base-path`, `-pa` | Base path to use as the prefix for all webdriver routes running on the server | string | `""` |
| `--config` | Path to an [Appium configuration JSON file](../../guides/config.md) | string | |
| `--bidi-heartbeat-interval` | Interval (in seconds) between WebSocket pings sent to each [BiDi](../api/bidi.md) client. A connection that misses two consecutive pongs is terminated. Disabled if set to `0`. | integer | `15` |
| `--bidi-max-buffered-bytes` | Maximum number of bytes the server may keep buffered for a BiDi connection whose client is not reading fast enough. A connection that stays above the limit for longer than `--bidi-max-buffered-ms`, or exceeds twice the limit, is closed with the code `1013`. Disabled if set to `0`, which also turns off skipping of droppable events. | integer | `33554432` |
| `--bidi-max-buffered-ms` | Time (in milliseconds) a BiDi connection may stay above `--bidi-max-buffered-bytes` before it is closed. If set to `0`, the connection is closed as soon as the limit is exceeded. | integer | `30000` |
| `--default-capabilities`, `-dc` | Capabilities that will be used for each session, unless overridden by received capabilities. See [Default Capabilities](#default-capabilities) for how they are applied. | object | |
| `--deny-insecure` | List of [insecure features](../../guides/security.md) that should be disabled in this server's sessions. Since all insecure features are disabled by default, this argument has no effect without either `--allow-insecure` or `--relaxed-security`, and is applied after both. | array<string> | `[]` |
| `--driver` | Driver-specific configuration. Keys should correspond to driver package names | object | |
| `--drivers-import-chunk-size` | Maximum number of drivers that can be imported in parallel on server startup | number | `3` |
| `--keep-alive-timeout`, `-ka` | Timeout (in seconds) to use as both the keep-alive timeout and the connection timeout for all client requests. Disabled if set to `0`. | integer | `600` |
| `--request-timeout` | Timeout (in seconds) for waiting to receive the entire HTTP request from the client. Disabled if set to `0`. Requests exceeding this timeout will be rejected with the code `HTTP 408`. | integer | `3600` |
| `--local-timezone` | Use local timezone for log timestamps | boolean | `false` |
| `--log`, `-g` | Path to a file where the server logs should be output. This does not affect output on the console. | string | |
| `--log-filters` | List of log filtering rules. See the [log filtering guide](../../guides/log-filters.md) for details. | array | |
| `--log-level` | The log level for the server logs. Supported values are `debug`, `info`, `warn`, or `error`. Combining two supported values using a colon (e.g. `warn:debug`) allows to set separate log levels for the console and file outputs, respectively. | string | `info` |
| `--log-format` | The log format of the server logs. Supported values are `text`, `json`, or `pretty_json`. Setting the value to `json` disables colors. | string | `text` |
| `--log-no-colors` | Disable colors in the server log | boolean | `false` |
| `--log-timestamp` | Show timestamps in the server log | boolean | `false` |
| `--long-stacktrace` | Add long stack traces to log entries. Recommended for debugging only. | boolean | `false` |
| `--max-ipc-data-size` | Maximum byte size of IPC message objects. | integer | `1048576` (1MB) |
| `--max-ipc-topics` | Maximum number of IPC topics per session. | integer | `1000` |
| `--no-perms-check` | Skip various permission checks on the server startup | boolean | `false` |
| `--plugin` | Plugin-specific configuration. Keys should correspond to plugin package names | object | |
| `--plugins-import-chunk-size` | Maximum number of plugins that can be imported in parallel on server startup | number | `7` |
| `--port`, `-p` | Port to listen on | integer | `4723` |
| `--relaxed-security` | Allow all [insecure features](../../guides/security.md). Only use this if all clients are in a trusted network and could not potentially break out of the session sandbox. Specific features can be overridden by using `--deny-insecure`. | boolean | `false` |
| `--session-override` | Enable session override (clobbering) | boolean | `false` |
| `--shutdown-timeout` | Timeout (in milliseconds) for waiting on all active connections to close, when shutting down the server | number | `5000` |
| `--ssl-cert-path` | Absolute path to the `.cert` file if TLS is used. Must be provided together with `--ssl-key-path`. See the [SSL/TLS/SPDY Support guide](../../guides/tls.md) for details. | string | |
| `--ssl-key-path` | Absolute path to the `.key` file if TLS is used. Must be provided together with `--ssl-cert-path`. See the [SSL/TLS/SPDY Support guide](../../guides/tls.md) for details. | string | |
| `--tmp` | Absolute path to the directory used for temporary files | string | [`os.tmpdir()`](https://nodejs.org/api/os.html#ostmpdir) |
| `--use-drivers` | List of drivers to activate. By default, all installed drivers are activated. | array<string> | `[]` |
| `--use-plugins` | List of plugins to activate. By default, no plugins are activated. Set to `["all"]` to activate all installed plugins. | array<string> | `[]` |
| `--webhook`, `-G` | URL for an HTTP listener where the server logs should be output. This does not affect output on the console. A bare `host:port` is also accepted, which posts the logs to the root path over plain http; a value having neither a scheme nor a port falls back to `127.0.0.1:9003`. | string | |
### Default Capabilities
Capabilities set with `--default-capabilities` are added to the received capabilities before a
driver is matched. This is Appium's own defaulting behavior, not something defined by the W3C
WebDriver specification.
- A value the client sends in `alwaysMatch`, or in a given `firstMatch` candidate, takes precedence
over the server default
- Defaults fill missing keys in each `firstMatch` candidate separately. A value in one candidate
does not stop the default from being applied to another candidate
- A key sent in both `alwaysMatch` and `firstMatch` is still rejected by the usual capability
validation. Server defaults do not change that
For example, with these server defaults:
```json
{"appium:newCommandTimeout": 60}
```
and these received capabilities:
```json
{
"alwaysMatch": {"appium:deviceName": "Pixel"},
"firstMatch": [
{"platformName": "iOS", "appium:newCommandTimeout": 120},
{"platformName": "Android"}
]
}
```
the iOS candidate keeps `appium:newCommandTimeout` of `120`, and the Android candidate gets the
default `60`. The session uses the value from whichever candidate it is created with.
### Info Options
@@ -33,7 +33,7 @@ appium setup browser
Installs the following extensions for desktop application testing:
- Drivers: `mac2`[^1], `windows`[^2]
- Drivers: `mac2`[^1], `wincore`[^2]
- Plugins: `images`, `inspector`
#### Usage
@@ -29,12 +29,11 @@ Appium sessions.
These capabilities are used in the Appium server/base driver, but are optional, and may have a
default value.
| <div style="width:19em">Capability</div> | Description | Type | Default |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------- |
| `webSocketUrl` | Toggle support of the WebDriver BiDi protocol | `boolean` | |
| `appium:eventTimings` (deprecated) | Toggle collection of [Event Timings](../../guides/event-timing.md). This capability is deprecated - please use the [`getLogEvents`](../api/appium.md#getlogevents) endpoint instead. | `boolean` | |
| `appium:newCommandTimeout` | Number of seconds the Appium server should wait for clients to send commands before stopping the session. A value of `0` disables the timeout. | `number` | `60` |
| `appium:printPageSourceOnFindFailure` | Toggle retrieval of the page source and its printing to the Appium log, whenever a request to find an element fails | `boolean` | |
| <div style="width:19em">Capability</div> | Description | Type | Default |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------- | ------- |
| `webSocketUrl` | Toggle support of the WebDriver BiDi protocol | `boolean` | |
| `appium:newCommandTimeout` | Number of seconds the Appium server should wait for clients to send commands before stopping the session. A value of `0` disables the timeout. | `number` | `60` |
| `appium:printPageSourceOnFindFailure` | Toggle retrieval of the page source and its printing to the Appium log, whenever a request to find an element fails | `boolean` | |
### Validated Capabilities
@@ -42,9 +41,9 @@ These capabilities are not directly used in the Appium server/base driver, but a
validation checks due to their relevance in other drivers. The actual handling of these
capabilities is optional and entirely driver-dependent.
| Capability | Validation |
| --------------------------------------------------- | ------------------------------------------------------------- |
| `platformVersion` | Must be `string` |
| `appium:app` | Must be `string`; empty values are ignored |
| `appium:fullReset` | Must be `boolean`; mutually exclusive with `appium:noReset` |
| `appium:noReset` | Must be `boolean`; mutually exclusive with `appium:fullReset` |
| Capability | Validation |
| ------------------------ | ------------------------------------------------------------- |
| `appium:platformVersion` | Must be `string` |
| `appium:app` | Must be `string`; empty values are ignored |
| `appium:fullReset` | Must be `boolean`; mutually exclusive with `appium:noReset` |
| `appium:noReset` | Must be `boolean`; mutually exclusive with `appium:fullReset` |
+3 -3
View File
@@ -76,14 +76,14 @@
"@sidvind/better-ajv-errors": "7.0.0",
"ajv": "8.20.0",
"ajv-formats": "3.0.1",
"argparse": "3.0.3",
"asyncbox": "6.6.0",
"argparse": "3.0.4",
"asyncbox": "7.0.0",
"axios": "1.20.0",
"lilconfig": "3.1.4",
"lru-cache": "11.5.3",
"normalize-package-data": "9.0.0",
"semver": "7.8.5",
"teen_process": "4.2.1",
"teen_process": "5.0.1",
"winston": "3.19.0",
"ws": "8.22.0",
"yaml": "2.9.1",
@@ -1,5 +1,5 @@
{
"devDependencies": {
"webdriverio": "9.32.0"
"webdriverio": "10.2.0"
}
}
+2 -2
View File
@@ -55,10 +55,10 @@
"dependencies": {
"@appium/support": "~8.0.0",
"@appium/types": "~2.0.0",
"asyncbox": "^6.6.0",
"asyncbox": "^7.0.0",
"axios": "^1.20.0",
"lru-cache": "^11.5.2",
"path-to-regexp": "^8.4.2",
"path-to-regexp": "^9.0.0",
"picomatch": "^4.0.7"
},
"devDependencies": {
+1 -1
View File
@@ -63,7 +63,7 @@
"diff": "^9.0.0",
"lilconfig": "^3.1.3",
"normalize-package-data": "^9.0.0",
"teen_process": "^4.2.1",
"teen_process": "^5.0.0",
"yaml": "^2.9.0",
"yargs": "^18.1.0",
"yargs-parser": "^22.0.0"
+2 -2
View File
@@ -1,5 +1,5 @@
mkdocs==1.6.1
mkdocs-git-revision-date-localized-plugin==1.6.2
mkdocs-material==9.8.0
mkdocs-git-revision-date-localized-plugin==1.7.0
mkdocs-material==9.8.1
mkdocs-redirects==1.2.3
mike==2.2.0
+1 -1
View File
@@ -54,7 +54,7 @@
},
"dependencies": {
"@appium/support": "~8.0.0",
"asyncbox": "^6.6.0"
"asyncbox": "^7.0.0"
},
"devDependencies": {
"@appium/types": "~2.0.0"
+2 -2
View File
@@ -50,7 +50,7 @@
},
"dependencies": {
"@appium/support": "8.0.0",
"webdriverio": "9.32.0"
"webdriverio": "10.2.0"
},
"devDependencies": {
"@appium/types": "2.0.0"
@@ -59,7 +59,7 @@
"appium": "^4.0.0-beta.0"
},
"engines": {
"node": "^22.22.2 || ^24.15.0 || >=26.0.0",
"node": "^22.23.4 || ^24.22.1 || >=26.12.1",
"npm": ">=10"
},
"appium": {
@@ -162,9 +162,8 @@ describe('ExecuteDriverPlugin', function () {
return await driver.$("~notfound");
`;
const {result} = await driver.executeDriverScript(script);
assert.strictEqual((result as any).error.error, 'no such element');
assert.match((result as any).error.message, /element could not be located/);
assert.ok((result as any).error.stacktrace.includes('NoSuchElementError:'));
// wdio 10 sets a real Error here, which JSON-serializes to an empty object
assert.ok((result as any).error);
assert.strictEqual((result as any).selector, '~notfound');
assert.strictEqual((result as any).sessionId, driver.sessionId);
});
+1 -1
View File
@@ -49,7 +49,7 @@
"dependencies": {
"@appium/http-server": "1.0.0",
"@xmldom/xmldom": "0.9.12",
"asyncbox": "6.6.0",
"asyncbox": "7.0.0",
"xpath": "0.0.35",
"yocto-spinner": "1.2.2"
},
@@ -6,6 +6,8 @@ import {deleteSession, initSession, W3C_PREFIXED_CAPS} from '../helpers.js';
export function contextTests(context: {port: number}) {
describe('contexts, webviews, frames', function () {
let driver: Awaited<ReturnType<typeof initSession>>;
// wdio 10 types only accept elements, but numeric frame ids are still passed through
const switchToFrame = (id: number | null) => driver.switchFrame(id as unknown as null);
before(async function () {
driver = await initSession(W3C_PREFIXED_CAPS, {port: context.port});
});
@@ -29,14 +31,14 @@ export function contextTests(context: {port: number}) {
assert.strictEqual(await (await driver.$('//*')).getTagName(), 'html');
});
it('should not switch to a frame that is not there', async function () {
await assert.rejects(driver.switchToFrame(2), /frame could not be found/);
await assert.rejects(switchToFrame(2), /frame could not be found/);
});
it('should switch to an iframe', async function () {
await driver.switchToFrame(1);
await switchToFrame(1);
assert.strictEqual(await driver.getTitle(), 'Test iFrame');
});
it('should switch back to default frame', async function () {
await driver.switchToFrame(null);
await switchToFrame(null);
assert.strictEqual(await driver.getTitle(), 'Test Webview');
});
it('should go back to native context', async function () {
@@ -45,7 +47,7 @@ export function contextTests(context: {port: number}) {
});
it('should not set a frame in a native context', async function () {
await driver.switchContext('NATIVE_APP');
await assert.rejects(driver.switchToFrame(1), /could not be executed in the current context/);
await assert.rejects(switchToFrame(1), /could not be executed in the current context/);
});
});
}
+1
View File
@@ -33,6 +33,7 @@ const WD_OPTS: Partial<Parameters<typeof wdio>[0]> = {
hostname: TEST_HOST,
connectionRetryCount: 0,
logLevel: 'error',
strictSelectors: false,
};
async function initSession(w3cPrefixedCaps: StringRecord, wdioOpts: Partial<Parameters<typeof wdio>[0]> = {}) {
+1 -1
View File
@@ -46,7 +46,7 @@
"dependencies": {
"@appium/base-plugin": "4.0.0",
"@appium/support": "8.0.0",
"asyncbox": "6.6.0"
"asyncbox": "7.0.0"
},
"devDependencies": {
"@appium/types": "2.0.0",
+1 -1
View File
@@ -59,7 +59,7 @@
"express": "^5.2.1",
"method-override": "^3.0.0",
"morgan": "^1.12.1",
"path-to-regexp": "^8.4.2"
"path-to-regexp": "^9.0.0"
},
"engines": {
"node": "^22.22.2 || ^24.15.0 || >=26.0.0",
@@ -10,7 +10,7 @@ class FakeDriver extends BaseDriver<Constraints> {
'/session/:sessionId/wrapped': {
POST: {command: 'wrappedCommand', payloadParams: {wrap: 'items', required: ['items']}},
},
};
} as const;
declare wdProxyActive: boolean;
+1 -1
View File
@@ -52,7 +52,7 @@
"dependencies": {
"@appium/opencv": "6.0.0",
"@appium/support": "8.0.0",
"asyncbox": "6.6.0",
"asyncbox": "7.0.0",
"lru-cache": "11.5.3",
"sharp": "0.35.5"
},
@@ -31,6 +31,7 @@ type WebdriverIOConfig = Parameters<typeof wdio>[0];
const WDIO_OPTS: WebdriverIOConfig = {
hostname: TEST_HOST,
connectionRetryCount: 0,
strictSelectors: false,
capabilities: TEST_CAPS,
};
+2 -2
View File
@@ -51,8 +51,8 @@
"test:unit": "exit 0"
},
"dependencies": {
"asyncbox": "^6.6.0",
"teen_process": "^4.2.1"
"asyncbox": "^7.0.0",
"teen_process": "^5.0.0"
},
"devDependencies": {
"@appium/types": "~2.0.0"
+1 -1
View File
@@ -53,7 +53,7 @@
},
"dependencies": {
"@appium/support": "8.0.0",
"asyncbox": "6.6.0",
"asyncbox": "7.0.0",
"lru-cache": "11.5.3",
"ws": "8.22.0"
},
+6 -4
View File
@@ -5,6 +5,9 @@ import type {JsonValue} from '@appium/types';
import {isUnicodeSupported, NullWritable, streamSupportsColor, stripAnsi} from './internal/index.js';
/** @deprecated Has no effect in recent Node.js versions. Will be removed in a future release. */
export type DeprecatedTextStyle = 'framed' | 'overlined';
/** ANSI styles supported by Node's `util.styleText`. `grey` is accepted as an alias for `gray`. */
export type TextStyle =
| 'reset'
@@ -35,20 +38,19 @@ export type TextStyle =
| 'bgMagenta'
| 'bgCyan'
| 'bgWhite'
| 'framed'
| 'overlined'
| 'redBright'
| 'greenBright'
| 'yellowBright'
| 'blueBright'
| 'magentaBright'
| 'cyanBright'
| 'whiteBright';
| 'whiteBright'
| DeprecatedTextStyle;
/** Applies terminal styling via Node's `util.styleText`. */
export function styleText(style: TextStyle, text: string): string {
const format = style === 'grey' ? 'gray' : style;
return nodeStyleText(format, text);
return nodeStyleText(format as Parameters<typeof nodeStyleText>[0], text);
}
/** Removes ANSI escape sequences (CSI and OSC) from a string. */
@@ -2,7 +2,6 @@ import {type BigIntStats, type PathLike, promises as fsPromises, type Stats} fro
import path from 'node:path';
import type {MoveFs} from './fs-like.js';
import {isWindows} from './platform.js';
import {isSubPath} from './sub-path.js';
/** Options for {@linkcode fs.mv} */
@@ -67,7 +66,9 @@ export class MoveOperation {
// File and symlink moves replace the destination entry itself.
let toStat: BigIntStats | undefined;
try {
toStat = await (fromStat.isDirectory() ? fsPromises.stat : fsPromises.lstat)(to, {bigint: true});
toStat = fromStat.isDirectory()
? await fsPromises.stat(to, {bigint: true})
: await fsPromises.lstat(to, {bigint: true});
} catch (err) {
if (!isErrnoException(err) || err.code !== 'ENOENT') {
throw err;
@@ -81,13 +82,13 @@ export class MoveOperation {
const fromName = path.basename(from);
const toName = path.basename(to);
if (
isWindows() &&
fromName !== toName &&
fromName.toLowerCase() === toName.toLowerCase() &&
(await fsPromises.realpath(path.dirname(from))) === (await fsPromises.realpath(path.dirname(to)))
) {
// Windows preserves spelling even when names identify the same entry. Do not remove
// either path: rename changes the spelling, and cleanup would delete the renamed entry.
// Case-insensitive volumes (Windows, macOS by default) preserve spelling even when names identify
// the same entry. Do not remove either path: rename changes the spelling, and cleanup would delete
// the renamed entry.
const toEntry = await fsPromises.lstat(to, {bigint: true});
if (fromStat.dev === toEntry.dev && fromStat.ino === toEntry.ino) {
await fsPromises.rename(from, to);
+4 -3
View File
@@ -55,7 +55,7 @@
"@appium/logger": "~3.0.0",
"@appium/types": "~2.0.0",
"archiver": "^8.0.0",
"asyncbox": "^6.6.0",
"asyncbox": "^7.0.0",
"axios": "^1.20.0",
"lockfile": "^1.0.4",
"mime-types": "^3.0.2",
@@ -64,12 +64,13 @@
"sanitize-filename": "^1.6.4",
"semver": "^7.8.5",
"shell-quote": "^1.12.0",
"teen_process": "^4.2.1",
"teen_process": "^5.0.0",
"which": "^7.0.0",
"yauzl": "^3.4.0"
},
"devDependencies": {
"@appium/tsconfig": "~2.0.0"
"@appium/tsconfig": "~2.0.0",
"@types/yauzl": "^2.10.3"
},
"engines": {
"node": "^22.22.2 || ^24.15.0 || >=26.0.0",
@@ -167,3 +167,47 @@ describe('moving directories with symlinks', {skip: system.isWindows()}, functio
assert.equal(await fsPromises.readFile(destination, 'utf8'), 'source');
});
});
describe('moving an entry that differs only by case', function () {
const sandbox = createSandbox();
let root: string;
beforeEach(async function () {
root = await tempDir.openDir();
});
afterEach(async function () {
sandbox.restore();
await fs.rimraf(root);
});
it('changes the spelling of a file', async function () {
const source = path.join(root, 'Foo.txt');
const destination = path.join(root, 'foo.txt');
await fsPromises.writeFile(source, 'payload');
// on a case-insensitive volume both spellings resolve to the same entry
const sourceStat = await fsPromises.lstat(source, {bigint: true});
sandbox.stub(fsPromises, 'lstat').callThrough().withArgs(destination, {bigint: true}).resolves(sourceStat);
await fs.mv(source, destination);
assert.deepEqual(await fsPromises.readdir(root), ['foo.txt']);
assert.equal(await fsPromises.readFile(destination, 'utf8'), 'payload');
});
it('changes the spelling of a directory', async function () {
const source = path.join(root, 'App');
const destination = path.join(root, 'app');
await fsPromises.mkdir(source);
await fsPromises.writeFile(path.join(source, 'payload.txt'), 'payload');
// a directory destination is read with stat, and the rename still checks lstat
const sourceStat = await fsPromises.lstat(source, {bigint: true});
sandbox.stub(fsPromises, 'stat').callThrough().withArgs(destination, {bigint: true}).resolves(sourceStat);
sandbox.stub(fsPromises, 'lstat').callThrough().withArgs(destination, {bigint: true}).resolves(sourceStat);
await fs.mv(source, destination);
assert.deepEqual(await fsPromises.readdir(root), ['app']);
assert.equal(await fsPromises.readFile(path.join(destination, 'payload.txt'), 'utf8'), 'payload');
});
});