# How XCResultCache Optimizes Test Result Data Access in iOS Simulator Workflows

> Discover how XCResultCache speeds up iOS Simulator workflows by caching xcresult bundles, eliminating redundant xcodebuild operations for instant test result analysis.

- Repository: [Conor/ios-simulator-skill](https://github.com/conorluddy/ios-simulator-skill)
- Tags: internals
- Published: 2026-02-27

---

**The XCResultCache is a lightweight filesystem-based cache that eliminates redundant xcodebuild operations by persistently storing Xcode xcresult bundles and enabling instant retrieval paths, dramatically accelerating repeated test result analysis.**

The XCResultCache class in the ios-simulator-skill repository solves the critical performance bottleneck of repeatedly parsing large Xcode test result bundles. By implementing a persistent storage layer at `~/.ios-simulator-skill/xcresults`, this caching system transforms expensive test result access into near-instantaneous file operations while minimizing token consumption for AI-driven workflows.

## Persistent Filesystem Storage Architecture

The cache stores Xcode **xcresult** bundles under a user-wide directory with unique timestamped identifiers, ensuring test artifacts survive across script invocations and system restarts. As implemented in [`ios-simulator-skill/scripts/xcode/cache.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/scripts/xcode/cache.py) (lines 20-45), the storage system creates the directory structure automatically and handles path normalization, eliminating the need to regenerate results between CI/CD pipeline stages.

## Instant Path Resolution

The `XCResultCache.get_path()` method converts any cache identifier into the exact filesystem location of the stored bundle. This method intelligently handles optional `.xcresult` extensions and validates bundle existence before returning the path. According to the source code in [`cache.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/cache.py) (lines 46-60), this lookup operation enables rapid access for downstream operations such as error parsing, log export, and result visualization without re-executing build commands.

## Progressive Disclosure for AI-Driven Analysis

Beyond storing raw bundles, the cache implements **progressive disclosure** through `save_stderr()` and `get_stderr()` methods. These helpers store a build's standard error output separately from the full xcresult bundle, allowing scripts to first display concise summaries and fetch detailed logs only on demand. This architectural pattern, found in [`cache.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/cache.py) (lines 76-89), dramatically reduces token output when integrating with AI-driven analysis workflows by avoiding the transmission of full result files unless necessary.

## Automatic Lifecycle Management

The `cleanup()` method prevents unbounded cache growth by removing older bundles while preserving a configurable number of recent results. By default, the system retains the most recent entries and purges aged artifacts automatically. As defined in [`cache.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/cache.py) (lines 33-57), this self-maintenance capability ensures the cache remains performant without manual intervention.

## Seamless Build Pipeline Integration

The XCResultCache integrates transparently into the build pipeline through dependency injection in the `BuildRunner` class. Located in [`ios-simulator-skill/scripts/xcode/builder.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/scripts/xcode/builder.py) (lines 30-48), the integration automatically instantiates a default cache instance when none is provided, making caching behavior transparent to calling scripts. The CLI entry point in [`build_and_test.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/build_and_test.py) leverages this integration to list cached bundles and execute progressive disclosure commands without explicit cache management code.

## Practical Implementation Example

```python

# Initialize the cache (uses default location if none provided)

cache = XCResultCache()

# Save a newly generated xcresult bundle after a build

bundle_id = cache.save(Path("/tmp/MyApp.xcresult"))

# Returns a timestamped ID like "xcresult-20251201-101530"

# Retrieve the bundle path later (e.g., to parse errors)

bundle_path = cache.get_path(bundle_id)

# Store the build's stderr for progressive disclosure

cache.save_stderr(bundle_id, "xcodebuild: error: ...")

# List the most recent bundles (default limit = 10)

recent = cache.list()
for entry in recent:
    print(entry["id"], entry["created"], entry["size_mb"], "MB")

# Clean up old bundles, keeping only the 20 newest

removed = cache.cleanup(keep_recent=20)
print(f"Removed {removed} old xcresult bundles")

```

## Summary

- **XCResultCache** eliminates redundant xcodebuild execution by persistently storing xcresult bundles in `~/.ios-simulator-skill/xcresults`
- **Instant retrieval** via `get_path()` converts identifiers to filesystem paths without re-parsing large result files
- **Progressive disclosure** through stderr caching reduces token consumption for AI analysis workflows
- **Automatic maintenance** via `cleanup()` prevents storage bloat while preserving recent test history
- **Zero-configuration integration** with `BuildRunner` makes caching transparent to existing build scripts

## Frequently Asked Questions

### How does XCResultCache improve CI/CD performance?

By storing Xcode xcresult bundles locally after the initial build and test run, XCResultCache eliminates the need to re-execute expensive `xcodebuild` commands or re-parse large result files during subsequent pipeline stages. This reduces test result access time from minutes to milliseconds while minimizing I/O overhead.

### Where does XCResultCache store test result data?

The cache stores bundles under `~/.ios-simulator-skill/xcresults` with timestamped identifiers like `xcresult-20251201-101530`. This user-wide directory ensures persistence across script invocations and system restarts, as implemented in [`ios-simulator-skill/scripts/xcode/cache.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/ios-simulator-skill/scripts/xcode/cache.py) (lines 20-45).

### What is progressive disclosure in XCResultCache?

Progressive disclosure refers to the cache's ability to store and retrieve a build's stderr output separately from the full xcresult bundle using `save_stderr()` and `get_stderr()`. This allows scripts to display concise error summaries first, fetching detailed logs only when needed, which minimizes token usage in AI-driven workflows according to the implementation in [`cache.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/cache.py) (lines 76-89).

### How does the cache prevent unlimited storage growth?

The `cleanup()` method automatically removes older xcresult bundles while retaining a configurable number of recent results via the `keep_recent` parameter. This lifecycle management, defined in [`cache.py`](https://github.com/conorluddy/ios-simulator-skill/blob/main/cache.py) (lines 33-57), ensures the cache directory does not consume excessive disk space over long-term usage.