@@ -43,14 +43,14 @@ For iOS/tvOS < 18 these tunnels are not required and the driver falls back to le
4343 - Developer tools and Xcode installed (for general iOS development and pairing)
4444- ** Optional dependency (required for tunnels)** :
4545 - The driver declares ` appium-ios-remotexpc ` as an ** optional dependency** , so in a normal
46- installation npm will install it automatically. You only need to install it manually if
47- the optional dependency step failed or you are wiring a custom environment.
46+ installation npm will install it automatically. You only need to install it manually if
47+ the optional dependency step failed or you are wiring a custom environment.
4848 - For details about Remote XPC and IPv6 tunneling, see the
49- [ ` appium-ios-remotexpc ` README] ( https://github.com/appium/appium-ios-remotexpc ) .
49+ [ ` appium-ios-remotexpc ` README] ( https://github.com/appium/appium-ios-remotexpc ) .
5050
5151- ** Privileges** :
5252 - ** sudo/root is required** to create TUN/TAP interfaces for the tunnel. You should generally run
53- the tunnel script with ` sudo ` (or an equivalent mechanism, such as a root container).
53+ the tunnel script with ` sudo ` (or an equivalent mechanism, such as a root container).
5454
5555To verify that the optional dependency and tunnel infrastructure are available you can run:
5656
@@ -90,30 +90,30 @@ The script supports a few options:
9090
9191- ** Target a specific device** :
9292
93- ``` bash
94- sudo appium driver run xcuitest tunnel-creation --udid < device-udid>
95- ```
93+ ``` bash
94+ sudo appium driver run xcuitest tunnel-creation --udid < device-udid>
95+ ```
9696
9797- ** Customize packet stream base port** :
9898
99- ``` bash
100- sudo appium driver run xcuitest tunnel-creation --packet-stream-base-port 52000
101- ```
99+ ` ` ` bash
100+ sudo appium driver run xcuitest tunnel-creation --packet-stream-base-port 52000
101+ ` ` `
102102
103- The script will assign ` 52000 ` , ` 52001 ` , ` 52002 ` , … to packet stream servers for each device.
103+ The script will assign ` 52000` , ` 52001` , ` 52002` , … to packet stream servers for each device.
104104
105105- ** Customize tunnel registry port** :
106106
107- ``` bash
108- sudo appium driver run xcuitest tunnel-creation --tunnel-registry-port 43000
109- ```
107+ ` ` ` bash
108+ sudo appium driver run xcuitest tunnel-creation --tunnel-registry-port 43000
109+ ` ` `
110110
111- The registry API will then be available at:
111+ The registry API will then be available at:
112112
113113 - ` http://localhost:43000/remotexpc/tunnels`
114114
115- The script also stores the chosen port in a strongbox entry for the ` appium-xcuitest-driver `
116- package so that driver instances can locate the registry automatically.
115+ The script also stores the chosen port in a strongbox entry for the ` appium-xcuitest-driver`
116+ package so that driver instances can locate the registry automatically.
117117
118118# ## Inspecting the tunnel registry
119119
@@ -131,15 +131,15 @@ Useful endpoints:
131131
132132- ** List all tunnels** :
133133
134- ``` bash
135- curl http://localhost:< port> /remotexpc/tunnels
136- ```
134+ ` ` ` bash
135+ curl http://localhost:< port> /remotexpc/tunnels
136+ ` ` `
137137
138138- ** Get tunnel for a specific UDID** :
139139
140- ``` bash
141- curl http://localhost:< port> /remotexpc/tunnels/< udid>
142- ```
140+ ` ` ` bash
141+ curl http://localhost:< port> /remotexpc/tunnels/< udid>
142+ ` ` `
143143
144144The response contains the IPv6 ` address` , ` rsdPort` , and other metadata required to establish
145145Remote XPC connections.
@@ -153,40 +153,40 @@ tests against iOS/tvOS 18+ real devices using normal capabilities.
153153
1541541. ** Start the tunnels (once per host)** :
155155
156- ``` bash
157- sudo appium driver run xcuitest tunnel-creation
158- ```
156+ ` ` ` bash
157+ sudo appium driver run xcuitest tunnel-creation
158+ ` ` `
159159
160- Leave this process running in the background while tests execute.
160+ Leave this process running in the background while tests execute.
161161
1621622. ** Start the Appium server** (in a separate terminal):
163163
164- ``` bash
165- appium
166- ```
164+ ` ` ` bash
165+ appium
166+ ` ` `
167167
1681683. ** Run your tests** using standard XCUITest capabilities:
169169
170- ``` json
171- {
172- "platformName" : " iOS" ,
173- "appium:automationName" : " XCUITest" ,
174- "appium:platformVersion" : " 18.4" ,
175- "appium:udid" : " <device-udid>" ,
176- }
177- ```
170+ ` ` ` json
171+ {
172+ " platformName" : " iOS" ,
173+ " appium:automationName" : " XCUITest" ,
174+ " appium:platformVersion" : " 18.4" ,
175+ " appium:udid" : " <device-udid>" ,
176+ }
177+ ` ` `
178178
179- For tvOS, set ` "platformName": "tvOS" ` and use the UDID of your Apple TV device.
179+ For tvOS, set ` " platformName" : " tvOS" ` and use the UDID of your Apple TV device.
180180
1811814. ** How the driver uses tunnels** :
182182
183183 - When ` platformVersion` is ** 18 or higher** on a ** real device** , the driver:
184184 - Automatically imports ` appium-ios-remotexpc` (via ` getRemoteXPCServices` )
185185 - Uses Remote XPC services (installation proxy, AFC, diagnostics, DVT instruments, etc.)
186- instead of the legacy paths
186+ instead of the legacy paths
187187 - Relies on the IPv6 tunnels created by the tunnel registry for connectivity
188188 - If ` appium-ios-remotexpc` is missing or tunnels are not available, some advanced real‑device
189- features for 18+ may be unavailable or will fall back to slower/less reliable code paths.
189+ features for 18+ may be unavailable or will fall back to slower/less reliable code paths.
190190
191191No extra capabilities are required to “enable” tunnels; they are automatically used when:
192192
@@ -207,55 +207,55 @@ Appium server as long as:
207207
2082081. ** Create tunnels for all connected devices** :
209209
210- ``` bash
211- sudo appium driver run xcuitest tunnel-creation
212- ```
210+ ` ` ` bash
211+ sudo appium driver run xcuitest tunnel-creation
212+ ` ` `
213213
2142142. ** Start one Appium server** :
215215
216- ``` bash
217- appium --port 4723
218- ```
216+ ` ` ` bash
217+ appium --port 4723
218+ ` ` `
219219
2202203. ** Run tests in parallel** , for example:
221221
222222 - Session A:
223223
224- ``` json
225- {
226- "platformName" : " iOS" ,
227- "appium:automationName" : " XCUITest" ,
228- "appium:platformVersion" : " 18.1" ,
229- "appium:udid" : " <iphone-udid>" ,
230- "appium:app" : " /path/to/iphone/app.app"
231- }
232- ```
224+ ` ` ` json
225+ {
226+ " platformName" : " iOS" ,
227+ " appium:automationName" : " XCUITest" ,
228+ " appium:platformVersion" : " 18.1" ,
229+ " appium:udid" : " <iphone-udid>" ,
230+ " appium:app" : " /path/to/iphone/app.app"
231+ }
232+ ` ` `
233233
234234 - Session B:
235235
236- ```json
237- {
238- "platformName" : " tvOS" ,
239- "appium:automationName" : " XCUITest" ,
240- "appium:platformVersion" : " 18.0" ,
241- "appium:udid" : " <appletv-udid>" ,
242- "appium:app" : " /path/to/tvos/app.app"
243- }
244- ```
236+ ` ` ` json
237+ {
238+ " platformName" : " tvOS" ,
239+ " appium:automationName" : " XCUITest" ,
240+ " appium:platformVersion" : " 18.0" ,
241+ " appium:udid" : " <appletv-udid>" ,
242+ " appium:app" : " /path/to/tvos/app.app"
243+ }
244+ ` ` `
245245
2462464. ** Driver behavior** :
247247
248248 - Each session uses the UDID to pick the appropriate tunnel from the registry.
249249 - Underneath, ` TunnelManager` maintains a registry of active tunnels and Remote XPC connections
250- keyed by tunnel address and reuses them when possible.
250+ keyed by tunnel address and reuses them when possible.
251251 - Packet stream servers created by the tunnel script are already bound to distinct TCP ports, so
252- traffic for different devices is isolated.
252+ traffic for different devices is isolated.
253253
254254# ## Guidelines for single‑server parallelism
255255
256256- ** Do not share a UDID across concurrent sessions** on the same server; use one session per device.
257257- Ensure the ** tunnel script is running before** starting parallel tests so that the registry is
258- populated.
258+ populated.
259259- If you frequently add/remove devices, re‑run the tunnel script to refresh the registry.
260260
261261# # Parallel tests with multiple Appium servers
@@ -267,24 +267,24 @@ tunnel registry** and tunnel process.
267267
2682681. ** Start a single global tunnel process** :
269269
270- ```bash
271- sudo appium driver run xcuitest tunnel-creation --tunnel-registry-port 43000
272- ```
270+ ` ` ` bash
271+ sudo appium driver run xcuitest tunnel-creation --tunnel-registry-port 43000
272+ ` ` `
273273
274274 - Leave this running in the background.
275275 - It creates tunnels for all currently connected devices and exposes the registry on ` 43000` .
276276 - The registry port is persisted in a strongbox entry for ` appium-xcuitest-driver` so that all
277- driver instances running in the same environment can discover it.
277+ driver instances running in the same environment can discover it.
278278
2792792. ** Start multiple Appium servers** , for example:
280280
281- ``` bash
282- # Server 1
283- appium --port 4723
281+ ` ` ` bash
282+ # Server 1
283+ appium --port 4723
284284
285- # Server 2
286- appium --port 4725
287- ```
285+ # Server 2
286+ appium --port 4725
287+ ` ` `
288288
2892893. ** Assign devices to servers** via capabilities:
290290
@@ -294,16 +294,16 @@ tunnel registry** and tunnel process.
2942944. ** Run tests in parallel** across servers:
295295
296296 - Each server behaves as described in the single‑server section, using the shared tunnel
297- registry.
297+ registry.
298298 - Tunnels are created only once; both servers reuse the same IPv6 tunnel and Remote XPC
299- infrastructure for each device.
299+ infrastructure for each device.
300300
301301# ## Alternative: one tunnel process per isolation boundary
302302
303303In more advanced setups (e.g., Docker, multiple hosts, CI agents), you might:
304304
305305- Run ** one tunnel‑creation process per container/VM** , started together with that container’s
306- Appium server(s).
306+ Appium server(s).
307307- Use distinct ` --tunnel-registry-port` values for each isolation boundary.
308308
309309This keeps tunnel state scoped to each environment, but within that boundary you should still
@@ -316,9 +316,9 @@ TUN/TAP configuration and USBMUX connections.
316316- Ensure all Appium servers that should share tunnels:
317317 - Run under the same user or environment where the strongbox entry is accessible, or
318318 - Are configured to discover the same tunnel registry port (by starting the script with an
319- explicit ` --tunnel-registry-port ` ).
319+ explicit ` --tunnel-registry-port` ).
320320- As with a single server, never assign the ** same UDID to multiple concurrent sessions** unless
321- your test coordination knows exactly what it is doing.
321+ your test coordination knows exactly what it is doing.
322322
323323# # tvOS‑specific notes
324324
@@ -328,4 +328,4 @@ TUN/TAP configuration and USBMUX connections.
328328 - A tvOS 18+ ` platformVersion`
329329 - The UDID of the Apple TV device
330330- Only devices connected via USB are currently supported. Support for wirelessly connected TV
331- devices is coming.
331+ devices is coming.
0 commit comments