Skip to content

fix(devicelab_ios): the agent's start brings back the app it sent to the background - #274

Open
luka-vladika-happening-xyz wants to merge 3 commits into
devicelab-dev:mainfrom
luka-vladika-happening-xyz:fix/devicelab-ios-agent-start-keeps-front-app
Open

luka-vladika-happening-xyz wants to merge 3 commits into
devicelab-dev:mainfrom
luka-vladika-happening-xyz:fix/devicelab-ios-agent-start-keeps-front-app

Conversation

@luka-vladika-happening-xyz

@luka-vladika-happening-xyz luka-vladika-happening-xyz commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Fixes #273.

A fresh agent start (not a re-attach) reads which app is in front before it launches the agent and, once the agent answers, launches that app again with simctl launch (no --terminate-running-process). That brings the running app back as it was: the same process on the same page, in about 0.25 s. Both launch modes do it.

simctl does not say which app is in front, but each simulator app is a process of the Mac, and its scheduling priority does (ps -o pri): 47-53 for the app in front, 4 for an app in the background, 31 for the agent's own runner (iOS 27.2; iOS 17.5 the same, 47 and 4). Only the apps simctl listapps lists are read: launchctl list also lists system processes as apps, and the home screen's widget renderer reads 47 while the page with widgets shows. XCTest runners (bundle ids ending in .xctrunner) are left out. With no app at 40 or above the home screen was in front, and nothing is launched. Right after a switch the app that left keeps its priority for 1-5 s, so while two apps read as in front they are read again for up to 5 s; if both stay, nothing is launched.

Every command has a deadline. One log line says what was brought back or why nothing was, and an app that was not brought back gets a console line too, whose text a test keeps for tools that look for it.

Tested: unit tests with fake launchctl list, simctl listapps and ps answers for each rule. On an iPhone 18 Pro simulator (iOS 27.2) with the agent stopped, hierarchy read Settings on a subpage, Safari and the home screen (both pages) as they were, with DEVICELAB_IOS_AGENT_LAUNCH=simctl and xcodebuild, and on an iPhone 15 simulator (iOS 17.5) Settings on a subpage; a fresh start took about 0.6 s more (6.0 s to 6.6 s for hierarchy). go test -race ./... and golangci-lint v2.13.2 pass.

Added in the follow-ups:

  • TestSimctlDeadlineHoldsWhenOutputStaysOpen: a simctl call whose output a child keeps open returns about 2 s after its deadline.
  • TestStartAgentBringsBackTheFrontApp and TestStartAgentReattachLeavesTheFrontApp: the read before the agent's launch, the bring-back after it, neither on a re-attach.

Left out: the agent's revive (a restart after it stopped answering, in the middle of a flow) goes through the same launch and could do the same. Say if you want it here. Also left: an app sent to the background a moment before a fresh start keeps its priority for 1-5 s, so it reads as in front and is brought back.

…the background

The agent's XCTest runner is launched as an app (simctl launch has no
background launch, and xcodebuild launches it the same way), so a fresh
start sent the app in front of the simulator to the background, and once
the agent was up the home screen was left. A flow that starts with
launchApp never noticed; a hierarchy read, or a flow that goes on from the
screen another tool left, read the home screen instead.

A fresh start (not a re-attach) now reads which app is in front before it
launches the agent and, once the agent answers, launches that app again
with simctl launch (without --terminate-running-process), which brings the
running app back as it was: the same process on the same page, in about
0.25 s. simctl does not say which app is in front, but each simulator app
is a process of the Mac, and its scheduling priority does: 47-53 for the
app in front, 4 for one in the background, 31 for the agent's own runner
(iOS 27.2). Only the apps simctl listapps lists are read: launchctl also
lists system processes as apps, and the home screen's widget renderer
reads 47 while the page with widgets shows. XCTest runners are left out.
With no app at 40 or above the home screen was in front, and nothing is
launched. Right after a switch the app that left keeps its priority for
1-5 s, so while two apps read as in front they are read again for up to
5 s; if both stay, nothing is launched. Every command has a deadline. One
log line says what was brought back or why nothing was, and an app that
was not brought back is said on the console too, in a line a test keeps.
@codecov

codecov Bot commented Nov 14, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

The deadline of the simctl helper killed xcrun, but CombinedOutput then
waited for the output pipe to close, and `simctl spawn` hands that pipe to
the process it starts in the simulator, which the kill does not reach: on
a wedged simulator the 15 s deadline on `launchctl list` (the read of the
app in front before the agent's start) did not hold. cmd.WaitDelay now
bounds that wait to 2 s once xcrun has exited or been killed.

A test with a stand-in xcrun whose child keeps the output open for 8 s:
the call returns about 2 s after its 200 ms deadline (8 s without this).
…efore it and brings it back after

The order is what makes the bring-back work: the app in front must be read
before the agent's launch sends it to the background, and launched again
only once the agent answers. A test of StartAgent's fresh start (the
simulator holding this build, so nothing is installed) checks the calls in
order: launchctl list and listapps, the agent's launch, then simctl launch
of the app that was in front. A second checks that a re-attach to a kept
agent launches nothing and so reads and brings back nothing. The launch
goes through launchAgent, which the tests replace, as appContainer is.

They fail when the read follows the launch, when the bring-back is left
out, and when a re-attach reads the app in front.
@luka-vladika-happening-xyz

Copy link
Copy Markdown
Contributor Author

Two follow-ups pushed to this branch:

  • The simctl helper's calls return soon after their deadline. simctl spawn hands its output to the process it starts in the simulator, which the deadline's kill of xcrun does not reach, so on a wedged simulator the 15 s deadline on launchctl list (the read of the app in front) did not hold: CombinedOutput waited for the pipe. cmd.WaitDelay (2 s) on the helper now bounds that wait. A test with a stand-in xcrun whose child keeps the output open for 8 s returns about 2 s after its 200 ms deadline (8 s before). The package's other xcrun simctl calls are not changed: the agent's own simctl launch in launchSimctl, simctlEnv, simctlStdin and the stall diagnostics' screenshot.
  • Tests of the start's wiring. A fresh start reads the app in front, launches the agent, then launches that app again, in that order; a re-attach to a kept agent does none of it. The launch goes through a launchAgent variable the tests replace, as appContainer is.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

DeviceLab iOS: the agent's start sends the simulator's app in front to the background

2 participants