Build Deterministic iOS Clipboard Tests with simctl

When iOS tests run remotely, clipboard features can easily fall into a blind spot where they work with a quick tap on a local machine but cannot be verified in the pipeline. Importing invitation codes, pasting debug commands, cleaning multiline text, and copying content within the app all depend on the system clipboard, yet ordinary unit tests often bypass the real entry point. A more reliable approach is to assign a dedicated simulator to each job, inject deterministic text with simctl, and then have a UI test perform the user-visible paste action.

Define the test scope first

This workflow is suitable for testing plain text, Unicode, whitespace, and line-ending handling. pbcopy should not be treated as an injector for arbitrary binary data. Images, file URLs, and custom UTIs should be supplied through in-app test fixtures or a dedicated test host.

Start by identifying the behaviors that genuinely need protection:

• Can single-line text enter a form through an explicit paste entry point?
• Are \n and \r\n normalized according to the product rules?
• Do Chinese characters, combining characters, and emoji remain intact?
• Does copied output contain extra spaces or invisible characters?
• Does the UI present an understandable state when the clipboard is empty?
• Is cross-job state cleaned up after the test finishes?

The goal of automation is not to read the system clipboard directly. It is to verify that the app displays the correct result after the user triggers a copy or paste action.

Prepare a clean simulator for every job

Parallel jobs must not share the ambiguous booted target. If two jobs run pbcopy at the same time, the later write will overwrite the earlier content. The orchestration layer should provide a fixed UDID and allocate separate directories for DerivedData and result bundles.

set -euo pipefail

: "${IOS_UDID:?IOS_UDID is required}"
JOB_ROOT="${PWD}/artifacts/${CI_JOB_ID:-local}"
mkdir -p "$JOB_ROOT"

xcrun simctl shutdown "$IOS_UDID" 2>/dev/null || true
xcrun simctl erase "$IOS_UDID"
xcrun simctl boot "$IOS_UDID"
xcrun simctl bootstatus "$IOS_UDID" -b

erase removes app containers and simulator settings, making it appropriate for acceptance jobs that prioritize deterministic results. If the pipeline needs to reuse installed apps to shorten setup time, cleanup still needs to be designed explicitly: at minimum, uninstall the app under test, clear the clipboard, and record the runtime version and UDID.

Inject auditable text fixtures

Do not assemble complex Unicode strings directly in the shell. Store fixtures as UTF-8 files so code review can reveal exactly how the input has changed.

mkdir -p Tests/ClipboardFixtures

printf '第一行\n第二行：café\nemoji：🧪\n' \
  > Tests/ClipboardFixtures/multiline.txt

xcrun simctl pbcopy "$IOS_UDID" \
  < Tests/ClipboardFixtures/multiline.txt

Fixtures should cover both normal and boundary inputs, but they should not combine every case into one oversized file. Maintain separate cases for single-line text, multiline text, leading and trailing whitespace, combining characters, and empty content. When a test fails, log only the fixture filename, byte count, and digest. Do not print the actual clipboard contents unconditionally because they may contain sensitive data.

During debugging, read the injected content back once to determine whether the problem is on the injection side or in the app:

xcrun simctl pbpaste "$IOS_UDID" > "$JOB_ROOT/clipboard-before.txt"
cmp Tests/ClipboardFixtures/multiline.txt \
  "$JOB_ROOT/clipboard-before.txt"

A production pipeline does not need to retain this plaintext permanently. Delete the file after confirming the match, or preserve only the output of shasum -a 256.

Trigger paste and copy through the real entry point

The app should provide a recognizable paste control instead of silently reading the clipboard when the screen loads. The UI test should tap that control and then inspect the result on screen. This covers the actual interaction path and avoids mistaking a successful background read for a working user-facing feature.

func testPasteMultilineFixture() {
    let app = XCUIApplication()
    app.launchArguments += ["-ui-testing"]
    app.launch()

    let pasteButton = app.buttons["clipboard.paste"]
    XCTAssertTrue(pasteButton.waitForExistence(timeout: 10))
    pasteButton.tap()

    let editor = app.textViews["clipboard.editor"]
    XCTAssertTrue(editor.waitForExistence(timeout: 5))
    XCTAssertEqual(
        editor.value as? String,
        "第一行\n第二行：café\nemoji：🧪"
    )
}

If the system displays a paste confirmation prompt, the test should treat it as part of the interaction rather than bypassing it through an internal API. Controls should have stable accessibility identifiers and must not depend on localized button labels.

Copying can be verified in the opposite direction: have the UI test enter fixed content and tap Copy, then export the result with pbpaste after the test completes. This can expose trailing line breaks, rich-text degradation, or incorrect whitespace cleanup.

Run tests, preserve evidence, and diagnose failures

Complete the build before running the tests. This keeps compilation failures and interaction failures from being mixed together in the same log.

xcodebuild build-for-testing \
  -scheme ClipboardApp \
  -destination "platform=iOS Simulator,id=$IOS_UDID" \
  -derivedDataPath "$JOB_ROOT/DerivedData"

xcodebuild test-without-building \
  -scheme ClipboardApp \
  -destination "platform=iOS Simulator,id=$IOS_UDID" \
  -derivedDataPath "$JOB_ROOT/DerivedData" \
  -resultBundlePath "$JOB_ROOT/ClipboardTests.xcresult"

When a failure occurs, check the following in order: whether the UDID belongs to the current job, whether the simulator finished booting, whether the fixture hash matches, whether the app actually tapped the paste control, and whether the assertion reads the final UI state. Do not immediately rerun every failure. A rerun can hide a race condition and destroy the original evidence.

The job can perform cleanup on exit, but failed runs should retain the xcresult, simulator logs, and screenshots. Clipboard plaintext should be deleted by default, leaving only its length, encoding, digest, and fixture name. If a test involves content that users might enter, redact the logs before archiving them.

Make the checks part of the pipeline

A stable clipboard regression job should meet at least these requirements:

1. The UDID, DerivedData, and result directory are isolated per job;
2. the simulator runtime version is recorded;
3. text fixtures are stored as UTF-8 files in version control;
4. tests trigger paste or copy through a user action;
5. empty clipboard, Unicode, and line-ending behavior have separate test cases;
6. UI evidence is preserved on failure, while clipboard plaintext is not retained long term;
7. temporary simulator state is cleaned up after the job exits.

The value of these tests is not in testing the system clipboard itself. It comes from turning the contract between the app and the clipboard into repeatable inputs and outputs. When every failure can be tied to a specific UDID, fixture digest, test step, and result bundle, remote diagnosis no longer depends on someone manually recounting what happened.

Frequently asked questions