# Setup Xcuitest

> Prepare and verify Appium XCUITest for iOS or tvOS on macOS by validating Node/Appium, Xcode, driver installation, doctor output, simulator or shared real-device prerequisites, and server smoke evidence. Use when the setup Skill selects XCUITest or appium-troubleshooting hands off an XCUITest prerequisite or doctor failure. For a real device, continue to xcuitest-real-device-config after this Skill passes. Do not use for real-device signing, provisioning, or WebDriverAgent deployment.

- Skill: `appium/setup-xcuitest` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add appium/setup-xcuitest`
- Raw SKILL.md: https://api.skillmd.com/api/skills/appium/setup-xcuitest/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: appium (https://skillmd.com/u/appium)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/appium/setup-xcuitest

---


# XCUITest Setup Workflow

## XCUITest setup routing and handoffs

Prepare shared Appium XCUITest prerequisites for iOS or tvOS. For a simulator,
complete this Skill after doctor and smoke checks pass. For a real device,
complete these shared prerequisites first and then continue with
`skills/xcuitest-real-device-config/SKILL.md` for trust, Developer Mode,
signing, provisioning, WebDriverAgent deployment, and connectivity. Hand later
runtime failures to `skills/appium-troubleshooting/SKILL.md`.

## Required inputs

Confirm iOS or tvOS, simulator or real device, macOS host, global `appium` mode
or explicitly requested local `npx appium` mode, Xcode state, permissions, and
optional FFmpeg requests.

## Workflow

1. Load the global command profile by default or the local profile only when
   explicitly requested.
2. Load the macOS and XCUITest profiles, shared Appium setup basics, Xcode
   prerequisites, and XCUITest decision, driver-doctor, and smoke references.
3. Run `node tools/appium/setup/scripts/check-xcuitest-env.mjs --format summary --report auto`; add
   `--appium-mode local` only for explicitly requested local mode. Require
   top-level `summary.requiredOk: true`.
   Apply required fixes in technical dependency order and rerun affected checks.
   If the gate remains unresolved, report `blocked` with evidence and the next
   action. Load the matching example only when needed.
4. Verify the direct doctor output reports `0 required fixes needed` using
   `appium driver doctor xcuitest`, or
   `npx --no-install appium driver doctor xcuitest` in local mode.
5. Run `node tools/appium/setup/scripts/smoke-appium-server.mjs --driver xcuitest --report auto`;
   add `--appium-mode local` only in local mode. Require
   `summary.requiredOk: true` for server readiness, driver evidence, and
   cleanup. The smoke reference documents target-specific options.
6. For a real device, record passing shared-setup evidence before continuing
   to `skills/xcuitest-real-device-config/SKILL.md`.

## XCUITest setup safety and approval constraints

- Require macOS.
- Ask before optional FFmpeg setup, privileged commands, Xcode license or
  first-launch changes, trust changes, signing changes, or device installation.
- Leave real-device signing, provisioning, and WDA deployment to the
  real-device Skill.
- Preserve the selected command mode and working Xcode and driver
  installations.

## Completion criteria

- `xcodebuild -version` and `xcode-select -p` succeed.
- Xcode license and first-launch requirements are handled.
- Appium succeeds in the selected command mode and the installed list includes
  `xcuitest`.
- `appium driver doctor xcuitest` reports `0 required fixes needed`; optional
  warnings are non-blocking.
- `/status` succeeds and logs list `xcuitest`.
- For a real-device request, the exact continuation to
  `skill.xcuitest-real-device-config` is reported after shared setup passes.

## Evidence boundary

Report Xcode tooling, Appium and XCUITest versions, helper and doctor summaries,
simulator or device target, `/status`, server driver evidence, cleanup, and
whether the real-device continuation applies.

## Self-Improvement Prompt

Before the final response, report any missing, ambiguous, outdated, or
retry-causing XCUITest setup instruction with its asset path and proposed
wording. Leave unrelated assets unchanged.