@digital-alchemy/hass 24.9.3 → 24.9.5

package/src/testing/ref-by.spec.ts

@@ -0,0 +1,300 @@
+import dayjs from "dayjs";
+
+import { ANY_ENTITY, ENTITY_STATE } from "../helpers";
+import { hassTestRunner } from "../mock_assistant";
+
+describe("References", () => {
+  afterEach(async () => {
+    await hassTestRunner.teardown();
+    jest.restoreAllMocks();
+  });
+
+  describe("loading", function () {
+    describe("refBy.id", () => {
+      it("can grab references by id", async () => {
+        expect.assertions(2);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          lifecycle.onReady(() => {
+            const sensor = hass.refBy.id("sensor.magic");
+            expect(sensor).toBeDefined();
+            expect(sensor.state).toBe("unavailable");
+          });
+        });
+      });
+    });
+
+    describe("domain", () => {
+      it("load references by domain", async () => {
+        expect.assertions(1);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          lifecycle.onReady(() => {
+            const sensor = hass.refBy.domain("sensor");
+            expect(sensor.length).toBe(8);
+          });
+        });
+      });
+    });
+
+    describe("unique_id", () => {
+      it("load references by unique_id", async () => {
+        expect.assertions(1);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          lifecycle.onReady(() => {
+            const sensor = hass.refBy.unique_id(
+              "e1806fdc93296bbd5ab42967003cd38729ff9ba6cfeefc3e15a03ad01ac894fe",
+            );
+            expect(sensor?.entity_id).toBe("sensor.magic");
+          });
+        });
+      });
+    });
+
+    describe("label", () => {
+      it("load references by label", async () => {
+        expect.assertions(1);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          lifecycle.onReady(() => {
+            const list = hass.refBy.label("synapse");
+            expect(list.length).toBe(7);
+          });
+        });
+      });
+
+      it("load references by label limiting by domain", async () => {
+        expect.assertions(1);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          lifecycle.onReady(() => {
+            const list = hass.refBy.label("synapse", "light");
+            expect(list.length).toBe(0);
+          });
+        });
+      });
+    });
+
+    describe("area", () => {
+      it("load references by area", async () => {
+        expect.assertions(2);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          lifecycle.onReady(() => {
+            const bedroom = hass.refBy.area("bedroom");
+            const kitchen = hass.refBy.area("kitchen");
+            expect(bedroom.length).toBe(2);
+            expect(kitchen.length).toBe(1);
+          });
+        });
+      });
+
+      it("load references by area limiting by domain", async () => {
+        expect.assertions(2);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          lifecycle.onReady(() => {
+            const bedroom = hass.refBy.area("bedroom", "light");
+            const kitchen = hass.refBy.area("kitchen", "light");
+            expect(bedroom.length).toBe(1);
+            expect(kitchen.length).toBe(0);
+          });
+        });
+      });
+    });
+
+    describe("device", () => {
+      it("load references by device", async () => {
+        expect.assertions(1);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          lifecycle.onReady(() => {
+            const synapse = hass.refBy.device("308e39cf50a9fc6c30b4110724ed1f2e");
+            expect(synapse.length).toBe(9);
+          });
+        });
+      });
+
+      it("load references by device limiting by domain", async () => {
+        expect.assertions(1);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          lifecycle.onReady(() => {
+            const synapse = hass.refBy.device("308e39cf50a9fc6c30b4110724ed1f2e", "light");
+            expect(synapse.length).toBe(0);
+          });
+        });
+      });
+    });
+
+    describe("platform", () => {
+      it("load references by platform", async () => {
+        expect.assertions(1);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          lifecycle.onReady(() => {
+            const synapse = hass.refBy.platform("synapse");
+            expect(synapse.length).toBe(7);
+          });
+        });
+      });
+
+      it("load references by platform limiting by domain", async () => {
+        expect.assertions(1);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          lifecycle.onReady(() => {
+            const synapse = hass.refBy.platform("synapse", "light");
+            expect(synapse.length).toBe(0);
+          });
+        });
+      });
+    });
+
+    describe("floor", () => {
+      it("load references by floor", async () => {
+        expect.assertions(1);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          lifecycle.onReady(() => {
+            const synapse = hass.refBy.floor("downstairs");
+            expect(synapse.length).toBe(3);
+          });
+        });
+      });
+
+      it("load references by floor limiting by domain", async () => {
+        expect.assertions(1);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          lifecycle.onReady(() => {
+            const synapse = hass.refBy.floor("downstairs", "light");
+            expect(synapse.length).toBe(0);
+          });
+        });
+      });
+    });
+  });
+
+  describe("functionality", () => {
+    describe("operators", () => {
+      it("has", async () => {
+        expect.assertions(15);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          lifecycle.onReady(() => {
+            const entity = hass.refBy.id("switch.bedroom_lamp");
+            // always there stuff
+            expect("does not exist" in entity).toBe(false);
+            [
+              "attributes",
+              "entity_id",
+              "history",
+              "last",
+              "nextState",
+              "once",
+              "onUpdate",
+              "previous",
+              "removeAllListeners",
+              "state",
+              "waitForState",
+            ].forEach(property => expect(property in entity).toBe(true));
+            // service calls exist too
+            ["toggle", "turn_off", "turn_on"].forEach(method =>
+              expect(method in entity).toBe(true),
+            );
+          });
+        });
+      });
+
+      it("ownKeys", async () => {
+        expect.assertions(1);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          lifecycle.onReady(() => {
+            const entity = hass.refBy.id("switch.bedroom_lamp");
+            const keys = Object.keys(entity);
+            // note: each section sorted alphabetically
+            expect(keys).toEqual([
+              // hard coded
+              "entity_id",
+              "state",
+              "attributes",
+              "last_changed",
+              "last_reported",
+              "last_updated",
+              "context",
+              "history",
+              "last",
+              "nextState",
+              "once",
+              "onUpdate",
+              "previous",
+              "removeAllListeners",
+              "waitForState",
+              // services
+              "toggle",
+              "turn_off",
+              "turn_on",
+            ]);
+          });
+        });
+      });
+      describe("set", () => {
+        it("state", () => {
+          // stub
+        });
+        it("attributes", () => {
+          // stub
+        });
+        it("everything else", () => {
+          // stub
+        });
+      });
+    });
+
+    describe("get", () => {
+      it("references have attributes", async () => {
+        expect.assertions(2);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          lifecycle.onReady(() => {
+            const sensor = hass.refBy.id("sensor.magic");
+            expect("attributes" in sensor).toBe(true);
+            expect(sensor.attributes).toEqual(expect.objectContaining({ friendly_name: "magic" }));
+          });
+        });
+      });
+
+      // mental note: legacy test
+      // better covered by the ownKeys & has operator tests now
+      it("references do not return random attributes", async () => {
+        expect.assertions(1);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          lifecycle.onReady(() => {
+            const sensor = hass.refBy.id("sensor.magic");
+            // @ts-expect-error it's the test
+            expect(sensor.foo).toBeUndefined();
+          });
+        });
+      });
+
+      it("references provide last_* as dayjs", async () => {
+        expect.assertions(3);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          lifecycle.onReady(() => {
+            const sensor = hass.refBy.id("sensor.magic");
+            expect(sensor.last_changed instanceof dayjs).toBe(true);
+            expect(sensor.last_reported instanceof dayjs).toBe(true);
+            expect(sensor.last_updated instanceof dayjs).toBe(true);
+          });
+        });
+      });
+
+      it("passes through history calls", async () => {
+        expect.assertions(2);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          lifecycle.onReady(async () => {
+            const result = [] as ENTITY_STATE<ANY_ENTITY>[];
+            const spy = jest
+              .spyOn(hass.fetch, "fetchEntityHistory")
+              .mockImplementation(async () => result);
+            const from = new Date();
+            const to = new Date();
+            const entity_id = "sensor.magic";
+
+            const entity = hass.refBy.id(entity_id);
+            const out = await entity.history(from, to);
+            expect(spy).toHaveBeenCalledWith(entity_id, from, to);
+            expect(out).toBe(result);
+          });
+        });
+      });
+    });
+  });
+});

package/src/testing/websocket.spec.ts

@@ -0,0 +1,63 @@
+import { hassTestRunner } from "../mock_assistant";
+
+describe("Websocket", () => {
+  afterEach(async () => {
+    await hassTestRunner.teardown();
+    jest.restoreAllMocks();
+  });
+
+  describe("API Interactions", () => {
+    it("should emit events onConnect", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        let hit = false;
+        hass.socket.onConnect(() => (hit = true));
+        lifecycle.onReady(() => {
+          expect(hit).toBe(true);
+        });
+      });
+    });
+
+    it("should emit a socket message with subscribeEvents", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass, context }) => {
+        const spy = jest
+          .spyOn(hass.socket, "sendMessage")
+          .mockImplementation(async () => undefined);
+        lifecycle.onReady(async () => {
+          await hass.socket.subscribe({
+            context,
+            event_type: "test",
+            exec: () => {},
+          });
+          expect(spy).toHaveBeenCalledWith(
+            expect.objectContaining({
+              event_type: "test",
+              type: "subscribe_events",
+            }),
+          );
+        });
+      });
+    });
+
+    it("should emit a socket message with fireEvent", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        const spy = jest
+          .spyOn(hass.socket, "sendMessage")
+          .mockImplementation(async () => undefined);
+        lifecycle.onReady(async () => {
+          const data = { example: "data" };
+          await hass.socket.fireEvent("test_event", data);
+          expect(spy).toHaveBeenCalledWith(
+            expect.objectContaining({
+              event_data: data,
+              event_type: "test_event",
+              type: "fire_event",
+            }),
+          );
+        });
+      });
+    });
+  });
+});

package/src/testing/workflow.spec.ts

@@ -0,0 +1,195 @@
+import { CronExpression, SECOND, sleep } from "@digital-alchemy/core";
+import dayjs from "dayjs";
+
+import { hassTestRunner } from "../mock_assistant";
+
+describe("Workflows", () => {
+  beforeAll(() => {
+    hassTestRunner.appendService(({ hass, scheduler }) => {
+      scheduler.cron({
+        async exec() {
+          await hass.call.switch.turn_on({
+            entity_id: "switch.bedroom_lamp",
+          });
+        },
+        schedule: CronExpression.EVERY_DAY_AT_8PM,
+      });
+
+      const entity = hass.refBy.id("sensor.magic");
+      entity.onUpdate(async () => {
+        const action = entity.state === "test" ? "turn_on" : "turn_off";
+        await hass.call.switch[action]({
+          entity_id: "switch.porch_light",
+        });
+      });
+
+      entity.onUpdate(async (new_state, old_state) => {
+        if (old_state.state === "away" && new_state.state === "here") {
+          await hass.call.switch.turn_on({
+            entity_id: "switch.living_room_mood_lights",
+          });
+        }
+      });
+    });
+  });
+
+  afterEach(async () => {
+    await hassTestRunner.teardown();
+    jest.restoreAllMocks();
+  });
+
+  describe("Event and Response", () => {
+    it("should be able to trigger a workflow", async () => {
+      expect.assertions(2);
+      await hassTestRunner.run(({ mock_assistant, hass, lifecycle }) => {
+        lifecycle.onReady(async () => {
+          const turnOn = jest.spyOn(hass.call.switch, "turn_on");
+          const turnOff = jest.spyOn(hass.call.switch, "turn_off");
+          await mock_assistant.events.emitEntityUpdate("sensor.magic", {
+            state: "test",
+          });
+          await mock_assistant.events.emitEntityUpdate("sensor.magic", {
+            state: "foo",
+          });
+          expect(turnOn).toHaveBeenCalledTimes(1);
+          expect(turnOff).toHaveBeenCalledTimes(1);
+        });
+      });
+    });
+
+    it("should be able to trigger a from an initial state", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ mock_assistant, hass, lifecycle }) => {
+        mock_assistant.fixtures.setState({
+          "sensor.magic": {
+            state: "away",
+          },
+        });
+        lifecycle.onReady(async () => {
+          const turnOn = jest.spyOn(hass.call.switch, "turn_on");
+          await mock_assistant.events.emitEntityUpdate("sensor.magic", {
+            state: "here",
+          });
+          await sleep(1);
+          expect(turnOn).toHaveBeenCalledWith({
+            entity_id: "switch.living_room_mood_lights",
+          });
+        });
+      });
+    });
+
+    it("should not trigger a from an invalid initial state", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ mock_assistant, hass, lifecycle }) => {
+        mock_assistant.fixtures.setState({
+          "sensor.magic": {
+            state: "mars",
+          },
+        });
+        lifecycle.onReady(async () => {
+          const turnOn = jest.spyOn(hass.call.switch, "turn_on");
+          await mock_assistant.events.emitEntityUpdate("sensor.magic", {
+            state: "here",
+          });
+          expect(turnOn).not.toHaveBeenCalledWith({
+            entity_id: "switch.living_room_mood_lights",
+          });
+        });
+      });
+    });
+  });
+
+  describe("Timers", () => {
+    beforeEach(() => {
+      jest.useFakeTimers();
+    });
+
+    afterEach(() => {
+      jest.useRealTimers();
+    });
+
+    it("should run at 3PM", async () => {
+      expect.assertions(1);
+      jest.setSystemTime(dayjs("2024-01-01 19:59:59").toDate());
+      jest.runOnlyPendingTimersAsync();
+      await hassTestRunner.run(({ hass, lifecycle }) => {
+        lifecycle.onReady(() => {
+          const turnOn = jest.spyOn(hass.call.switch, "turn_on");
+          jest.advanceTimersByTime(2 * SECOND);
+          expect(turnOn).toHaveBeenCalledWith({
+            entity_id: "switch.bedroom_lamp",
+          });
+        });
+      });
+    });
+  });
+
+  describe("Call", () => {
+    const EXPECTED_KEYS = [
+      "persistent_notification",
+      "homeassistant",
+      "system_log",
+      "logger",
+      "recorder",
+      "person",
+      "frontend",
+      "cloud",
+      "ffmpeg",
+      "tts",
+      "scene",
+      "timer",
+      "input_number",
+      "conversation",
+      "input_select",
+      "zone",
+      "input_button",
+      "script",
+      "automation",
+      "logbook",
+      "input_boolean",
+      "button",
+      "switch",
+      "input_datetime",
+      "backup",
+      "shopping_list",
+      "counter",
+      "schedule",
+      "input_text",
+      "synapse",
+      "todo",
+      "notify",
+      "calendar",
+    ];
+    it("does not allow set", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ hass }) => {
+        try {
+          // @ts-expect-error testing
+          hass.call.button = {};
+        } catch (error) {
+          expect(error).toBeDefined();
+        }
+      });
+    });
+
+    it("provides keys via ownKeys", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ hass, lifecycle }) => {
+        lifecycle.onReady(() => {
+          const keys = Object.keys(hass.call);
+          expect(keys).toEqual(EXPECTED_KEYS);
+        });
+      });
+    });
+
+    it("does has correctly", async () => {
+      expect.assertions(34);
+      await hassTestRunner.run(({ hass, lifecycle }) => {
+        lifecycle.onReady(() => {
+          EXPECTED_KEYS.forEach(i => expect(i in hass.call).toBe(true));
+          expect("unknown_property" in hass.call).toBe(false);
+        });
+      });
+    });
+  });
+});

package/src/testing/zone.spec.ts

@@ -0,0 +1,109 @@
+import { sleep } from "@digital-alchemy/core";
+
+import { ZONE_REGISTRY_UPDATED, ZoneDetails } from "../helpers";
+import { hassTestRunner } from "../mock_assistant";
+
+describe("Zone", () => {
+  afterEach(async () => {
+    await hassTestRunner.teardown();
+    jest.restoreAllMocks();
+  });
+
+  const EXAMPLE_ZONE = {
+    icon: "",
+    latitude: 0,
+    longitude: 0,
+    name: "Test",
+    passive: true,
+  } as ZoneDetails;
+
+  describe("Lifecycle", () => {
+    it("should force values to be available before ready", async () => {
+      expect.assertions(1);
+      await hassTestRunner.run(({ lifecycle, hass }) => {
+        const spy = jest
+          .spyOn(hass.socket, "sendMessage")
+          .mockImplementation(async () => [EXAMPLE_ZONE]);
+        lifecycle.onReady(async () => {
+          await hass.zone.list();
+          expect(spy).toHaveBeenCalledWith(expect.objectContaining({ type: "zone/list" }));
+        });
+      });
+    });
+  });
+
+  describe("API", () => {
+    describe("Formatting", () => {
+      it("should call list properly", async () => {
+        expect.assertions(1);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          const spy = jest.spyOn(hass.socket, "sendMessage").mockImplementation(async () => []);
+          lifecycle.onReady(async () => {
+            await hass.zone.list();
+            expect(spy).toHaveBeenCalledWith(expect.objectContaining({ type: "zone/list" }));
+          });
+        });
+      });
+
+      it("should call create properly", async () => {
+        expect.assertions(1);
+        await hassTestRunner.run(({ lifecycle, hass, event }) => {
+          const spy = jest
+            .spyOn(hass.socket, "sendMessage")
+            .mockImplementation(async () => undefined);
+          lifecycle.onReady(async () => {
+            setImmediate(() => event.emit(ZONE_REGISTRY_UPDATED));
+            await hass.zone.create(EXAMPLE_ZONE);
+
+            expect(spy).toHaveBeenCalledWith({
+              type: "zone/create",
+              ...EXAMPLE_ZONE,
+            });
+          });
+        });
+      });
+    });
+
+    describe("Order of operations", () => {
+      it("should debounce updates properly", async () => {
+        expect.assertions(1);
+        await hassTestRunner.run(({ lifecycle, hass }) => {
+          jest.spyOn(hass.socket, "sendMessage").mockImplementation(async () => undefined);
+          let counter = 0;
+          hass.events.onZoneRegistryUpdate(() => counter++);
+          lifecycle.onReady(async () => {
+            setImmediate(async () => {
+              hass.socket.socketEvents.emit("zone_registry_updated");
+              await sleep(5);
+              hass.socket.socketEvents.emit("zone_registry_updated");
+              await sleep(5);
+              hass.socket.socketEvents.emit("zone_registry_updated");
+              await sleep(75);
+              hass.socket.socketEvents.emit("zone_registry_updated");
+            });
+            await sleep(200);
+            expect(counter).toBe(2);
+          });
+        });
+      });
+
+      it("should wait for an update before returning when creating", async () => {
+        expect.assertions(1);
+        await hassTestRunner.run(({ lifecycle, hass, event }) => {
+          jest.spyOn(hass.socket, "sendMessage").mockImplementation(async () => undefined);
+          lifecycle.onReady(async () => {
+            const response = hass.zone.create(EXAMPLE_ZONE);
+            let order = "";
+            setTimeout(() => {
+              order += "a";
+              event.emit(ZONE_REGISTRY_UPDATED);
+            }, 5);
+            await response;
+            order += "b";
+            expect(order).toEqual("ab");
+          });
+        });
+      });
+    });
+  });
+});

package/dist/helpers/metrics.helper.d.ts

@@ -1,29 +0,0 @@
-import { Counter, Gauge, Summary } from "prom-client";
-/**
- * Tracks the number of times a socket event callback has been executed.
- */
-export declare const SOCKET_EVENT_EXECUTION_COUNT: Counter<"event" | "context" | "label">;
-/**
- * Counts the number of errors occurred during socket event callback executions.
- */
-export declare const SOCKET_EVENT_ERRORS: Counter<"event" | "context" | "label">;
-/**
- * Counts the number of errors occurred during socket event callback executions.
- */
-export declare const SOCKET_SENT_MESSAGES: Counter<"type">;
-/**
- * Counts the number of errors occurred during socket event callback executions.
- */
-export declare const SOCKET_RECEIVED_MESSAGES: Counter<"type">;
-/**
- * Summary for Execution Time
- */
-export declare const SOCKET_EVENT_EXECUTION_TIME: Summary<"event" | "context" | "label">;
-/**
- * Show the current state
- */
-export declare const SOCKET_CONNECTION_STATE: Gauge<"state">;
-/**
- * Counter for service calls made through the call proxy
- */
-export declare const CALL_PROXY_SERVICE_CALL: Counter<"service" | "domain">;