debug
- Repo stars 357
- License GPL-2.0
- Author repo woocommerce-ios
- Domain
- Engineering
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 94 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @woocommerce · GPL-2.0
- Token usage
- Lean
- Setup complexity
- Guided setup
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Shell exec
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
Debug a build failure or test failure in the WooCommerce iOS project.
## For Build Failures
1. Run the build and capture errors:
```bash
bundle exec fastlane build_for_testing 2>&1 \
| grep -E "error:|fatal|cannot find|undefined|ambiguous" | head -30
```
2. Identify the failing file and error type
3. Read the failing file and surrounding context
4. Common root causes in this codebase:
- **Missing module**: Check Modules/Package.swift target dependencies
- **Type mismatch**: A Networking model changed — check if Yosemite/Storage need updates
- **Cannot find type**: May need `bundle exec rake generate` after adding GeneratedCopiable/Fakeable
- **Ambiguous reference**: Duplicate type names across Networking vs Storage
- **CoreData model errors**: Check Storage/CoreData/ model versions
5. Propose or apply the fix
## For Test Failures
1. Run the specific failing test (targeted tests require `xcodebuild` directly):
```bash
xcodebuild -workspace WooCommerce.xcworkspace -scheme WooCommerce \
-destination 'platform=iOS Simulator,name=iPhone 16' \
-sdk iphonesimulator test \
-only-testing:"<target>/<class>/<method>" 2>&1 | tail -50
```
2. Read the test file and understand what it expects
3. Read the implementation file being tested
4. Check the mock class setup
5. Common test failure patterns:
- **Assertion mismatch**: Verify expected vs actual, check mock stub values
- **Async timeout**: Check if mock callbacks are being invoked, verify continuation setup
- **Nil unwrap**: Check if mock return values are configured
- **Wrong mock state**: Verify spy properties are set correctly
- **CoreData errors**: Ensure InMemoryStorage is used, not persistent storage
- **Missing @MainActor**: Some tests need MainActor annotation
6. Propose or apply the fix
If the simulator destination fails, run `xcrun simctl list devices available` to discover available simulators, then re-run with a matching device name.
Sections and files
Listed in source order.
sections -> For Build Failures → For Test Failures
terms -> Missing module · Type mismatch · Cannot find type · Ambiguous reference · CoreData model errors · Assertion mismatch · Async timeout · Nil unwrap
files/cmd -> bundle exec rake generate · xcodebuild · xcrun simctl list devices available · Modules/Package.swift · Yosemite/Storage · GeneratedCopiable/Fakeable · Storage/CoreData
body sha256 -> d24f2f8784a5
For Build Failures
Run the build and capture errors: Identify the failing file and error type Read the failing file and surrounding context Common root causes in this codebase: Missing module: Check Modules/Package.swift target dependencies
For Test Failures
Run the specific failing test (targeted tests require
xcodebuilddirectly): Read the test file and understand what it expects Read the implementation file being tested Check the mock class setup Common test failure patterns: