Accessibility Helper

Retrofit Accessibility Identifiers onto existing Xcode UI — and turn them into UI tests.

Suitable for large iOS codebases that grew up without consistent accessibilityIdentifiers. This suite walks .storyboard / .xib files, stamps readable, deterministic IDs, improves VoiceOver metadata, and emits CSV + WebdriverIO / Appium scaffolding so QA and automation can work from the same source of truth.

---

Why this exists

Manual accessibility IDs (or random UUIDs) don’t scale:

Problem	What this suite does
Thousands of unlabeled controls	Batch-tags storyboards and xibs
Opaque IDs in test failures	Builds IDs like login-Home-button-ingresar
VoiceOver incomplete	Adds label, Spanish type-based hint, and traits
Tests written by hand from scratch	Emits CSV + WebdriverIO / Appium skeletons
Fear of running a batch script blind	Preview elements in a macOS drag-and-drop app

Related predecessor: python-xcode-housekeeping (UUID-style IDs). This repo is the more advanced, production-oriented evolution.

---

What’s inside

accessibility-helper/
├── xcode-accessibility-generator/   # Main Python CLI
├── accessibility-scan-app/          # macOS SwiftUI preview app
├── appium-test-generator/           # CSV → Appium/WebdriverIO script
├── prepare-app-for-tests.sh         # Example end-to-end CI-ish flow
└── LICENSE

Component	Role
xcode-accessibility-generator	Retro-fits IDs + VoiceOver metadata; writes per-screen CSV and JS test skeletons
accessibility-scan-app	Native macOS app: drag a folder, browse elements and preview IDs before batch runs
appium-test-generator	Turns an accessibility CSV into a runnable Appium/WebdriverIO script
prepare-app-for-tests.sh	Example flow: rebase branch → generate IDs → simulator build → push

---

Quick start

1. Generate accessibility IDs (CLI)

Requirements: Python 3.

cd xcode-accessibility-generator

# Point BASE_PATH at your Xcode project root (edit the script):
#   STORYBOARDS_PATH → …/Storyboards/Base.lproj
#   MODULES_PATH     → …/Modules
# Adjust if your layout differs.

python3 main_accessibility_generator.py

Effects:

• Updates .storyboard / .xib in place (adds missing accessibility nodes)
• Writes Output/CSV/<name>_accessibility.csv
• Writes Output/JS/<name>_accessibility_tests.js (WebdriverIO-style client.$('~id') lookups)

Example ID shape:

login-Home-button-ingresar
# screen / module – view context – control type – control text

2. Preview before batch (macOS app)

Requirements: Xcode 15+, macOS 13+.

1. Open accessibility-scan-app/AccessibilityScan/AccessibilityScan.xcodeproj
2. Run the app
3. Drag a folder that contains .storyboard / .xib files onto the window
4. Browse elements and the IDs that would be generated

3. Scaffold Appium tests from CSV

cd appium-test-generator
# Set csv_file in AppiumScriptGenerator.py to your CSV path
python3 AppiumScriptGenerator.py
# → appium_generated_tests.js

4. Optional full flow

Edit placeholders in prepare-app-for-tests.sh (MyApp, scheme, branches), then:

./prepare-app-for-tests.sh

---

How the generator decides IDs

1. Walk storyboards and feature modules (xibs)
2. Keep interactive / meaningful control types (buttons, fields, switches, etc.)
3. Normalize visible text into a stable camelCase fragment
4. Compose: context-viewController-type-text
5. Attach VoiceOver label, hint (Spanish defaults by type), and traits
6. Export inventory (CSV) and test stubs (JS)

IDs stay stable across runs as long as context, type, and text don’t change — so tests don’t churn when you re-run the tool.

---

Typical workflow

  ┌─────────────────────┐
  │ accessibility-scan  │  optional: preview a folder
  │        (macOS)      │
  └──────────┬──────────┘
             │
             ▼
  ┌─────────────────────┐
  │ xcode-accessibility │  batch: patch UI + CSV + JS
  │     -generator      │
  └──────────┬──────────┘
             │
             ├──────────────► Output/CSV  ──► appium-test-generator
             └──────────────► Output/JS   ──► fill assertions / ship to QA

1. Spot-check a module in the macOS app
2. Run the generator on the full project (on a dedicated git branch)
3. Review the storyboard/xib diff and the CSV
4. Generate or extend Appium/WebdriverIO tests
5. Open a PR for the accessibility retrofit

---

Requirements

Piece	Needs
Generator & Appium tools	Python 3
Scan app	Xcode 15+, macOS 13+ (SwiftUI)
prepare-app-for-tests.sh	git, CocoaPods (if used), Xcode CLT

No tokens or private API keys are required for the core tools.

---

License

MIT — Copyright (c) 2021–2026 Juan Carlos Correa Arango

Author

Juan Correa (@serenoj)

---

Related repos

Repo	Relation
python-xcode-housekeeping	Earlier UUID-based accessibility tooling
ios-build-scripts	CI archive / test / distribute scripts
ios-analysis-toolkit	Periphery + Sourcery analysis helpers