Skip to content

Commit 7847bcd

Browse files
Fix indentation
1 parent 2426433 commit 7847bcd

1 file changed

Lines changed: 84 additions & 84 deletions

File tree

docs/guides/remotexpc-tunnels-real-devices.md

Lines changed: 84 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -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

5555
To 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

144144
The response contains the IPv6 `address`, `rsdPort`, and other metadata required to establish
145145
Remote XPC connections.
@@ -153,40 +153,40 @@ tests against iOS/tvOS 18+ real devices using normal capabilities.
153153

154154
1. **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

162162
2. **Start the Appium server** (in a separate terminal):
163163

164-
```bash
165-
appium
166-
```
164+
```bash
165+
appium
166+
```
167167

168168
3. **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

181181
4. **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

191191
No extra capabilities are required to “enable” tunnels; they are automatically used when:
192192

@@ -207,55 +207,55 @@ Appium server as long as:
207207

208208
1. **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

214214
2. **Start one Appium server**:
215215

216-
```bash
217-
appium --port 4723
218-
```
216+
```bash
217+
appium --port 4723
218+
```
219219

220220
3. **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

246246
4. **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

268268
1. **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

279279
2. **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

289289
3. **Assign devices to servers** via capabilities:
290290

@@ -294,16 +294,16 @@ tunnel registry** and tunnel process.
294294
4. **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

303303
In 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

309309
This 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

Comments
 (0)