learning_ai_common_plat/AI.dev/SKILLS/test-ios-app.md

# Test iOS App Skill

**Description**: Build and test iOS applications in Xcode Simulator during development.

## When to Use

- Developing new iOS features
- Verifying UI/UX changes
- Testing platform-specific functionality
- Debugging iOS-only issues

## Prerequisites

### Environment Setup

- Xcode installed from Mac App Store
- iOS Simulator available
- Backend services running (if applicable)
- Apple Developer account (for device testing)

### Service Dependencies

```bash
# Start required backend services
./run-local-all-services.sh start

# Verify backend health
curl http://127.0.0.1:8000/health

# Check all services
./run-local-all-services.sh status
```

## Testing Workflow

### 1. Open Project in Xcode

```bash
# Navigate to iOS project
cd mobile_app/ios

# Open the workspace (not project)
open LysnrAI.xcworkspace
```

### 2. Configure Build Settings

In Xcode:

- **Scheme**: LysnrAI (or your app name)
- **Destination**: iPhone 16 Pro Simulator (or preferred device)
- **Configuration**: Debug (for development)

### 3. Build and Run

**Using Xcode:**

- Press `Cmd+R` to build and run
- Or Product → Run

**Using Command Line:**

```bash
# Build
xcodebuild -workspace LysnrAI.xcworkspace \
  -scheme LysnrAI \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
  build

# Run
xcodebuild -workspace LysnrAI.xcworkspace \
  -scheme LysnrAI \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
  test
```

### 4. Core Functionality Testing

#### Authentication Flow

```swift
// Test cases to verify:
// 1. Registration with valid email/password
// 2. Registration with invalid data (show errors)
// 3. Login with existing credentials
// 4. Login with wrong password (show error)
// 5. Logout functionality
// 6. Session persistence
```

#### Main Features

```swift
// Verify these screens work:
// 1. Home screen with personalized greeting
// 2. Core feature screens (e.g., recording, dashboard)
// 3. Settings/profile screen
// 4. Navigation between tabs
// 5. Form validation throughout
```

### 5. Platform-Specific Testing

#### iOS Features

- [ ] Push notifications (if enabled)
- [ ] Background app refresh
- [ ] Face ID/Touch ID (if implemented)
- [ ] Dark mode support
- [ ] Dynamic Type (font scaling)
- [ ] VoiceOver accessibility
- [ ] iPad layout (if universal app)

#### Device Testing

```bash
# List available simulators
xcrun simctl list devices

# Boot specific simulator
xcrun simctl boot "iPhone 16 Pro"

# Install app on simulator
xcrun simctl install "iPhone 16 Pro" build/Build/Products/Debug-iphonesimulator/YourApp.app

# Launch app
xcrun simctl launch "iPhone 16 Pro" com.yourbundle.yourapp
```

## Key Testing Areas

### 1. User Interface

- Layout on different screen sizes
- iPhone vs iPad layout differences
- Rotation support
- Keyboard appearance/disappearance
- Safe area handling

### 2. Network Behavior

- API calls with valid responses
- Error handling (no network, server errors)
- Loading states
- Offline functionality (if any)
- Request timeout handling

### 3. Data Persistence

- Core Data/UserDefaults saving
- Data survives app restart
- Sync with backend (if applicable)
- Data migration between versions

### 4. Performance

- App startup time
- Screen transition smoothness
- Memory usage monitoring
- Battery drain assessment

## Debugging Tools

### Xcode Debugging

```swift
// Breakpoints
// Use lldb commands in console
// po object - print object description
// p variable - print variable value
// expr expression - evaluate expression

// View hierarchy debugging
// Debug → View Debugging → Capture View Hierarchy
```

### Console Logging

```swift
// Structured logging
import os.log

let logger = Logger(subsystem: "com.yourapp.yourapp", category: "Main")

logger.info("User logged in")
logger.error("Failed to load data: \(error.localizedDescription)")
```

### Network Debugging

```swift
// Use Charles Proxy or Proxyman
// Or implement network logging
extension NetworkLogger {
    static func log(request: URLRequest) {
        print("🌐 \(request.httpMethod ?? "") \(request.url?.absoluteString ?? "")")
    }
}
```

## Automated Testing

### Unit Tests

```swift
// Tests/YourAppTests/AuthenticationTests.swift
import XCTest
@testable import YourApp

class AuthenticationTests: XCTestCase {
    var authService: AuthService!

    override func setUp() {
        super.setUp()
        authService = AuthService()
    }

    func testValidLogin() async {
        let result = await authService.login(email: "test@example.com", password: "password")
        XCTAssertTrue(result.success)
    }

    func testInvalidLogin() async {
        let result = await authService.login(email: "test@example.com", password: "wrong")
        XCTAssertFalse(result.success)
    }
}
```

### UI Tests

```swift
// Tests/YourAppUITests/AuthenticationUITests.swift
import XCTest

class AuthenticationUITests: XCTestCase {
    override func setUpWithError() throws {
        continueAfterFailure = false
    }

    func testLoginFlow() throws {
        let app = XCUIApplication()
        app.launch()

        // Tap login button
        app.buttons["Login"].tap()

        // Enter credentials
        app.textFields["Email"].typeText("test@example.com")
        app.secureTextFields["Password"].typeText("password")

        // Submit
        app.buttons["Sign In"].tap()

        // Verify home screen
        XCTAssertTrue(app.staticTexts["Welcome"].waitForExistence(timeout: 5))
    }
}
```

### Run Tests

```bash
# Unit tests
xcodebuild test -workspace LysnrAI.xcworkspace \
  -scheme LysnrAI \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro'

# UI tests
xcodebuild test -workspace LysnrAI.xcworkspace \
  -scheme LysnrAI \
  -destination 'platform=iOS Simulator,name=iPhone 16 Pro' \
  -only-testing:LysnrAITests
```

## Common Issues and Solutions

### Build Issues

| Problem                | Solution                                 |
| ---------------------- | ---------------------------------------- |
| "No such module"       | Run `pod install` and clean build        |
| Code signing errors    | Set automatic signing in target settings |
| Simulator won't launch | Reset Simulator content and settings     |
| App crashes on launch  | Check device console logs                |

### Runtime Issues

| Problem               | Solution                         |
| --------------------- | -------------------------------- |
| Network requests fail | Check API endpoint configuration |
| UI not updating       | Verify main thread usage         |
| Data not persisting   | Check Core Data model version    |
| Memory leaks          | Use Instruments → Leaks          |

## Performance Testing

### Instruments

```bash
# Launch with Instruments
xcrun xctrace open --template Time Profiler
xcrun xctrace open --template Allocations
xcrun xctrace open --template Leaks
```

### Metrics to Track

- App startup time (< 3 seconds)
- Memory usage (< 100MB typical)
- CPU usage during tasks
- Network request times
- Battery consumption

## Device Testing

### Physical Device Setup

```bash
# Connect device
# Trust computer on device
# Check in Xcode: Window → Devices and Simulators

# Install on device
xcodebuild -workspace LysnrAI.xcworkspace \
  -scheme LysnrAI \
  -destination 'platform=iOS,name=Your iPhone' \
  install
```

### Test on Real Devices

- Performance differences
- Touch ID/Face ID
- Camera/microphone access
- Push notifications
- Background modes

## CI/CD Integration

### GitHub Actions

```yaml
name: iOS Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: macos-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Xcode
        uses: maxim-lobanov/setup-xcode@v1
        with:
          xcode-version: latest-stable

      - name: Install CocoaPods
        run: |
          cd mobile_app/ios
          pod install          

      - name: Run Tests
        run: |
          xcodebuild test \
            -workspace mobile_app/ios/LysnrAI.xcworkspace \
            -scheme LysnrAI \
            -destination 'platform=iOS Simulator,name=iPhone 16 Pro'          
```

## Test Documentation

### Test Checklist Template

```markdown
# iOS Test Report - Version 1.0.0

## Environment

- Xcode: 15.0
- iOS: 17.0
- Device: iPhone 16 Pro Simulator

## Test Results

| Feature            | Status | Notes                |
| ------------------ | ------ | -------------------- |
| Authentication     | ✅     | All flows working    |
| Home Screen        | ✅     | Data loads correctly |
| Settings           | ⚠️     | Dark mode issue      |
| Push Notifications | ❌     | Not configured       |

## Bugs Found

1. Settings screen crashes in dark mode
2. Push notification permission not requested

## Next Steps

1. Fix dark mode crash
2. Implement push permission flow
```

## Best Practices

### Testing Strategy

1. **Test on multiple devices** - Different screen sizes
2. **Test iOS versions** - Support current and previous major version
3. **Use real devices** - Simulators don't catch everything
4. **Automate regression tests** - Prevent breaking existing features

### Debugging Tips

1. **Use breakpoints effectively** - Conditional breakpoints
2. **Check console logs** - Both Xcode and device console
3. **Use view debugger** - Inspect UI hierarchy
4. **Profile performance** - Don't guess, measure

## Notes

- **Simulator limitations** - Some features differ on real devices
- **iOS version differences** - Test on minimum supported version
- **App Store guidelines** - Test against review guidelines
- **Accessibility matters** - Test with VoiceOver and other accessibility features

## Related Skills

- [iOS Release](./ios-release.md) - After testing
- [Mobile Code Quality](./mobile-code-quality.md) - Code standards
- [Test Strategies](./test-strategies.md) - General testing
- [Debug Service](./debug-service.md) - Troubleshooting