Validate App Clip Invocation and Host Bundle Consistency on a Cloud Mac

An App Clip launching successfully from its Scheme on a development Mac does not mean the deliverable is correct. The most common issues are not compilation failures, but a Clip missing from the host archive, inconsistent parent-child identifiers, or invocation URLs that cover only the ideal path. Moving these checks into continuous integration on a cloud Mac ensures that every commit uses the same Xcode version, simulators, and validation scripts.

Define verifiable delivery outcomes first

Do not treat “Build Succeeded” as the only outcome. A complete validation run should produce at least the host .xcarchive, a separate App Clip build log, parsed entitlement files, and records of invocation scenarios. Store test URLs in repository configuration rather than scattering them across developers’ personal Scheme settings.

Launching the Clip independently validates the business entry point. Archiving the host and then inspecting the embedding relationship validates the deliverable structure. Neither check can replace the other.

Keep the build directory stable

Cloud jobs should use isolated DerivedData so that artifacts from a previous run cannot hide copy-phase errors. Build the simulator version of the App Clip first, then archive the host. Passing Scheme names through environment variables allows the script to be reused across branches.

set -euo pipefail

ROOT="$PWD"
OUT="$ROOT/.ci-artifacts"
DERIVED="$OUT/DerivedData"
ARCHIVE="$OUT/HostApp.xcarchive"

rm -rf "$OUT"
mkdir -p "$OUT"

xcodebuild \
  -workspace "$WORKSPACE" \
  -scheme "$CLIP_SCHEME" \
  -sdk iphonesimulator \
  -destination "$SIMULATOR_DESTINATION" \
  -derivedDataPath "$DERIVED" \
  clean build | tee "$OUT/app-clip-build.log"

xcodebuild \
  -workspace "$WORKSPACE" \
  -scheme "$HOST_SCHEME" \
  -destination "generic/platform=iOS" \
  -archivePath "$ARCHIVE" \
  archive | tee "$OUT/host-archive.log"

SIMULATOR_DESTINATION can be pinned to a device type and OS version installed in the pipeline. After upgrading Xcode, update the baseline job first instead of allowing an ordinary feature commit to change the test runtime implicitly.

Inspect the bundle relationship between the host and Clip

Locate the embedded artifact

After archiving, locate the host .app under Products/Applications, then verify that its AppClips directory contains exactly the expected target. Do not rely on a fixed application filename. Search by extension and validate the number of results instead.

HOST_APP="$(find "$ARCHIVE/Products/Applications" -maxdepth 1 -name '*.app' -print -quit)"
CLIP_APP="$(find "$HOST_APP/AppClips" -maxdepth 1 -name '*.app' -print -quit)"

test -n "$HOST_APP"
test -n "$CLIP_APP"

HOST_ID="$(/usr/libexec/PlistBuddy -c 'Print :CFBundleIdentifier' "$HOST_APP/Info.plist")"
CLIP_ID="$(/usr/libexec/PlistBuddy -c 'Print :CFBundleIdentifier' "$CLIP_APP/Info.plist")"

printf '%s
' "$HOST_ID" > "$OUT/host-bundle-id.txt"
printf '%s
' "$CLIP_ID" > "$OUT/clip-bundle-id.txt"

If the AppClips directory is missing, first inspect the host Target’s embedding phase, confirm that the Clip Target belongs to the current archive Scheme, and check whether the Release configuration overrides settings that work in Debug.

Compare the final entitlements

Declarations in the project file do not always match the final values signed into the artifacts. Use codesign -d --entitlements :- to export the host and Clip entitlements separately, then use plutil to convert them into a stable format. The gate should verify that the Clip’s parent application association points to the current host while also restricting capabilities that must not be inherited.

codesign -d --entitlements :- "$HOST_APP" > "$OUT/host-entitlements.plist"
codesign -d --entitlements :- "$CLIP_APP" > "$OUT/clip-entitlements.plist"

plutil -lint "$OUT/host-entitlements.plist"
plutil -lint "$OUT/clip-entitlements.plist"

Do not compare the entire files as text, because Xcode version changes may alter key ordering. Instead, extract and compare each key that must remain stable, and write the actual values to the build artifacts so they can be reviewed after a failure.

Validate routing with three URL categories

Invocation tests should cover at least the base entry point, valid parameters, and invalid input. For example, the base entry point should open the default lightweight experience; a URL containing a resource identifier should open the specified content; and missing or invalid parameters should lead to a safe fallback page rather than leaving the app in a blank state.

Treat URLs as test inputs

Using _XCAppClipURL in the App Clip Scheme is suitable for manual debugging, but continuous integration should not depend on a developer’s local Scheme state. A more reliable approach is to let the router accept a URL and cover the inputs directly with unit tests, while retaining one simulator smoke job to validate the application lifecycle.

func testInvocationRoutes() throws {
    let base = try XCTUnwrap(URL(string: invocationBaseURL))
    XCTAssertEqual(router.route(for: base), .home)

    let item = try XCTUnwrap(URL(string: invocationItemURL))
    XCTAssertEqual(router.route(for: item), .item(id: "42"))

    let malformed = try XCTUnwrap(URL(string: invocationMalformedURL))
    XCTAssertEqual(router.route(for: malformed), .fallback)
}

This separates domain resolution, path matching, query-parameter validation, and UI startup. Router unit tests cover all branches, while the simulator job only confirms that the real process starts and presents its first screen, making failures easier to isolate.

Tighten the gate and preserve failure evidence

When the gate fails, archive at least the xcodebuild logs, both Info.plist files, exported entitlement files, host and Clip identifiers, and the names of failed test cases. If logs contain access tokens, temporary credentials, or sensitive fragments of local paths, redact them before uploading.

Use a fixed validation order: clean the isolated build directory, build the Clip, archive the host, inspect embedding, compare critical entitlements, execute routing tests, and run the simulator smoke test. Stop immediately when a preliminary structural check fails to avoid spending simulator time on an invalid archive.

Jobs on GPUMini should also explicitly record xcodebuild -version, the selected SDK, and the simulator runtime. What requires long-term maintenance is not a screenshot of a single successful run, but a set of checks with explicit inputs, traceable artifacts, and failures that can be reproduced quickly.

Frequently asked questions