From bb951d1d11d19f9387f0dce9122d80ecdd679feb Mon Sep 17 00:00:00 2001 From: lvladika Date: Sat, 14 Nov 2026 11:17:39 +0100 Subject: [PATCH] fix(devicelab_ios): the agent's start brings back the app it sent to 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. --- pkg/driver/devicelab_ios/agent.go | 3 + pkg/driver/devicelab_ios/front.go | 228 +++++++++++++++++++ pkg/driver/devicelab_ios/front_test.go | 293 +++++++++++++++++++++++++ 3 files changed, 524 insertions(+) create mode 100644 pkg/driver/devicelab_ios/front.go create mode 100644 pkg/driver/devicelab_ios/front_test.go diff --git a/pkg/driver/devicelab_ios/agent.go b/pkg/driver/devicelab_ios/agent.go index 07a2e290..5cb35bc3 100644 --- a/pkg/driver/devicelab_ios/agent.go +++ b/pkg/driver/devicelab_ios/agent.go @@ -250,10 +250,13 @@ func StartAgent(ctx context.Context, opts AgentOptions) (*Agent, *Client, error) if err := a.install(ctx, m.Version); err != nil { return nil, nil, err } + // The launch sends the app in front to the background (front.go). + front, why := frontApp(ctx, opts.UDID) c, err := a.launch(ctx) if err != nil { return nil, nil, err } + a.bringBack(ctx, front, why) c.SetReviver(a.revive) return a, c, nil } diff --git a/pkg/driver/devicelab_ios/front.go b/pkg/driver/devicelab_ios/front.go new file mode 100644 index 00000000..49a7189d --- /dev/null +++ b/pkg/driver/devicelab_ios/front.go @@ -0,0 +1,228 @@ +package devicelab_ios + +import ( + "context" + "errors" + "fmt" + "io" + "os" + "os/exec" + "strconv" + "strings" + "time" + + "github.com/devicelab-dev/maestro-runner/pkg/logger" +) + +// The agent's start sends the app in front of the simulator to the +// background: its XCTest runner is launched as an app (simctl launch has no +// background launch, and xcodebuild launches it the same way), and once it +// is up the home screen is left. A flow that starts with launchApp never +// notices; a hierarchy read, or a flow that goes on from the screen another +// tool left, found the home screen instead. So a fresh start reads which app +// was in front before it, and launches that app again once the agent +// answers: simctl launch of a running app brings it to the front 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 (ps's pri, iOS 27.2): +// 47-53 for the app in front, 4 for an app in the background, 31 for the +// agent's own runner. An app that leaves the front keeps its priority for 1-5 +// s, so right after a switch two apps read as in front. launchctl also lists +// system processes as apps, and the home screen's widget renderer reads 47 +// while the page with widgets shows: only the apps simctl listapps knows are +// read (it lists Settings and Safari, not the renderer, Spotlight or the +// Messages view service). + +// frontPriority is the lowest priority that reads as in front: above the +// background's 4 and the 31 of a background process that is not throttled +// (the agent's runner), below the front's 47. +const frontPriority = 40 + +// frontSettle bounds the wait for one of two apps that read as in front to +// drop, and frontPoll is how often they are read again meanwhile. +var ( + frontSettle = 5 * time.Second + frontPoll = 250 * time.Millisecond +) + +// runningApp is an app running on the simulator. +type runningApp struct { + id string + pid int +} + +// frontSimctl runs simctl for frontApp and bringBack; tests replace it. +var frontSimctl = simctl + +// readPriorities answers `ps -o pid=,pri=` for pids, "" when none of them +// runs any more; tests replace it. +var readPriorities = func(ctx context.Context, pids []int) (string, error) { + list := make([]string, len(pids)) + for i, pid := range pids { + list[i] = strconv.Itoa(pid) + } + c, cancel := context.WithTimeout(ctx, 10*time.Second) + defer cancel() + out, err := exec.CommandContext(c, "ps", "-o", "pid=,pri=", "-p", strings.Join(list, ",")).Output() + var exit *exec.ExitError + if errors.As(err, &exit) && c.Err() == nil && len(strings.TrimSpace(string(out))) == 0 { + return "", nil // ps exits 1 when it finds none of the pids + } + return string(out), err +} + +// installedApps parses `simctl listapps` for the bundle ids it lists (each +// entry's CFBundleIdentifier). +func installedApps(listapps string) map[string]bool { + ids := map[string]bool{} + for _, line := range strings.Split(listapps, "\n") { + k, v, ok := strings.Cut(strings.TrimSpace(line), "=") + if ok && strings.TrimSpace(k) == "CFBundleIdentifier" { + ids[strings.Trim(strings.TrimSpace(v), `";`)] = true + } + } + return ids +} + +// runningApps parses `launchctl list` for the running apps (each listed as +// PID, status, UIKitApplication:BUNDLE[xxxx][rb-legacy]) that installed +// holds, leaving out XCTest runners (bundle ids ending in .xctrunner): this +// agent's, another tool's, WebDriverAgent's. +func runningApps(list string, installed map[string]bool) []runningApp { + var apps []runningApp + for _, line := range strings.Split(list, "\n") { + f := strings.Fields(line) + if len(f) < 3 || !strings.HasPrefix(f[2], "UIKitApplication:") { + continue + } + pid, err := strconv.Atoi(f[0]) + if err != nil || pid <= 0 { // "-": not running + continue + } + id := strings.TrimPrefix(f[2], "UIKitApplication:") + if i := strings.IndexByte(id, '['); i >= 0 { + id = id[:i] + } + if !installed[id] || strings.HasSuffix(id, ".xctrunner") { + continue + } + apps = append(apps, runningApp{id: id, pid: pid}) + } + return apps +} + +// inFront keeps the apps whose priority in ps's answer reads as in front. +func inFront(apps []runningApp, ps string) []runningApp { + pri := map[int]int{} + for _, line := range strings.Split(ps, "\n") { + f := strings.Fields(line) + if len(f) != 2 { + continue + } + pid, err1 := strconv.Atoi(f[0]) + p, err2 := strconv.Atoi(f[1]) + if err1 == nil && err2 == nil { + pri[pid] = p + } + } + var front []runningApp + for _, app := range apps { + if p, ok := pri[app.pid]; ok && p >= frontPriority { + front = append(front, app) + } + } + return front +} + +// frontApp reads the app in front of the simulator: nil with an empty why +// for the home screen, nil with why when it cannot tell. While two or more +// apps read as in front it reads them again, up to frontSettle. +func frontApp(ctx context.Context, udid string) (*runningApp, string) { + list, err := frontSimctl(ctx, 15*time.Second, "spawn", udid, "launchctl", "list") + if err != nil { + return nil, fmt.Sprintf("launchctl list: %v", err) + } + listapps, err := frontSimctl(ctx, 15*time.Second, "listapps", udid) + if err != nil { + return nil, fmt.Sprintf("simctl listapps: %v", err) + } + apps := runningApps(list, installedApps(listapps)) + deadline := time.Now().Add(frontSettle) + for { + var front []runningApp + if len(apps) > 0 { + pids := make([]int, len(apps)) + for i, app := range apps { + pids[i] = app.pid + } + out, err := readPriorities(ctx, pids) + if err != nil { + return nil, fmt.Sprintf("ps: %v", err) + } + front = inFront(apps, out) + } + switch { + case len(front) == 0: + return nil, "" + case len(front) == 1: + return &front[0], "" + } + if !time.Now().Add(frontPoll).Before(deadline) { + ids := make([]string, len(front)) + for i, app := range front { + ids[i] = app.id + } + return nil, fmt.Sprintf("%s read as in front for %s", strings.Join(ids, " and "), frontSettle) + } + apps = front // a switch is under way: wait for the app that left to drop + select { + case <-ctx.Done(): + return nil, ctx.Err().Error() + case <-time.After(frontPoll): + } + } +} + +// bringBack launches the app that was in front before the agent's start +// (frontApp's answer) again, and says in the log what it did. +func (a *Agent) bringBack(ctx context.Context, app *runningApp, why string) { + switch { + case why != "": + notBroughtBack("which app was in front is not known: " + why) + case app == nil: + logger.Info("[devicelab-ios] the home screen was in front before the agent's start: nothing to bring back") + default: + // Without --terminate-running-process: the running app comes to + // the front as it was. + start := time.Now() + out, err := frontSimctl(ctx, 30*time.Second, "launch", a.opts.UDID, app.id) + out = strings.TrimSpace(out) + if err != nil { + notBroughtBack(fmt.Sprintf("simctl launch %s: %v: %s", app.id, err, out)) + return + } + anew := "" + if !strings.HasSuffix(out, ": "+strconv.Itoa(app.pid)) { + anew = ", started anew: " + out + } + logger.Info("[devicelab-ios] brought %s back to the front, where it was before the agent's start (%s%s)", + app.id, time.Since(start).Round(time.Millisecond), anew) + } +} + +// notBroughtBack says why the app in front before the agent's start was not +// brought back, on the console too (notBroughtBackLine): the run may begin on +// the home screen. +func notBroughtBack(why string) { + logger.Warn("[devicelab-ios] %s%s", notBroughtBackLine, why) + fmt.Fprintf(frontConsole, " ⚠ %s%s\n", notBroughtBackLine, oneLine(why)) +} + +// notBroughtBackLine starts the console line of an app not brought back. A +// tool that drives the runner may look for it to tell its user, so a test +// keeps it as it is. +const notBroughtBackLine = "the app in front before the agent's start was not brought back: " + +// frontConsole is where notBroughtBack's line goes; tests replace it. +var frontConsole io.Writer = os.Stderr diff --git a/pkg/driver/devicelab_ios/front_test.go b/pkg/driver/devicelab_ios/front_test.go new file mode 100644 index 00000000..d57c856c --- /dev/null +++ b/pkg/driver/devicelab_ios/front_test.go @@ -0,0 +1,293 @@ +package devicelab_ios + +import ( + "bytes" + "context" + "errors" + "fmt" + "os" + "path/filepath" + "strings" + "sync" + "testing" + "time" + + "github.com/devicelab-dev/maestro-runner/pkg/logger" +) + +// launchdList is `launchctl list` on a simulator (iOS 27.2): Settings and +// Safari running, Maps not, the agent's runner and WebDriverAgent's running, +// and three system processes listed as apps: the home screen's widget +// renderer, Spotlight and the Messages view service. +const launchdList = `PID Status Label +- 0 com.apple.progressd +45983 0 com.apple.CoreAuthentication.daemon +25658 0 UIKitApplication:com.apple.Preferences[2b8b][rb-legacy] +45920 0 UIKitApplication:com.apple.mobilesafari[d3ff][rb-legacy] +- 0 UIKitApplication:com.apple.Maps[1c2d][rb-legacy] +48829 0 UIKitApplication:dev.devicelab.agent.uitests.xctrunner[4364][rb-legacy] +51000 0 UIKitApplication:com.facebook.WebDriverAgentRunner.xctrunner[77aa][rb-legacy] +93754 0 UIKitApplication:com.apple.chrono.WidgetRenderer-Default[a3a3][rb-legacy] +93805 0 UIKitApplication:com.apple.Spotlight[8b49][rb-legacy] +46071 0 UIKitApplication:com.apple.iMessageAppsViewService[3a9f][rb-legacy] +` + +// listApps is `simctl listapps` on that simulator, cut short: the apps a +// person sees and the agent's, none of the system processes above. +const listApps = `{ + "com.apple.Maps" = { + ApplicationType = System; + CFBundleDisplayName = Maps; + CFBundleIdentifier = "com.apple.Maps"; + GroupContainers = { + "group.com.apple.Maps" = "file:///x/"; + }; + }; + "com.apple.Preferences" = { + ApplicationType = System; + CFBundleIdentifier = "com.apple.Preferences"; + }; + "com.apple.mobilesafari" = { + ApplicationType = System; + CFBundleIdentifier = "com.apple.mobilesafari"; + }; + "dev.devicelab.agent.uitests.xctrunner" = { + ApplicationType = User; + CFBundleIdentifier = "dev.devicelab.agent.uitests.xctrunner"; + }; + "com.facebook.WebDriverAgentRunner.xctrunner" = { + ApplicationType = User; + CFBundleIdentifier = "com.facebook.WebDriverAgentRunner.xctrunner"; + }; +} +` + +const settings, safari, renderer = 25658, 45920, 93754 + +// fakeFront stands in for simctl and ps: launchctl answers list (or +// listErr), listapps answers apps (or appsErr), ps answers each pid the +// priority its function gives at that call (absent: not running), and a +// launch is recorded. +type fakeFront struct { + mu sync.Mutex + list string + listErr error + apps string + appsErr error + pri func(pid, call int) (int, bool) + psErr error + psCalls int + launches []string + launch func(id string) (string, error) +} + +func (f *fakeFront) install(t *testing.T) { + t.Helper() + savedSimctl, savedPS := frontSimctl, readPriorities + savedSettle, savedPoll := frontSettle, frontPoll + t.Cleanup(func() { + frontSimctl, readPriorities = savedSimctl, savedPS + frontSettle, frontPoll = savedSettle, savedPoll + }) + frontSettle, frontPoll = 300*time.Millisecond, 20*time.Millisecond + frontSimctl = func(_ context.Context, timeout time.Duration, args ...string) (string, error) { + if timeout <= 0 { + t.Errorf("simctl %v without a deadline", args) + } + f.mu.Lock() + defer f.mu.Unlock() + switch cmd := strings.Join(args, " "); { + case cmd == "spawn SIM-1 launchctl list": + return f.list, f.listErr + case cmd == "listapps SIM-1": + return f.apps, f.appsErr + case strings.HasPrefix(cmd, "launch "): + f.launches = append(f.launches, cmd) + if f.launch != nil { + return f.launch(args[len(args)-1]) + } + return args[len(args)-1] + ": 25658", nil + default: + t.Errorf("unexpected simctl %s", cmd) + return "", errors.New("unexpected") + } + } + readPriorities = func(_ context.Context, pids []int) (string, error) { + f.mu.Lock() + defer f.mu.Unlock() + f.psCalls++ + if f.psErr != nil { + return "", f.psErr + } + var b strings.Builder + for _, pid := range pids { + if p, ok := f.pri(pid, f.psCalls); ok { + fmt.Fprintf(&b, "%5d %3d\n", pid, p) + } + } + return b.String(), nil + } +} + +// priorities answers fixed priorities by pid. +func priorities(m map[int]int) func(int, int) (int, bool) { + return func(pid, _ int) (int, bool) { p, ok := m[pid]; return p, ok } +} + +// captureFront collects the log and the console of the front app's code. +func captureFront(t *testing.T) (log func() string, console *bytes.Buffer) { + t.Helper() + path := filepath.Join(t.TempDir(), "runner.log") + if err := logger.Init(path); err != nil { + t.Fatal(err) + } + t.Cleanup(logger.Close) + console = &bytes.Buffer{} + saved := frontConsole + frontConsole = console + t.Cleanup(func() { frontConsole = saved }) + return func() string { + data, err := os.ReadFile(path) + if err != nil { + t.Fatal(err) + } + return string(data) + }, console +} + +func TestRunningApps(t *testing.T) { + got := runningApps(launchdList, installedApps(listApps)) + want := []runningApp{{"com.apple.Preferences", settings}, {"com.apple.mobilesafari", safari}} + if fmt.Sprint(got) != fmt.Sprint(want) { + t.Errorf("runningApps = %v, want %v (no daemon, no app that is not running, no XCTest runner, no system process listapps does not list)", got, want) + } + if apps := installedApps(listApps); len(apps) != 5 || !apps["com.apple.Maps"] || apps["group.com.apple.Maps"] { + t.Errorf("installedApps = %v", apps) + } +} + +func TestFrontApp(t *testing.T) { + for _, tc := range []struct { + name string + pri func(pid, call int) (int, bool) + want string // the app's id, "" for none + why string // a part of why, "" for none + minWait time.Duration + }{ + {name: "the app in front", pri: priorities(map[int]int{settings: 53, safari: 4, renderer: 4}), want: "com.apple.Preferences"}, + {name: "Safari's 47 reads as in front", pri: priorities(map[int]int{settings: 4, safari: 47, renderer: 4}), want: "com.apple.mobilesafari"}, + {name: "the home screen: every app in the background", pri: priorities(map[int]int{settings: 4, safari: 4, renderer: 4})}, + { + // The home screen's page with widgets: its renderer reads 47 + // the whole time, and brought "back" it covers the screen. + name: "the home screen's widgets: the renderer is no app", + pri: priorities(map[int]int{settings: 4, safari: 4, renderer: 47}), + }, + {name: "a background app that is not throttled is not in front", pri: priorities(map[int]int{settings: 31, safari: 4})}, + {name: "an app that ended is not in front", pri: priorities(map[int]int{safari: 4})}, + { + name: "two after a switch: the one that left drops", + pri: func(pid, call int) (int, bool) { + if pid == settings && call >= 3 { + return 4, true + } + return map[int]int{settings: 53, safari: 47, renderer: 47}[pid], true + }, + want: "com.apple.mobilesafari", + minWait: 2 * 20 * time.Millisecond, + }, + { + name: "two that stay: nothing", + pri: priorities(map[int]int{settings: 53, safari: 47}), + why: "com.apple.Preferences and com.apple.mobilesafari read as in front for 300ms", + minWait: 250 * time.Millisecond, + }, + } { + t.Run(tc.name, func(t *testing.T) { + f := &fakeFront{list: launchdList, apps: listApps, pri: tc.pri} + f.install(t) + start := time.Now() + app, why := frontApp(context.Background(), "SIM-1") + got := "" + if app != nil { + got = app.id + } + if got != tc.want || (tc.why == "") != (why == "") || !strings.Contains(why, tc.why) { + t.Errorf("frontApp = %q, %q; want %q, %q", got, why, tc.want, tc.why) + } + if waited := time.Since(start); waited < tc.minWait || waited > 2*time.Second { + t.Errorf("frontApp took %s, want at least %s", waited, tc.minWait) + } + }) + } +} + +func TestFrontAppCannotTell(t *testing.T) { + f := &fakeFront{list: launchdList, apps: listApps, listErr: errors.New("exit status 148"), pri: priorities(nil)} + f.install(t) + if app, why := frontApp(context.Background(), "SIM-1"); app != nil || !strings.Contains(why, "launchctl list: exit status 148") { + t.Errorf("launchctl failing: frontApp = %v, %q", app, why) + } + f.listErr, f.appsErr = nil, errors.New("exit status 2") + if app, why := frontApp(context.Background(), "SIM-1"); app != nil || !strings.Contains(why, "simctl listapps: exit status 2") { + t.Errorf("listapps failing: frontApp = %v, %q", app, why) + } + f.appsErr, f.psErr = nil, errors.New("signal: killed") + if app, why := frontApp(context.Background(), "SIM-1"); app != nil || !strings.Contains(why, "ps: signal: killed") { + t.Errorf("ps failing: frontApp = %v, %q", app, why) + } + f.psErr = nil + f.list = "PID\tStatus\tLabel\n" // no app runs: ps is not asked + if app, why := frontApp(context.Background(), "SIM-1"); app != nil || why != "" || f.psCalls != 1 { + t.Errorf("no app: frontApp = %v, %q, ps calls %d", app, why, f.psCalls) + } +} + +func TestBringBack(t *testing.T) { + a := &Agent{opts: AgentOptions{UDID: "SIM-1"}} + ctx := context.Background() + log, console := captureFront(t) + + f := &fakeFront{} + f.install(t) + a.bringBack(ctx, &runningApp{"com.apple.Preferences", settings}, "") + if fmt.Sprint(f.launches) != "[launch SIM-1 com.apple.Preferences]" { + t.Errorf("the app in front: launches = %v, want it launched again (without --terminate-running-process)", f.launches) + } + if l := log(); !strings.Contains(l, "brought com.apple.Preferences back to the front") || strings.Contains(l, "anew") || console.Len() != 0 { + t.Errorf("the app back: log %q, console %q", l, console) + } + + // An app that ended meanwhile is started again: simctl answers another pid. + f.launch = func(id string) (string, error) { return id + ": 31337\n", nil } + a.bringBack(ctx, &runningApp{"com.apple.Preferences", settings}, "") + if l := log(); !strings.Contains(l, "started anew: com.apple.Preferences: 31337") { + t.Errorf("an app that ended: log %q", l) + } + + f.launches = nil + a.bringBack(ctx, nil, "") + if len(f.launches) != 0 || !strings.Contains(log(), "the home screen was in front") || console.Len() != 0 { + t.Errorf("the home screen: launches = %v, console %q", f.launches, console) + } + a.bringBack(ctx, nil, "ps: signal: killed") + if len(f.launches) != 0 { + t.Errorf("an app not known: launches = %v, want none", f.launches) + } + // The console line is a contract: a tool that drives the runner looks + // for it to tell its user the app was not brought back. + if want := " ⚠ the app in front before the agent's start was not brought back: which app was in front is not known: ps: signal: killed\n"; console.String() != want { + t.Errorf("console = %q, want %q", console, want) + } + + // A launch that fails is said, not returned: the agent is up. + console.Reset() + f.launch = func(string) (string, error) { return "An error was encountered\nmore", errors.New("exit status 4") } + a.bringBack(ctx, &runningApp{"com.apple.Preferences", settings}, "") + if want := " ⚠ the app in front before the agent's start was not brought back: simctl launch com.apple.Preferences: exit status 4: An error was encountered\n"; console.String() != want || len(f.launches) != 1 { + t.Errorf("a failed launch: console = %q, want %q; launches %v", console, want, f.launches) + } + if !strings.Contains(log(), "not brought back: simctl launch com.apple.Preferences: exit status 4") { + t.Errorf("a failed launch: log %q", log()) + } +}