ha-validate-dashboards
Original:🇺🇸 English
Translated
Provides 3-tier validation approach for Home Assistant dashboards including pre-publish validation (entity checks, config structure), post-publish verification (log analysis), and visual validation (browser console, rendering). Use when validating HA dashboards, checking dashboard configs, verifying entity IDs, debugging rendering issues, or before deploying dashboard changes. Triggers on "validate dashboard", "check HA config", "dashboard errors", "entity not found", or "test dashboard". Works with Home Assistant WebSocket/REST APIs, Chrome extension MCP tools, Python dashboard builders, and YAML dashboard configurations.
2installs
Added on
NPX Install
npx skill4agent add dawiddutoit/custom-claude ha-validate-dashboardsTags
Translated version includes tags in frontmatterSKILL.md Content
View Translation Comparison →Home Assistant Dashboard Validation
Validates Home Assistant dashboard and configuration changes using a comprehensive 3-tier validation approach to catch errors before they impact users.
Quick Start
Run a complete validation before deploying a dashboard:
bash
# 1. Validate config structure and entities (pre-publish)
python3 << 'EOF'
import json
with open('climate_dashboard.json') as f:
config = json.load(f)
from validation_helpers import validate_dashboard_config, verify_entities_exist, extract_all_entity_ids
is_valid, errors = validate_dashboard_config(config)
if not is_valid:
print("Config errors:", errors)
exit(1)
entities = extract_all_entity_ids(config)
existence = verify_entities_exist(entities)
missing = [e for e, exists in existence.items() if not exists]
if missing:
print("Missing entities:", missing)
exit(1)
print("✅ Pre-publish validation passed")
EOF
# 2. Publish dashboard
./run.sh dashboard_builder.py
# 3. Check HA logs (post-publish)
curl -s "http://192.168.68.123:8123/api/error_log" \
-H "Authorization: Bearer $HA_LONG_LIVED_TOKEN" | \
grep -i "lovelace" | tail -5
# 4. Visual validation (browser)
mcp-cli call claude-in-chrome/navigate '{"url": "http://192.168.68.123:8123/climate-dashboard"}'
sleep 2
mcp-cli call claude-in-chrome/read_console_messages '{}'Table of Contents
- When to Use This Skill
- The 3-Tier Validation Approach
- Validation Workflows
- Common Failure Modes
- Supporting Files
- Integration with Project
- Requirements
- Red Flags to Avoid
When to Use This Skill
Explicit Triggers:
- "validate my dashboard"
- "check HA dashboard config"
- "verify dashboard entities"
- "validate before publish"
Implicit Triggers:
- Before deploying dashboard changes
- After modifying dashboard builder scripts
- Before committing dashboard code changes
Debugging Triggers:
- Dashboard shows "Entity not available"
- Cards fail to render or show error states
- Console shows JavaScript errors
- HACS card doesn't appear after installation
Usage
Use this skill to validate Home Assistant dashboards before deployment. Run the Quick Start workflow for a complete validation, or use individual tiers (pre-publish, post-publish, visual) for specific validation needs. Always run pre-publish validation first to catch config errors before they reach production.
The 3-Tier Validation Approach
Tier 1: Pre-Publish Validation (API-Based)
Validate configuration and entities BEFORE publishing to Home Assistant.
Config Structure Validation:
python
def validate_dashboard_config(config: dict) -> tuple[bool, list[str]]:
"""Validate dashboard configuration structure."""
errors = []
if "views" not in config:
errors.append("Missing required 'views' key")
return False, errors
if not isinstance(config["views"], list):
errors.append("'views' must be a list")
return False, errors
for idx, view in enumerate(config["views"]):
if "title" not in view:
errors.append(f"View {idx}: Missing required 'title'")
if "cards" in view and not isinstance(view["cards"], list):
errors.append(f"View {idx}: 'cards' must be a list")
return len(errors) == 0, errorsEntity Existence Check:
python
def verify_entities_exist(entity_ids: list[str]) -> dict[str, bool]:
"""Check if entities exist via REST API."""
url = "http://192.168.68.123:8123/api/states"
headers = {"Authorization": f"Bearer {os.environ['HA_LONG_LIVED_TOKEN']}"}
response = requests.get(url, headers=headers, timeout=10)
existing_entities = {state["entity_id"] for state in response.json()}
return {
entity_id: entity_id in existing_entities
for entity_id in entity_ids
}Extract All Entity IDs:
python
def extract_all_entity_ids(config: dict) -> list[str]:
"""Recursively extract all entity IDs from dashboard config."""
entity_ids = []
def extract_from_dict(d):
if isinstance(d, dict):
if "entity" in d and isinstance(d["entity"], str):
entity_ids.append(d["entity"])
if "entities" in d and isinstance(d["entities"], list):
for item in d["entities"]:
if isinstance(item, str):
entity_ids.append(item)
elif isinstance(item, dict) and "entity" in item:
entity_ids.append(item["entity"])
for value in d.values():
if isinstance(value, (dict, list)):
extract_from_dict(value)
elif isinstance(d, list):
for item in d:
extract_from_dict(item)
extract_from_dict(config)
return list(set(entity_ids))Why Pre-Publish Validation Matters:
- Catches config errors before they reach HA
- Prevents "Entity not available" errors in production
- Verifies HACS cards are installed
- Fast feedback loop (API calls only)
Tier 2: Post-Publish Verification (Log Analysis)
Monitor Home Assistant logs for errors after publishing dashboard changes.
Log Comparison Workflow:
bash
# 1. Capture baseline errors before change
curl -s "http://192.168.68.123:8123/api/error_log" \
-H "Authorization: Bearer $HA_LONG_LIVED_TOKEN" > pre-change-errors.log
# 2. Make dashboard changes via WebSocket/API
# 3. Wait for errors to propagate
sleep 5
# 4. Capture post-change errors
curl -s "http://192.168.68.123:8123/api/error_log" \
-H "Authorization: Bearer $HA_LONG_LIVED_TOKEN" > post-change-errors.log
# 5. Compare for new errors
diff pre-change-errors.log post-change-errors.logKey Error Patterns:
| Error Pattern | Meaning | Fix |
|---|---|---|
| HACS card not installed/loaded | Install via HACS, clear cache |
| Entity doesn't exist or offline | Check entity ID, verify device |
| Dashboard config syntax error | Check config structure |
| Card validation failed | Review card schema |
Why Log Analysis Matters:
- Detects runtime errors that pre-publish checks miss
- Catches integration-specific issues
- Provides detailed error messages for debugging
- Confirms changes didn't break existing functionality
Tier 3: Visual Validation (Browser Automation)
Use Chrome extension MCP tools to verify rendering and check browser console.
Browser Validation Workflow:
bash
# 1. Navigate to dashboard
mcp-cli call claude-in-chrome/navigate '{
"url": "http://192.168.68.123:8123/climate-dashboard"
}'
# 2. Wait for page load
sleep 2
# 3. Check console for JavaScript errors
mcp-cli call claude-in-chrome/read_console_messages '{}'
# 4. Take screenshot for visual verification
mcp-cli call claude-in-chrome/computer '{
"action": "screenshot"
}'
# 5. Read page content to verify cards rendered
mcp-cli call claude-in-chrome/read_page '{}'Console Error Interpretation:
| Console Error | Root Cause | Fix |
|---|---|---|
| HACS card not loaded | Hard refresh (Ctrl+Shift+R) |
| Entity ID mismatch | Check entity via API |
| Network/API connectivity | Check HA availability |
| JSON config syntax error | Validate JSON structure |
When to Use Visual Testing:
Always use for:
- Major dashboard restructuring
- New custom cards from HACS
- card_mod CSS customizations
- After updating HACS cards
Skip for:
- Simple entity ID changes
- Backend configuration
- Non-frontend changes
Why Visual Validation Matters:
- Catches rendering issues that API checks miss
- Verifies card styling and layout
- Confirms HACS cards loaded correctly
- Provides visual proof of correctness
Validation Workflows
Quick Validation (Minor Changes)
Fast validation for simple entity ID updates:
bash
#!/bin/bash
# quick_validate.sh
DASHBOARD="climate-dashboard"
# Rebuild dashboard
./run.sh dashboard_builder.py
# Check logs for errors
if curl -s "http://192.168.68.123:8123/api/error_log" \
-H "Authorization: Bearer $HA_LONG_LIVED_TOKEN" | \
grep -i "error.*lovelace"; then
echo "❌ Errors in logs"
exit 1
fi
# Quick browser check
mcp-cli call claude-in-chrome/navigate "{\"url\": \"http://192.168.68.123:8123/$DASHBOARD\"}" > /dev/null
sleep 2
mcp-cli call claude-in-chrome/read_console_messages '{}' | grep -q '"level": "error"'
if [ $? -eq 0 ]; then
echo "❌ Console errors detected"
exit 1
fi
echo "✅ Quick validation passed"Full Validation (Major Changes)
Comprehensive validation for major dashboard updates. See for the complete full validation script (full_validate.sh).
references/workflows.mdKey steps:
- Pre-publish validation (config + entities)
- Publish to production
- Check HA logs for new errors
- Automated browser validation
- Take screenshot for visual confirmation
Incremental Testing
Build complex dashboards section by section with validation:
python
def build_dashboard_incrementally():
"""Build dashboard section by section with validation."""
cards = []
# Section 1: Temperature
temp_cards = create_temperature_section()
test_partial_dashboard("test-temp", temp_cards)
cards.extend(temp_cards)
# Section 2: Humidity
humidity_cards = create_humidity_section()
test_partial_dashboard("test-humidity", cards + humidity_cards)
cards.extend(humidity_cards)
# Final publish
publish_dashboard("climate-dashboard", {
"views": [{"title": "Climate", "cards": cards}]
})Common Failure Modes
Configuration Errors
| Failure Mode | Detection | Fix |
|---|---|---|
| Missing entity ID | API entity check | Fix entity ID typo |
| Invalid card type | Console error | Check spelling, verify HACS |
| Malformed JSON | WebSocket error | Validate JSON syntax |
| Missing required field | Pre-publish validation | Add required field |
HACS Card Issues
| Failure Mode | Detection | Fix |
|---|---|---|
| Card not installed | Console, HACS check | Install via HACS |
| Card not loaded | Console, network tab | Hard refresh |
| Version incompatibility | Check versions | Update card or HA |
Entity Issues
| Failure Mode | Detection | Fix |
|---|---|---|
| Entity unavailable | API state check | Check device connection |
| Entity renamed | API 404 | Update entity ID |
| Entity removed | Pre-publish check | Remove/update card |
Supporting Files
references/validation-reference.md
Comprehensive reference documentation including:
- REST API endpoint reference (full request/response examples)
- WebSocket API command reference (auth flow, dashboard operations)
- MCP Chrome extension tool details (all available tools)
- Complete validation function implementations
- Entity state validation patterns
- Log analysis techniques and Python helpers
When to read: Need API details, complete code examples, or advanced validation patterns.
references/workflows.md
Detailed workflow documentation including:
- Pre-commit validation checklist
- Rollback strategy and procedures (backup/restore)
- Complete end-to-end deployment workflow
- CI/CD integration patterns (GitHub Actions, pre-commit hooks)
- Automated testing scripts (validate_all.py, check_entities.py)
When to read: Setting up automation, implementing CI/CD, or need complete deployment scripts.
Integration with Project
This skill integrates with the Home Assistant dashboard management workflow:
Integration Points:
-
Dashboard Builder Scripts ()
dashboard_builder.py- Add validation calls before publishing
- Use wrapper
publish_dashboard_safely()
-
Card Utilities ()
ha_card_utils.py- Validation helpers can be added here
- Keep utilities project-specific
-
Chrome Extension (MCP tools)
- Use for visual validation
- Check console errors, take screenshots
-
CLAUDE.md Documentation
- Update validation checklist
- Document validation commands
Example Integration:
python
# In dashboard_builder.py
from validation_helpers import validate_dashboard_config, verify_entities_exist
def build_climate_dashboard():
"""Build climate dashboard with validation."""
cards = create_climate_cards()
config = {"views": [{"title": "Climate", "cards": cards}]}
# Validate before publish
is_valid, errors = validate_dashboard_config(config)
if not is_valid:
print("❌ Validation failed:", errors)
return False
# Verify entities
entities = extract_all_entity_ids(config)
existence = verify_entities_exist(entities)
missing = [e for e, exists in existence.items() if not exists]
if missing:
print("❌ Missing entities:", missing)
return False
# Safe publish
success, msg = publish_dashboard_safely("climate-dashboard", config)
return successRequirements
Environment
- Home Assistant 2025.12.3+ (WebSocket/REST API)
- Python 3.11+ (validation scripts)
- Chrome browser with Claude extension (visual testing)
- MCP CLI installed and configured
Dependencies
bash
pip install requests websocket-client
export HA_LONG_LIVED_TOKEN="your-token"Knowledge Required
- Basic Python programming
- Home Assistant entity ID format
- Dashboard config structure (views, cards)
- curl and bash scripting basics
Red Flags to Avoid
- Skipping pre-publish validation - Always validate BEFORE deploying
- Ignoring entity existence checks - Missing entities cause runtime errors
- Not checking HACS cards - Custom cards must be installed first
- Skipping log analysis - New errors won't be detected
- Publishing without backup - Always save current config before changes
- Ignoring console errors - Browser console shows critical rendering issues
- Testing only in code - Visual validation catches real rendering problems
- Not using incremental testing - Build dashboards section by section
- Publishing to production first - Test on test-dashboard first
- Ignoring rollback strategy - Know how to revert if deployment fails
Notes
- Integration Priority: Pre-publish validation is most critical - it prevents bad configs from reaching HA
- Visual Testing Cost: Browser automation is slower but catches rendering issues that API checks miss
- Log Monitoring: Post-publish log checks detect issues that only appear at runtime
- Incremental Testing: Build complex dashboards section by section to isolate issues quickly
- Rollback Safety: Always capture current config before making changes for easy rollback