feat: Let binding IP address to be configurable via USE_IP environment variable #1066

karlbaumg · 2025-10-30T19:56:21Z

We run multiple instances of iOS Simulator on the same macOS host and each gets an IP address from a central IP address management for all simulators in the network, but when they all start WebDriverAgent, they get "address in use" errors as expected.

The suggested way of preventing this is to use USE_PORT but that introduces two challenges:

We need synchronization and lock for the instances running on the same host apart from IP management we already have,
The host must communicate back and tell which port belongs to which iOS simulator instance. With IP, we already have that information centrally so we'd always keep going to :8100 for WebDriverAgent.

This change introduces USE_IP environment variable where users can optionally change the IP that the RoutingHTTPServer binds to remove the need for host-wide synchronization for port number in scenarios where each simulator already has a known IP.

Here is how I tested it:

Add the custom IP to lo0 interface so WDA can bind.
```
sudo ifconfig lo0 alias 10.244.1.2
```

Run it in a simulator with the following command:

xcodebuild test \
  -project WebDriverAgent.xcodeproj \
  -scheme WebDriverAgentRunner \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
  USE_IP=10.244.1.2

Once up and running, you'll see these log lines:

2025-10-30 22:48:37.208232+0300 WebDriverAgentRunner-Runner[52590:11285751] Using custom binding IP address: 10.244.1.2
2025-10-30 22:48:37.208485+0300 WebDriverAgentRunner-Runner[52590:11285751] ServerURLHere->http://10.244.1.2:8100<-ServerURLHere

Test if it serves only on this custom IP:

curl http://10.244.1.2:8100/health
<!DOCTYPE html><html><title>Health Check</title><body><p>I-AM-ALIVE</p></body></html>

curl http://127.0.0.1:8100/health
curl: (7) Failed to connect to 127.0.0.1 port 8100 after 0 ms: Couldn't connect to server

When I run it with the following command, e.g. no override, I see usual behavior.

xcodebuild test \
  -project WebDriverAgent.xcodeproj \
  -scheme WebDriverAgentRunner \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro'

2025-10-30 22:53:28.503846+0300 WebDriverAgentRunner-Runner[57207:11300071] Built at Oct 30 2025 22:48:25
2025-10-30 22:53:28.517162+0300 WebDriverAgentRunner-Runner[57207:11300071] ServerURLHere->http://192.168.1.110:8100<-ServerURLHere

curl http://127.0.0.1:8100/health
<!DOCTYPE html><html><title>Health Check</title><body><p>I-AM-ALIVE</p></body></html>

curl http://192.168.1.110:8100/health
<!DOCTYPE html><html><title>Health Check</title><body><p>I-AM-ALIVE</p></body></html>

linux-foundation-easycla · 2025-10-30T19:56:28Z

The committers listed above are authorized under a signed CLA.

✅ login: karlbaumg / name: Karl Baumgartner (1946c97, 2b5150e, 2d5d803, f88b345)

lib/utils.js

lib/webdriveragent.js

WebDriverAgentLib/Routing/FBWebServer.m

…lator scenarios Signed-off-by: Karl Baumgartner <178656887+karlbaumg@users.noreply.github.com>

Signed-off-by: Karl Baumgartner <178656887+karlbaumg@users.noreply.github.com>

karlbaumg · 2025-10-31T08:29:58Z

Thanks @mykola-mokhnach ! I addressed all the comments and tested again with the flow in the PR description.

lib/utils.js

Signed-off-by: Karl Baumgartner <178656887+karlbaumg@users.noreply.github.com>

karlbaumg · 2025-10-31T11:09:09Z

@mykola-mokhnach Some of the integration tests seem to be failing but they don't look related. Are they flaky? Do I need to do anything?

mykola-mokhnach · 2025-10-31T12:27:31Z

yes, they are sometimes flaky due to the general CI slowness. Don't worry about them. I just wanted @KazuCocoa to take another look at the PR and them we could merge it

KazuCocoa

lg, let us merge once ci worked

KazuCocoa · 2025-10-31T15:36:41Z

lib/types.ts

  wdaLocalPort?: number;
  wdaRemotePort?: number;
  wdaBaseUrl?: string;
+  wdaBindingIP?: string;


mykola-mokhnach · 2025-10-31T19:05:09Z

@karlbaumg Would you also like to also create a follow-up PR to https://github.com/appium/appium-xcuitest-driver ?

## [10.2.0](v10.1.4...v10.2.0) (2025-10-31) ### Features * Let binding IP address to be configurable via USE_IP environment variable ([#1066](#1066)) ([70ed7cf](70ed7cf))

github-actions · 2025-10-31T19:13:55Z

🎉 This PR is included in version 10.2.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

karlbaumg · 2025-11-01T09:13:35Z

@mykola-mokhnach Sure. While doing that, I noticed some missing pieces that was uncovered when I tested end to end with the driver. #1067 is the fix for those and appium/appium-xcuitest-driver#2645 waits for that PR to be merged.

KazuCocoa · 2025-11-15T07:34:54Z

Hi @karlbaumg, congrats: the Appium project wants to compensate you for this contribution! Please reply to this comment mentioning @jlipps and @KazuCocoa and sharing your OpenCollective account name, so that we can initiate payment! Or let us know if you decline to receive compensation via OpenCollective. Thank you!

KazuCocoa changed the title ~~Let binding IP address to be configurable~~ feat: Let binding IP address to be configurable via USE_IP environment variable Oct 31, 2025

KazuCocoa reviewed Oct 31, 2025

View reviewed changes

lib/utils.js Outdated Show resolved Hide resolved

KazuCocoa requested a review from mykola-mokhnach October 31, 2025 06:03

mykola-mokhnach reviewed Oct 31, 2025

View reviewed changes

lib/utils.js Outdated Show resolved Hide resolved

mykola-mokhnach reviewed Oct 31, 2025

View reviewed changes

lib/webdriveragent.js Outdated Show resolved Hide resolved

mykola-mokhnach reviewed Oct 31, 2025

View reviewed changes

lib/webdriveragent.js Show resolved Hide resolved

mykola-mokhnach reviewed Oct 31, 2025

View reviewed changes

WebDriverAgentLib/Routing/FBWebServer.m Outdated Show resolved Hide resolved

karlbaumg added 3 commits October 31, 2025 11:14

wda: add USE_IP env var to override what IP to bind to for multi-simu…

2b5150e

…lator scenarios Signed-off-by: Karl Baumgartner <178656887+karlbaumg@users.noreply.github.com>

wda: make sure we log the true server host when USE_IP is used too

f88b345

Signed-off-by: Karl Baumgartner <178656887+karlbaumg@users.noreply.github.com>

lib: update to incorporate the new USE_IP env var

2d5d803

Signed-off-by: Karl Baumgartner <178656887+karlbaumg@users.noreply.github.com>

karlbaumg force-pushed the add-bind-ip branch from d5ae56f to 2d5d803 Compare October 31, 2025 08:23

mykola-mokhnach reviewed Oct 31, 2025

View reviewed changes

lib/utils.js Outdated Show resolved Hide resolved

mykola-mokhnach reviewed Oct 31, 2025

View reviewed changes

lib/utils.js Outdated Show resolved Hide resolved

mykola-mokhnach reviewed Oct 31, 2025

View reviewed changes

lib/utils.js Show resolved Hide resolved

mykola-mokhnach approved these changes Oct 31, 2025

View reviewed changes

lib: fix the jsdoc for the optional wdaBindingIp argument

1946c97

Signed-off-by: Karl Baumgartner <178656887+karlbaumg@users.noreply.github.com>

KazuCocoa approved these changes Oct 31, 2025

View reviewed changes

lib/types.ts

wdaLocalPort?: number;

wdaRemotePort?: number;

wdaBaseUrl?: string;

wdaBindingIP?: string;

Copy link

Member

KazuCocoa Oct 31, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍

mykola-mokhnach merged commit 70ed7cf into appium:master Oct 31, 2025
40 of 44 checks passed

github-actions bot added the released label Oct 31, 2025

This was referenced Nov 1, 2025

fix: update xcodebuild commands for the new binding ip capability #1067

Merged

chore: update webdriveragent to 10.2.1 appium/appium-xcuitest-driver#2645

Merged

KazuCocoa added the size:S contribution size: S label Nov 1, 2025

feat: Let binding IP address to be configurable via USE_IP environment variable #1066

feat: Let binding IP address to be configurable via USE_IP environment variable #1066

Uh oh!

Conversation

karlbaumg commented Oct 30, 2025

Uh oh!

linux-foundation-easycla bot commented Oct 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

karlbaumg commented Oct 31, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

karlbaumg commented Oct 31, 2025

Uh oh!

mykola-mokhnach commented Oct 31, 2025

Uh oh!

KazuCocoa left a comment

Choose a reason for hiding this comment

Uh oh!

KazuCocoa Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mykola-mokhnach commented Oct 31, 2025

Uh oh!

github-actions bot commented Oct 31, 2025

Uh oh!

karlbaumg commented Nov 1, 2025

Uh oh!

KazuCocoa commented Nov 15, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

linux-foundation-easycla bot commented Oct 30, 2025 •

edited

Loading