Skip to content

n0an/VivaDicta / .agents/skills/ios-simulator-skill

ios-simulator-skill

Verified

21 production-ready scripts for iOS app testing, building, and automation. Provides semantic UI navigation, build automation, accessibility testing, and simulator lifecycle management. Optimized for AI agents with minimal token output.

FileKindSize
SKILL.mdskill md9.9 KB
agents/openai.yamlconfig279 B
references/accessibility_checklist.mdmarkdown1.5 KB
references/idb_quick.mdmarkdown1.1 KB
references/simctl_quick.mdmarkdown1.3 KB
references/test_patterns.mdmarkdown1.6 KB
references/troubleshooting.mdmarkdown1.3 KB
scripts/accessibility_audit.pyexecutablescript10.0 KB
scripts/app_launcher.pyexecutablescript9.5 KB
scripts/app_state_capture.pyexecutablescript12.9 KB
scripts/build_and_test.pyexecutablescript11.1 KB
scripts/clipboard.pyexecutablescript2.6 KB
scripts/common/__init__.pyscript1.5 KB
scripts/common/cache_utils.pyscript8.1 KB
scripts/common/device_utils.pyscript13.5 KB
scripts/common/idb_utils.pyscript5.3 KB
scripts/common/screenshot_utils.pyscript10.0 KB
scripts/gesture.pyexecutablescript12.3 KB
scripts/keyboard.pyexecutablescript11.5 KB
scripts/log_monitor.pyexecutablescript14.6 KB
scripts/navigator.pyexecutablescript14.0 KB
scripts/privacy_manager.pyexecutablescript8.7 KB
scripts/push_notification.pyexecutablescript6.5 KB
scripts/screen_mapper.pyexecutablescript10.4 KB
scripts/sim_health_check.shexecutablescript7.7 KB
scripts/sim_list.pyexecutablescript8.9 KB
scripts/simctl_boot.pyexecutablescript8.6 KB
scripts/simctl_create.pyexecutablescript8.9 KB
scripts/simctl_delete.pyexecutablescript10.3 KB
scripts/simctl_erase.pyexecutablescript9.8 KB
scripts/simctl_shutdown.pyexecutablescript8.4 KB
scripts/simulator_selector.pyexecutablescript10.3 KB
scripts/status_bar.pyexecutablescript6.6 KB
scripts/test_recorder.pyexecutablescript10.6 KB
scripts/visual_diff.pyexecutablescript7.6 KB
scripts/xcode/__init__.pyscript378 B
scripts/xcode/builder.pyscript12.8 KB
scripts/xcode/cache.pyscript5.5 KB
scripts/xcode/config.pyscript5.4 KB
scripts/xcode/reporter.pyscript10.3 KB
scripts/xcode/xcresult.pyscript16.5 KB

scripts/accessibility_audit.py

View on GitHub
#!/usr/bin/env python3
"""
iOS Simulator Accessibility Audit

Scans the current simulator screen for accessibility compliance issues.
Optimized for minimal token output while maintaining functionality.

Usage: python scripts/accessibility_audit.py [options]
"""

import argparse
import json
import subprocess
import sys
from dataclasses import asdict, dataclass
from typing import Any

from common import flatten_tree, get_accessibility_tree, resolve_udid


@dataclass
class Issue:
    """Represents an accessibility issue."""

    severity: str  # critical, warning, info
    rule: str
    element_type: str
    issue: str
    fix: str

    def to_dict(self) -> dict:
        """Convert to dictionary for JSON serialization."""
        return asdict(self)


class AccessibilityAuditor:
    """Performs accessibility audits on iOS simulator screens."""

    # Critical rules that block users
    CRITICAL_RULES = {
        "missing_label": lambda e: e.get("type") in ["Button", "Link"] and not e.get("AXLabel"),
        "empty_button": lambda e: e.get("type") == "Button"
        and not (e.get("AXLabel") or e.get("AXValue")),
        "image_no_alt": lambda e: e.get("type") == "Image" and not e.get("AXLabel"),
    }

    # Warnings that degrade UX
    WARNING_RULES = {
        "missing_hint": lambda e: e.get("type") in ["Slider", "TextField"] and not e.get("help"),
        "missing_traits": lambda e: e.get("type") and not e.get("traits"),
    }

    # Info level suggestions
    INFO_RULES = {
        "no_identifier": lambda e: not e.get("AXUniqueId"),
        "deep_nesting": lambda e: e.get("depth", 0) > 5,
    }

    def __init__(self, udid: str | None = None):
        """Initialize auditor with optional device UDID."""
        self.udid = udid

    def get_accessibility_tree(self) -> dict:
        """Fetch accessibility tree from simulator using shared utility."""
        return get_accessibility_tree(self.udid, nested=True)

    @staticmethod
    def _is_small_target(element: dict) -> bool:
        """Check if touch target is too small (< 44x44 points)."""
        frame = element.get("frame", {})
        width = frame.get("width", 0)
        height = frame.get("height", 0)
        return width < 44 or height < 44

    def _flatten_tree(self, node: dict, depth: int = 0) -> list[dict]:
        """Flatten nested accessibility tree for easier processing using shared utility."""
        return flatten_tree(node, depth)

    def audit_element(self, element: dict) -> list[Issue]:
        """Audit a single element for accessibility issues."""
        issues = []

        # Check critical rules
        for rule_name, rule_func in self.CRITICAL_RULES.items():
            if rule_func(element):
                issues.append(
                    Issue(
                        severity="critical",
                        rule=rule_name,
                        element_type=element.get("type", "Unknown"),
                        issue=self._get_issue_description(rule_name),
                        fix=self._get_fix_suggestion(rule_name),
                    )
                )

        # Check warnings (skip if critical issues found)
        if not issues:
            for rule_name, rule_func in self.WARNING_RULES.items():
                if rule_func(element):
                    issues.append(
                        Issue(
                            severity="warning",
                            rule=rule_name,
                            element_type=element.get("type", "Unknown"),
                            issue=self._get_issue_description(rule_name),
                            fix=self._get_fix_suggestion(rule_name),
                        )
                    )

        # Check info level (only if verbose or no other issues)
        if not issues:
            for rule_name, rule_func in self.INFO_RULES.items():
                if rule_func(element):
                    issues.append(
                        Issue(
                            severity="info",
                            rule=rule_name,
                            element_type=element.get("type", "Unknown"),
                            issue=self._get_issue_description(rule_name),
                            fix=self._get_fix_suggestion(rule_name),
                        )
                    )

        return issues

    def _get_issue_description(self, rule: str) -> str:
        """Get human-readable issue description."""
        descriptions = {
            "missing_label": "Interactive element missing accessibility label",
            "empty_button": "Button has no text or label",
            "image_no_alt": "Image missing alternative text",
            "missing_hint": "Complex control missing hint",
            "small_touch_target": "Touch target smaller than 44x44pt",
            "missing_traits": "Element missing accessibility traits",
            "no_identifier": "Missing accessibility identifier",
            "deep_nesting": "Deeply nested (>5 levels)",
        }
        return descriptions.get(rule, "Accessibility issue")

    def _get_fix_suggestion(self, rule: str) -> str:
        """Get fix suggestion for issue."""
        fixes = {
            "missing_label": "Add accessibilityLabel",
            "empty_button": "Set button title or accessibilityLabel",
            "image_no_alt": "Add accessibilityLabel with description",
            "missing_hint": "Add accessibilityHint",
            "small_touch_target": "Increase to minimum 44x44pt",
            "missing_traits": "Set appropriate accessibilityTraits",
            "no_identifier": "Add accessibilityIdentifier for testing",
            "deep_nesting": "Simplify view hierarchy",
        }
        return fixes.get(rule, "Review accessibility")

    def audit(self, verbose: bool = False) -> dict[str, Any]:
        """Perform full accessibility audit."""
        # Get accessibility tree
        tree = self.get_accessibility_tree()

        # Flatten for processing
        elements = self._flatten_tree(tree)

        # Audit each element
        all_issues = []
        for element in elements:
            issues = self.audit_element(element)
            for issue in issues:
                issue_dict = issue.to_dict()
                # Add minimal element info for context
                issue_dict["element"] = {
                    "type": element.get("type", "Unknown"),
                    "label": element.get("AXLabel", "")[:30] if element.get("AXLabel") else None,
                }
                all_issues.append(issue_dict)

        # Count by severity
        critical = len([i for i in all_issues if i["severity"] == "critical"])
        warning = len([i for i in all_issues if i["severity"] == "warning"])
        info = len([i for i in all_issues if i["severity"] == "info"])

        # Build result (token-optimized)
        result = {
            "summary": {
                "total": len(elements),
                "issues": len(all_issues),
                "critical": critical,
                "warning": warning,
                "info": info,
            }
        }

        if verbose:
            # Full details only if requested
            result["issues"] = all_issues
        else:
            # Default: top issues only (token-efficient)
            result["top_issues"] = self._get_top_issues(all_issues)

        return result

    def _get_top_issues(self, issues: list[dict]) -> list[dict]:
        """Get top 3 issues grouped by type (token-efficient)."""
        if not issues:
            return []

        # Group by rule
        grouped = {}
        for issue in issues:
            rule = issue["rule"]
            if rule not in grouped:
                grouped[rule] = {
                    "severity": issue["severity"],
                    "rule": rule,
                    "count": 0,
                    "fix": issue["fix"],
                }
            grouped[rule]["count"] += 1

        # Sort by severity and count
        severity_order = {"critical": 0, "warning": 1, "info": 2}
        sorted_issues = sorted(
            grouped.values(), key=lambda x: (severity_order[x["severity"]], -x["count"])
        )

        return sorted_issues[:3]


def main():
    """Main entry point."""
    parser = argparse.ArgumentParser(
        description="Audit iOS simulator screen for accessibility issues"
    )
    parser.add_argument(
        "--udid",
        help="Device UDID (auto-detects booted simulator if not provided)",
    )
    parser.add_argument("--output", help="Save JSON report to file")
    parser.add_argument(
        "--verbose", action="store_true", help="Include all issue details (increases output)"
    )

    args = parser.parse_args()

    # Resolve UDID with auto-detection
    try:
        udid = resolve_udid(args.udid)
    except RuntimeError as e:
        print(f"Error: {e}")
        sys.exit(1)

    # Perform audit
    auditor = AccessibilityAuditor(udid=udid)

    try:
        result = auditor.audit(verbose=args.verbose)
    except Exception as e:
        print(f"Error: {e}")
        sys.exit(1)

    # Output results
    if args.output:
        # Save to file
        with open(args.output, "w") as f:
            json.dump(result, f, indent=2)
        # Print minimal summary
        summary = result["summary"]
        print(f"Audit complete: {summary['issues']} issues ({summary['critical']} critical)")
        print(f"Report saved to: {args.output}")
    # Print to stdout (token-optimized by default)
    elif args.verbose:
        print(json.dumps(result, indent=2))
    else:
        # Ultra-compact output
        summary = result["summary"]
        print(f"Elements: {summary['total']}, Issues: {summary['issues']}")
        print(
            f"Critical: {summary['critical']}, Warning: {summary['warning']}, Info: {summary['info']}"
        )

        if result.get("top_issues"):
            print("\nTop issues:")
            for issue in result["top_issues"]:
                print(
                    f"  [{issue['severity']}] {issue['rule']} ({issue['count']}x) - {issue['fix']}"
                )

    # Exit with error if critical issues found
    if result["summary"]["critical"] > 0:
        sys.exit(1)


if __name__ == "__main__":
    main()
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall