1.0.7 — fix flaky browser setup, and make the adb port configurable

[gautam-jain-dev]

Follow-up to #18, which fixed Brave's first-run race. Soaking all five browsers surfaced the same class of failure in the other scripts, plus three further defects. Also folds in a small, independent change: the adb server port is now configurable.

Problem

Sessions fail intermittently at creation with socket hang up or Debug list is empty or invalid on /json/list.

The skip-welcome-* scripts clear the browser profile — which guarantees first-run onboarding appears — then dismiss it by clicking a hard-coded sequence of controls. That choreography is racy in practice:

• Dialog order and content vary per launch. Brave's first dialog was android:id/button2 on one run and com.brave.browser:id/btn_negative on the next.
• Some stages are conditional. Opera unconditionally waited 30 s for the "Allow" notification prompt; when it does not appear the script threw with onboarding still on screen.
• Edge's first-run screen is web-rendered and sometimes shows none of the expected controls ("Not now" missed 21 times in one run).
• An Android system dialog can cover everything. A page-source dump during a failure showed "System UI isn't responding" / "Close app" / "Wait" — a SystemUI ANR over the welcome screen. No expected element is findable, and restarting the browser does not clear it.

When any of these happen the browser never opens its devtools socket. Worse, most of these scripts caught every error and still exited 0, so the caller reported success and started a session that could not work.

Fix

Converge on the end state the driver needs instead of requiring a fixed sequence. New scripts/browserReady.js:

• dismisses whatever is on screen from a set of known-safe controls (ANR "Wait" first, so a system dialog is cleared before anything beneath it is touched);
• relaunches the browser when nothing is dismissable;
• treats the browser as ready only when onboarding is gone, the devtools endpoint belongs to this package, and /json/list reports an attachable page target. Ownership is checked through the Android-Package field of /json/version, since chrome, brave and edge share the chrome_devtools_remote name; the page check ignores worker targets, which also carry a webSocketDebuggerUrl. The list is polled, not slept on;
• throws if the browser never becomes ready, so a failed setup is visible immediately instead of surfacing later as an opaque session error.

Browser	Change
edge	Optional FRE suppression, off by default (see below). Walkthrough and readiness pass handle it otherwise.
opera	continue_button and the Allow dialog are optional; clicks no longer abort the walkthrough when the screen changes underneath them. Opera does not honour the Chromium flag (its onboarding is com.opera.android.startup.WelcomeActivity), so it relies on the readiness pass.
duckduckgo	Readiness uses the pid-scoped webview_devtools_remote_<pid> socket — the bare prefix also matches other apps' WebViews.
samsung	Readiness check added; walkthrough unchanged.
brave	Shares the readiness helper. The flag written by #18 is now opt-in (see below).

src/driver.js

1. Target selection. data.find((t) => t.url.includes('appium.io')) was a hard requirement; after a redirect, a new tab, or an onboarding page there is no such target and the session failed with Cannot read properties of undefined (reading 'webSocketDebuggerUrl'). Now falls back to any page target with a debugger URL, with a clear error if there is none. This reproduced independently on a second host after ~150 clean runs.
2. Empty debug list. When /json/list returned [] the driver retried the fetch ten times, but nothing in that loop made a page appear. It now opens the start URL between attempts, via a new openStartUrl() — deliberately a plain VIEW intent rather than startApplication(), because the latter passes -S and force-stops the process; for WebView browsers the pid changes and the existing port forward is left pointing at a dead socket.

Configurable adb server port

The driver could only talk to adb on 5037: ADB.createADB() was called with no options in six places, and the appium:adbPort capability that callers already send was discarded (sessions logged it under "capabilities were provided, but are not recognized"). The port now resolves as appium:adbPort → CDP_ADB_PORT → 5037.

The environment variable is not redundant: the skip-welcome-* scripts run as separate processes and never see the session's capabilities, so a capability-only fix would leave the browser setup on the requested port while the walkthrough silently used 5037. Each script also passes the resolved port into its UiAutomator2 session, so both halves address the same adb server.

No behaviour change when neither is set — resolveAdbPort() returns 5037, and unusable values fall back to it rather than producing a broken -P. Covered by tests.

Verified on an Android emulator host, against a live Android 15 emulator:

Case	Resolved	adb argv	Result
Neither set	5037	-P 5037	adb shell getprop → sdk=35
CDP_ADB_PORT=5038, default server killed	5038	-P 5038	sdk=35, with 0 listeners on 5037 for the whole case
appium:adbPort=5038, default server killed	5038	-P 5038	sdk=35
CDP_ADB_PORT=5039 pointed at a non-adb listener, 5037 healthy	5039	-P 5039	fails — no silent fallback

The second case is the load-bearing one: with no adb server on 5037 at all, the 5038 server answered with a device entry (127.0.0.1:5555) that only it had. The last case is the inverse — a healthy 5037 was deliberately left running, and the driver still failed on the port it was told to use rather than quietly succeeding elsewhere.

Verification

A controlled A/B on Android 15 and 16 emulators (Appium 2.6.0), five browsers rotating, one session at a time, 400 tests in four builds of 100:

Group	Driver	Tests	Passed	Session-creation failures
host A	this branch	100	100	0
host B	this branch	100	100	0
long-lived machines	current release	100	84	16 (16%)
freshly provisioned machines	current release	100	100	0

Every failure was brave (13) or Edge (3) — exactly the two browsers whose first-run experience this change suppresses. Opera, DuckDuckGo and Samsung never failed anywhere. The freshly-provisioned control is the useful one: it ran the same current release and was clean, because a new machine has no stale first-run state — which isolates the cause to onboarding state rather than the driver, the machine, or the OS version.

FRE suppression was measured separately: 31 launches on freshly-cleared profiles across brave and Edge, 0 first-run screens. Note the 400-test run above had suppression enabled; the default path (readiness pass only, no file written) has not been measured at that scale for brave and edge, though it is the path the other three browsers used throughout.

Tests: test/browser-ready.spec.js (page-vs-worker target selection) and test/adb-port.spec.js (port resolution, including the 5037 default) — 10 cases, all passing.

Notes for the reviewer

• First-run suppression is opt-in. /data/local/tmp/chrome-command-line is shared with Chrome, and chromedriver writes its own chromeOptions.args there, so writing it for brave or edge could change an unrelated Chrome session on the same device. Nothing is written unless CDP_SUPPRESS_FIRST_RUN=1 is set; by default onboarding is handled by the readiness pass, as it is for opera, duckduckgo and samsung. Note this differs from fix: flaky browser setup — converge on devtools readiness instead of onboarding choreography #18, which wrote the file unconditionally for brave.
• Whether brave and edge honour a package-specific command-line file is unknown. It would avoid the shared path entirely, but I could not establish it: the only emulators available for testing are inside sessions that pin the foreground app, so a second browser cannot be launched in them. If you know the answer, this could become a per-package file and the opt-in would be unnecessary.
• am start does not honour a bare trailing package. Both openStartUrl() and the readiness helper's page-open step used that form and were opening the start URL in whichever browser handles VIEW by default; they now pass -n <package>/<activity>. This was invisible in practice because a page was usually already present from the preceding launch.
• The ownership check is best-effort. /json/version on some forks may omit Android-Package; when the field is absent the endpoint is accepted, since the socket name is browser-specific for everything except the chrome/brave/edge trio.
• Samsung has no failure evidence behind it — it never failed in 400 tests. The readiness check was added for consistency, as its walkthrough has the same swallow-everything shape as the others.
• Readiness costs a few adb calls and a short poll per setup on the happy path; the previous fixed 4 s sleep was removed in favour of polling.

🤖 Generated with Claude Code