@appium/mcp-documentation 1.0.2 → 1.0.4

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/ci-setup.md

@@ -0,0 +1,47 @@
+---
+title: Continuous Integration
+---
+
+Setting up the XCUITest driver in an automated environment brings a few challenges with it. Any scenario
+where user interaction is required must be automated or avoided altogether. For real device setup,
+you should first follow the [Real Device Setup tutorial](../getting-started/device-setup.md#real-devices).
+
+### Keychains
+
+One common scenario is a prompt asking for a keychain to be unlocked in order to sign the WebDriverAgent.
+There are multiple possible solutions for this:
+
+1. Keychains can be set to have no timeout and be unlocked manually once. This can be done using the
+   keychain access application. Sometimes keychains still lock themselves though and this approach
+   is not recommended.
+2. [It is possible to create a second keychain](../troubleshooting/index.md#real-device-security-settings),
+   which just stores the required certificate to sign the WebDriverAgent. The issue with this
+   approach is that Codesign wants to unlock all listed keychains regardless of the specified
+   keychain, thus leading to a password prompt. This can be avoided by setting the default keychain
+   and basically hiding the login keychain at the start of the build.
+   [See this Stackoverflow article](https://stackoverflow.com/questions/16550594/jenkins-xcode-build-works-codesign-fails)
+   for how to utilize this approach. It is impractical when running other build jobs simultaneously.
+3. Stick with the existing keychains as in approach 1, but explicitly call unlock keychain before
+   **each** build. This can be done using [fastlane unlock_keychain](https://docs.fastlane.tools/actions/unlock_keychain/)
+   or by using [security unlock-keychain](https://www.unix.com/man-page/osx/1/security/) directly.
+   The password can be saved as a CI variable/secret or on the machine itself.
+
+It is recommended to go with the second or third option. The third one is the easiest and most
+reliable one to set up, at the cost of having to set the keychain password as an environment variable.
+
+### Xcode
+
+When setting up a new machine as a CI server, you are probably going to install Xcode, without
+executing it once, because you are not going to use it for development. Make sure to start Xcode at
+least once and do the initial set up and install the suggested extensions.
+
+### Linking Apple Account
+
+This only applies for real device set up. Make sure to link your 'Apple Developer Account' in the
+machine's system wide "Account Panel" when using the "Basic Automatic Configuration" described
+[here](../getting-started/provisioning-profile/auto-config.md).
+
+### Troubleshooting
+
+Enable the `appium:showXcodeLog` [capability](../reference/capabilities.md#webdriveragent) and
+check the Appium server output.

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/clipboard.md

@@ -0,0 +1,47 @@
+---
+hide:
+  - toc
+
+title: Get/Set Clipboard
+---
+
+Working with the clipboard on real devices has an Apple security limitation, where the
+WebDriverAgentRunner application must be in foreground in order for the action to work. Otherwise
+an empty string is always returned, or it could raise an exception like
+[this issue](https://github.com/appium/appium/issues/18730).
+
+Consider using [`mobile: activateApp`](../reference/execute-methods.md/#mobile-activateapp)
+and [`mobile: backgroundApp`](../reference/execute-methods.md/#mobile-backgroundapp) to change the
+foreground application.
+
+## Get Clipboard
+
+Applies to iOS 13+ real devices. You can also use
+[`mobile: getPasteboard`](../reference/execute-methods.md#mobile-getpasteboard) for simulators.
+
+```ruby
+# Ruby
+
+# Bring the WebDriverAgent foreground. The bundle id depends on configuration such as "appium:updatedWDABundleId" for real devices.
+driver.execute_script 'mobile: activateApp', {bundleId: 'com.facebook.WebDriverAgentRunner.xctrunner'}
+# Get the clipboard content
+driver.get_clipboard
+# Go back to the application under test
+driver.execute_script 'mobile: activateApp', {bundleId: '<bundle id of the test app>'}
+```
+
+## Set Clipboard
+
+Applies to iOS 15+ real devices. You can also use
+[`mobile: setPasteboard`](../reference/execute-methods.md#mobile-setpasteboard) for simulators.
+
+```ruby
+# Ruby
+
+# Bring the WebDriverAgent foreground. The bundle id depends on configuration such as "appium:updatedWDABundleId" for real devices.
+driver.execute_script 'mobile: activateApp', {bundleId: 'com.facebook.WebDriverAgentRunner.xctrunner'}
+# Set the clipboard content
+driver.set_clipboard(content: 'happy testing')
+# Go back to the application under test
+driver.execute_script 'mobile: activateApp', {bundleId: '<bundle id of the test app>'}
+```

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/file-transfer.md

@@ -0,0 +1,147 @@
+---
+title: File Transfer
+---
+
+The XCUITest driver provides several [extension commands](../reference/execute-methods.md) for file transfer:
+
+* [`mobile: pullFolder`](../reference/execute-methods.md#mobile-pullfolder)
+* [`mobile: pullFile`](../reference/execute-methods.md#mobile-pullfile)
+* [`mobile: pushFile`](../reference/execute-methods.md#mobile-pushfile)
+* [`mobile: deleteFolder`](../reference/execute-methods.md#mobile-deletefolder)
+* [`mobile: deleteFile`](../reference/execute-methods.md#mobile-deletefile)
+
+This documentation aims to help to understand how they work on iOS.
+
+## Formats
+
+All commands require a parameter with a path to the file/folder on the target device. There are 3
+possible formats this path can take:
+
+### Format 1
+
+```
+@<app-bundle-id>:<container-type>/<path-to-file-or-folder>
+```
+
+* `@<app-bundle-id>` is the application bundle identifier
+* `<container-type>` is the container type
+    * On simulators, common values are `app`, `data`, `groups`, but a custom one can also be provided
+    * On real devices, the only accepted value is `documents`. All others are treated as Format 2
+        * This value can only be specified for apps that have the `UIFileSharingEnabled` flag set to
+          `true`. You can use the [`mobile: listApps`](../reference/execute-methods.md#mobile-listapps)
+          extension to identify such apps.
+        * By assigning the `skipDocumentsContainerCheck` [Settings API](https://appium.io/docs/en/latest/guides/settings/) to `true`, you may skip the above limitation for certain apps.
+
+* `<path-to-file-or-folder>` is the target file or folder
+    * On real devices, if `<container-type>` is set to `documents`, this path will be mapped to
+      `On My iPhone/<app name>` in the _Files_ app
+
+### Format 2
+
+```
+@<app-bundle-id>/<path-to-file-or-folder>
+```
+
+* On simulators, the implicit `<container-type>` is set to `app`.
+* On real device, only apps with the `UIFileSharingEnabled` flag set to `true` in their `info.plist`
+  can be mounted. You can use the [`mobile: listApps`](../reference/execute-methods.md#mobile-listapps)
+  extension to identify such apps.
+
+### Format 3
+
+```
+<path-to-file-or-folder>
+```
+
+This format is only supported on simulators. The implicit `<container-type>` is set to `app`.
+Eventually the whole simulator file system is
+[available](https://stackoverflow.com/questions/6480607/is-there-any-way-to-see-the-file-system-on-the-ios-simulator)
+directly from the macOS Finder, so you may pull any file from there by providing a path to it
+relatively to the simulator's file system root.
+
+## Examples
+
+### `pullFile`
+
+This example pulls a file present in _Files -> On My iPhone -> Keynote_:
+
+|Top | On  My iPhone | Keynote |
+|:----:|:----:|:----:|
+|![](./assets/images/ios-xctest-file-movement/top_files.png)|![](./assets/images/ios-xctest-file-movement/on_my_iphone.png)|![](./assets/images/ios-xctest-file-movement/keynote.png)|
+
+=== "JS (WebdriverIO)"
+
+    ```javascript
+    let data = driver.pullFile('@com.apple.Keynote:documents/Presentation.key');
+    await fs.writeFile('presentation.key', Buffer.from(data, 'base64'), 'binary');
+    ```
+
+=== "Ruby"
+
+    ```ruby
+    file = @driver.pull_file '@com.apple.Keynote:documents/Presentation.key'
+    File.open('presentation.key', 'wb') { |f| f<< file }
+    ```
+
+If the file is in deeper place like _Keynote/Dir1/Dir2_, then the path changes:
+
+=== "JS (WebdriverIO)"
+
+    ```javascript
+    let data = driver.pullFile('@com.apple.Keynote:documents/Dir1/Dir2/Presentation.key');
+    await fs.writeFile('presentation.key', Buffer.from(data, 'base64'), 'binary');
+    ```
+
+=== "Ruby"
+
+    ```ruby
+    file = @driver.pull_file '@com.apple.Keynote:documents/Dir1/Dir2/Presentation.key'
+    File.open('presentation.key', 'wb') { |f| f<< file }
+    ```
+
+Example for a simulator using Format 3:
+
+```java
+// Java
+// Get AddressBook.sqlitedb in test app package ('app' container)
+byte[] fileContent = driver.pullFile("Library/AddressBook/AddressBook.sqlitedb");
+Path dstPath = Paths.get(new File("/local/path/AddressBook.sqlitedb"));
+Files.write(dstPath, fileContent);
+```
+
+### `pullFolder`
+
+You can pull folders similarly to files, but the path must end with a forward slash (`/`).
+
+=== "JS (WebdriverIO)"
+
+    ```javascript
+    let data = driver.pullFolder('@com.apple.Keynote:documents/');
+    await fs.writeFile('documents.zip', Buffer.from(data, 'base64'), 'binary');
+    ```
+
+=== "Ruby"
+
+    ```ruby
+    file = @driver.pull_folder '@com.apple.Keynote:documents/'
+    File.open('documents.zip', 'wb') { |f| f<< file }
+    ```
+
+### `pushFile`
+
+=== "JS (WebdriverIO)"
+
+    ```javascript
+    driver.pushFile('@com.apple.Keynote:documents/text.txt', new Buffer("Hello World").toString('base64'));
+    ```
+
+=== "Ruby"
+
+    ```ruby
+    @driver.push_file '@com.apple.Keynote:documents/text.txt', (File.read 'path/to/file')
+    ```
+
+## References
+- <https://stackoverflow.com/questions/1108076/where-does-the-iphone-simulator-store-its-data>
+- <https://stackoverflow.com/questions/48884248/how-can-i-add-files-to-the-ios-simulator>
+- <https://apple.stackexchange.com/questions/299413/how-to-allow-the-files-app-to-save-to-on-my-iphone-or-to-on-my-ipad-in-ios/299565#299565>

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/gestures.md

@@ -0,0 +1,55 @@
+---
+hide:
+  - toc
+
+title: Gestures
+---
+
+The XCUITest driver provides multiple options for touch gestures automation.
+For simple gestures, like tap by coordinates, long tap, multi-finger tap, double/triple tap,
+swipe, drag, rotate, scroll or pinch use the below gesture shortcuts:
+
+- [mobile: tap](../reference/execute-methods.md#mobile-tap)
+- [mobile: doubleTap](../reference/execute-methods.md#mobile-doubletap)
+- [mobile: touchAndHold](../reference/execute-methods.md#mobile-touchandhold)
+- [mobile: twoFingerTap](../reference/execute-methods.md#mobile-twofingertap)
+- [mobile: dragFromToForDuration](../reference/execute-methods.md#mobile-dragfromtoforduration)
+- [mobile: dragFromToWithVelocity](../reference/execute-methods.md#mobile-dragfromtowithvelocity)
+- [mobile: rotateElement](../reference/execute-methods.md#mobile-rotateelement)
+- [mobile: tapWithNumberOfTaps](../reference/execute-methods.md#mobile-tapwithnumberoftaps)
+- [mobile: forcePress](../reference/execute-methods.md#mobile-forcepress)
+- [mobile: scrollToElement](../reference/execute-methods.md#mobile-scrolltoelement)
+- [mobile: scroll](../reference/execute-methods.md#mobile-scroll)
+- [mobile: pinch](../reference/execute-methods.md#mobile-pinch)
+
+For more sophisticated gestures
+consider using [W3C actions](https://w3c.github.io/webdriver/#actions).
+
+Make sure you don't use deprecated JSONWP TouchActions APIs. They have been
+removed from the XCUITest driver since version 7.
+
+If the action code in the client source looks good and satisfies the above requirements,
+but its execution still does not deliver the expected result then the following debugging
+measures might be applied:
+
+- Make sure the gesture has valid coordinates and respects pauses between pointer state changes.
+  For example, it is always mandatory to provide a valid element or valid `absolute` coordinates
+  to any gesture at the beginning. iOS only registers
+  a long touch/click if the pointer has been depressed for longer than 500ms. For shorter actions
+  a simple click is registered instead.
+- If your tests run on Simulator then it is possible to activate pointer tracing by enabling
+  the [appium:simulatorTracePointer](../reference/capabilities.md#simulator) capability or by enabling
+  `Visual Indicators` items from Simulator settings. After running
+  your automation code with this feature enabled you would be able to see the exact pointer trace path
+  and check the velocity of the gesture. Compare the trace
+  to how the same gesture is usually done manually and apply the necessary updates to your code.
+- Do not mix webview and native elements in actions arguments. It simply won't work. Native
+  actions could only consume native elements. A single possibility to perform a native action
+  on a web element would be to translate its coordinates into the native context and pass these
+  coordinates as native action arguments.
+
+Check the below tutorials for more details on how to build reliable action chains:
+
+- [Automating Complex Gestures with the W3C Actions API](https://appiumpro.com/editions/29-automating-complex-gestures-with-the-w3c-actions-api)
+- [Swiping your way through Appium by Wim Selles #AppiumConf2021](https://www.youtube.com/watch?v=oAJ7jwMNFVU)
+- [About iOS Input Events](./input-events.md)

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/hybrid.md

@@ -0,0 +1,137 @@
+---
+title: Hybrid Apps
+---
+
+One of the core principles of XCUITest driver is that you shouldn't have to change your
+app to test it. In line with that methodology, it is possible to test hybrid
+apps the same way you can with Selenium for web apps. There is a bit of technical
+complexity required so that XCUITest driver knows whether you want to automate the native
+aspects of the app or the web views. But, thankfully, we can stay within the
+Selenium WebDriver protocol for everything.
+
+Once the test is in a web view context the command set that is available is the
+full [Selenium](http://www.seleniumhq.org/) [WebDriver API](https://www.w3.org/TR/webdriver/).
+
+### Requirements
+
+To interact with a web view XCUITest driver establishes a connection using a custom
+[remote debugger](https://github.com/appium/appium-remote-debugger).
+This debugger can connect directly to any WebKit debugger socket exposed by the system.
+The protocol used for the communication there is a proprietary Apple's JSON RPC similar
+to Chrome's [Devtools Protocol](https://chromedevtools.github.io/devtools-protocol/).
+Not all web views expose debugger web sockets by default thus making them invisible
+for the XCUITest driver and not showing in the available contexts list.
+Make sure the following prerequisites are satisfied if you are unsure about whether
+the particular web view is debuggable or not:
+
+- If you use real devices then make sure the Settings→Safari→Advanced→Web Inspector
+  checkbox is turned on.
+- If your app's web view is based on WKWebView then make sure the
+  [isInspectable](https://developer.apple.com/documentation/webkit/wkwebview/4111163-inspectable?language=objc) property of it set to `true`. Note, that you must have access to the application sources in order
+  to ensure that!
+- Make sure you see the corresponding web view in Safari's
+  [remote debugger](https://help.salesforce.com/s/articleView?id=000391692&type=1) list.
+
+If all the above requirements have been satisfied, but the desired web view is still not present in the
+XCUITest driver's context list then there is probably an issue in the driver itself, which must be reported
+to driver maintainers.
+
+### Entering the web view context
+
+Here are the steps required to talk to a web view in your XCUITest driver test:
+
+1. Navigate to a portion of your app where a web view is active
+2. Retrieve the currently available contexts
+    * This returns a list of contexts we can access, like `'NATIVE_APP'` or `'WEBVIEW_1'`
+3. Set the id of the context you want to access
+    * This puts your XCUITest session into a mode where all commands are
+      interpreted as being intended for automating the web view, rather than the
+      native portion of the app. For example, if you run `findElement`, it
+      will operate on the DOM of the web view, rather than return native elements.
+      Of course, certain WebDriver methods only make sense in one context or
+      another, so in the wrong context you will receive an error message.
+4. To stop automating in the web view context and go back to automating the
+   native portion of the app, simply set the context
+   again with the native context id (generally `'NATIVE_APP'`) to leave the web
+   context and once again access the native commands.
+
+### Automatically entering the web view context on session start
+
+If your application begins in a web view, and you do not want to automate the
+native application before entering it, you can have XCUITest driver automatically enter
+the web view context on session initialization by setting the `autoWebview`
+[capability](../reference/capabilities.md) to `true`.
+
+
+### Examples
+
+=== "Java"
+    ```java
+    // java
+    // assuming we have a set of capabilities
+    driver = new AppiumDriver(new URL("http://127.0.0.1:4723/"), options);
+
+    Set<String> contextNames = driver.getContextHandles();
+    for (String contextName : contextNames) {
+        System.out.println(contextName); //prints out something like NATIVE_APP \n WEBVIEW_1
+    }
+    driver.context(contextNames.toArray()[1]); // set context to WEBVIEW_1
+
+    //do some web testing
+    String myText = driver.findElement(By.cssSelector(".green_button")).click();
+
+    driver.context("NATIVE_APP");
+
+    // do more native testing if we want
+
+    driver.quit();
+    ```
+    
+=== "Ruby"
+    ```ruby
+    # ruby_lib_core
+    # assuming we have a set of capabilities
+    @driver = Appium::Core.for(url: SERVER_URL, desired_capabilities: capabilities).start_driver
+    # ruby_lib
+    # opts = { caps: capabilities, appium_lib: { custom_url: SERVER_URL }}
+    # @driver = Appium::Driver.new(opts, true).start_driver
+
+    # I switch to the last context because its always the webview in our case, in other cases you may need to specify a context
+    # View the appium logs while running @driver.contexts to figure out which context is the one you want and find the associated ID
+    # Then switch to it using @driver.switch_to.context("WEBVIEW_6")
+
+    Given(/^I switch to webview$/) do
+        webview = @driver.available_contexts.last
+        @driver.switch_to.context(webview)
+    end
+
+    Given(/^I switch out of webview$/) do
+        @driver.switch_to.context(@driver.contexts.first)
+    end
+
+    # Now you can use CSS to select an element inside your webview
+
+    And(/^I click a webview button $/) do
+        @driver.find_element(:css, ".green_button").click
+    end
+    ```
+
+=== "Python"
+    ```python
+    # python
+    # assuming we have an initialized `driver` object for an app
+
+    # switch to webview
+    webview = driver.contexts.last
+    driver.switch_to.context(webview)
+
+    # do some webby stuff
+    driver.find_element(By.CSS, ".green_button").click
+
+    # switch back to native view
+    driver.switch_to.context(driver.contexts.first)
+
+    # do more native testing if we want
+
+    driver.quit()
+    ```

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/input-events.md

@@ -0,0 +1,67 @@
+---
+title: iOS Input Events
+---
+
+## What Are Input Events
+
+iOS uses the Events concept to handle signals received from different input devices. An Event is an
+object generated in response to a signal from an input device. These objects are then delivered to
+the corresponding kernel subsystem, which processes them and notifies all listening processes about
+taps, key presses, swipes, etc. This means that in order to emulate a signal generated by an external
+device, such as a touch screen, it is necessary to just send Event objects with the same properties
+and in the same sequence as they would be generated by a real device.
+
+## Simulating a Single Tap
+
+The Events API itself is a part of Apple private API, and it is neither open sourced nor documented.
+The XCTest framework also does not expose any _public_ APIs for input events generation, although
+there is a possibility to perform events generation via XCTest _private_ undocumented APIs.
+
+In particular, we are interested in the
+[`XCPointerEventPath`](https://github.com/appium/WebDriverAgent/blob/master/PrivateHeaders/XCTest/XCPointerEventPath.h)
+and [`XCSynthesizedEventRecord`](https://github.com/appium/WebDriverAgent/blob/master/PrivateHeaders/XCTest/XCSynthesizedEventRecord.h)
+interfaces. These APIs allow to create chains of input events and supply them to the system kernel
+for execution.
+
+In order to synthesize a single tap, it is necessary to:
+
+- Create a new `XCPointerEventPath` instance and initialize it for touch at the starting point
+- Add a new `liftUp` event at `0.125s` offset using `liftUpAtOffset:` method
+- Add the generated event path object to `XCSynthesizedEventRecord` instance using
+  `addPointerEventPath:` method
+- Execute the events using `synthesizeWithError:` method of `XCSynthesizedEventRecord` instance and
+  control the returned error
+
+There are several limitations to these APIs:
+
+- Each `XCPointerEventPath` instance can only be executed for a single action. If one tries to add,
+  for example, two taps to a single path, then these are effectively ignored
+- Each `XCPointerEventPath` instance can only be initialized for a particular pointer type: touch,
+  mouse (since Xcode 10.2) or keyboard (since Xcode 10.2)
+- Events can only be added with increasing offset values to an existing `XCPointerEventPath` instance
+
+## More Complicated Actions
+
+Unfortunately, because the API is private and has zero documentation, one can only figure out what
+it can do by playing with it and trying different input combinations.
+
+It is known that providing multiple `XCPointerEventPath` instances with overlapping timeouts will
+generate a multitouch action with the amount of fingers equal to the amount of the supplied event
+paths. So, in order to generate two-finger symmetric swipe we need to supply the following events:
+
+- Create a two `XCPointerEventPath` instances and init them for touch at the starting point
+- Add a `moveToPoint` event at `0.525s` offset using `moveToPoint:` method to each path
+- Add a `liftUp` eventa at `0.525s` offset using `liftUpAtOffset:` method to each path
+- Add the generated event paths to `XCSynthesizedEventRecord` instance using `addPointerEventPath:` method
+- Execute the events using `synthesizeWithError:` method of `XCSynthesizedEventRecord` instance and
+  control the returned error
+
+## Further Reading
+
+Unfortunately, there is no information on this topic at all (private API `¯\_(ツ)_/¯`). Consider
+visiting the following resources:
+
+* <https://github.com/appium/WebDriverAgent/tree/master/PrivateHeaders/XCTest>
+* <https://github.com/appium/WebDriverAgent/blob/master/WebDriverAgentTests/IntegrationTests/FBW3CTouchActionsIntegrationTests.m>
+* <https://github.com/appium/WebDriverAgent/blob/master/WebDriverAgentTests/IntegrationTests/FBW3CMultiTouchActionsIntegrationTests.m>
+* <https://github.com/appium/WebDriverAgent/blob/master/WebDriverAgentLib/Utilities/FBW3CActionsSynthesizer.m>

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/install-certificate.md

@@ -0,0 +1,20 @@
+---
+hide:
+  - toc
+
+title: Self-Signed Certificates
+---
+
+Unfortunately, Apple does not provide any command line options which can help to install self-signed
+certificate on a real device or simulator. However, there is
+[over-the-air](https://developer.apple.com/library/content/documentation/NetworkingInternet/Conceptual/iPhoneOTAConfiguration/Introduction/Introduction.html)
+enrollment technology, which allows the deployment of several entity types, including such
+certificates, by simply downloading specially prepared configuration files with the built-in web
+browser. After the configuration is downloaded it can be installed and trusted by going through
+several simple wizard steps.
+
+You can use the following extension methods to assist with this. Please note that on real devices,
+this functionality is only supported starting from iOS/tvOS 18.
+
+* [`mobile: installCertificate`](../reference/execute-methods.md#mobile-installcertificate)
+* [`mobile: removeCertificate`](../reference/execute-methods.md#mobile-removecertificate)

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/mjpeg.md

@@ -0,0 +1,98 @@
+---
+title: MJPEG Screenshot Stream
+---
+
+The XCUITest driver supports a **MJPEG screenshot stream** provided by WebDriverAgent (WDA). This feature allows real-time device screens to be broadcast as a continuous stream of JPEG frames over HTTP, which can be used for screen recording, live viewing, or using the latest stream frame as the source for screenshot commands.
+
+## Overview
+
+When WDA runs on the device or simulator, it starts an **MJPEG screenshots broadcaster** service on a dedicated TCP port (default **9100**). This service:
+
+- Captures the device screen at a configurable framerate (screenshots per second)
+- Encodes each frame as JPEG with configurable quality
+- Optionally downscales frames by a configurable factor
+- Streams frames to all connected clients using the **multipart/x-mixed-replace** HTTP response format (standard MJPEG over HTTP)
+
+Any client that connects to the stream URL and sends a request receives a never-ending HTTP response where the body is a sequence of JPEG images (each with a boundary and headers). This is the same format used by many IP cameras and browser-based MJPEG viewers.
+
+## Use Cases
+
+| Use case | Description |
+|----------|-------------|
+| **Screen recording** | The driver’s [`mobile: startScreenRecording`](../reference/execute-methods.md#mobile-startscreenrecording) (or [`startRecordingScreen`](../reference/commands.md#startrecordingscreen) over HTTP) can use the MJPEG stream as input to **ffmpeg** to produce MP4 (or other) video files. This is the default when using the `mjpeg` video type. |
+| **Screenshots from stream** | If you set the **`mjpegScreenshotUrl`** capability, the driver uses the **latest frame** from that MJPEG stream when you call the screenshot command instead of calling WDA’s regular screenshot API. |
+| **Live viewing / custom tools** | Any HTTP client (browser, script, or custom app) can connect to the MJPEG URL (after port forwarding for real devices) to view or process the live screen. |
+
+## Capabilities
+
+| <div style="width:14em">Capability</div> | Description |
+|------------|-------------|
+| **`appium:mjpegServerPort`** | Port on which WDA broadcasts the MJPEG stream. Default: **9100**. Change this if the default port is already in use (e.g. when running [parallel sessions](parallel-tests.md)); each session must use a unique MJPEG port if you use MJPEG features. |
+| **`appium:mjpegScreenshotUrl`** | URL of a service that provides real-time device screenshots in MJPEG format. If set, the driver uses this stream for the **screenshot** command (returning the latest frame as the screenshot). Appium does **not** set up port forwarding for this URL; you must ensure the URL is reachable (e.g. by using the same port forwarding that `mjpegServerPort` uses, or an external MJPEG server). Example: `http://<host>:9100`. |
+
+For full capability details, see [Capabilities](../reference/capabilities.md).
+
+## Settings
+
+You can tune how WDA produces the MJPEG stream via the [Settings API](../reference/settings.md). These settings affect framerate, scaling, and JPEG quality of the broadcast only.
+
+| <div style="width:15em">Setting</div> | Type | Description | Default |
+|------------------------------|------|-------------|---------|
+| **`mjpegServerFramerate`** | `int` | Maximum screenshots per second sent by the MJPEG broadcaster. Allowed range: **1–60**. | `10` |
+| **`mjpegScalingFactor`** | `float` | Percentage used to downscale MJPEG frames. **1–100**; `100` means no downscaling. | `100` |
+| **`mjpegServerScreenshotQuality`** | `int` | JPEG compression quality for MJPEG frames (1–100). Lower values mean smaller **file size on the wire** (more compression) and lower visual quality; higher values mean larger frames (less compression) and better visual quality. | `25` |
+| **`mjpegFixOrientation`** | `boolean` | Whether to automatically normalize the orientation of MJPEG frames so that they match the current device orientation. Affects only the MJPEG screenshots broadcaster and does not change regular screenshot responses. | `true` |
+
+You can also set initial values for some of these settings via environment variables before WDA starts, namely `MJPEG_SCALING_FACTOR` (for `mjpegScalingFactor`) and `MJPEG_SERVER_SCREENSHOT_QUALITY` (for `mjpegServerScreenshotQuality`). See [Environment variables](../reference/env-vars.md) for details.
+
+Example (via Settings API):
+
+```json
+{
+  "settings": {
+    "mjpegServerFramerate": 15,
+    "mjpegScalingFactor": 50,
+    "mjpegServerScreenshotQuality": 50
+  }
+}
+```
+
+## How it works (driver and WDA)
+
+### Port forwarding
+
+- For **real devices**, the driver forwards the **device** MJPEG port to the **host** so that clients can connect to e.g. `http://localhost:9100` (or the port you set with `mjpegServerPort`). If the default port is in use and you did not set `mjpegServerPort`, the driver logs a warning and MJPEG-based features (like MJPEG-based screen recording) may be unavailable for that session.
+- For **simulators**, the MJPEG server is already on the host, so no port forwarding is needed for local access.
+
+### WDA implementation (WebDriverAgentLib)
+
+At a high level, [WebDriverAgent](https://github.com/appium/WebDriverAgent) exposes an HTTP MJPEG endpoint that continuously captures the screen, encodes each frame as JPEG, and streams frames to all connected clients using the `multipart/x-mixed-replace` response format. The capture rate, scaling, quality, and orientation of these frames are controlled by the MJPEG-related [settings](../reference/settings.md) and a few [environment variables](../reference/env-vars.md) that WebDriverAgent reads when the screenshots broadcaster is initialized.
+
+### Screenshot command and `mjpegScreenshotUrl`
+
+If **`appium:mjpegScreenshotUrl`** is set at session start, the driver starts an internal **MJPEG stream client** that connects to that URL. When you call the **screenshot** command, the driver returns the **latest received frame** from this stream (as PNG base64) instead of calling WDA’s normal screenshot endpoint. If no frame has been received yet, it falls back to the regular screenshot path.
+
+### Screen recording
+
+For **`mobile: startScreenRecording`** / **`startRecordingScreen`** (HTTP) with video type **`mjpeg`** (the default), the driver uses **ffmpeg** with input `-f mjpeg -i <url>`, where the URL is the MJPEG stream (typically the forwarded `mjpegServerPort`). Frames from the stream are then encoded (e.g. to H.264) and written to an MP4 file. The recording quality and framerate can be aligned with the MJPEG settings (e.g. `mjpegServerFramerate`, `mjpegServerScreenshotQuality`) and with the `videoFps` / `videoQuality` options of the recording API.
+
+## Parallel sessions
+
+When running [parallel tests](parallel-tests.md), each session that uses MJPEG (e.g. screen recording or `mjpegScreenshotUrl`) must use a **different** `mjpegServerPort`. Otherwise port conflicts or wrong-stream issues can occur. The driver will try to forward the requested MJPEG port; if the default 9100 is already in use and you did not set a custom port, it only warns and leaves MJPEG features unavailable for that session.
+
+## Requirements
+
+- **Screen recording** via MJPEG: **ffmpeg** must be installed and on the PATH (e.g. `brew install ffmpeg`). The driver uses the MJPEG stream as ffmpeg input.
+- **`mjpegScreenshotUrl`**: The given URL must be reachable from the Appium process (e.g. correct host/port and, for real devices, port forwarding if the stream is on the device).
+
+## Summary
+
+| Topic | Details |
+|-------|---------|
+| **Default port** | 9100 (`mjpegServerPort`) |
+| **Protocol** | HTTP, `multipart/x-mixed-replace` (MJPEG) |
+| **Default framerate** | 10 fps (`mjpegServerFramerate`) |
+| **Default quality** | 25% JPEG (`mjpegServerScreenshotQuality`) |
+| **Default scaling** | 100% (`mjpegScalingFactor`) |
+| **Related commands** | Screenshot (when `mjpegScreenshotUrl` is set), `mobile: startScreenRecording` / `startRecordingScreen` (HTTP) (with MJPEG input) |
+| **Related reference** | [Capabilities](../reference/capabilities.md), [Settings](../reference/settings.md), [Execute methods](../reference/execute-methods.md) |

package/src/resources/submodules/appium-xcuitest-driver/docs/guides/multiple-xcode-versions.md

@@ -0,0 +1,37 @@
+---
+hide:
+  - toc
+
+title: Multiple Xcode Installs
+---
+
+If you have multiple Xcode installations, you may choose which toolset Appium should use with one
+of two ways:
+
+### `xcode-select` tool
+Only available with `sudo` privileges, affects the whole system.
+
+Assuming you want to choose `/Applications/Xcode13.app`:
+
+1. Set the default Xcode
+  ```
+  sudo xcode-select -s /Applications/Xcode13.app/Contents/Developer
+  ```
+2. Run Appium
+  ```
+  appium
+  ```
+
+### Environment variable
+No privileges needed, affects only the current shell, so Appium should be started within that shell.
+
+Assuming you want to choose `/Applications/Xcode12.app`:
+
+1. Set the `DEVELOPER_DIR` environment variable
+  ```
+  export DEVELOPER_DIR=/Applications/Xcode12.app/Contents/Developer
+  ```
+2. Run Appium
+  ```
+  appium
+  ```