ha-validate-dashboards

What this skill does

# 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

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

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

**Entity 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.log
```

**Key Error Patterns:**

| Error Pattern | Meaning | Fix |
|---------------|---------|-----|
| `Custom element doesn't exist: custom:*-card` | HACS card not installed/loaded | Install via HACS, clear cache |
| `Entity not available: sensor.*` | Entity doesn't exist or offline | Check entity ID, verify device |
| `Error while loading page lovelace` | Dashboard config syntax error | Check config structure |
| `Invalid configuration for card` | 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 |
|---------------|------------|-----|
| `Custom element doesn't exist: custom:*` | HACS card not loaded | Hard refresh (Ctrl+Shift+R) |
| `Uncaught TypeError: Cannot read property 'state'` | Entity ID mismatch | Check entity via API |
| `Failed to fetch` | Network/API connectivity | Check HA availability |
| `SyntaxError: Unexpected token` | 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