From 23f0135986ea3771bcb4fac9f9538ea2f68d5f99 Mon Sep 17 00:00:00 2001 From: PJ Date: Mon, 8 Jun 2026 23:15:10 +0530 Subject: [PATCH] feat(ioscompanion): runner-only device driver mode NewDevice reuses Driver with d.companion set to the runner dialed over an iproxy usbmux tunnel, hybrid=false, runnerClient=nil. The existing accessor seams then route launch/snapshot/text/gesture to the runner with no new DeviceDriver methods. Device seams swap clear-state to a devicectl reinstall, container reset to a warn-once no-op, and paste grant to a no-op. realSpawnDeviceRunner builds and signs the runner at run time via the App Store Connect API key (no Xcode UI), caching on a source hash. --- internal/driver/ioscompanion/device.go | 227 +++++++++++ internal/driver/ioscompanion/devicerunner.go | 398 +++++++++++++++++++ internal/driver/ioscompanion/driver.go | 20 + 3 files changed, 645 insertions(+) create mode 100644 internal/driver/ioscompanion/device.go create mode 100644 internal/driver/ioscompanion/devicerunner.go diff --git a/internal/driver/ioscompanion/device.go b/internal/driver/ioscompanion/device.go new file mode 100644 index 0000000..e1170d2 --- /dev/null +++ b/internal/driver/ioscompanion/device.go @@ -0,0 +1,227 @@ +// This file implements the physical-device mode of Driver. The device is driven +// runner-only: the in-device XCUITest runner serves every capability over a +// usbmux tunnel, with no legacy companion. The simulator hybrid path is left +// byte-identical; device mode swaps three sim-only seams (reinstall, container +// reset, paste grant) and brings the runner up over the tunnel instead of a +// local listener. +package ioscompanion + +import ( + "context" + "errors" + "fmt" + "io" + "net" + "os/exec" + "strings" + "time" + + "github.com/priyanshujain/sanderling/internal/driver/ioscompanion/transport" +) + +// DeviceOptions configures a device-mode Driver. Signing credentials are not +// carried here: realSpawnDeviceRunner reads them from the environment at the +// point of use so secrets never reach the Options struct or run artifacts. +type DeviceOptions struct { + // HardwareUDID feeds xcodebuild -destination and iproxy -u. + HardwareUDID string + // CoreDeviceID feeds devicectl install/uninstall. + CoreDeviceID string + // BundleID is the app under test. + BundleID string + // AppPath is the .app bundle installed via devicectl for clear-state. + AppPath string + // Output receives the runner session log path and driver warnings. + Output io.Writer + // DoubleTapGapMilliseconds overrides the synthesized double-tap gap. + DoubleTapGapMilliseconds float64 + + // Test seams. Production leaves them nil and NewDevice wires the real + // build/spawn/tunnel/dial. + spawnRunner func(ctx context.Context, address string) (*exec.Cmd, error) + spawnTunnel func(ctx context.Context, hardwareUDID, localPort, devicePort string) (*exec.Cmd, error) + dialRunner func(address string) (transport.Companion, error) + pickAddress func() (string, error) +} + +// deviceStartupTimeout bounds the runner's startup once its hosting test +// session is spawned and the tunnel is up. The session's cold start on a +// physical device is slower than the simulator's, and the build that precedes +// it runs outside this window (under the process context, not the startup one). +const deviceStartupTimeout = 180 * time.Second + +// NewDevice brings up a runner-only Driver against a physical device: it builds +// and spawns the in-device runner, opens a usbmux tunnel to it, dials the runner +// over the tunnel, health-probes it, and caches the screen dimensions. Call +// Close when done to stop the runner session and the tunnel. +func NewDevice(ctx context.Context, options DeviceOptions) (*Driver, error) { + if options.HardwareUDID == "" { + return nil, errors.New("ios device: HardwareUDID is required") + } + if options.CoreDeviceID == "" { + return nil, errors.New("ios device: CoreDeviceID is required") + } + output := options.Output + if output == nil { + output = io.Discard + } + gap := options.DoubleTapGapMilliseconds + if gap <= 0 { + gap = DefaultDoubleTapGapMilliseconds + } + + d := &Driver{ + udid: options.HardwareUDID, + coreDeviceID: options.CoreDeviceID, + bundleID: options.BundleID, + appPath: options.AppPath, + output: output, + doubleTapGapMilliseconds: gap, + deviceMode: true, + hybrid: false, + spawnRunner: options.spawnRunner, + spawnTunnel: options.spawnTunnel, + } + if d.spawnRunner == nil { + d.spawnRunner = d.realSpawnDeviceRunner + } + if d.spawnTunnel == nil { + d.spawnTunnel = spawnTunnel + } + d.dialRunner = options.dialRunner + if d.dialRunner == nil { + d.dialRunner = func(address string) (transport.Companion, error) { + return transport.DialRunner(address, d.udid, d.bundleID) + } + } + if options.pickAddress != nil { + d.pickDeviceAddress = options.pickAddress + } else { + d.pickDeviceAddress = pickLoopbackAddress + } + + // Device seams: clear-state reinstalls via devicectl; the container reset and + // paste grant are simulator-only and become no-ops. The runner types + // natively, so no paste prompt is ever hit. + d.reinstallApp = d.devicectlReinstall + d.resetContainer = d.deviceResetContainerUnsupported + d.grantPaste = func(context.Context) error { return nil } + d.restart = d.respawnDevice + d.processContext, d.processCancel = context.WithCancel(ctx) + + if err := d.bringUpDevice(ctx); err != nil { + d.Close() + return nil, err + } + + description, err := d.companion.Describe(ctx) + if err != nil { + d.Close() + return nil, fmt.Errorf("describe device: %w", err) + } + d.screenWidth = description.WidthPoints + d.screenHeight = description.HeightPoints + return d, nil +} + +// bringUpDevice builds (if needed) and spawns the in-device runner, opens the +// tunnel, waits for the forwarded listener, dials the runner, and confirms +// health. The build runs inside spawnRunner under the process context, so the +// startup timeout only bounds the post-spawn wait, not the build. +func (d *Driver) bringUpDevice(ctx context.Context) error { + address, err := d.pickDeviceAddress() + if err != nil { + return err + } + _, port, err := net.SplitHostPort(address) + if err != nil { + return err + } + d.runnerAddress = address + + // The runner listens on the device loopback at the same port number the host + // tunnel forwards from, so one picked free port covers both ends. + runnerChild, err := d.spawnRunner(d.processContext, address) + if err != nil { + return fmt.Errorf("spawn device runner: %w", err) + } + d.runnerChild = runnerChild + + tunnelChild, err := d.spawnTunnel(d.processContext, d.udid, port, port) + if err != nil { + d.stopRunnerChild() + return fmt.Errorf("spawn tunnel: %w", err) + } + d.tunnelChild = tunnelChild + + startupCtx, cancel := context.WithTimeout(ctx, deviceStartupTimeout) + defer cancel() + + if err := waitForListener(startupCtx, address); err != nil { + d.stopTunnelChild() + d.stopRunnerChild() + return fmt.Errorf("device runner listener: %w", err) + } + + companion, err := d.dialRunner(address) + if err != nil { + d.stopTunnelChild() + d.stopRunnerChild() + return fmt.Errorf("dial device runner: %w", err) + } + d.companion = companion + + if err := d.waitForHealth(startupCtx); err != nil { + _ = companion.Close() + d.stopTunnelChild() + d.stopRunnerChild() + return fmt.Errorf("device runner health: %w", err) + } + return nil +} + +// respawnDevice is the device-path supervision restart: it tears down the runner +// transport, its hosting session, and the tunnel, then brings a fresh set up. +// Both the session and the tunnel restart together because a dropped usbmux +// connection can take either down. +func (d *Driver) respawnDevice(ctx context.Context) error { + if d.companion != nil { + _ = d.companion.Close() + } + d.stopRunnerChild() + d.stopTunnelChild() + return d.bringUpDevice(ctx) +} + +// devicectlReinstall uninstalls then installs the app bundle via devicectl, +// keyed on the CoreDevice id. App lifecycle stays with devicectl: the runner's +// own install path is simulator-specific. +func (d *Driver) devicectlReinstall(ctx context.Context) error { + _ = exec.CommandContext(ctx, "xcrun", devicectlUninstallArgs(d.coreDeviceID, d.bundleID)...).Run() + output, err := exec.CommandContext(ctx, "xcrun", devicectlInstallArgs(d.coreDeviceID, d.appPath)...).CombinedOutput() + if err != nil { + return fmt.Errorf("devicectl install: %w: %s", err, strings.TrimSpace(string(output))) + } + return nil +} + +// devicectlUninstallArgs and devicectlInstallArgs build the devicectl app +// lifecycle commands keyed on the CoreDevice id, as xcrun subcommand arguments. +func devicectlUninstallArgs(coreDeviceID, bundleID string) []string { + return []string{"devicectl", "device", "uninstall", "app", "--device", coreDeviceID, bundleID} +} + +func devicectlInstallArgs(coreDeviceID, appPath string) []string { + return []string{"devicectl", "device", "install", "app", "--device", coreDeviceID, appPath} +} + +// deviceResetContainerUnsupported warns once that device clear-state needs an +// app path for a devicectl reinstall: there is no simulator-style data-container +// wipe on a physical device. +func (d *Driver) deviceResetContainerUnsupported(context.Context) error { + if !d.clearStateWarned { + fmt.Fprintln(d.output, "clear-state on a physical device requires --ios-app-path for a reinstall; skipping (state not cleared)") + d.clearStateWarned = true + } + return nil +} diff --git a/internal/driver/ioscompanion/devicerunner.go b/internal/driver/ioscompanion/devicerunner.go new file mode 100644 index 0000000..f193cc3 --- /dev/null +++ b/internal/driver/ioscompanion/devicerunner.go @@ -0,0 +1,398 @@ +package ioscompanion + +import ( + "context" + "crypto/sha256" + "encoding/hex" + "encoding/json" + "fmt" + "net" + "os" + "os/exec" + "path/filepath" + "sort" + "strings" + "syscall" +) + +// developmentTeam is read from the environment so the account-specific team id +// is never committed. The App Store Connect API key path/id/issuer come from the +// same source. These back the no-Xcode-UI signing path. +const ( + envTeam = "SANDERLING_IOS_TEAM" + envTeamFallback = "DEVELOPMENT_TEAM" + envAuthKeyPath = "ASC_API_KEY_PATH" + envAuthKeyID = "ASC_API_KEY_ID" + envAuthIssuer = "ASC_API_ISSUER_ID" + envCompanionDir = "SANDERLING_COMPANION_DIR" +) + +// deviceRunnerScheme and deviceRunnerTarget mirror companion/project.yml. The +// build product is the runner whose xctestrun the test session consumes. +const ( + deviceRunnerScheme = "CompanionRunner" + deviceRunnerProject = "CompanionRunner.xcodeproj" +) + +// signingCredentials carries the no-UI signing inputs read from the environment. +type signingCredentials struct { + team string + authKeyPath string + authKeyID string + authIssuerID string +} + +// readSigningCredentials gathers the signing inputs from the environment and +// reports every missing one at once. The .p8 key must exist on disk. +func readSigningCredentials() (signingCredentials, error) { + creds := signingCredentials{ + team: firstNonEmpty(os.Getenv(envTeam), os.Getenv(envTeamFallback)), + authKeyPath: os.Getenv(envAuthKeyPath), + authKeyID: os.Getenv(envAuthKeyID), + authIssuerID: os.Getenv(envAuthIssuer), + } + var missing []string + if creds.team == "" { + missing = append(missing, envTeam) + } + if creds.authKeyPath == "" { + missing = append(missing, envAuthKeyPath) + } + if creds.authKeyID == "" { + missing = append(missing, envAuthKeyID) + } + if creds.authIssuerID == "" { + missing = append(missing, envAuthIssuer) + } + if len(missing) > 0 { + return creds, fmt.Errorf("device signing requires environment variables: %s", strings.Join(missing, ", ")) + } + if creds.authKeyPath != "" { + if _, err := os.Stat(creds.authKeyPath); err != nil { + return creds, fmt.Errorf("App Store Connect key not found at %s: %w", creds.authKeyPath, err) + } + } + return creds, nil +} + +func firstNonEmpty(values ...string) string { + for _, value := range values { + if value != "" { + return value + } + } + return "" +} + +// realSpawnDeviceRunner regenerates the runner project, builds it for the device +// (skipping when the cached build matches the current sources), injects the +// session port into the device xctestrun, and spawns the test session that hosts +// the runner on the device. address carries the host loopback port, reused as +// the device-side COMPANION_PORT. +func (d *Driver) realSpawnDeviceRunner(ctx context.Context, address string) (*exec.Cmd, error) { + _, port, err := net.SplitHostPort(address) + if err != nil { + return nil, err + } + companionDir, err := resolveCompanionDir() + if err != nil { + return nil, err + } + creds, err := readSigningCredentials() + if err != nil { + return nil, err + } + + derivedDataPath := filepath.Join(os.TempDir(), "sanderling-device-runner") + if err := os.MkdirAll(derivedDataPath, 0o755); err != nil { + return nil, err + } + + if err := d.buildDeviceRunnerIfNeeded(ctx, companionDir, derivedDataPath, creds); err != nil { + return nil, err + } + + xctestrunPath, err := locateDeviceXctestrun(derivedDataPath) + if err != nil { + return nil, err + } + if err := injectCompanionPort(ctx, xctestrunPath, port); err != nil { + return nil, fmt.Errorf("inject companion port: %w", err) + } + + logPath := filepath.Join(derivedDataPath, "device-session-"+port+".log") + logFile, err := os.Create(logPath) + if err != nil { + return nil, fmt.Errorf("create device session log: %w", err) + } + + args := testWithoutBuildingArgs(xctestrunPath, d.udid, creds) + command := exec.CommandContext(ctx, "xcrun", args...) + command.Stdout = logFile + command.Stderr = logFile + // Minimal environment: the session can echo its environment into the run + // log, so secrets in the parent environment must not reach it. Signing is + // passed by flag (a key-file path), not env. + command.Env = []string{ + "HOME=" + os.Getenv("HOME"), + "PATH=/usr/bin:/bin", + "TMPDIR=" + os.TempDir(), + } + command.Cancel = func() error { return command.Process.Signal(syscall.SIGTERM) } + command.WaitDelay = shutdownGrace + startErr := command.Start() + logFile.Close() + if startErr != nil { + return nil, fmt.Errorf("start device session: %w", startErr) + } + fmt.Fprintf(d.output, "device runner session pid=%d port=%s (log: %s)\n", command.Process.Pid, port, logPath) + return command, nil +} + +// buildDeviceRunnerIfNeeded regenerates the project and runs build-for-testing, +// skipping the build when a marker recording the current source hash already +// matches. The device signature is per-account/per-device, so the build cannot +// be embedded; the stable derivedDataPath makes the build incremental. +func (d *Driver) buildDeviceRunnerIfNeeded(ctx context.Context, companionDir, derivedDataPath string, creds signingCredentials) error { + sources, err := sourceHash(companionDir) + if err != nil { + return err + } + marker := filepath.Join(derivedDataPath, "device-runner.sha256") + if existing, readErr := os.ReadFile(marker); readErr == nil && string(existing) == sources { + fmt.Fprintln(d.output, "device runner build is up to date; skipping build") + return nil + } + + if out, genErr := runQuiet(ctx, companionDir, xcodegenArgs(filepath.Join(companionDir, "project.yml"))...); genErr != nil { + return fmt.Errorf("xcodegen: %w: %s", genErr, strings.TrimSpace(string(out))) + } + + projectPath := filepath.Join(companionDir, deviceRunnerProject) + args := buildForTestingArgs(projectPath, derivedDataPath, creds) + fmt.Fprintln(d.output, "building device runner (first run is slow; subsequent runs are cached)") + if out, buildErr := runQuiet(ctx, companionDir, append([]string{"xcrun"}, args...)...); buildErr != nil { + return fmt.Errorf("build-for-testing: %w: %s", buildErr, tailLines(string(out), 20)) + } + if err := os.WriteFile(marker, []byte(sources), 0o644); err != nil { + return err + } + return nil +} + +// xcodegenArgs regenerates the runner project from its spec. +func xcodegenArgs(specPath string) []string { + return []string{"xcodegen", "--spec", specPath} +} + +// buildForTestingArgs builds the runner for a generic device destination, signed +// through the App Store Connect API key with automatic provisioning. A generic +// destination keeps the build off any specific booted device; the wildcard dev +// profile covers every provisioned device in the team. +func buildForTestingArgs(projectPath, derivedDataPath string, creds signingCredentials) []string { + return []string{"xcodebuild", "build-for-testing", + "-project", projectPath, + "-scheme", deviceRunnerScheme, + "-destination", "generic/platform=iOS", + "-derivedDataPath", derivedDataPath, + "-allowProvisioningUpdates", + "-authenticationKeyPath", creds.authKeyPath, + "-authenticationKeyID", creds.authKeyID, + "-authenticationKeyIssuerID", creds.authIssuerID, + "CODE_SIGN_STYLE=Automatic", + "DEVELOPMENT_TEAM=" + creds.team, + "GENERATE_INFOPLIST_FILE=YES", + } +} + +// testWithoutBuildingArgs runs the prebuilt runner's test session on the +// specific device, installing the signed runner via the same automatic +// provisioning the build used. +func testWithoutBuildingArgs(xctestrunPath, hardwareUDID string, creds signingCredentials) []string { + return []string{"xcodebuild", "test-without-building", + "-xctestrun", xctestrunPath, + "-destination", "platform=iOS,id=" + hardwareUDID, + "-allowProvisioningUpdates", + "-authenticationKeyPath", creds.authKeyPath, + "-authenticationKeyID", creds.authKeyID, + "-authenticationKeyIssuerID", creds.authIssuerID, + } +} + +// iproxyArgs forwards the host loopback localPort to the device devicePort over +// usbmux for the device selected by hardwareUDID. +func iproxyArgs(localPort, devicePort, hardwareUDID string) []string { + return []string{"iproxy", localPort + ":" + devicePort, "-u", hardwareUDID} +} + +// spawnTunnel opens the usbmux tunnel via iproxy. SIGTERM on cancel closes the +// forwarded sockets cleanly so no orphan lingers. +func spawnTunnel(ctx context.Context, hardwareUDID, localPort, devicePort string) (*exec.Cmd, error) { + args := iproxyArgs(localPort, devicePort, hardwareUDID) + command := exec.CommandContext(ctx, args[0], args[1:]...) + command.Cancel = func() error { return command.Process.Signal(syscall.SIGTERM) } + command.WaitDelay = shutdownGrace + if err := command.Start(); err != nil { + return nil, fmt.Errorf("start iproxy: %w", err) + } + return command, nil +} + +// locateDeviceXctestrun finds the device build's xctestrun under the derived +// data products. The name embeds the device SDK version, so it is discovered +// rather than hardcoded. +func locateDeviceXctestrun(derivedDataPath string) (string, error) { + products := filepath.Join(derivedDataPath, "Build", "Products") + entries, err := os.ReadDir(products) + if err != nil { + return "", fmt.Errorf("read build products: %w", err) + } + for _, entry := range entries { + if strings.HasSuffix(entry.Name(), ".xctestrun") { + return filepath.Join(products, entry.Name()), nil + } + } + return "", fmt.Errorf("no xctestrun under %s", products) +} + +// injectCompanionPort sets COMPANION_PORT in the runner's environment inside the +// device xctestrun. The device xctestrun has no port placeholder and its +// test-target dict name embeds the SDK, so the name is parsed from the plist and +// the key is set (created when absent). +func injectCompanionPort(ctx context.Context, xctestrunPath, port string) error { + jsonBytes, err := plistAsJSON(ctx, xctestrunPath) + if err != nil { + return err + } + target, err := testTargetNameFromJSON(jsonBytes) + if err != nil { + return err + } + keyPath := ":" + target + ":EnvironmentVariables:COMPANION_PORT" + // Set updates an existing key; when the key is absent (the common device + // case) Set fails and Add creates it. Running both, ignoring Set's failure, + // makes the injection idempotent across reruns against a cached build. + _ = exec.CommandContext(ctx, "/usr/libexec/PlistBuddy", "-c", "Set "+keyPath+" "+port, xctestrunPath).Run() + if out, err := exec.CommandContext(ctx, "/usr/libexec/PlistBuddy", + "-c", "Add "+keyPath+" string "+port, xctestrunPath).CombinedOutput(); err != nil { + // Add fails when the key already exists, which means Set above succeeded. + if !strings.Contains(string(out), "Entry Already Exists") { + return fmt.Errorf("PlistBuddy: %w: %s", err, strings.TrimSpace(string(out))) + } + } + return nil +} + +// plistAsJSON converts a plist to JSON via plutil so it can be parsed without a +// plist library. +func plistAsJSON(ctx context.Context, plistPath string) ([]byte, error) { + out, err := exec.CommandContext(ctx, "plutil", "-convert", "json", "-o", "-", plistPath).Output() + if err != nil { + return nil, fmt.Errorf("plutil convert %s: %w", plistPath, err) + } + return out, nil +} + +// testTargetNameFromJSON returns the single test-target dict name in a parsed +// xctestrun: the lone top-level key that is not the metadata entry. +func testTargetNameFromJSON(data []byte) (string, error) { + var top map[string]json.RawMessage + if err := json.Unmarshal(data, &top); err != nil { + return "", fmt.Errorf("parse xctestrun json: %w", err) + } + var names []string + for key := range top { + if key == "__xctestrun_metadata__" || strings.HasPrefix(key, "CodeCoverageBuildableInfos") { + continue + } + names = append(names, key) + } + sort.Strings(names) + switch len(names) { + case 1: + return names[0], nil + case 0: + return "", fmt.Errorf("xctestrun has no test-target dict") + default: + return "", fmt.Errorf("xctestrun has multiple test-target dicts: %s", strings.Join(names, ", ")) + } +} + +// sourceHash digests the runner sources and project spec so a source edit +// invalidates the cached device build. Mirrors the runnerassets checksum reuse. +func sourceHash(companionDir string) (string, error) { + var paths []string + sourcesDir := filepath.Join(companionDir, "Sources") + walkErr := filepath.Walk(sourcesDir, func(path string, info os.FileInfo, err error) error { + if err != nil { + return err + } + if !info.IsDir() { + paths = append(paths, path) + } + return nil + }) + if walkErr != nil { + return "", walkErr + } + paths = append(paths, filepath.Join(companionDir, "project.yml")) + sort.Strings(paths) + hash := sha256.New() + for _, path := range paths { + content, err := os.ReadFile(path) + if err != nil { + return "", err + } + fmt.Fprintf(hash, "%s\n", path) + hash.Write(content) + } + return hex.EncodeToString(hash.Sum(nil)), nil +} + +// resolveCompanionDir finds the companion source tree: the SANDERLING_COMPANION_DIR +// override if set, otherwise the nearest ancestor of the working directory that +// holds companion/project.yml. The device runner is built from source at run +// time, so the tree must be present (it is, in a source checkout). +func resolveCompanionDir() (string, error) { + if override := os.Getenv(envCompanionDir); override != "" { + if _, err := os.Stat(filepath.Join(override, "project.yml")); err != nil { + return "", fmt.Errorf("%s=%s has no project.yml: %w", envCompanionDir, override, err) + } + return override, nil + } + directory, err := os.Getwd() + if err != nil { + return "", err + } + for { + candidate := filepath.Join(directory, "companion") + if _, statErr := os.Stat(filepath.Join(candidate, "project.yml")); statErr == nil { + return candidate, nil + } + parent := filepath.Dir(directory) + if parent == directory { + break + } + directory = parent + } + return "", fmt.Errorf("companion source tree not found; run from a sanderling checkout or set %s", envCompanionDir) +} + +// runQuiet runs a command in dir with the inherited environment and returns its +// combined output. Used for the transient build steps (xcodegen, xcodebuild +// build-for-testing) whose output is surfaced only on failure. +func runQuiet(ctx context.Context, dir string, args ...string) ([]byte, error) { + command := exec.CommandContext(ctx, args[0], args[1:]...) + command.Dir = dir + return command.CombinedOutput() +} + +// tailLines returns the last n lines of text, so a long xcodebuild failure log +// surfaces its tail (where the error is) without flooding the run output. +func tailLines(text string, n int) string { + lines := strings.Split(strings.TrimRight(text, "\n"), "\n") + if len(lines) <= n { + return strings.Join(lines, "\n") + } + return strings.Join(lines[len(lines)-n:], "\n") +} diff --git a/internal/driver/ioscompanion/driver.go b/internal/driver/ioscompanion/driver.go index 9fb4725..f398ae5 100644 --- a/internal/driver/ioscompanion/driver.go +++ b/internal/driver/ioscompanion/driver.go @@ -125,6 +125,16 @@ type Driver struct { dialRunner func(address string) (transport.Companion, error) hybrid bool + // Device-mode fields. On the physical-device path d.companion is the runner + // dialed over a usbmux tunnel, hybrid is false, and runnerClient is nil. + // coreDeviceID feeds devicectl; tunnelChild is the iproxy process forwarding + // the host loopback port to the runner's device-side port. + deviceMode bool + coreDeviceID string + tunnelChild *exec.Cmd + spawnTunnel func(ctx context.Context, hardwareUDID, localPort, devicePort string) (*exec.Cmd, error) + pickDeviceAddress func() (string, error) + // processContext owns the companion child's lifetime: it is derived from // New's context (so a canceled run still reaps the child) and canceled by // Close. Spawning under a startup-scoped context would SIGTERM the child @@ -985,11 +995,21 @@ func (d *Driver) Close() { d.runnerClient = nil } d.stopRunnerChild() + d.stopTunnelChild() if d.processCancel != nil { d.processCancel() } } +// stopTunnelChild terminates the iproxy usbmux tunnel on the device path. +// SIGTERM lets it close its forwarded sockets before exit; a nil child (the +// simulator path) is a no-op. +func (d *Driver) stopTunnelChild() { + child := d.tunnelChild + d.tunnelChild = nil + stopProcess(child) +} + // stopChild terminates the companion child gracefully (SIGTERM, grace window, // then SIGKILL) so it leaves no orphan behind. func (d *Driver) stopChild() {