# IOS Cn1ss Xcode Debug

> Reproduce and debug HelloCodenameOne iOS CN1SS build/test failures on a Mac using local ios-source generation plus xcodebuild logs.

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

---


# iOS CN1SS Xcode Debug

Use this skill when CN1SS iOS runs fail, produce blank screenshots, or crash during build/test.
This workflow is validated to compile and run locally against repository snapshots.

## Preconditions

- macOS with Xcode CLI tools installed (`xcodebuild` available).
- Java 8 available locally.
- Repository root checked out.

## Fast Workflow

1. Set Java 8 for Maven runs.
2. Install CN1 iOS artifacts from this repo into `~/.m2`.
3. Force-regenerate iOS local source for `scripts/hellocodenameone` so local snapshots are actually copied.
4. Run `xcodebuild` on the generated workspace.
5. Run the full CN1SS runner and inspect screenshot/log artifacts.
6. Extract first compile/runtime/test failure from logs.

## Commands

Run from repo root unless noted.

```bash
export JAVA_HOME=/Users/shai/Library/Java/JavaVirtualMachines/azul-1.8.0_372/Contents/Home
export PATH="$JAVA_HOME/bin:$PATH"
```

```bash
cd maven
mvn -q -pl ios -am -DskipTests -Dmaven.javadoc.skip=true install
```

```bash
cd ../scripts/hellocodenameone
rm -rf ios/target/hellocodenameone-ios-1.0-SNAPSHOT-ios-source
./mvnw -q package -DskipTests -Dcodename1.platform=ios -Dcodename1.buildTarget=ios-source -o -e
```

```bash
cd ios/target/hellocodenameone-ios-1.0-SNAPSHOT-ios-source
xcodebuild -list -workspace HelloCodenameOne.xcworkspace
xcodebuild -workspace HelloCodenameOne.xcworkspace -scheme HelloCodenameOne -configuration Debug -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' build
```

For full logs plus focused errors:

```bash
xcodebuild -workspace HelloCodenameOne.xcworkspace -scheme HelloCodenameOne -configuration Debug -sdk iphonesimulator -destination 'generic/platform=iOS Simulator' build > /tmp/hellocn1-xcodebuild.log 2>&1
rg -n "error:|fatal error:|undeclared function|BUILD FAILED|test host" /tmp/hellocn1-xcodebuild.log
```

Run the full UI test harness:

```bash
XCODE_APP=/Applications/Xcode.app \
scripts/run-ios-ui-tests.sh \
scripts/hellocodenameone/ios/target/hellocodenameone-ios-1.0-SNAPSHOT-ios-source/HelloCodenameOne.xcworkspace \
HelloCodenameOne
```

Post-run quick checks:

```bash
ls -1 artifacts/*.png | wc -l
shasum artifacts/*.png | sort | uniq -c | sort -nr | head
rg -n "CN1SS:ERR|CN1SS:SUITE:FINISHED" artifacts/device-runner.log
```

## Common Failure Signatures

- `Could not find test host for HelloCodenameOneTests`
  - The generated unit-test scheme host path is invalid. Prefer building/running `HelloCodenameOne` scheme directly for CN1SS troubleshooting.

- `call to undeclared function 'virtual_com_codename1_...'`
  - Common cause: static invocation of an instance API in app/test code.
  - Verify generated symbols in `HelloCodenameOne-src/com_codename1_*.m` and match call style.
  - Reinstall local CN1 maven artifacts from current repo (`maven -pl ios -am`) and regenerate ios-source.
  - Re-generate `ios-source` after reinstall.

- Build succeeds but screenshots are blank or repetitive
  - Check CN1SS log markers in app/test output:
    - `CN1SS:INFO:test=... png_bytes=...`
    - `CN1SS:ERR:...`
  - If PNG bytes are tiny or absent, investigate app startup and current form readiness (`Cn1ssDeviceRunnerHelper.emitCurrentFormScreenshot` path).
  - If many screenshots share the same hash, the runner is capturing a stable frame repeatedly. Check test navigation/state transitions before capture.
  - If tests appear hung and simulator shows system permission alerts, this is usually not a screenshot pipeline bug; unblock/disable the modal first.

- `Scheme file not found for env injection ... xcschemes/*.xcscheme`
  - The runner can continue, but scheme-based env injection is skipped.
  - Inspect `artifacts/device-runner.log` and decoded screenshots directly.

## Artifacts To Inspect

- Generated iOS project:
  - `scripts/hellocodenameone/ios/target/hellocodenameone-ios-1.0-SNAPSHOT-ios-source`
- Build log:
  - `/tmp/hellocn1-xcodebuild.log`
- CN1SS device log:
  - `artifacts/device-runner.log`
- Decoded screenshots:
  - `artifacts/*.png`
- Xcode derived data for this project:
  - `~/Library/Developer/Xcode/DerivedData/HelloCodenameOne-*`

## Notes

- `scripts/hellocodenameone/ios/pom.xml` includes Objective-C files from `src/main/objectivec` as resources; headers should only include imports that are available in generated project context.
- If a native interface exists in common, platform impl classes should exist for every built platform variant used by generated stubs (at least android/ios/javase in this project).

## Lessons Learned (Local Notifications + White Screenshots Incident)

- Keep only stable fixes in core code:
  - Temporary diagnostics (`NSLog`, extra CN1SS/CN1SHOT channels, timeout tweaks) are useful for triage but should be removed once root cause is proven.
- Propagation is a common trap:
  - Rebuilding `maven/ios` is not enough if generated `ios-source` is stale.
  - Always delete `scripts/hellocodenameone/ios/target/...-ios-source` before regeneration when validating port/native changes.
- Simulator behavior differs from device behavior:
  - Startup notification authorization can block CN1SS runs with an iOS modal.
  - A correct simulator-safe fix is to avoid notification authorization prompts on simulator startup paths.
- Stale SpringBoard state can mask fixes:
  - After changing notification authorization behavior, erase the simulator before re-testing:
    - `xcrun simctl shutdown <udid>`
    - `xcrun simctl erase <udid>`
- Validate assumptions with direct evidence:
  - Capture live simulator screenshots while tests run.
  - Query logs directly with `simctl log show` for app process markers to confirm which code path actually executed.