advanced-camera-card/tests/browser/fake-hass.ts

import {
  STATE_RUNNING,
  type Connection,
  type HassConfig,
  type HassEntities,
  type HassEntity,
  type MessageBase,
} from 'home-assistant-js-websocket';
import { mock } from 'vitest-mock-extended';

import type { Entity } from '../../src/ha/registry/entity/types';
import type { HomeAssistant } from '../../src/ha/types';
import { createRegistryEntity, createStateEntity } from '../test-utils';

// A WebSocket command handler. Returning a rejected promise models a command
// Home Assistant refuses; throwing models a malformed request.
export type WSCommandHandler = (message: MessageBase) => Promise<unknown> | unknown;

export interface FakeEntityOptions {
  state?: string;
  attributes?: Record<string, unknown>;
  lastChanged?: Date;
  lastUpdated?: Date;
}

export interface FakeHASSOptions {
  // Entities present from the start, as entity ID to state options (or a
  // bare state string).
  entities?: Record<string, FakeEntityOptions | string>;

  // Entity registry entries, as entity ID to a partial registry entry.
  registry?: Record<string, Partial<Entity>>;

  language?: string;
  isAdmin?: boolean;
}

// Home Assistant sends real timestamps, and the card measures a state's age
// against them: must use a dynamic (vs static) date.
const createDefaultTime = (): Date => new Date();

// `Auth` is a class built from real credentials, and `locale` is typed with
// ambient enums that have no runtime value, so neither can be constructed here.
// The card reads neither.
const { auth: INERT_AUTH, locale: INERT_LOCALE } = mock<HomeAssistant>();

const createConfig = (state: HassConfig['state']): HassConfig => ({
  latitude: 0,
  longitude: 0,
  elevation: 0,
  radius: 0,
  unit_system: {
    length: 'km',
    mass: 'kg',
    volume: 'L',
    temperature: '°C',
    pressure: 'Pa',
    wind_speed: 'km/h',
    accumulated_precipitation: 'mm',
  },
  location_name: 'Fake',
  time_zone: 'UTC',
  components: [],
  config_dir: '/config',
  allowlist_external_dirs: [],
  allowlist_external_urls: [],
  version: '2026.7.0',
  config_source: 'storage',
  recovery_mode: false,
  safe_mode: false,
  state,
  external_url: null,
  internal_url: null,
  currency: 'USD',
  country: null,
  language: 'en',
});

const createRegistryEntry = (entityID: string, overrides?: Partial<Entity>): Entity =>
  createRegistryEntity({ entity_id: entityID, unique_id: entityID, ...overrides });

/**
 * A driveable stand-in for the `hass` object the card is handed by Home
 * Assistant.
 *
 * Home Assistant updates immutably, and that is the behaviour reproduced here:
 * a change hands consumers a new top-level object and a new `states` map
 * holding a new state object for the entity that changed, while every other
 * entity keeps the object it already had. Anything the card can observe about
 * a real `hass` it must be able to observe about this one, so a divergence here
 * is a bug in the fake rather than a shortcut worth taking.
 */
export class FakeHASS {
  private _hass: HomeAssistant;
  private _states: HassEntities = {};
  private _registry = new Map<string, Entity>();
  private _config: HassConfig = createConfig(STATE_RUNNING);
  private _connected = true;
  private _connection: Connection;
  private _language: string;
  private _isAdmin: boolean;
  private _handlers = new Map<string, WSCommandHandler>();
  private _commandLog: MessageBase[] = [];

  constructor(options?: FakeHASSOptions) {
    this._language = options?.language ?? 'en';
    this._isAdmin = options?.isAdmin ?? true;

    for (const [entityID, entityOptions] of Object.entries(options?.entities ?? {})) {
      this._states[entityID] = this._createEntity(entityID, entityOptions);
    }
    for (const [entityID, entry] of Object.entries(options?.registry ?? {})) {
      this._registry.set(entityID, createRegistryEntry(entityID, entry));
    }

    this._connection = this._createConnection();
    this._registerDefaultHandlers();
    this._hass = this._createHASS();
  }

  public getHASS(): HomeAssistant {
    return this._hass;
  }

  /**
   * Register a handler for a WebSocket command, replacing any existing one.
   */
  public registerCommand(type: string, handler: WSCommandHandler): void {
    this._handlers.set(type, handler);
  }

  /**
   * Every WebSocket command the card has issued, in order.
   */
  public getCommandLog(): readonly MessageBase[] {
    return this._commandLog;
  }

  /**
   * Change one entity, then renew. The changed entity gets a new state object;
   * every other entity keeps the one it already had.
   */
  public setState(entityID: string, options: FakeEntityOptions | string): void {
    this._states = {
      ...this._states,
      [entityID]: this._createEntity(entityID, options),
    };
    this._renew();
  }

  /**
   * Remove an entity from the state map, as happens when its integration is
   * unloaded.
   */
  public removeState(entityID: string): void {
    const states = { ...this._states };
    delete states[entityID];
    this._states = states;
    this._renew();
  }

  /**
   * Replace the `hass` object without changing any entity, as Home Assistant
   * does constantly. Every entity keeps its identity, so a card that re-does
   * work after this is reacting to the object rather than to what is in it.
   */
  public renew(): void {
    this._renew();
  }

  /**
   * Drop or restore the WebSocket, as a Home Assistant restart does. Home
   * Assistant keeps handing the card a `hass` while it is disconnected, which
   * is why this renews rather than going silent.
   */
  public setConnected(connected: boolean): void {
    this._connected = connected;
    this._renew();
  }

  private _createEntity(
    entityID: string,
    options: FakeEntityOptions | string,
  ): HassEntity {
    const resolved: FakeEntityOptions =
      typeof options === 'string' ? { state: options } : options;

    return createStateEntity({
      entity_id: entityID,
      state: resolved.state ?? 'unknown',
      attributes: resolved.attributes ?? {},
      last_changed: (resolved.lastChanged ?? createDefaultTime()).toISOString(),
      last_updated: (resolved.lastUpdated ?? createDefaultTime()).toISOString(),
      context: { id: entityID, user_id: null, parent_id: null },
    });
  }

  private _renew(): void {
    this._hass = this._createHASS();
  }

  private _createConnection(): Connection {
    const connection = mock<Connection>();
    connection.subscribeMessage.mockResolvedValue(() => Promise.resolve());
    connection.subscribeEvents.mockResolvedValue(() => Promise.resolve());

    // `callWS` and `sendMessagePromise` are the same request/response channel,
    // so both go through one handler table. Given two tables, a command
    // registered by a test would be silently ignored for any caller that
    // reached the connection directly.
    connection.sendMessagePromise.mockImplementation((message) => this._callWS(message));
    return connection;
  }

  private _registerDefaultHandlers(): void {
    this.registerCommand('config/entity_registry/get', (message) => {
      const entry = this._registry.get(String(message.entity_id));
      if (!entry) {
        return Promise.reject(
          new Error(`Entity not found in the fake registry: ${message.entity_id}`),
        );
      }
      return entry;
    });
    this.registerCommand('config/entity_registry/list', () => [
      ...this._registry.values(),
    ]);
    this.registerCommand('lovelace/resources', () => []);

    // Not a card command: `ha-nunjucks` fetches the label registry once when a
    // template first renders.
    this.registerCommand('config/label_registry/list', () => []);
  }

  private async _callWS<T>(message: MessageBase): Promise<T> {
    this._commandLog.push(message);
    const handler = this._handlers.get(message.type);
    if (!handler) {
      // Loudly, because a card that starts issuing a new command must not
      // appear to work against a fake that knows nothing about it.
      throw new Error(`FakeHASS received an unregistered WS command: ${message.type}`);
    }

    // A WebSocket response is untyped on the wire, and the caller's generic is
    // its claim about the shape. Callers parse what they get with Zod, so a
    // handler returning the wrong shape surfaces there.
    return (await handler(message)) as unknown as T;
  }

  private _unsupported(name: string): () => never {
    return () => {
      throw new Error(`FakeHASS does not implement ${name}`);
    };
  }

  private _createHASS(): HomeAssistant {
    return {
      auth: INERT_AUTH,
      locale: INERT_LOCALE,

      states: this._states,
      config: this._config,
      connected: this._connected,
      connection: this._connection,
      language: this._language,
      selectedLanguage: null,
      selectedTheme: null,
      resources: {},
      services: {},
      themes: {
        default_theme: 'default',
        themes: {},
      },
      panels: {},
      panelUrl: 'lovelace',
      translationMetadata: { fragments: [], translations: {} },
      dockedSidebar: false,
      moreInfoEntityId: '',
      user: {
        id: 'fake-user',
        is_owner: this._isAdmin,
        is_admin: this._isAdmin,
        name: 'Fake User',
        credentials: [],
        mfa_modules: [],
      },

      callWS: (message) => this._callWS(message),
      hassUrl: (path?: string) => new URL(path ?? '/', window.location.href).href,
      localize: (key: string) => key,

      // Everything the card can call has to either work or fail loudly. A
      // method that quietly returns nothing would let a card start depending on
      // it without any test noticing.
      callService: this._unsupported('callService'),
      callApi: this._unsupported('callApi'),
      fetchWithAuth: this._unsupported('fetchWithAuth'),
      sendWS: this._unsupported('sendWS'),
    };
  }
}