wiim — Cursor Rules

❌ WRONG: `python def _is_eq_supported(self) -> bool: # Check capabilities first if capabilities.get("supports_eq"): return True # Fallback: check if player has presets (WORKAROUND) if player.available_eq_presets: return True ` ✅ RIGHT: `python def _is_eq_supported(self) -> bool: # pywiim MUST provide this via capabilities return capabilities.get("supports_eq", False) ` If pywiim doesn't set supports_eq correctly → FIX PYWIIM

• CRITICAL: Always add tests for new code - Codecov requires 77.88% patch coverage • Every new function, method, or feature must have corresponding tests • Every code change must include tests for the modified functionality • Codecov will fail if new/changed code lacks test coverage • Patch coverage (new code) is separate from project coverage (overall) • NEVER skip writing tests to "fix Codecov later" - tests must be written WITH the code • Test pywiim integration, not device hardware • Mock pywiim Player and Client objects • Test error handling and edge cases • No integration tests that require actual hardware • When adding new code: • Write the code • Write tests for the new code immediately • Ensure all new lines are covered by tests • ALWAYS test locally before pushing - Run ./scripts/check-before-push.sh or pytest --cov to verify everything works • NEVER push with --no-verify unless explicitly debugging CI infrastructure • NEVER push to see if it works - fix issues locally first

CRITICAL: Codecov enforces 77.40% patch coverage (as of Dec 2025) What is patch coverage? • Patch coverage = coverage of NEW or CHANGED lines in a PR/commit • This is separate from overall project coverage • Codecov compares your changes against the baseline commit What happens if patch coverage is too low? • CI will fail with: 28.20% of diff hit (target 77.40%) • The release process will be blocked • You cannot merge until coverage is fixed Common causes of low patch coverage: • Adding new code without tests - Most common! Every new function/method needs tests • Skipping tests for "complex" code - No exceptions! Complex code needs MORE tests • Error paths not tested - If you add error handling, test it! • Conditional logic not fully covered - Test all branches (if/else, try/except) • Disabled code still counts - Even if a function is pass, it needs a test How to fix low patch coverage: • Identify uncovered lines: pytest --cov=custom_components/wiim --cov-report=term-missing • Write tests for ALL uncovered lines • Test both success and error paths • Test edge cases (None, empty lists, invalid inputs) • Re-run coverage until >77.40% Example: Join service fix (Dec 2025) • Added new coordinator lookup logic → Needed 5+ new tests • Added error handling paths → Each error path needed a test • Result: Coverage went from 28.20% → 77%+ after adding comprehensive tests Golden Rule: If you write code, you MUST write tests. No exceptions.

• Developer Guide: See /development/README.md for architecture and contribution guidelines • Testing Guide: See /development/TESTING.md for test requirements and examples • HA Integration Guide: See /development/HA_INTEGRATION_GUIDE.md for Home Assistant specific patterns (references upstream guides) • User Documentation: See /docs/ for user-facing guides Do not create new documentation files without being explicitly asked. Always reference upstream pywiim documentation (see "Reference Upstream Documentation" section below) instead of duplicating content.