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.

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

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

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

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:

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:

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:

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.