agent-device 0.17.1 → 0.17.3

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+ScrollGesture.swift

@@ -0,0 +1,200 @@
+import XCTest
+
+// Swift port of buildScrollGesturePlan from src/core/scroll-gesture.ts.
+//
+// This is a deliberate two-place invariant: the daemon keeps the TS implementation (for Android,
+// recording, and reported-pixels), and the runner places the gesture with this Swift copy. The
+// parity test vectors at the bottom of this file mirror src/core/__tests__/scroll-gesture.test.ts —
+// if you change the math in either language, update the other and both vector sets.
+//
+// All inputs here are positive (reference dims, travel, center), so Swift's `.rounded()`
+// (half away from zero) matches JS `Math.round` (half up) on every value computed below.
+
+struct RunnerScrollGesturePlan {
+  let x1: Double
+  let y1: Double
+  let x2: Double
+  let y2: Double
+  let travelPixels: Double
+}
+
+private let runnerDefaultScrollAmount = 0.6
+private let runnerDefaultEdgePaddingFraction = 0.05
+
+func runnerScrollGesturePlan(
+  direction: String,
+  amount: Double?,
+  pixels: Double?,
+  referenceWidth: Double,
+  referenceHeight: Double
+) -> RunnerScrollGesturePlan? {
+  // Mirror the TS INVALID_ARGS contract: non-positive or non-finite amount/pixels are rejected
+  // rather than clamped into a journaled 1px scroll. The daemon validates before sending, so
+  // this only triggers for non-daemon wire clients.
+  if let amount, !(amount.isFinite && amount > 0) { return nil }
+  if let pixels, !(pixels.isFinite && pixels > 0) { return nil }
+  let axisLength = (direction == "up" || direction == "down") ? referenceHeight : referenceWidth
+  let requestedAmount = amount ?? runnerDefaultScrollAmount
+  let requestedPixels: Double =
+    pixels.map { max(1, $0.rounded()) } ?? (axisLength * requestedAmount).rounded()
+  let edgePadding = max(1, (axisLength * runnerDefaultEdgePaddingFraction).rounded())
+  let maxTravelPixels = max(1, axisLength - edgePadding * 2)
+  let travelPixels = max(1, min(requestedPixels, maxTravelPixels))
+  let halfTravel = (travelPixels / 2).rounded()
+  let centerX = (referenceWidth / 2).rounded()
+  let centerY = (referenceHeight / 2).rounded()
+
+  func plan(_ x1: Double, _ y1: Double, _ x2: Double, _ y2: Double) -> RunnerScrollGesturePlan {
+    RunnerScrollGesturePlan(x1: x1, y1: y1, x2: x2, y2: y2, travelPixels: travelPixels)
+  }
+
+  switch direction {
+  case "up":
+    return plan(centerX, centerY - halfTravel, centerX, centerY + halfTravel)
+  case "down":
+    return plan(centerX, centerY + halfTravel, centerX, centerY - halfTravel)
+  case "left":
+    return plan(centerX - halfTravel, centerY, centerX + halfTravel, centerY)
+  case "right":
+    return plan(centerX + halfTravel, centerY, centerX - halfTravel, centerY)
+  default:
+    return nil
+  }
+}
+
+extension RunnerTests {
+  // Cross-language parity vectors mirroring src/core/__tests__/scroll-gesture.test.ts. Keep these
+  // in sync with the vitest vectors so the two buildScrollGesturePlan implementations cannot drift.
+
+  func testRunnerScrollGesturePlanMapsRelativeAmount() throws {
+    let plan = try XCTUnwrap(
+      runnerScrollGesturePlan(
+        direction: "down",
+        amount: 0.5,
+        pixels: nil,
+        referenceWidth: 400,
+        referenceHeight: 800
+      )
+    )
+    XCTAssertEqual(plan.x1, 200)
+    XCTAssertEqual(plan.y1, 600)
+    XCTAssertEqual(plan.x2, 200)
+    XCTAssertEqual(plan.y2, 200)
+    XCTAssertEqual(plan.travelPixels, 400)
+  }
+
+  func testRunnerScrollGesturePlanPixelsDown() throws {
+    // 300x600, down, pixels 120 -> (150,360)->(150,240), travel 120.
+    let plan = try XCTUnwrap(
+      runnerScrollGesturePlan(
+        direction: "down",
+        amount: nil,
+        pixels: 120,
+        referenceWidth: 300,
+        referenceHeight: 600
+      )
+    )
+    XCTAssertEqual(plan.x1, 150)
+    XCTAssertEqual(plan.y1, 360)
+    XCTAssertEqual(plan.x2, 150)
+    XCTAssertEqual(plan.y2, 240)
+    XCTAssertEqual(plan.travelPixels, 120)
+  }
+
+  func testRunnerScrollGesturePlanClampsAmountAboveOne() throws {
+    // 400x800, down, amount 2 -> requested 1600 clamps to the safe band (720): (200,760)->(200,40).
+    let plan = try XCTUnwrap(
+      runnerScrollGesturePlan(
+        direction: "down",
+        amount: 2,
+        pixels: nil,
+        referenceWidth: 400,
+        referenceHeight: 800
+      )
+    )
+    XCTAssertEqual(plan.x1, 200)
+    XCTAssertEqual(plan.y1, 760)
+    XCTAssertEqual(plan.x2, 200)
+    XCTAssertEqual(plan.y2, 40)
+    XCTAssertEqual(plan.travelPixels, 720)
+  }
+
+  func testRunnerScrollGesturePlanFloorsTinyFrames() throws {
+    // 2x2, down, pixels 10 engages every max(1, ...) floor and the .5 rounding cases the two
+    // ports must agree on (halfTravel 0.5 -> 1, center 1 from 2/2): (1,2)->(1,0), travel 1.
+    let plan = try XCTUnwrap(
+      runnerScrollGesturePlan(
+        direction: "down",
+        amount: nil,
+        pixels: 10,
+        referenceWidth: 2,
+        referenceHeight: 2
+      )
+    )
+    XCTAssertEqual(plan.x1, 1)
+    XCTAssertEqual(plan.y1, 2)
+    XCTAssertEqual(plan.x2, 1)
+    XCTAssertEqual(plan.y2, 0)
+    XCTAssertEqual(plan.travelPixels, 1)
+  }
+
+  func testRunnerScrollGesturePlanClampsToSafeBand() throws {
+    // 300x600, right, pixels 500 clamps travel to the safe band (270).
+    let plan = try XCTUnwrap(
+      runnerScrollGesturePlan(
+        direction: "right",
+        amount: nil,
+        pixels: 500,
+        referenceWidth: 300,
+        referenceHeight: 600
+      )
+    )
+    XCTAssertEqual(plan.x1, 285)
+    XCTAssertEqual(plan.x2, 15)
+    XCTAssertEqual(plan.y1, 300)
+    XCTAssertEqual(plan.y2, 300)
+    XCTAssertEqual(plan.travelPixels, 270)
+  }
+
+  func testRunnerScrollGesturePlanRejectsUnknownDirection() {
+    XCTAssertNil(
+      runnerScrollGesturePlan(
+        direction: "sideways",
+        amount: nil,
+        pixels: 100,
+        referenceWidth: 300,
+        referenceHeight: 600
+      )
+    )
+  }
+
+  func testRunnerScrollGesturePlanRejectsInvalidAmountAndPixels() {
+    XCTAssertNil(
+      runnerScrollGesturePlan(
+        direction: "down",
+        amount: 0,
+        pixels: nil,
+        referenceWidth: 300,
+        referenceHeight: 600
+      )
+    )
+    XCTAssertNil(
+      runnerScrollGesturePlan(
+        direction: "down",
+        amount: nil,
+        pixels: -10,
+        referenceWidth: 300,
+        referenceHeight: 600
+      )
+    )
+    XCTAssertNil(
+      runnerScrollGesturePlan(
+        direction: "down",
+        amount: .infinity,
+        pixels: nil,
+        referenceWidth: 300,
+        referenceHeight: 600
+      )
+    )
+  }
+}

package/ios-runner/AgentDeviceRunner/AgentDeviceRunnerUITests/RunnerTests+SequenceExecution.swift

@@ -0,0 +1,406 @@
+import XCTest
+
+extension RunnerTests {
+  // MARK: - Sequence command
+
+  /// Hard cap mirrored from the daemon (MAX_RUNNER_SEQUENCE_STEPS). Keeps the worst-case
+  /// retained journal response well under the 16KB cap and bounds the lost-response window.
+  var maxSequenceSteps: Int { 20 }
+
+  /// Allowlisted step kinds. Validated on both sides so an unsupported kind is rejected with a
+  /// clear INVALID_ARGS naming the step index, executing nothing.
+  private var sequenceableStepKinds: Set<String> { ["tap", "doubleTap", "longPress", "drag"] }
+
+  /// Per-step outcome carried by `assembleSequenceExecution`. The timing is captured by the
+  /// executor closure (via performGesture) so ordering/stop-on-failure stay device-free testable.
+  struct SequenceStepOutcome {
+    let outcome: RunnerInteractionOutcome
+    let gestureStartUptimeMs: Double
+    let gestureEndUptimeMs: Double
+  }
+
+  func executeSequence(command: Command, activeApp: XCUIApplication) -> Response {
+    guard let steps = command.steps, !steps.isEmpty else {
+      return sequenceInvalidArgs("sequence requires at least one step")
+    }
+    guard steps.count <= maxSequenceSteps else {
+      return sequenceInvalidArgs(
+        "sequence accepts at most \(maxSequenceSteps) steps, received \(steps.count)"
+      )
+    }
+    for (index, step) in steps.enumerated() {
+      if let error = validateSequenceStep(step, index: index) {
+        return error
+      }
+    }
+
+    // Touch frame resolves from the first step's coords so recording-gestures works unchanged.
+    let firstStep = steps[0]
+    let firstFrame = (firstStep.x != nil && firstStep.y != nil)
+      ? resolvedTouchVisualizationFrame(app: activeApp, x: firstStep.x!, y: firstStep.y!)
+      : nil
+
+    let execution = assembleSequenceExecution(steps: steps) { _, step in
+      performSequenceStep(step, activeApp: activeApp)
+    }
+    return sequenceResponse(execution: execution, touchFrame: firstFrame)
+  }
+
+  /// Pure, device-free assembler: runs each step in order via `perform`, stops at the first
+  /// `.unsupported` outcome, and assembles the DataPayload (completedSteps, optional
+  /// failedStepIndex, per-step results, top-level gesture timing spanning first..last executed).
+  /// Steps after the failed index are never invoked and produce no result entries, so
+  /// results.count == completedSteps + (failedStepIndex != nil ? 1 : 0).
+  func assembleSequenceExecution(
+    steps: [SequenceStep],
+    perform: (Int, SequenceStep) -> SequenceStepOutcome
+  ) -> SequenceExecutionResult {
+    var results: [SequenceStepResult] = []
+    var completedSteps = 0
+    var failedStepIndex: Int?
+    var gestureStartUptimeMs: Double?
+    var gestureEndUptimeMs: Double?
+
+    for (index, step) in steps.enumerated() {
+      let stepOutcome = perform(index, step)
+      if gestureStartUptimeMs == nil {
+        gestureStartUptimeMs = stepOutcome.gestureStartUptimeMs
+      }
+      gestureEndUptimeMs = stepOutcome.gestureEndUptimeMs
+
+      switch stepOutcome.outcome {
+      case .performed:
+        results.append(
+          SequenceStepResult(
+            ok: true,
+            kind: step.kind,
+            errorCode: nil,
+            errorMessage: nil,
+            gestureStartUptimeMs: stepOutcome.gestureStartUptimeMs,
+            gestureEndUptimeMs: stepOutcome.gestureEndUptimeMs
+          )
+        )
+        completedSteps += 1
+      case .unsupported(let message, _):
+        results.append(
+          SequenceStepResult(
+            ok: false,
+            kind: step.kind,
+            errorCode: "UNSUPPORTED_OPERATION",
+            errorMessage: message,
+            gestureStartUptimeMs: stepOutcome.gestureStartUptimeMs,
+            gestureEndUptimeMs: stepOutcome.gestureEndUptimeMs
+          )
+        )
+        failedStepIndex = index
+        return SequenceExecutionResult(
+          results: results,
+          completedSteps: completedSteps,
+          failedStepIndex: failedStepIndex,
+          gestureStartUptimeMs: gestureStartUptimeMs,
+          gestureEndUptimeMs: gestureEndUptimeMs
+        )
+      }
+    }
+
+    return SequenceExecutionResult(
+      results: results,
+      completedSteps: completedSteps,
+      failedStepIndex: nil,
+      gestureStartUptimeMs: gestureStartUptimeMs,
+      gestureEndUptimeMs: gestureEndUptimeMs
+    )
+  }
+
+  struct SequenceExecutionResult {
+    let results: [SequenceStepResult]
+    let completedSteps: Int
+    let failedStepIndex: Int?
+    let gestureStartUptimeMs: Double?
+    let gestureEndUptimeMs: Double?
+  }
+
+  // MARK: - Step validation / execution
+
+  private func validateSequenceStep(_ step: SequenceStep, index: Int) -> Response? {
+    guard sequenceableStepKinds.contains(step.kind) else {
+      return sequenceInvalidArgs(
+        "sequence step \(index) has unsupported kind \"\(step.kind)\"; allowed: tap, doubleTap, longPress, drag"
+      )
+    }
+    guard let x = step.x, let y = step.y, x.isFinite, y.isFinite else {
+      return sequenceInvalidArgs("sequence step \(index) (\(step.kind)) requires finite x and y")
+    }
+    if step.kind == "drag" {
+      guard let x2 = step.x2, let y2 = step.y2, x2.isFinite, y2.isFinite else {
+        return sequenceInvalidArgs("sequence step \(index) (drag) requires finite x2 and y2")
+      }
+    }
+    return nil
+  }
+
+  private func performSequenceStep(
+    _ step: SequenceStep,
+    activeApp: XCUIApplication
+  ) -> SequenceStepOutcome {
+    let x = step.x ?? 0
+    let y = step.y ?? 0
+    // Synthesized HID tap fast path mirrors the individual `tap` command (idleTimeout:false, with
+    // a tapAt fallback when synthesis is unsupported), so fusing a jittered tap series does not
+    // change the touch mechanism for these inputs.
+    if step.kind == "tap", step.synthesized == true {
+      let (timing, outcome) = performGesture(activeApp, idleTimeout: false) {
+        synthesizedTapAt(app: activeApp, x: x, y: y)
+      }
+      if case .performed = outcome {
+        if let pauseMs = step.pauseMs, pauseMs > 0 {
+          sleepFor(min(max(pauseMs, 0), 10000) / 1000.0)
+        }
+        return SequenceStepOutcome(
+          outcome: outcome,
+          gestureStartUptimeMs: timing.gestureStartUptimeMs,
+          gestureEndUptimeMs: timing.gestureEndUptimeMs
+        )
+      }
+      // Synthesis unsupported (e.g. macOS) — fall through to the drag-based tapAt below.
+    }
+    let (timing, outcome) = performGesture(activeApp) {
+      switch step.kind {
+      case "doubleTap":
+        // doubleTapAt per step, matching the behavior of the retired tapSeries doubleTap path.
+        return doubleTapAt(app: activeApp, x: x, y: y)
+      case "longPress":
+        let duration = min(max(step.durationMs ?? 800, 16), 10000) / 1000.0
+        return longPressAt(app: activeApp, x: x, y: y, duration: duration)
+      case "drag":
+        // Route through keyboardAvoidingDragPoints for parity with the individual `.drag` command
+        // (RunnerTests+CommandExecution.swift). durationMs is intentionally ignored on this
+        // coordinate-drag path, matching that command's non-synthesized branch.
+        let dragPoints = keyboardAvoidingDragPoints(
+          app: activeApp, x: x, y: y, x2: step.x2 ?? x, y2: step.y2 ?? y)
+        return dragAt(
+          app: activeApp,
+          x: dragPoints.x,
+          y: dragPoints.y,
+          x2: dragPoints.x2,
+          y2: dragPoints.y2,
+          holdDuration: coordinateDragHoldDuration()
+        )
+      default:
+        return tapAt(app: activeApp, x: x, y: y)
+      }
+    }
+    // Sleep AFTER the step — pauseMs is the inter-step gap — but only when the step performed.
+    // assembleSequenceExecution stops at the first unsupported outcome, so pausing after a failed
+    // step would burn up to 10s of watchdog budget with no following step to separate from.
+    if case .performed = outcome, let pauseMs = step.pauseMs, pauseMs > 0 {
+      sleepFor(min(max(pauseMs, 0), 10000) / 1000.0)
+    }
+    return SequenceStepOutcome(
+      outcome: outcome,
+      gestureStartUptimeMs: timing.gestureStartUptimeMs,
+      gestureEndUptimeMs: timing.gestureEndUptimeMs
+    )
+  }
+
+  private func sequenceResponse(
+    execution: SequenceExecutionResult,
+    touchFrame: TouchVisualizationFrame?
+  ) -> Response {
+    return Response(
+      ok: true,
+      data: DataPayload(
+        message: "sequence",
+        gestureStartUptimeMs: execution.gestureStartUptimeMs,
+        gestureEndUptimeMs: execution.gestureEndUptimeMs,
+        x: touchFrame?.x,
+        y: touchFrame?.y,
+        referenceWidth: touchFrame?.referenceWidth,
+        referenceHeight: touchFrame?.referenceHeight,
+        completedSteps: execution.completedSteps,
+        failedStepIndex: execution.failedStepIndex,
+        sequenceResults: execution.results
+      )
+    )
+  }
+
+  private func sequenceInvalidArgs(_ message: String) -> Response {
+    Response(ok: false, error: ErrorPayload(code: "INVALID_ARGS", message: message))
+  }
+}
+
+// MARK: - In-bundle unit tests (device-free)
+
+extension RunnerTests {
+  func testSequenceDecodesStepsFromWire() throws {
+    let json = """
+    {"command":"sequence","commandId":"seq-1","steps":[
+      {"kind":"tap","x":100,"y":200},
+      {"kind":"doubleTap","x":101,"y":200},
+      {"kind":"longPress","x":102,"y":200,"durationMs":300},
+      {"kind":"drag","x":10,"y":600,"x2":10,"y2":200,"durationMs":250,"pauseMs":50}
+    ]}
+    """
+    let command = try JSONDecoder().decode(Command.self, from: Data(json.utf8))
+    XCTAssertEqual(command.command, .sequence)
+    XCTAssertEqual(command.steps?.count, 4)
+    XCTAssertEqual(command.steps?[0].kind, "tap")
+    XCTAssertEqual(command.steps?[1].kind, "doubleTap")
+    XCTAssertEqual(command.steps?[3].x2, 10)
+    XCTAssertEqual(command.steps?[3].pauseMs, 50)
+  }
+
+  func testSequenceAcceptsDoubleTapKind() {
+    // A doubleTap step missing coords must fail on the coords check, not the kind allowlist —
+    // proving "doubleTap" passes validateSequenceStep without needing a device to execute on.
+    let response = executeSequenceForTest(steps: [
+      sequenceStep(kind: "doubleTap", x: nil)
+    ])
+    XCTAssertEqual(response.ok, false)
+    XCTAssertEqual(response.error?.code, "INVALID_ARGS")
+    XCTAssertTrue(response.error?.message.contains("requires finite x and y") ?? false)
+    XCTAssertFalse(response.error?.message.contains("unsupported kind") ?? true)
+  }
+
+  func testSequenceRejectsUnknownKind() throws {
+    let response = executeSequenceForTest(steps: [
+      sequenceStep(kind: "tap", x: 1, y: 2),
+      sequenceStep(kind: "pinch", x: 3, y: 4),
+    ])
+    XCTAssertEqual(response.ok, false)
+    XCTAssertEqual(response.error?.code, "INVALID_ARGS")
+    XCTAssertTrue(response.error?.message.contains("step 1") ?? false)
+    XCTAssertTrue(response.error?.message.contains("pinch") ?? false)
+  }
+
+  func testSequenceRejectsEmpty() {
+    let response = executeSequenceForTest(steps: [])
+    XCTAssertEqual(response.ok, false)
+    XCTAssertEqual(response.error?.code, "INVALID_ARGS")
+  }
+
+  func testSequenceRejectsTooManySteps() {
+    let steps = (0..<21).map { _ in sequenceStep(kind: "tap", x: 1, y: 2) }
+    let response = executeSequenceForTest(steps: steps)
+    XCTAssertEqual(response.ok, false)
+    XCTAssertEqual(response.error?.code, "INVALID_ARGS")
+    XCTAssertTrue(response.error?.message.contains("at most 20") ?? false)
+  }
+
+  func testSequenceRejectsDragMissingSecondPoint() {
+    let response = executeSequenceForTest(steps: [
+      sequenceStep(kind: "tap", x: 1, y: 2),
+      sequenceStep(kind: "drag", x: 3, y: 4),
+    ])
+    XCTAssertEqual(response.ok, false)
+    XCTAssertEqual(response.error?.code, "INVALID_ARGS")
+    XCTAssertTrue(response.error?.message.contains("step 1") ?? false)
+  }
+
+  func testAssembleSequencePreservesOrderOnSuccess() {
+    let steps = [
+      sequenceStep(kind: "tap", x: 1, y: 1),
+      sequenceStep(kind: "longPress", x: 2, y: 2),
+      sequenceStep(kind: "tap", x: 3, y: 3),
+    ]
+    var calls: [Int] = []
+    let execution = assembleSequenceExecution(steps: steps) { index, _ in
+      calls.append(index)
+      return SequenceStepOutcome(
+        outcome: .performed,
+        gestureStartUptimeMs: Double(index * 10),
+        gestureEndUptimeMs: Double(index * 10 + 5)
+      )
+    }
+    XCTAssertEqual(calls, [0, 1, 2])
+    XCTAssertEqual(execution.completedSteps, 3)
+    XCTAssertNil(execution.failedStepIndex)
+    XCTAssertEqual(execution.results.map { $0.kind }, ["tap", "longPress", "tap"])
+    XCTAssertEqual(execution.gestureStartUptimeMs, 0)
+    XCTAssertEqual(execution.gestureEndUptimeMs, 25)
+  }
+
+  func testAssembleSequenceStopsAtFirstFailure() {
+    let steps = [
+      sequenceStep(kind: "tap", x: 1, y: 1),
+      sequenceStep(kind: "drag", x: 2, y: 2),
+      sequenceStep(kind: "tap", x: 3, y: 3),
+    ]
+    var calls: [Int] = []
+    let execution = assembleSequenceExecution(steps: steps) { index, _ in
+      calls.append(index)
+      if index == 1 {
+        return SequenceStepOutcome(
+          outcome: .unsupported(message: "drag unsupported", hint: nil),
+          gestureStartUptimeMs: 10,
+          gestureEndUptimeMs: 15
+        )
+      }
+      return SequenceStepOutcome(outcome: .performed, gestureStartUptimeMs: 0, gestureEndUptimeMs: 5)
+    }
+    // Step 2 is never invoked.
+    XCTAssertEqual(calls, [0, 1])
+    XCTAssertEqual(execution.completedSteps, 1)
+    XCTAssertEqual(execution.failedStepIndex, 1)
+    // results.count == completedSteps + 1 (the failed step).
+    XCTAssertEqual(execution.results.count, 2)
+    XCTAssertEqual(execution.results[1].ok, false)
+    XCTAssertEqual(execution.results[1].errorCode, "UNSUPPORTED_OPERATION")
+    XCTAssertEqual(execution.results[1].errorMessage, "drag unsupported")
+  }
+
+  func testSequenceWorstCaseResponseStaysUnderJournalCap() throws {
+    let longMessage = String(repeating: "e", count: 200)
+    let results = (0..<20).map { index in
+      SequenceStepResult(
+        ok: index < 19,
+        kind: "drag",
+        errorCode: index < 19 ? nil : "UNSUPPORTED_OPERATION",
+        errorMessage: index < 19 ? nil : longMessage,
+        gestureStartUptimeMs: 123456.789,
+        gestureEndUptimeMs: 123466.789
+      )
+    }
+    let response = Response(
+      ok: true,
+      data: DataPayload(
+        message: "sequence",
+        completedSteps: 19,
+        failedStepIndex: 19,
+        sequenceResults: results
+      )
+    )
+    let encoded = try JSONEncoder().encode(response)
+    XCTAssertLessThan(encoded.count, 16 * 1024)
+  }
+
+  private func sequenceStep(
+    kind: String,
+    x: Double?,
+    y: Double? = nil,
+    x2: Double? = nil,
+    y2: Double? = nil
+  ) -> SequenceStep {
+    SequenceStep(
+      kind: kind, x: x, y: y, x2: x2, y2: y2, durationMs: nil, pauseMs: nil, synthesized: nil)
+  }
+
+  /// Validation runs before any executor call, so the INVALID_ARGS paths are exercised without
+  /// reaching the device executor (which is never invoked when validation rejects).
+  private func executeSequenceForTest(steps: [SequenceStep]) -> Response {
+    let command = makeSequenceCommand(steps: steps)
+    return executeSequence(command: command, activeApp: app)
+  }
+
+  /// Build a sequence Command via JSON so the test does not depend on the memberwise init's
+  /// parameter order.
+  private func makeSequenceCommand(steps: [SequenceStep]) -> Command {
+    struct SequenceCommandFixture: Encodable {
+      let command = "sequence"
+      let commandId = "seq-test"
+      let steps: [SequenceStep]
+    }
+    let data = try! JSONEncoder().encode(SequenceCommandFixture(steps: steps))
+    return try! JSONDecoder().decode(Command.self, from: data)
+  }
+}