mirror of
https://github.com/appium/appium.git
synced 2026-11-17 08:07:03 +08:00
Compare commits
14
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
51cfc7b292 | ||
|
|
e67a1980b0 | ||
|
|
8bd55ec338 | ||
|
|
aad17b1ba9 | ||
|
|
a8d646b6cc | ||
|
|
2b232adb2a | ||
|
|
2a6ef950f0 | ||
|
|
96bcc11ff4 | ||
|
|
f7ccf0fb7c | ||
|
|
5e1ec327c4 | ||
|
|
61bfbebe3c | ||
|
|
6447e97999 | ||
|
|
5cf9d9bba6 | ||
|
|
0f5284f1f4 |
@@ -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
@@ -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))
|
||||
|
||||
@@ -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/)
|
||||
|
||||
|
||||
Generated
+483
-1588
File diff suppressed because it is too large
Load Diff
+4
-4
@@ -88,7 +88,7 @@
|
||||
"@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
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 });
|
||||
```
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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` |
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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).
|
||||
如果没有这个请求头,上述日志值将不会被掩码处理。这样就可以根据扩展处理的具体请求来有条件地屏蔽日志记录;如果日志表达式位于公共部分,就可以在这里统一控制。
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 });
|
||||
```
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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 命令集的示例(注意,这不是包含所有导入的工作示例代码;请参阅每个客户端库的设置和命令参考说明):
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -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` |
|
||||
|
||||
@@ -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"
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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": {
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -54,7 +54,7 @@
|
||||
},
|
||||
"dependencies": {
|
||||
"@appium/support": "~8.0.0",
|
||||
"asyncbox": "^6.6.0"
|
||||
"asyncbox": "^7.0.0"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@appium/types": "~2.0.0"
|
||||
|
||||
@@ -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);
|
||||
});
|
||||
|
||||
@@ -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/);
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
@@ -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]> = {}) {
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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;
|
||||
|
||||
|
||||
@@ -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,
|
||||
};
|
||||
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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"
|
||||
},
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -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');
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user