appium-mac2-driver 4.0.3 → 4.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/CHANGELOG.md +6 -0
  2. package/README.md +25 -963
  3. package/npm-shrinkwrap.json +102 -49
  4. package/package.json +6 -1
package/README.md CHANGED
@@ -1,977 +1,39 @@
1
- Appium Mac2 Driver
2
- ====
1
+ ## Appium Mac2 Driver
2
+
3
+ <p align="center">
4
+ <a href="https://appium.github.io/appium-mac2-driver/">
5
+ <picture>
6
+ <source media="(prefers-color-scheme: light)" srcset="docs/assets/images/appium-plus-mac2-light.png">
7
+ <source media="(prefers-color-scheme: dark)" srcset="docs/assets/images/appium-plus-mac2-dark.png">
8
+ <img width="400" alt="Appium Mac2 Driver">
9
+ </picture>
10
+ </a>
11
+ </p>
12
+
13
+ <div align="center">
3
14
 
4
15
  [![NPM version](http://img.shields.io/npm/v/appium-mac2-driver.svg)](https://npmjs.org/package/appium-mac2-driver)
5
16
  [![Downloads](http://img.shields.io/npm/dm/appium-mac2-driver.svg)](https://npmjs.org/package/appium-mac2-driver)
6
-
7
17
  [![Release](https://github.com/appium/appium-mac2-driver/actions/workflows/publish.js.yml/badge.svg)](https://github.com/appium/appium-mac2-driver/actions/workflows/publish.js.yml)
8
18
 
19
+ </div>
9
20
 
10
- This is Appium driver for automating macOS applications using Apple's [XCTest](https://developer.apple.com/documentation/xctest) framework.
11
- The driver operates in scope of [W3C WebDriver protocol](https://www.w3.org/TR/webdriver/) with several custom extensions to cover operating-system specific scenarios.
12
- The original idea and parts of the source code are borrowed from the Facebook's [WebDriverAgent](https://github.com/facebookarchive/WebDriverAgent) project.
13
-
14
- > [!IMPORTANT]
15
- > Since major version *3.0.0*, this driver is only compatible with Appium 3. Use the `appium driver install mac2`
16
- > command to add it to your dist.
17
-
18
-
19
- ## Requirements
20
-
21
- On top of standard Appium requirements Mac2 driver also expects the following prerequisites:
22
-
23
- - macOS 11 or later
24
- - Xcode 13 or later should be installed
25
- - `xcode-select` should be pointing to `<full_path_to_xcode_app>/Contents/Developer` developer directory instead of `/Library/Developer/CommandLineTools` to run `xcodebuild` commands
26
- - Xcode Helper app should be enabled for Accessibility access. The app itself could be usually found at `/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/Library/Xcode/Agents/Xcode Helper.app`. In order to enable Accessibility access for it simply open the parent folder in Finder: `open /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/Library/Xcode/Agents/` and drag & drop the `Xcode Helper` app to `Security & Privacy -> Privacy -> Accessibility` list of your `System Settings`. This action must only be done once.
27
- - `testmanagerd` process requires UIAutomation authentication since macOS 12. `automationmodetool enable-automationmode-without-authentication` command may help to disable it. This may be particularly useful in CI environments. [Apple forum thread](https://developer.apple.com/forums/thread/693850).
28
-
29
- ### Doctor
30
-
31
- Since driver version 1.9.0 you can automate the validation for the most of the above
32
- requirements as well as various optional ones needed by driver extensions by running the
33
- `appium driver doctor mac2` server command.
34
-
35
-
36
- ## Capabilities
37
-
38
- Capability Name | Description
39
- --- | ---
40
- platformName | Should be set to `mac`
41
- automationName | Must always be set to `mac2`. Values of automationName are compared case-insensitively.
42
- appium:systemPort | The number of the port for the internal server to listen on. If not provided then Mac2Driver will use the default port `10100`.
43
- appium:systemHost | The name of the host for the internal server to listen on. If not provided then Mac2Driver will use the default host address `127.0.0.1`. You could set it to `0.0.0.0` to make the server listening on all available network interfaces. It is also possible to set the particular interface name, for example `en1`.
44
- appium:webDriverAgentMacUrl | Appium will connect to an existing WebDriverAgentMac instance at this URL instead of starting a new one. e.g. `http://192.168.10.1:10101`
45
- appium:showServerLogs | Set it to `true` in order to include xcodebuild output to the Appium server log. `false` by default.
46
- appium:bootstrapRoot | The full path to `WebDriverAgentMac` root folder where Xcode project of the server sources lives. By default this project is located in the same folder where the corresponding driver Node.js module lives.
47
- appium:serverStartupTimeout | The number of milliseconds to wait util the WebDriverAgentMac project is built and started. `120000` by default
48
- appium:bundleId | The bundle identifier of the application to automate, for example `com.apple.TextEdit`. This is an optional capability. If it is not provided then the session will be started without an application under test (actually, it will be Finder). If the application with the given identifier is not installed then an error will be thrown on session startup. If the application is already running then it will be moved to the foreground.
49
- appium:arguments | Array of application command line arguments. This capability is only going to be applied if the application is not running on session startup.
50
- appium:environment | A dictionary of environment variables (name->value) that are going to be passed to the application under test on top of environment variables inherited from the parent process. This capability is only going to be applied if the application is not running on session startup.
51
- appium:skipAppKill | Whether to skip the termination of the application under test when the testing session quits. `false` by default. This capability is only going to be applied if `bundleId` is set.
52
- appium:prerun | An object containing either `script` or `command` key. The value of each key must be a valid AppleScript script or command to be executed prior to the Mac2Driver session startup. See [AppleScript commands execution](#applescript-commands-execution) for more details. Example: `{command: 'do shell script "echo hello"'}`
53
- appium:postrun | An object containing either `script` or `command` key. The value of each key must be a valid AppleScript script or command to be executed after Mac2Driver session is stopped. See [AppleScript commands execution](#applescript-commands-execution) for more details.
54
- appium:noReset | Whether to restart the app whose bundle identifier was passed to capabilities as `bundleId` value if it was already running on the session startup (`false`, the default value) or just pick it up without changing the app state (`true`). Note that neither of `arguments` or `environment` capabilities will take effect if the app did not restart.
55
- appium:appPath | The path to the application to automate, for example `/Applications/MyAppName.app`. This is an optional capability, but it requires `bundleId` to be present until mac2 driver v1.13.0. In earlier versions if `bundleId` is empty, `appPath` would be ignored. If the path is invalid or application is damaged/incomplete then an error will be thrown on session startup. This capability could be useful when you have multiple builds of the same application with the same bundleId on your machine (for example one production build in /Applications/ and several dev builds). If you provide bundleId only, the operating system could open any of these builds. By providing `appPath` you have a guarantee that the specified .app will be launched, rather than a random one.
56
- appium:appLocale | A dictionary with the following possible entries: `locale` (application locale name, for example `uk_UA`), `language` (application language name, for example `de`), `useMetricUnits` (whether to use metric units for the app, if `false` then imperial units are used), `measurementUnits` (the name of measurement units to use in the app, for example `Inches`). This capability only changes the locale for the app under test, it does not modify the system locale. You can achieve the same effect by providing custom values to reserved app command line arguments like `-AppleLanguages` or `-AppleLocale` using the `appium:arguments` capability. Example: use `appLocale = {locale: "de", language: "de_DE"}` to start the app in German language (if no German resources are defined in the destination app bundle then the app is started with the default locale, usually en_US).
57
- appium:appTimeZone | Defines the custom time zone override for the application under test. You can use UTC, PST, EST, as well as place-based timezone names such as America/Los_Angeles. The application must be (re)launched for the capability to take effect. See the [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) for more details. The same behavior could be achieved by providing a custom value to the [TZ](https://developer.apple.com/forums/thread/86951#263395) environment variable via the `appium:environment` capability
58
- appium:initialDeeplinkUrl | A deeplink URL used to run either the application assigned to `appium:bundleId`, or the default application assigned to handle the particular deeplink protocol if `appium:bundleId` is not set. An error is thrown on session init if either the value of the capability is not a valid URL, or XCTest was not able to associate it with any existing app, or the actual Xcode version is below *14.3*
59
-
60
- ## Element Attributes
61
-
62
- Mac2 driver supports the following element attributes:
63
-
64
- Name | Description | Example
65
- --- | --- | ---
66
- elementType | Integer-encoded element class. See the official documentation on [XCUIElementType enumeration](https://developer.apple.com/documentation/xctest/xcuielementtype?language=objc) for more details. | '2'
67
- frame | Coordinates of bounding element rectangle | {x: 1, y: 2.5, width: 100, height: 200}
68
- placeholderValue | It is usually only present for text fields. For other element types it's mostly empty | 'my placeholder'
69
- enabled | Contains `true` if the element is enabled | 'false'
70
- focused | Contains `true` if the element has the keyboard input focus | 'false'
71
- selected | Contains `true` if the element is selected | 'false'
72
- hittable | Contains `true` if the element is hittable | 'true'
73
- label | Element's label value. Could be empty | 'my label'
74
- title | Element's title value. Could be empty | 'my title'
75
- identifier | Element's accessibility identifier. Could be empty | 'identifier'
76
- value | The value could be different depending on the actual element type. For example, text fields might have their text context there and sliders would contain the float position value, while switches would have either `1` or `0` | '1.5'
77
-
78
- These attribute values could be retrieved from the page source output and then used for elements location. See the official documentation on [XCUIElementAttributes protocol](https://developer.apple.com/documentation/xctest/xcuielementattributes?language=objc) for more details on each attribute.
79
-
80
- ## Element Location
81
-
82
- Mac2 driver supports the following location strategies:
83
-
84
- Name | Description | Speed Ranking | Pseudocode
85
- --- | --- | --- | ---
86
- accessibilityId, id, name | These all strategies are mapped to the same Mac2 driver ByIdentifier lookup strategy. The locator matches the passed value with element's `identifier` attribute case-sensitively. | `⭐⭐⭐⭐⭐` | AppiumBy.accessibilityId("identifier"), By.id("identifier"), By.name("identifier")
87
- className | Class name uses stringified element types for lookup | `⭐⭐⭐⭐⭐` | By.className("XCUIElementTypePopUpButton")
88
- predicate | Lookup by predicate is natively supported by XCTest and is as fast as previous lookup strategies. This lookup strategy could only use the supported [element attributes](#element-attributes). Unknown attribute names would throw an exception. Check [NSPredicate cheat sheet](https://academy.realm.io/posts/nspredicate-cheatsheet/) for more details on how to build effective and flexible locators. | `⭐⭐⭐⭐⭐` | AppiumBy.iOSNsPredicateString("elementType == 2 AND label BEGINSWITH 'Safari'")
89
- classChain | This strategy is a combination of Xpath flexibility and fast predicate lookup. Prefer it over Xpath unless there is no other way to build the desired locator. Visit [Class Chain Construction Rules tutorial](https://github.com/facebookarchive/WebDriverAgent/wiki/Class-Chain-Queries-Construction-Rules) to get more knowledge on how to build class chain locators. | `⭐⭐⭐⭐` | AppiumBy.iOSClassChain("**/XCUIElementTypeRuler[$elementType == 72 AND value BEGINSWITH '10'$]")
90
- xpath | For elements lookup XPath strategy the driver uses the same XML tree that is generated by page source API. [XPath 2.0](https://www.w3.org/TR/xpath20/) is supported since driver version 1.20.0. All driver versions below 1.20.0 only support XPath 1.0 (based on xmllib2). | `⭐⭐⭐` | By.xpath("//XCUIElementTypePopUpButton[@value=\"Regular\" and @label=\"type face\"]")
91
-
92
- Check the [integration tests](/test/functional/find-e2e-specs.js) for more examples on different location strategies usage.
93
-
94
-
95
- ## Platform-Specific Extensions
96
-
97
- Beside of standard W3C APIs the driver provides the below custom command extensions to execute platform specific scenarios. Use the following source code examples in order to invoke them from your client code:
98
-
99
- ```java
100
- // Java 11+
101
- var result = driver.executeScript("macos: <methodName>", Map.of(
102
- "arg1", "value1",
103
- "arg2", "value2"
104
- // you may add more pairs if needed or skip providing the map completely
105
- // if all arguments are defined as optional
106
- ));
107
- ```
108
-
109
- ```js
110
- // WebdriverIO
111
- const result = await driver.executeScript('macos: <methodName>', [{
112
- arg1: "value1",
113
- arg2: "value2",
114
- }]);
115
- ```
116
-
117
- ```python
118
- # Python
119
- result = driver.execute_script('macos: <methodName>', {
120
- 'arg1': 'value1',
121
- 'arg2': 'value2',
122
- })
123
- ```
124
-
125
- ```ruby
126
- # Ruby
127
- result = @driver.execute_script 'macos: <methodName>', {
128
- arg1: 'value1',
129
- arg2: 'value2',
130
- }
131
- ```
132
-
133
- ```csharp
134
- // Dotnet
135
- object result = driver.ExecuteScript("macos: <methodName>", new Dictionary<string, object>() {
136
- {"arg1", "value1"},
137
- {"arg2", "value2"}
138
- });
139
- ```
140
-
141
- ### macos: click
142
-
143
- Perform click gesture on an element or by relative/absolute coordinates
144
-
145
- #### Arguments
146
-
147
- Name | Type | Required | Description | Example
148
- --- | --- | --- | --- | ---
149
- elementId ("element" prior to Appium v 1.22) | string | if `x` or `y` are unset | Unique identifier of the element to perform the click on. Either this property or/and x and y must be set. If both are set then x and y are considered as relative element coordinates. If only x and y are set then these are parsed as absolute coordinates. | 21045BC8-013C-43BD-9B1E-4C6DC7AB0744
150
- x | number | if `y` is set or `elementId` is unset | click X coordinate | 100
151
- y | number | if `x` is set or `elementId` is unset | click Y coordinate | 100
152
- keyModifierFlags | number | no | if set then the given key modifiers will be applied while click is performed. See the official documentation on [XCUIKeyModifierFlags enumeration](https://developer.apple.com/documentation/xctest/xcuikeymodifierflags) for more details | `1 << 1 | 1 << 2`
153
-
154
- #### References
155
-
156
- - [click (XCUIElement)](https://developer.apple.com/documentation/xctest/xcuielement/1500316-click?language=objc)
157
- - [click (XCUICoordinate)](https://developer.apple.com/documentation/xctest/xcuicoordinate/1500677-click?language=objc)
158
-
159
- ### macos: scroll
160
-
161
- Perform scroll gesture on an element or by relative/absolute coordinates
162
-
163
- #### Arguments
164
-
165
- Name | Type | Required | Description | Example
166
- --- | --- | --- | --- | ---
167
- elementId ("element" prior to Appium v 1.22) | string | if `x` or `y` are unset | Unique identifier of the element to be scrolled. Either this property or/and x and y must be set. If both are set then x and y are considered as relative element coordinates. If only x and y are set then these are parsed as absolute coordinates. | 21045BC8-013C-43BD-9B1E-4C6DC7AB0744
168
- x | number | if `y` is set or `elementId` is unset | scroll X coordinate | 100
169
- y | number | if `y` is set or `elementId` is unset | scroll Y coordinate | 100
170
- deltaX | number | yes | Horizontal delta as float number. Could be negative | 100
171
- deltaY | number | yes | vertical delta as float number. Could be negative | 100
172
- keyModifierFlags | number | no | if set then the given key modifiers will be applied while scroll is performed. See the official documentation on [XCUIKeyModifierFlags enumeration](https://developer.apple.com/documentation/xctest/xcuikeymodifierflags) for more details | `1 << 1 | 1 << 2`
173
-
174
- #### References
175
-
176
- - [scrollByDeltaX:deltaY: (XCUIElement)](https://developer.apple.com/documentation/xctest/xcuielement/1500758-scrollbydeltax?language=objc)
177
- - [scrollByDeltaX:deltaY: (XCUICoordinate)](https://developer.apple.com/documentation/xctest/xcuicoordinate?language=objc)
178
-
179
- ### macos: rightClick
180
-
181
- Perform right click gesture on an element or by relative/absolute coordinates
182
-
183
- #### Arguments
184
-
185
- Name | Type | Required | Description | Example
186
- --- | --- | --- | --- | ---
187
- elementId ("element" prior to Appium v 1.22) | string | if `x` or `y` are unset | Unique identifier of the element to perform the right click on. Either this property or/and x and y must be set. If both are set then x and y are considered as relative element coordinates. If only x and y are set then these are parsed as absolute coordinates. | 21045BC8-013C-43BD-9B1E-4C6DC7AB0744
188
- x | number | if `y` is set or `elementId` is unset | right click X coordinate | 100
189
- y | number | if `y` is set or `elementId` is unset | right click Y coordinate | 100
190
- keyModifierFlags | number | no | if set then the given key modifiers will be applied while right click is performed. See the official documentation on [XCUIKeyModifierFlags enumeration](https://developer.apple.com/documentation/xctest/xcuikeymodifierflags) for more details | `1 << 1 | 1 << 2`
191
-
192
- #### References
193
-
194
- - [rightClick (XCUIElement)](https://developer.apple.com/documentation/xctest/xcuielement/1500469-rightclick?language=objc)
195
- - [rightClick (XCUICoordinate)](https://developer.apple.com/documentation/xctest/xcuicoordinate/1500503-rightclick?language=objc)
196
-
197
- ### macos: hover
198
-
199
- Perform hover gesture on an element or by relative/absolute coordinates
200
-
201
- #### Arguments
202
-
203
- Name | Type | Required | Description | Example
204
- --- | --- | --- | --- | ---
205
- elementId ("element" prior to Appium v 1.22) | string | if `x` or `y` are unset | Unique identifier of the element to perform the hover on. Either this property or/and x and y must be set. If both are set then x and y are considered as relative element coordinates. If only x and y are set then these are parsed as absolute coordinates. | 21045BC8-013C-43BD-9B1E-4C6DC7AB0744
206
- x | number | if `y` is set or `elementId` is unset | long click X coordinate | 100
207
- y | number | if `y` is set or `elementId` is unset | long click Y coordinate | 100
208
- keyModifierFlags | number | no | if set then the given key modifiers will be applied while hover is performed. See the official documentation on [XCUIKeyModifierFlags enumeration](https://developer.apple.com/documentation/xctest/xcuikeymodifierflags) for more details | `1 << 1 | 1 << 2`
209
-
210
- #### References
211
-
212
- - [hover (XCUIElement)](https://developer.apple.com/documentation/xctest/xcuielement/1500437-hover?language=objc)
213
- - [hover (XCUICoordinate)](https://developer.apple.com/documentation/xctest/xcuicoordinate/1501021-hover?language=objc)
214
-
215
- ### macos: doubleClick
216
-
217
- Perform double click gesture on an element or by relative/absolute coordinates
218
-
219
- #### Arguments
220
-
221
- Name | Type | Required | Description | Example
222
- --- | --- | --- | --- | ---
223
- elementId ("element" prior to Appium v 1.22) | string | if `x` or `y` are unset | Unique identifier of the element to perform the double click on. Either this property or/and x and y must be set. If both are set then x and y are considered as relative element coordinates. If only x and y are set then these are parsed as absolute coordinates. | 21045BC8-013C-43BD-9B1E-4C6DC7AB0744
224
- x | number | if `y` is set or `elementId` is unset | double click X coordinate | 100
225
- y | number | if `y` is set or `elementId` is unset | double click Y coordinate | 100
226
- keyModifierFlags | number | no | if set then the given key modifiers will be applied while click is performed. See the official documentation on [XCUIKeyModifierFlags enumeration](https://developer.apple.com/documentation/xctest/xcuikeymodifierflags) for more details | `1 << 1 | 1 << 2`
227
-
228
- #### References
229
-
230
- - [doubleClick (XCUIElement)](https://developer.apple.com/documentation/xctest/xcuielement/1500571-doubleclick?language=objc)
231
- - [doubleClick (XCUICoordinate)](https://developer.apple.com/documentation/xctest/xcuicoordinate/1500302-doubleclick?language=objc)
232
-
233
- ### macos: clickAndDrag
234
-
235
- Perform long click and drag gesture on an element or by absolute coordinates
236
-
237
- #### Arguments
238
-
239
- Name | Type | Required | Description | Example
240
- --- | --- | --- | --- | ---
241
- sourceElementId ("sourceElement" prior to Appium v 1.22) | string | if `startX`, `startY`, `endX` and `endY` are unset or if `destinationElementId` is set | Uuid of the element to start the drag from. | 21045BC8-013C-43BD-9B1E-4C6DC7AB0744
242
- destinationElementId ("destinationElement" prior to Appium v 1.22) | string | if `startX`, `startY`, `endX` and `endY` are unset or if `sourceElementId` is set | Uuid of the element to end the drag on. | 21045BC8-013C-43BD-9B1E-4C6DC7AB0745
243
- startX | number | if `sourceElementId` and `destinationElementId` are unset | starting X coordinate | 100
244
- startY | number | if `sourceElementId` and `destinationElementId` are unset | starting Y coordinate | 110
245
- endX | number | if `sourceElementId` and `destinationElementId` are unset | end X coordinate | 200
246
- endY | number | if `sourceElementId` and `destinationElementId` are unset | end Y coordinate | 220
247
- duration | number | yes | The number of float seconds to hold the mouse button | 2.5
248
- keyModifierFlags | number | no | if set then the given key modifiers will be applied while drag is performed. See the official documentation on [XCUIKeyModifierFlags enumeration](https://developer.apple.com/documentation/xctest/xcuikeymodifierflags) for more details | `1 << 1 | 1 << 2`
249
-
250
- #### References
251
-
252
- - [clickForDuration:thenDragToElement (XCUIElement)](https://developer.apple.com/documentation/xctest/xcuielement/1500989-clickforduration?language=objc)
253
- - [clickForDuration:thenDragToCoordinate: (XCUICoordinate)](https://developer.apple.com/documentation/xctest/xcuicoordinate/1500369-clickforduration?language=objc)
254
-
255
- ### macos: clickAndDragAndHold
256
-
257
- Perform long click, drag and hold gesture on an element or by absolute coordinates
258
-
259
- #### Arguments
260
-
261
- Name | Type | Required | Description | Example
262
- --- | --- | --- | --- | ---
263
- sourceElementId ("sourceElement" prior to Appium v 1.22) | string | if `startX`, `startY`, `endX` and `endY` are unset or if `destinationElementId` is set | Uuid of the element to start the drag from. | 21045BC8-013C-43BD-9B1E-4C6DC7AB0744
264
- destinationElementId ("destinationElement" prior to Appium v 1.22) | string | if `startX`, `startY`, `endX` and `endY` are unset or if `sourceElementId` is set | Uuid of the element to end the drag on. | 21045BC8-013C-43BD-9B1E-4C6DC7AB0745
265
- startX | number | if `sourceElementId` and `destinationElementId` are unset | starting X coordinate | 100
266
- startY | number | if `sourceElementId` and `destinationElementId` are unset | starting Y coordinate | 110
267
- endX | number | if `sourceElementId` and `destinationElementId` are unset | end X coordinate | 200
268
- endY | number | if `sourceElementId` and `destinationElementId` are unset | end Y coordinate | 220
269
- duration | number | yes | The number of float seconds to hold the mouse button | 2.5
270
- holdDuration | number | yes | Touch hold duration in float seconds | 2.5
271
- velocity | number | no | Dragging velocity in pixels per second. If not provided then the default velocity is used. See official documentation on [XCUIGestureVelocity structure](https://developer.apple.com/documentation/xctest/xcuigesturevelocity) for more details | 2500
272
- keyModifierFlags | number | no | if set then the given key modifiers will be applied while drag is performed. See the official documentation on [XCUIKeyModifierFlags enumeration](https://developer.apple.com/documentation/xctest/xcuikeymodifierflags) for more details | `1 << 1 | 1 << 2`
273
-
274
- #### References
275
-
276
- - [clickForDuration:thenDragToElement:withVelocity:thenHoldForDuration: (XCUIElement)](https://developer.apple.com/documentation/xctest/xcuielement/3553192-clickforduration?language=objc)
277
- - [clickForDuration:thenDragToCoordinate:withVelocity:thenHoldForDuration: (XCUICoordinate)](https://developer.apple.com/documentation/xctest/xcuicoordinate/3553191-clickforduration?language=objc)
278
-
279
- ### macos: swipe
280
-
281
- This extension performs a swipe gesture on the particular screen element or by given coordinates.
282
- The API is only available on macOS since Xcode SDK 13.
283
-
284
- #### Arguments
285
-
286
- Name | Type | Required | Description | Example
287
- --- | --- | --- | --- | ---
288
- elementId ("element" prior to Appium v 1.22) | string | if `x` or `y` are unset | The internal element identifier (as hexadecimal hash string) to swipe on. If both are set then x and y are considered as relative element coordinates. If only x and y are set then these are parsed as absolute coordinates. | fe50b60b-916d-420b-8728-ee2072ec53eb
289
- x | number | if `y` is set or `elementId` is unset | long click X coordinate | 100
290
- y | number | if `y` is set or `elementId` is unset | long click Y coordinate | 100
291
- direction | Either 'up', 'down', 'left' or 'right' | yes | The direction in which to swipe | up
292
- velocity | number | no | The value is measured in pixels per second and same values could behave differently on different devices depending on their display density. Higher values make swipe gesture faster (which usually scrolls larger areas if we apply it to a list) and lower values slow it down. Only values greater than zero have effect. | 250
293
- keyModifierFlags | number | no | if set then the given key modifiers will be applied while swipe is performed. See the official documentation on [XCUIKeyModifierFlags enumeration](https://developer.apple.com/documentation/xctest/xcuikeymodifierflags) for more details | `1 << 1 | 1 << 2`
294
-
295
- #### References
296
-
297
- - [swipeDown (XCUIElement)](https://developer.apple.com/documentation/xctest/xcuielement/1618664-swipedown?language=objc)
298
- - [swipeDown (XCUICoordinate)](https://developer.apple.com/documentation/xctest/xcuicoordinate/3752780-swipedown?language=objc)
299
- - [swipeDownWithVelocity: (XCUIElement)](https://developer.apple.com/documentation/xctest/xcuielement/3551694-swipedownwithvelocity?language=objc)
300
- - [swipeDownWithVelocity: (XCUICoordinate)](https://developer.apple.com/documentation/xctest/xcuicoordinate/3752781-swipedownwithvelocity?language=objc)
301
- - ...
302
-
303
- ### macos: press
304
-
305
- Perform press gesture on a Touch Bar element or by relative/absolute coordinates
306
-
307
- #### Arguments
308
-
309
- Name | Type | Required | Description | Example
310
- --- | --- | --- | --- | ---
311
- elementId | string | if `x` or `y` are unset | Unique identifier of a Touch Bar element to perform the press on. Either this property or/and x and y must be set. If both are set then x and y are considered as relative element coordinates. If only x and y are set then these are parsed as absolute Touch Bar coordinates. | 21045BC8-013C-43BD-9B1E-4C6DC7AB0744
312
- x | number | if `y` is set or `elementId` is unset | long click X coordinate | 100
313
- y | number | if `y` is set or `elementId` is unset | long click Y coordinate | 100
314
- duration | number | yes | The number of float seconds to hold the touch | 2.5
315
- keyModifierFlags | number | no | if set then the given key modifiers will be applied while the gesture is performed. See the official documentation on [XCUIKeyModifierFlags enumeration](https://developer.apple.com/documentation/xctest/xcuikeymodifierflags) for more details | `1 << 1 | 1 << 2`
316
-
317
- #### References
318
-
319
- - [pressForDuration: (XCUIElement)](https://developer.apple.com/documentation/xctest/xcuielement/1618663-pressforduration?language=objc)
320
- - [pressForDuration: (XCUICoordinate)](https://developer.apple.com/documentation/xctest/xcuicoordinate/1615002-pressforduration?language=objc)
321
-
322
- ### macos: tap
323
-
324
- Perform tap gesture on a Touch Bar element or by relative/absolute coordinates
325
-
326
- #### Arguments
327
-
328
- Name | Type | Required | Description | Example
329
- --- | --- | --- | --- | ---
330
- elementId | string | if `x` or `y` are unset | Unique identifier of a Touch Bar element to perform the tap on. Either this property or/and x and y must be set. If both are set then x and y are considered as relative element coordinates. If only x and y are set then these are parsed as absolute Touch Bar coordinates. | 21045BC8-013C-43BD-9B1E-4C6DC7AB0744
331
- x | number | if `y` is set or `elementId` is unset | click X coordinate | 100
332
- y | number | if `y` is set or `elementId` is unset | click Y coordinate | 100
333
- keyModifierFlags | number | no | if set then the given key modifiers will be applied while the gesture is performed. See the official documentation on [XCUIKeyModifierFlags enumeration](https://developer.apple.com/documentation/xctest/xcuikeymodifierflags) for more details | `1 << 1 | 1 << 2`
334
-
335
- #### References
336
-
337
- - [tap (XCUIElement)](https://developer.apple.com/documentation/xctest/xcuielement/1618666-tap?language=objc)
338
- - [tap (XCUICoordinate)](https://developer.apple.com/documentation/xctest/xcuicoordinate/1615004-tap?language=objc)
339
-
340
- ### macos: doubleTap
341
-
342
- Perform double tap gesture on a Touch Bar element or by relative/absolute coordinates
343
-
344
- #### Arguments
345
-
346
- Name | Type | Required | Description | Example
347
- --- | --- | --- | --- | ---
348
- elementId | string | if `x` or `y` are unset | Unique identifier of a Touch Bar element to perform the double tap on. Either this property or/and x and y must be set. If both are set then x and y are considered as relative element coordinates. If only x and y are set then these are parsed as absolute Touch Bar coordinates. | 21045BC8-013C-43BD-9B1E-4C6DC7AB0744
349
- x | number | if `y` is set or `elementId` is unset | click X coordinate | 100
350
- y | number | if `y` is set or `elementId` is unset | click Y coordinate | 100
351
- keyModifierFlags | number | no | if set then the given key modifiers will be applied while the gesture is performed. See the official documentation on [XCUIKeyModifierFlags enumeration](https://developer.apple.com/documentation/xctest/xcuikeymodifierflags) for more details | `1 << 1 | 1 << 2`
352
-
353
- #### References
354
-
355
- - [doubleTap (XCUIElement)](https://developer.apple.com/documentation/xctest/xcuielement/1618673-doubletap?language=objc)
356
- - [doubleTap (XCUICoordinate)](https://developer.apple.com/documentation/xctest/xcuicoordinate/1615005-doubletap?language=objc)
357
-
358
- ### macos: pressAndDrag
359
-
360
- Perform long press and drag gesture on a Touch Bar element or by absolute Touch Bar coordinates
361
-
362
- #### Arguments
363
-
364
- Name | Type | Required | Description | Example
365
- --- | --- | --- | --- | ---
366
- sourceElementId | string | if `startX`, `startY`, `endX` and `endY` are unset or if `destinationElementId` is set | Uuid of a Touch Bar element to start the drag from. | 21045BC8-013C-43BD-9B1E-4C6DC7AB0744
367
- destinationElementId | string | if `startX`, `startY`, `endX` and `endY` are unset or if `sourceElementId` is set | Uuid of a Touch Bar element to end the drag on. | 21045BC8-013C-43BD-9B1E-4C6DC7AB0745
368
- startX | number | if `sourceElementId` and `destinationElementId` are unset | starting X coordinate | 100
369
- startY | number | if `sourceElementId` and `destinationElementId` are unset | starting Y coordinate | 110
370
- endX | number | if `sourceElementId` and `destinationElementId` are unset | end X coordinate | 200
371
- endY | number | if `sourceElementId` and `destinationElementId` are unset | end Y coordinate | 220
372
- duration | number | yes | The number of float seconds to hold the touch | 2.5
373
- keyModifierFlags | number | no | if set then the given key modifiers will be applied while the gesture is performed. See the official documentation on [XCUIKeyModifierFlags enumeration](https://developer.apple.com/documentation/xctest/xcuikeymodifierflags) for more details | `1 << 1 | 1 << 2`
374
-
375
- #### References
376
-
377
- - [pressForDuration:thenDragToElement: (XCUIElement)](https://developer.apple.com/documentation/xctest/xcuielement/1618670-pressforduration?language=objc)
378
- - [pressForDuration:thenDragToCoordinate: (XCUICoordinate)](https://developer.apple.com/documentation/xctest/xcuicoordinate/1615003-pressforduration?language=objc)
379
-
380
- ### macos: pressAndDragAndHold
381
-
382
- Perform long press, drag and hold gesture on a Touch Bar element or by absolute Touch Bar coordinates
383
-
384
- #### Arguments
385
-
386
- Name | Type | Required | Description | Example
387
- --- | --- | --- | --- | ---
388
- sourceElementId | string | if `startX`, `startY`, `endX` and `endY` are unset or if `destinationElementId` is set | Uuid of a Touch Bar element to start the drag from. | 21045BC8-013C-43BD-9B1E-4C6DC7AB0744
389
- destinationElementId | string | if `startX`, `startY`, `endX` and `endY` are unset or if `sourceElementId` is set | Uuid of a Touch Bar element to end the drag on. | 21045BC8-013C-43BD-9B1E-4C6DC7AB0745
390
- startX | number | if `sourceElementId` and `destinationElementId` are unset | starting X coordinate | 100
391
- startY | number | if `sourceElementId` and `destinationElementId` are unset | starting Y coordinate | 110
392
- endX | number | if `sourceElementId` and `destinationElementId` are unset | end X coordinate | 200
393
- endY | number | if `sourceElementId` and `destinationElementId` are unset | end Y coordinate | 220
394
- duration | number | yes | The number of float seconds to hold the touch | 2.5
395
- holdDuration | number | yes | Touch hold duration in float seconds | 2.5
396
- velocity | number | no | Dragging velocity in pixels per second. If not provided then the default velocity is used. See official documentation on [XCUIGestureVelocity structure](https://developer.apple.com/documentation/xctest/xcuigesturevelocity) for more details | 2500
397
- keyModifierFlags | number | no | if set then the given key modifiers will be applied while the gesture is performed. See the official documentation on [XCUIKeyModifierFlags enumeration](https://developer.apple.com/documentation/xctest/xcuikeymodifierflags) for more details | `1 << 1 | 1 << 2`
398
-
399
- #### References
400
-
401
- - [pressForDuration:thenDragToElement:withVelocity:thenHoldForDuration: (XCUIElement)](https://developer.apple.com/documentation/xctest/xcuielement/3551693-pressforduration?language=objc)
402
- - [pressForDuration:thenDragToCoordinate:withVelocity:thenHoldForDuration: (XCUICoordinate)](https://developer.apple.com/documentation/xctest/xcuicoordinate/3551692-pressforduration?language=objc)
403
-
404
- ### macos: keys
405
-
406
- Send keys to the given element or to the application under test
407
-
408
- #### Arguments
409
-
410
- Name | Type | Required | Description | Example
411
- --- | --- | --- | --- | ---
412
- elementId ("element" prior to Appium v 1.22) | string | no | Unique identifier of the element to send the keys to. If unset then keys are sent to the current application under test. | 21045BC8-013C-43BD-9B1E-4C6DC7AB0744
413
- keys | array | yes | Array of keys to type. Each item could either be a string, that represents a key itself (see the official documentation on XCUIElement's [typeKey:modifierFlags: method](https://developer.apple.com/documentation/xctest/xcuielement/1500604-typekey?language=objc) and on [XCUIKeyboardKey constants](https://developer.apple.com/documentation/xctest/xcuikeyboardkey?language=objc)) or a dictionary with `key` and `modifierFlags` entries, if the key should also be entered with modifiers. | ['h', 'i'] or [{key: 'h', modifierFlags: 1 << 1}, {key: 'i', modifierFlags: 1 << 2}] or ['XCUIKeyboardKeyEscape'] |
414
-
415
- > [!NOTE]
416
- > The `modifierFlags` argument is of `unsigned long` type and defines the bitmask with depressed modifier keys for the given key.
417
- > XCTest defines the following possible bitmasks for modifier keys:
418
- >
419
- > <pre>
420
- > typedef NS_OPTIONS(NSUInteger, XCUIKeyModifierFlags) {
421
- > XCUIKeyModifierNone = 0,
422
- > XCUIKeyModifierCapsLock = (1UL << 0),
423
- > XCUIKeyModifierShift = (1UL << 1),
424
- > XCUIKeyModifierControl = (1UL << 2),
425
- > XCUIKeyModifierOption = (1UL << 3),
426
- > XCUIKeyModifierCommand = (1UL << 4),
427
- > XCUIKeyModifierFunction = (1UL << 5),
428
- > // These values align with UIKeyModifierFlags and CGEventFlags.
429
- > XCUIKeyModifierAlphaShift = XCUIKeyModifierCapsLock,
430
- > XCUIKeyModifierAlternate = XCUIKeyModifierOption,
431
- > };
432
- > </pre>
433
- >
434
- > So, for example, if you want Ctrl and Shift to be depressed while entering your key then `modifierFlags` should be set to
435
- > `(1 << 1) | (1 << 2)`, where the first constant defines `XCUIKeyModifierShift` and the seconds
436
- > one - `XCUIKeyModifierControl`. We apply the [bitwise or](https://www.programiz.com/c-programming/bitwise-operators#or)
437
- > (`|`) operator between them to raise both bitflags
438
- > in the resulting value. The [left bitshift](https://www.programiz.com/c-programming/bitwise-operators#left-shift)
439
- > (`<<`) operator defines the binary bitmask for the given modifier key.
440
- > You may combine more keys using the same approach.
441
-
442
- #### References
443
-
444
- - [typeKey:modifierFlags:](https://developer.apple.com/documentation/xctest/xcuielement/1500604-typekey?language=objc)
445
-
446
- ### macos: source
447
-
448
- Retrieves the string representation of the current application
449
-
450
- #### Arguments
451
-
452
- Name | Type | Required | Description | Example
453
- --- | --- | --- | --- | ---
454
- format | string | yes | The format of the application source to retrieve. Only two formats are supported: `xml` (returns the source formatted as XML document, the default value) and `description` (returns the source formatted as debugDescription output). See the official documentation on XCUIElement's [debugDescription method](https://developer.apple.com/documentation/xctest/xcuielement/1500909-debugdescription?language=objc) for more details. | description
455
-
456
- #### Returns
457
-
458
- The source of the current page in a string representation
459
-
460
- ### macos: launchApp
461
-
462
- Start an app with the given bundle identifier or activates it if the app is already running. An exception is thrown if the app with the given identifier cannot be found.
463
- This API influences the state of the [Application Under Test](#application-under-test-concept).
464
-
465
- #### Arguments
466
-
467
- Name | Type | Required | Description | Example
468
- --- | --- | --- | --- | ---
469
- bundleId | string | no | Bundle identifier of the app to be launched or activated. Either this argument or the `path` one must be provided | com.apple.TextEdit
470
- path | string | no | Full path to the app bundle. Either this argument or the `bundleId` one must be provided | /Applications/Xcode.app
471
- arguments | array | no | the list of command line arguments for the app to be be launched with. This argument is ignored if the app is already running. | ['--help']
472
- environment | dictionary | no | Environment variables mapping. Custom variables are added to the default process environment. This argument is ignored if the app is already running. | { myEnvVar: 'value' }
473
-
474
- ### macos: activateApp
475
-
476
- Activates an app with the given bundle identifier. An exception is thrown if the app with the given identifier cannot be found or if the app is not running.
477
- This API influences the state of the [Application Under Test](#application-under-test-concept).
478
-
479
- #### Arguments
480
-
481
- Name | Type | Required | Description | Example
482
- --- | --- | --- | --- | ---
483
- bundleId | string | no | Bundle identifier of the app to be activated. Either this argument or the `path` one must be provided | com.apple.Finder
484
- path | string | no | Full path to the app bundle. Either this argument or the `bundleId` one must be provided | /Applications/Xcode.app
485
-
486
- ### macos: terminateApp
487
-
488
- Terminate an app with the given bundle identifier. An exception is thrown if the app cannot be found.
489
- This API influences the state of the [Application Under Test](#application-under-test-concept).
490
-
491
- #### Arguments
21
+ ---
492
22
 
493
- Name | Type | Required | Description | Example
494
- --- | --- | --- | --- | ---
495
- bundleId | string | no | Bundle identifier of the app to be terminated. Either this argument or the `path` one must be provided | com.apple.Finder
496
- path | string | no | Full path to the app bundle. Either this argument or the `bundleId` one must be provided | /Applications/Xcode.app
23
+ <p align="center"><b>
24
+ <a href="https://appium.github.io/appium-mac2-driver/">Documentation</a> |
25
+ <a href="https://appium.github.io/appium-mac2-driver/latest/getting-started/">Get Started</a> |
26
+ <a href="https://github.com/appium/appium-mac2-driver/blob/master/CHANGELOG.md">Changelog</a>
27
+ </b></p>
497
28
 
498
- #### Returns
29
+ ---
499
30
 
500
- `true` if the app was running before being terminated
501
-
502
- ### macos: queryAppState
503
-
504
- Query an app state with given bundle identifier. An exception is thrown if the pp cannot be found.
505
-
506
- #### Arguments
507
-
508
- Name | Type | Required | Description | Example
509
- --- | --- | --- | --- | ---
510
- bundleId | string | no | Bundle identifier of the app to be queried. Either this argument or the `path` one must be provided | com.apple.TextEdit
511
- path | string | no | Full path to the app bundle. Either this argument or the `bundleId` one must be provided | /Applications/Xcode.app
512
-
513
- #### Returns
514
-
515
- An integer value representing the application state. See the official documentation on [XCUIApplicationState enumeration](https://developer.apple.com/documentation/xctest/xcuiapplicationstate?language=objc) for more details.
516
-
517
- ### macos: appleScript
518
-
519
- Executes the given AppleScript command or a whole script based on the
520
- given options. Either of these options must be provided. If both are provided
521
- then the `command` one gets the priority.
522
- Note that AppleScript command cannot contain line breaks. Consider making it
523
- to a script in such case.
524
- Note that by default AppleScript engine blocks commands/scripts execution if your script
525
- is trying to access some private entities, like cameras or the desktop screen
526
- and no permissions to do it are given to the parent (for example, Appium or Terminal)
527
- process in System Settings -> Privacy list.
528
- See [AppleScript Commands Execution](#applescript-commands-execution) for more details.
529
-
530
- #### Arguments
531
-
532
- Name | Type | Required | Description | Example
533
- --- | --- | --- | --- | ---
534
- command | string | yes if `script` is not provided | AppleScript command to execute | `do shell script "echo hello"`
535
- script | string | yes if `command` is not provided | AppleScript script to execute | `do shell script "echo hello"\ndo shell script "echo hello2"`
536
- language | string | no | Overrides the scripting language. Basically, sets the value of `-l` command line argument of `osascript` tool. If unset the AppleScript language is assumed. | JavaScript
537
- timeout | number | no | The number of seconds to wait until a long-running blocking command is finished. An error is thrown if the command is still running after this timeout expires. | 60000
538
- cwd | string | no | The path to an existing folder which is going to be set as the working directory for the command/script being executed. | `/tmp`
539
-
540
- #### Returns
541
-
542
- The actual stdout of the provided script if its execution was successful (e.g. got zero return code).
543
-
544
- ### macos: startRecordingScreen
545
-
546
- Record the display in background while the automated test is running. This method requires [FFMPEG](https://www.ffmpeg.org/download.html) to be installed and present in PATH. Also, the Appium process must be allowed to access screen recording in System Settings->Security & Privacy->Screen Recording. The resulting video uses H264 codec and is ready to be played by media players built-in into web browsers.
547
-
548
- #### Arguments
549
-
550
- Name | Type | Required | Description | Example
551
- --- | --- | --- | --- | ---
552
- deviceId | number | yes | Screen device index to use for the recording. The list of available devices could be retrieved using `ffmpeg -f avfoundation -list_devices true -i` command. | 1
553
- videoFilter | string | no | The video filter spec to apply for ffmpeg. See https://trac.ffmpeg.org/wiki/FilteringGuide for more details on the possible values. | Set it to `scale=ifnot(gte(iw\,1024)\,iw\,1024):-2` in order to limit the video width to 1024px. The height will be adjusted automatically to match the actual ratio.
554
- fps | number | no | The count of frames per second in the resulting video. The greater fps it has the bigger file size is. The default vale is `15` | 10
555
- preset | string | no | One of the supported encoding presets. Possible values are: `ultrafast`, `superfast`, `veryfast` (the default value), `faster`, `fast`, `medium`, `slow`, `slower`, `veryslow`. A preset is a collection of options that will provide a certain encoding speed to compression ratio. A slower preset will provide better compression (compression is quality per filesize). This means that, for example, if you target a certain file size or constant bit rate, you will achieve better quality with a slower preset. Read https://trac.ffmpeg.org/wiki/Encode/H.264 for more details. | fast
556
- captureCursor | boolean | no | Whether to capture the mouse cursor while recording the screen. `false` by default | true
557
- captureClicks | boolean | no | Whether to capture mouse clicks while recording the screen. `false` by default | true
558
- timeLimit | number | no | The maximum recording time, in seconds. The default value is 600 seconds (10 minutes) | 300
559
- forceRestart | boolean | no | Whether to ignore the call if a screen recording is currently running (`false`) or to start a new recording immediately and terminate the existing one if running (`true`, the default value). | true
560
-
561
- ### macos: stopRecordingScreen
562
-
563
- Stop recording the screen. If no screen recording has been started before then the method returns an empty string.
564
-
565
- #### Arguments
566
-
567
- Name | Type | Required | Description | Example
568
- --- | --- | --- | --- | ---
569
- remotePath | string | no | The path to the remote location, where the resulting video should be uploaded. The following protocols are supported: http/https, ftp. Null or empty string value (the default setting) means the content of resulting file should be encoded as Base64 and passed as the endpoint response value. An exception will be thrown if the generated media file is too big to fit into the available process memory. | https://myserver.com/upload/video.mp4
570
- user | string | no | The name of the user for the remote authentication. | myname
571
- pass | string | no | The password for the remote authentication. | mypassword
572
- method | string | no | The http multipart upload method name. The 'PUT' one is used by default. | POST
573
- headers | map | no | Additional headers mapping for multipart http(s) uploads | `{"header": "value"}`
574
- fileFieldName | string | no | The name of the form field, where the file content BLOB should be stored for http(s) uploads. `file` by default | payload
575
- formFields | Map or `Array<Pair>` | no | Additional form fields for multipart http(s) uploads | `{"field1": "value1", "field2": "value2"}` or `[["field1", "value1"], ["field2", "value2"]]`
576
-
577
- #### Returns
578
-
579
- Base64-encoded content of the recorded media file if `remotePath` parameter is falsy or an empty string.
580
-
581
- ### macos: screenshots
582
-
583
- Retrieves a screenshot of each display available to macOS.
584
-
585
- #### Arguments
586
-
587
- Name | Type | Required | Description | Example
588
- --- | --- | --- | --- | ---
589
- displayId | number | no | Display identifier to take a screenshot for. If not provided then all display screenshots are going to be returned. If no matches were found then an error is thrown. Use the `system_profiler -json SPDisplaysDataType` Terminal command to list IDs of connected displays or the [macos: listDisplays](#macos-listdisplays) API. | 1
590
-
591
- #### Returns
592
-
593
- A list of dictionaries where each item has the following keys:
594
- - `id`: Display identifier
595
- - `isMain`: Whether this display is the main one
596
- - `payload`: The actual PNG screenshot data encoded to base64 string
597
-
598
- ### macos: deepLink
599
-
600
- Opens the given URL with the default or the given application.
601
- Xcode must be at version 14.3+.
602
-
603
- #### Arguments
604
-
605
- Name | Type | Required | Description | Example
606
- --- | --- | --- | --- | ---
607
- url | string | yes | The URL to be opened. This parameter is manadatory. | https://apple.com, myscheme:yolo
608
- bundleId | string | no | The bundle identifier of an application to open the given url with. If not provided then the default application for the given url scheme is going to be used. | com.myapp.yolo
609
-
610
- ### macos: startNativeScreenRecording
611
-
612
- Initiates a new native screen recording session via XCTest.
613
- If the screen recording is already running then this call results in noop.
614
- A screen recording is running until a testing session is finished.
615
- If a recording has never been stopped explicitly during a test session
616
- then it would be stopped automatically upon the test session termination,
617
- and leftover videos would be deleted as well.
618
- Xcode must be at version 15+.
619
-
620
- > [!TIP]
621
- > Invocation of this API also triggers broadcasting of
622
- > [appium:mac2.nativeVideoRecordingChunkAdded](./docs/bidi.md#appiummac2nativevideorecordingchunkadded)
623
- > BiDi events. Make sure to subscribe to such events **before** this API is invoked to ensure
624
- > all video chunks are being properly consumed on the client side.
625
-
626
- #### Arguments
627
-
628
- Name | Type | Required | Description | Example
629
- --- | --- | --- | --- | ---
630
- fps | number | no | Frame Per Second setting for the resulting screen recording. 24 by default. Higher FPS values may significantly increase the size of the resulting video. | 60
631
- codec | number | no | Possible codec value, where `0` means H264 (the default setting), `1` means HEVC | 1
632
- displayId | number | no | Valid display identifier to record the video from. Main display ID is assumed by default. Use the `system_profiler -json SPDisplaysDataType` Terminal command to list IDs of connected displays or the [macos: listDisplays](#macos-listdisplays) API. | 1
633
-
634
- #### Returns
635
-
636
- The information about the asynchronously running video recording, which includes the following items:
637
-
638
- Name | Type | Description | Example
639
- --- | --- | --- | ---
640
- fps | number | Frame Per Second value | 24
641
- codec | number | Codec value, where `0` means H264 (the default setting), `1` means HEVC | 1
642
- displayId | number | Display identifier used to record this video for. | 1
643
- uuid | string | Unique video identifier. It is also used by XCTest to store the video on the file system. Look for `$HOME/Library/Daemon Containers/<testmanager_id>/Data/Attachments/<uuid>` to find the appropriate video file. Add the `.mp4` extension to it to make it openable by video players.
644
- startedAt | number | Unix timestamp of the video startup moment | 123456789
645
-
646
- ### macos: getNativeScreenRecordingInfo
647
-
648
- Fetches the information of the currently running native video recording.
649
- Xcode must be at version 15+.
650
-
651
- #### Returns
652
-
653
- Either `null` if no native video recording is currently active or the same map that [macos: startNativeScreenRecording](#macos-startnativescreenrecording) returns.
654
-
655
- ### macos: stopNativeScreenRecording
656
-
657
- Stops native screen recording previously started by
658
- [macos: startNativeScreenRecording](#macos-startnativescreenrecording)
659
- and returns the video payload or uploads it to a remote location,
660
- depending on the provided arguments.
661
- The actual video file is removed from the local file system after the video payload is
662
- successfully consumed.
663
- If no screen recording has been started before then this API throws an exception.
664
- Xcode must be at version 15+.
31
+ This is an Appium driver for automating macOS applications using Apple's XCTest framework.
665
32
 
666
33
  > [!IMPORTANT]
667
- > In order to retrieve the recorded video from the local file system the Appium Server process itself
668
- > or its parent process (e.g. Terminal) must have the "Full Disk Access" permission granted
669
- > in 'System Settings'→'Privacy & Security' tab.
670
-
671
- > [!NOTE]
672
- > Be careful while recording lengthy videos. They could be pretty large, and may easily exceed
673
- > the free space on the home partition.
674
-
675
- #### Arguments
676
-
677
- Name | Type | Required | Description | Example
678
- --- | --- | --- | --- | ---
679
- remotePath | string | no | The path to the remote location, where the resulting video should be uploaded. The following protocols are supported: http/https, ftp. Null or empty string value (the default setting) means the content of resulting file should be encoded as Base64 and passed as the endpoint response value. An exception will be thrown if the generated media file is too big to fit into the available process memory. | https://myserver.com/upload/video.mp4
680
- user | string | no | The name of the user for the remote authentication. | myname
681
- pass | string | no | The password for the remote authentication. | mypassword
682
- method | string | no | The http multipart upload method name. The 'PUT' one is used by default. | POST
683
- headers | map | no | Additional headers mapping for multipart http(s) uploads | `{"header": "value"}`
684
- fileFieldName | string | no | The name of the form field, where the file content BLOB should be stored for http(s) uploads. `file` by default | payload
685
- formFields | Map or `Array<Pair>` | no | Additional form fields for multipart http(s) uploads | `{"field1": "value1", "field2": "value2"}` or `[["field1", "value1"], ["field2", "value2"]]`
686
- ignorePayload | boolean | no | Whether to ignore the resulting video payload and return an empty string. Useful if you prefer to fetch video chunks via the [appium:mac2.nativeVideoRecordingChunkAdded](./docs/bidi.md#appiummac2nativevideorecordingchunkadded) BiDi event. false by default. | true
687
-
688
- #### Returns
689
-
690
- Base64-encoded content of the recorded media file if `remotePath` parameter is falsy or an empty string.
691
-
692
- ### macos: listDisplays
693
-
694
- Fetches information about available displays.
695
-
696
- #### Returns
697
-
698
- A map where keys are display identifiers represented as strings and values are display infos containing the following items:
699
-
700
- Name | Type | Description | Example
701
- --- | --- | --- | ---
702
- id | number | Display identifier | 12345
703
- isMain | boolean | Is `true` if the display is configured as a main system display | false
704
-
705
- ### macos: setClipboard
706
-
707
- Set the macOS clipboard content as base64-encoded string. The existing clipboard content (if present) will be cleared.
708
-
709
- #### Arguments
710
-
711
- Name | Type | Required | Description | Example
712
- --- | --- | --- | --- | ---
713
- content | string | yes | The content to be set as base64 encoded string | hello
714
- contentType | string | no | The type of the content to set. Only `plaintext` (default), `image` and `url` are supported. If set to `url`, then `content` must be a valid URL. If set to `image`, then `content` must contain a valid PNG or TIFF image payload. | url
715
-
716
- ### macos: getClipboard
717
-
718
- Get the macOS clipboard content as base64-encoded string.
719
-
720
- #### Arguments
721
-
722
- Name | Type | Required | Description | Example
723
- --- | --- | --- | --- | ---
724
- contentType | string | no | The type of the content to get. Only `plaintext` (default), `image` and `url` are supported. | image
725
-
726
- #### Returns
727
-
728
- The actual clipboard content encoded into base64 string. An empty string is returned if the clipboard
729
- contains no data for the given content type.
730
-
731
- ### macos: performAccessibilityAudit
732
-
733
- Performs an accessibility audit for the current application under test.
734
- Xcode must be at version 15+.
735
-
736
- #### Arguments
737
-
738
- Name | Type | Required | Description | Example
739
- --- | --- | --- | --- | ---
740
- auditTypes | array\<string\> | no | A list of audit type names as defined by [XCUIAccessibilityAuditType](https://developer.apple.com/documentation/xcuiautomation/xcuiaccessibilityaudittype?language=objc). If not provided then `XCUIAccessibilityAuditTypeAll` is used. | `['XCUIAccessibilityAuditTypeContrast']`
741
-
742
- #### Returns
743
-
744
- An array of audit issue objects. Each item includes:
745
- - `detailedDescription`: human-readable issue details
746
- - `compactDescription`: short issue summary
747
- - `auditType`: the resolved audit type name
748
- - `element`: string representation of the affected element
749
- - `elementDescription`: debug description of the affected element
750
-
751
-
752
- ## Application Under Test Concept
753
-
754
- The Mac2 driver has the concept of `Application Under Test`. This is the app, whose bundle identifier has been passed as `bundleId` capability or as an argument to `macos: activateApp` or `macos: launchApp` extensions.
755
- If this application is unexpectedly terminated during test session execution then an exception is going to be thrown upon any following session command invocation. In such case the driver assumes the application under test is crashed and it is impossible to proceed.
756
- Also, the `Application Under Test` is going to be terminated when the testing session quits (unless canceled by `skipAppKill` capability).
757
- It is possible to reset the `Application Under Test` value to none by executing `macos: terminateApp` helper and providing the bundle identifier of this app to it. Also, `macos: activateApp` or `macos: launchApp` calls can change `Application Under Test` value if a bundle identifier different from the current one is provided to them.
758
-
759
-
760
- ## AppleScript Commands Execution
761
-
762
- There is a possibility to run custom AppleScript
763
- from your client code. This feature is potentially insecure and thus needs to be
764
- explicitly enabled when executing the server by providing `apple_script` key to the list
765
- of enabled insecure features. Check [Appium Security document](https://github.com/appium/appium/blob/master/docs/en/writing-running-appium/security.md) for more details.
766
- It is possible to either execute a single AppleScript command (use the `command` argument)
767
- or a whole script (use the `script` argument) and get its
768
- stdout in response. If the script execution returns non-zero exit code then an exception
769
- is going to be thrown. The exception message will contain the actual stderr.
770
- If the script is a blocking one then it could only run up to 20 seconds long. After that the script
771
- will be terminated and a timeout error will be thrown. This timeout could be customized by
772
- providing the `timeout` option value.
773
- You could also customize the script working directory by providing the `cwd` option.
774
- Here's an example code of how to get a shell command output:
775
-
776
- ```java
777
- // java
778
- String appleScript = "do shell script \"echo hello\"";
779
- System.println(driver.executeScript("macos: appleScript", ImmutableMap.of("command", appleScript)));
780
- ```
781
-
782
-
783
- ## W3C Action Recipes
784
-
785
- In theory it is possible to emulate a mouse gesture of any complexity with W3C actions.
786
- However, there is a set of "standard" gestures, where each operating system has its own
787
- requirements, like clicks, double clicks, etc. All such action parameters
788
- must comply with these requirements to be recognized properly. Here is a short list of
789
- examples for the most common macOS pointer gestures:
790
-
791
- ### Click
792
-
793
- ```json
794
- [
795
- {"type": "pointerMove", "duration": 10, "x": 100, "y": 100},
796
- {"type": "pointerDown", "button": 0},
797
- {"type": "pause", "duration": 100},
798
- {"type": "pointerUp", "button": 0}
799
- ]
800
- ```
801
-
802
- The duration of mouse button suppression should be 0-125 ms.
803
-
804
- ### Right Click
805
-
806
- ```json
807
- [
808
- {"type": "pointerMove", "duration": 10, "x": 100, "y": 100},
809
- {"type": "pointerDown", "button": 2},
810
- {"type": "pointerUp", "button": 2}
811
- ]
812
- ```
813
-
814
- The duration of mouse button suppression should be 0-125 ms.
815
-
816
- ### Double Click
817
-
818
- ```json
819
- [
820
- {"type": "pointerMove", "duration": 10, "x": 100, "y": 100},
821
- {"type": "pointerDown", "button": 0},
822
- {"type": "pointerUp", "button": 0},
823
- {"type": "pause", "duration": 1000},
824
- {"type": "pointerDown", "button": 0},
825
- {"type": "pointerUp", "button": 0}
826
- ]
827
- ```
828
-
829
- The duration between two clicks should be 600-1000 ms.
830
-
831
- ### Drag & Drop
832
-
833
- ```json
834
- [
835
- {"type": "pointerMove", "duration": 10, "x": 100, "y": 100},
836
- {"type": "pointerDown", "button": 0},
837
- {"type": "pause", "duration": 600},
838
- {"type": "pointerMove", "duration": 10, "x": 200, "y": 200},
839
- {"type": "pointerUp", "button": 0}
840
- ]
841
- ```
842
-
843
- The longer is the duration of the second `pointerMove` action the lesser is the drag velocity
844
- and vice versa. One could add more `pointerMove` actions before releasing the mouse button
845
- to simulate complex cursor moving paths. Mac2Driver terminates action execution with a timeout
846
- error if the duration of it exceeds 5 minutes.
847
-
848
- ### Hover
849
-
850
- ```json
851
- [
852
- {"type": "pointerMove", "duration": 10, "x": 100, "y": 100},
853
- {"type": "pointerMove", "duration": 1000, "x": 200, "y": 200}
854
- ]
855
- ```
856
-
857
- This snippet tells the mouse pointer to hover over [100, 100, 200, 200] area for 1 second.
858
- In general, hover action will be performed every time if there is no preceding `pointerDown`
859
- to the current `pointerMove` one or the preceding `pointerDown` action has been ended by
860
- the `pointerUp` one.
861
-
862
-
863
- ## Settings API
864
-
865
- Mac2Driver supports Appium [Settings API](https://appium.io/docs/en/advanced-concepts/settings/).
866
- Along with the common settings the following driver-specific settings are currently available:
867
-
868
- Name | Type | Description
869
- --- | --- | ---
870
- boundElementsByIndex | boolean | Whether to use elements binding by index (`true`) or by accessibility identifier (the default setting, `false`). It makes sense to switch the binding strategy to workaround stale element reference errors containing `Identity Binding` text in their descriptions. See the corresponding [Stack Overflow discussion](https://stackoverflow.com/questions/49307513/meaning-of-allelementsboundbyaccessibilityelement) to know more details on the difference between these two binding strategies.
871
- useDefaultUiInterruptionsHandling | boolean | Whether to use the default XCTest UI interruptions handling (`true`, the default setting) or to disable it for the [Application Under Test](#application-under-test-concept) (`false`). It makes sense to disable the default handler if it is necessary to validate the interrupting element's presence in your test or do some other actions on it rather than just closing the view implicitly. Check [this WWDC presentation](https://developer.apple.com/videos/play/wwdc2020/10220/) from Apple to get more details on the UI interruptions handling.
872
- fetchFullText | boolean | Whether to use custom snapshotting mechanism to fetch full element's text payload instead of the first 512 chars. By default, this setting is set to false, which makes the driver to use the standard XCTest's snapshotting mechanism. It's fast, but may also cut long textual payloads of various UI element's in order to optimize internal UI hierarchy snapshotting performance. If the performance is less important for you that the ability to validate full element's text then consider enabling this setting while calling [Get Element Text](https://www.w3.org/TR/webdriver1/#dfn-get-element-text) API.
873
-
874
-
875
- ## Scripts
876
-
877
- The Mac2 driver supports the following scripts:
878
-
879
- ### open-wda
880
-
881
- Run `appium driver run mac2 open-wda` to open the bundled WebDriverAgentMac source in Xcode and to print the path to the main .xcodeproj file into the Terminal.
882
-
883
-
884
- ## Troubleshooting
885
-
886
- ### "WebDriverAgentRunner-Runner is from unidentified developer" system alert is shown on session startup
887
-
888
- This is a macOS security feature and it cannot be disabled.
889
- The only way to workaround this behavior is to configure digital signing for WDA.
890
- Check [the Stackoverlow thread](https://stackoverflow.com/questions/41062607/osx-complains-that-app-is-from-unidentified-developer-although-it-passes-all-va)
891
- for more details on how to do it. Use the [open-wda driver script](#open-wda) to quickly
892
- open WebDriverAgent sources in Xcode.
893
-
894
-
895
- ## Examples
896
-
897
- ```python
898
- # Python3 + PyTest
899
- import pytest
900
-
901
- from appium import webdriver
902
- # Options are available in Python client since v2.6.0
903
- from appium.options.mac import Mac2Options
904
- from appium.webdriver.common.appiumby import AppiumBy
905
-
906
-
907
- @pytest.fixture()
908
- def driver():
909
- options = Mac2Options()
910
- options.bundle_id = 'com.apple.TextEdit'
911
- # The default URL is http://127.0.0.1:4723/wd/hub in Appium1
912
- drv = webdriver.Remote('http://127.0.0.1:4723', options=options)
913
- yield drv
914
- drv.quit()
915
-
916
-
917
- def test_edit_text(driver):
918
- edit_field = driver.find_element(by=AppiumBy.CLASS_NAME, value='XCUIElementTypeTextView')
919
- edit_field.send_keys('hello world')
920
- assert edit_field.text == 'hello world'
921
- edit_field.clear()
922
- assert edit_field.text == ''
923
-
924
-
925
- def test_sending_custom_keys(driver):
926
- edit_field = driver.find_element(by=AppiumBy.CLASS_NAME, value='XCUIElementTypeTextView')
927
- flagsShift = 1 << 1
928
- driver.execute_script('macos: keys', {
929
- 'keys': [{
930
- 'key': 'h',
931
- 'modifierFlags': flagsShift,
932
- }, {
933
- 'key': 'i',
934
- 'modifierFlags': flagsShift,
935
- }]
936
- })
937
- assert edit_field.text == 'HI'
938
- ```
939
-
940
-
941
- ## Parallel Execution
942
-
943
- Parallel execution of multiple Mac2 driver instances is highly discouraged. Only one UI test must be running at the same time, since the access to accessibility layer is single-threaded. Also HID devices, like the mouse or the keyboard, must be acquired exclusively.
944
-
945
- ## Environment Variables
946
-
947
- The server part of the driver recognizes the following environment variables:
948
-
949
- - `ENABLE_AUTOMATIC_SCREENSHOTS`: enables automatic XCTest screenshots.
950
- These screenshots are stored in the same folder where WDA test logs are located and are taken automatically.
951
- This feature is disabled by default. Only enable it if you know what you are doing otherwise these
952
- screenshots may quickly fill up the free disk space.
953
- - `ENABLE_AUTOMATIC_SCREEN_RECORDINGS`: enables automatic XCTest screen recordings.
954
- These screen recordings are stored in the same folder where WDA test logs are located and are taken automatically. This feature is disabled by default.
955
- Only enable it if you know what you are doing otherwise these videos may quickly fill up the free disk space.
956
- The native screen recording feature only works on Xcode 15+.
957
- - `USE_PORT`. If enabled then the server listens on the given port. Otherwise, a random free port from the
958
- 10100..10200 range is selected. By default, the port is selected by the driver (see the `appium:systemPort`
959
- capability description).
960
- - `VERBOSE_LOGGING`. If enabled then server logs should include various verbose details. Disabled by default.
961
-
962
- ## Development & Testing
963
-
964
- This module uses the same [development tools](https://github.com/appium/appium/tree/master/docs/cn/contributing-to-appium) as the other Appium drivers.
965
-
966
- Check out the source. Then run:
967
-
968
- ```bash
969
- npm install
970
- ```
971
-
972
- Execute `npm run test` to run unit tests and `npm run e2e-test` to run integration tests.
34
+ > Since major version *3.0.0*, this driver is only compatible with Appium 3.
973
35
 
974
36
 
975
- ## Notes
37
+ ## Documentation
976
38
 
977
- - W3C actions support is limited (only mouse actions are supported). You could also use `macos:` extension APIs to cover your test scenarios
39
+ You can access the documentation here: [**https://appium.github.io/appium-mac2-driver**](https://appium.github.io/appium-mac2-driver)