feat(testing): Support reusable prepared test artifacts (#475)

* feat(xcodebuild): Support prepared test artifacts

Extend existing build and test tools to prepare, return, and consume reusable test artifacts while preserving normal build behavior.

Fixes #450

* feat(manifest): Support conditional next steps

Move conditional next-step selection into tool manifests and preserve the behavior across MCP, CLI, daemon, and snapshot outputs.

Refs #450

* fix(testing): Stabilize prepared test execution

Keep source-only xcodebuild arguments out of the generated test-without-building phase and sort final test failures independently of emission order.

* test(snapshot): Align device test schema versions

* fix(test): Extract failures from managed result bundles

* fix(test): Preserve explicit test destinations

* test(snapshot): isolate snapshot preflight state

Share per-test environment setup and cleanup across snapshot suites, cache suite-level simulator builds, and normalize volatile output so fixtures remain stable. Update non-environmental fixtures and add coverage for cleanup and normalization behavior.

* fix(testing): address prepared test review findings

Prevent session defaults and selectors from leaking into prepared test runs, remove a useless simulator state initializer, and align volatile snapshot fixtures across CLI and MCP.

* fix(testing): preserve prepared test selectors

Keep only-testing and skip-testing arguments in the prepared test phase while retaining session-default conflict filtering.

* fix(testing): only mark successful test products complete

* fix: stabilize prepared test snapshot fixtures

* fix: honor test product retention options

* fix: reject device destinations without prepared tests

* fix: isolate session destinations for device builds

* fix: mark failed prepared builds complete

* fix: remove unstable snapshot fixture churn

* fix(snapshot): Tolerate simulator lifecycle races

Retry app cleanup after a concurrent simulator shutdown and tolerate a boot that completes between the state check and boot command.

* test(snapshot): Align prepared test fixtures

Update the discovery schema expectation and keep device and macOS fixtures aligned with the generated artifacts.

* fix(snapshot): Handle teardown shutdown races

Treat an already-shut-down simulator as successful cleanup and align compiler-failure fixtures with the emitted result shape.

* fix: Align prepared test review fixes

* fix(snapshot): Stabilize isolated fixture output

* fix(test): Sanitize managed test product paths

* fix: preserve test product retention cap

Author: Cameron Cooke

CHANGELOG.md

@@ -6,6 +6,11 @@
 
 - Added `xcodebuildmcp purge` to report and explicitly clean XcodeBuildMCP-managed workspace storage, including opt-in DerivedData cleanup with dry-run and confirmation safeguards.
 - Added `extraArgs` as a first-class session-default value. Repo config or runtime defaults can now carry common `xcodebuild` flags (for example `-skipPackagePluginValidation` or `-disableAutomaticPackageResolution`) so they don't need repeating on every build or test call. Per-call `extraArgs` replace matching configured flags or build settings and append after non-matching defaults, while an explicit empty array (`extraArgs: []`) clears the defaults for a single call. The session management tools show, set, sync, and clear `extraArgs` alongside the other defaults.
+- Added reusable test preparation to the existing simulator, device, and macOS build tools. Builds can now return a portable `.xctestproducts` artifact, and test tools can run that artifact—or an advanced `.xctestrun` input—without rebuilding before producing a new `.xcresult` ([#450](https://github.com/getsentry/XcodeBuildMCP/issues/450)).
+
+### Changed
+
+- Tool manifests can now conditionally expose static next steps using handler-activated condition keys, while runtime-generated parameters continue to flow through the existing next-step parameter contract.
 
 ### Fixed
 
@@ -694,4 +699,3 @@ Please note that the UI automation features are an early preview and currently i
 ## [v1.0.1] - 2025-04-02
 - Initial release of XcodeBuildMCP
 - Basic support for building iOS and macOS applications
-

README.md

@@ -85,6 +85,12 @@ xcodebuildmcp tools
 
 # Build for simulator
 xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj
+
+# Prepare portable test products without running tests
+xcodebuildmcp simulator build --scheme MyApp --project-path ./MyApp.xcodeproj --simulator-name "iPhone 17" --build-for-testing --test-products-path ./MyApp.xctestproducts
+
+# Run previously prepared test products
+xcodebuildmcp simulator test --test-products-path ./MyApp.xctestproducts --simulator-name "iPhone 17"
 ```
 
 Check for updates and upgrade in place:

example_projects/iOS_Calculator/CalculatorApp/CalculatorApp.swift

@@ -3,14 +3,19 @@ import OSLog
 import CalculatorAppFeature
 
 private let logger = Logger(subsystem: "io.sentry.calculatorapp", category: "lifecycle")
+private let snapshotScrollSurfaceArgument = "--snapshot-scroll-surface"
 
 @main
 struct CalculatorApp: App {
     @Environment(\.scenePhase) private var scenePhase
 
     var body: some Scene {
         WindowGroup {
-            ContentView()
+            if ProcessInfo.processInfo.arguments.contains(snapshotScrollSurfaceArgument) {
+                SnapshotScrollSurface()
+            } else {
+                ContentView()
+            }
         }
         .onChange(of: scenePhase) { _, newPhase in
             switch newPhase {
@@ -25,6 +30,21 @@ struct CalculatorApp: App {
     }
 }
 
+private struct SnapshotScrollSurface: View {
+    var body: some View {
+        ScrollView {
+            LazyVStack(spacing: 16) {
+                ForEach(0..<30, id: \.self) { index in
+                    Text("Snapshot row \(index)")
+                        .frame(maxWidth: .infinity, minHeight: 44)
+                }
+            }
+            .padding()
+        }
+        .accessibilityIdentifier("snapshot-scroll-surface")
+    }
+}
+
 #Preview {
     ContentView()
 }

manifests/tools/batch.yaml

@@ -15,3 +15,8 @@ annotations:
   readOnlyHint: true
   destructiveHint: false
   openWorldHint: false
+nextSteps:
+  - label: Refresh after UI action
+    toolId: snapshot_ui
+    when: success
+    condition: ui_action_needs_refresh

manifests/tools/build_device.yaml

@@ -6,7 +6,7 @@ names:
 description: Build for device.
 outputSchema:
   schema: xcodebuildmcp.output.build-result
-  version: "2"
+  version: '3'
 predicates:
   - hideWhenXcodeAgentMode
 annotations:
@@ -19,3 +19,8 @@ nextSteps:
     toolId: get_device_app_path
     priority: 1
     when: success
+    condition: app_build_succeeded
+  - label: Run prepared tests
+    toolId: test_device
+    when: success
+    condition: prepared_tests_available

manifests/tools/build_macos.yaml

@@ -6,7 +6,7 @@ names:
 description: Build macOS app.
 outputSchema:
   schema: xcodebuildmcp.output.build-result
-  version: "2"
+  version: '3'
 predicates:
   - hideWhenXcodeAgentMode
 annotations:
@@ -19,3 +19,8 @@ nextSteps:
     toolId: get_mac_app_path
     priority: 1
     when: success
+    condition: app_build_succeeded
+  - label: Run prepared tests
+    toolId: test_macos
+    when: success
+    condition: prepared_tests_available

manifests/tools/build_sim.yaml

@@ -6,7 +6,7 @@ names:
 description: Build for iOS sim (compile-only, no launch).
 outputSchema:
   schema: xcodebuildmcp.output.build-result
-  version: "2"
+  version: '3'
 predicates:
   - hideWhenXcodeAgentMode
 annotations:
@@ -19,3 +19,8 @@ nextSteps:
     toolId: get_sim_app_path
     priority: 1
     when: success
+    condition: app_build_succeeded
+  - label: Run prepared tests
+    toolId: test_sim
+    when: success
+    condition: prepared_tests_available

manifests/tools/button.yaml

@@ -14,3 +14,8 @@ annotations:
   readOnlyHint: true
   destructiveHint: false
   openWorldHint: false
+nextSteps:
+  - label: Refresh after UI action
+    toolId: snapshot_ui
+    when: success
+    condition: ui_action_needs_refresh

manifests/tools/drag.yaml

@@ -15,3 +15,8 @@ annotations:
   readOnlyHint: true
   destructiveHint: false
   openWorldHint: false
+nextSteps:
+  - label: Refresh after UI action
+    toolId: snapshot_ui
+    when: success
+    condition: ui_action_needs_refresh

manifests/tools/gesture.yaml

@@ -14,3 +14,8 @@ annotations:
   readOnlyHint: true
   destructiveHint: false
   openWorldHint: false
+nextSteps:
+  - label: Refresh after UI action
+    toolId: snapshot_ui
+    when: success
+    condition: ui_action_needs_refresh