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:

# 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

1. When to Use This Skill
2. The 3-Tier Validation Approach
3. Validation Workflows
4. Common Failure Modes
5. Supporting Files
6. Integration with Project
7. Requirements
8. 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:

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, errors

Entity Existence Check:

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:

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:

# 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.log

Key Error Patterns:

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:

# 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:

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:

#!/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 references/workflows.md for the complete full validation script (full_validate.sh).

Key steps:

1. Pre-publish validation (config + entities)
2. Publish to production
3. Check HA logs for new errors
4. Automated browser validation
5. Take screenshot for visual confirmation

Incremental Testing

Build complex dashboards section by section with validation:

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

HACS Card Issues

Entity Issues

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:

1. Dashboard Builder Scripts (dashboard_builder.py)

   • Add validation calls before publishing
   • Use publish_dashboard_safely() wrapper

2. Card Utilities (ha_card_utils.py)

   • Validation helpers can be added here
   • Keep utilities project-specific

3. Chrome Extension (MCP tools)

   • Use for visual validation
   • Check console errors, take screenshots

4. CLAUDE.md Documentation

   • Update validation checklist
   • Document validation commands

Example Integration:

# 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 success

Requirements

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

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