@digital-alchemy/hass 24.9.4 → 24.10.1

package/src/mock_assistant/mock-assistant.module.ts

@@ -0,0 +1,90 @@
+import { CreateLibrary, createModule, SINGLE } from "@digital-alchemy/core";
+import { join } from "path";
+import { cwd } from "process";
+
+import { LIB_HASS } from "..";
+import {
+  MockAreaExtension,
+  MockConfig,
+  MockDeviceExtension,
+  MockEntityExtension,
+  MockEntityRegistryExtension,
+  MockEvents,
+  MockFixtures,
+  MockFloorExtension,
+  MockLabelExtension,
+  MockServices,
+  MockWebsocketAPI,
+  MockZoneExtension,
+} from "./extensions";
+
+export const LIB_MOCK_ASSISTANT = CreateLibrary({
+  configuration: {
+    EMIT_SLEEP: {
+      default: SINGLE,
+      description: "Time in ms to wait after emitting entity update events",
+      type: "number",
+    },
+    FIXTURES_FILE: {
+      default: join(cwd(), "fixtures.json"),
+      description: [],
+      type: "string",
+    },
+    PASS_AUTH: {
+      default: true,
+      description: "Auto pass for auth challenges",
+      type: "boolean",
+    },
+  },
+  depends: [LIB_HASS],
+  name: "mock_assistant",
+  priorityInit: [
+    "socket",
+    "floor",
+    "device",
+    "area",
+    "label",
+    "config",
+    "entity",
+    "entity_registry",
+    "services",
+    "fixtures",
+  ],
+  services: {
+    area: MockAreaExtension,
+    config: MockConfig,
+    device: MockDeviceExtension,
+    entity: MockEntityExtension,
+    entity_registry: MockEntityRegistryExtension,
+    events: MockEvents,
+    fixtures: MockFixtures,
+    floor: MockFloorExtension,
+    label: MockLabelExtension,
+    services: MockServices,
+    socket: MockWebsocketAPI,
+    zone: MockZoneExtension,
+  },
+});
+
+declare module "@digital-alchemy/core" {
+  export interface LoadedModules {
+    mock_assistant: typeof LIB_MOCK_ASSISTANT;
+  }
+}
+
+/**
+ * @internal
+ *
+ * Make your own
+ */
+export const createTestRunner = () =>
+  createModule
+    .fromLibrary(LIB_HASS)
+    .extend()
+    .toTest()
+    .configure({
+      boilerplate: { IS_TEST: true },
+    })
+    .appendLibrary(LIB_MOCK_ASSISTANT);
+
+export const hassTestRunner = createTestRunner();

package/src/quickboot.module.ts

@@ -0,0 +1,23 @@
+import { CreateApplication, TServiceParams } from "@digital-alchemy/core";
+
+import { LIB_HASS } from ".";
+
+/**
+ * Use from the node command line to probe apis
+ * Not for normal application usage
+ */
+export async function QuickBoot(name: string) {
+  let out: TServiceParams;
+  const app = CreateApplication({
+    libraries: [LIB_HASS],
+    // @ts-expect-error fake app, name used for loading credentials
+    name,
+    services: {
+      Loader(params: TServiceParams) {
+        out = params;
+      },
+    },
+  });
+  await app.bootstrap();
+  return out;
+}

package/src/testing/area.spec.ts

@@ -0,0 +1,189 @@
+import { sleep } from "@digital-alchemy/core";
+
+import { TAreaId } from "../dynamic";
+import { AREA_REGISTRY_UPDATED, AreaDetails } from "../helpers";
+import { hassTestRunner, INTERNAL_MESSAGE } from "../mock_assistant";
+
+describe("Area", () => {
+  const EXAMPLE_AREA = {
+    area_id: "empty_area" as TAreaId,
+    floor_id: null,
+    icon: null,
+    labels: [],
+    name: "Empty Area",
+    picture: null,
+  } as AreaDetails;
+
+  afterEach(async () => {
+    await hassTestRunner.teardown();
+    jest.restoreAllMocks();
+  });
+
+  describe("Lifecycle", () => {
+    it("should force values to be available before ready", async () => {
+      expect.assertions(1);
+
+      const app = await hassTestRunner.run(({ mock_assistant, lifecycle, hass }) => {
+        const spy = jest.fn();
+        mock_assistant.socket.connection.on(INTERNAL_MESSAGE, spy);
+        lifecycle.onReady(async () => {
+          await hass.area.list();
+          expect(spy).toHaveBeenCalledWith(
+            expect.objectContaining({ type: "config/area_registry/list" }),
+          );
+        }, -1);
+      });
+      await app.teardown();
+    });
+  });
+
+  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.area.list();
+            expect(spy).toHaveBeenCalledWith(
+              expect.objectContaining({ type: "config/area_registry/list" }),
+            );
+          });
+        });
+      });
+
+      it("should call update 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(AREA_REGISTRY_UPDATED));
+            await hass.area.update(EXAMPLE_AREA);
+
+            expect(spy).toHaveBeenCalledWith({
+              type: "config/area_registry/update",
+              ...EXAMPLE_AREA,
+            });
+          });
+        });
+      });
+
+      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.onAreaRegistryUpdate(() => counter++);
+          lifecycle.onReady(async () => {
+            setImmediate(async () => {
+              hass.socket.socketEvents.emit("area_registry_updated");
+              await sleep(5);
+              hass.socket.socketEvents.emit("area_registry_updated");
+              await sleep(5);
+              hass.socket.socketEvents.emit("area_registry_updated");
+              await sleep(75);
+              hass.socket.socketEvents.emit("area_registry_updated");
+            });
+            await sleep(200);
+            expect(counter).toBe(2);
+          });
+        });
+      });
+
+      it("should call delete 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(AREA_REGISTRY_UPDATED));
+            await hass.area.delete(EXAMPLE_AREA.area_id);
+
+            expect(spy).toHaveBeenCalledWith({
+              area_id: "empty_area",
+              type: "config/area_registry/delete",
+            });
+          });
+        });
+      });
+
+      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(AREA_REGISTRY_UPDATED));
+            await hass.area.create(EXAMPLE_AREA);
+
+            expect(spy).toHaveBeenCalledWith({
+              type: "config/area_registry/create",
+              ...EXAMPLE_AREA,
+            });
+          });
+        });
+      });
+    });
+
+    describe("Order of operations", () => {
+      it("should wait for an update before returning when updating", async () => {
+        expect.assertions(1);
+        await hassTestRunner.run(({ lifecycle, hass, event }) => {
+          jest.spyOn(hass.socket, "sendMessage").mockImplementation(async () => undefined);
+          lifecycle.onReady(async () => {
+            const response = hass.area.update(EXAMPLE_AREA);
+            let order = "";
+            setTimeout(() => {
+              order += "a";
+              event.emit(AREA_REGISTRY_UPDATED);
+            }, 5);
+            await response;
+            order += "b";
+            expect(order).toEqual("ab");
+          });
+        });
+      });
+
+      it("should wait for an update before returning when deleting", async () => {
+        expect.assertions(1);
+        await hassTestRunner.run(({ lifecycle, hass, event }) => {
+          jest.spyOn(hass.socket, "sendMessage").mockImplementation(async () => undefined);
+          lifecycle.onReady(async () => {
+            const response = hass.area.delete("example_area" as TAreaId);
+            let order = "";
+            setTimeout(() => {
+              order += "a";
+              event.emit(AREA_REGISTRY_UPDATED);
+            }, 5);
+            await response;
+            order += "b";
+            expect(order).toEqual("ab");
+          });
+        });
+      });
+
+      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.area.create(EXAMPLE_AREA);
+            let order = "";
+            setTimeout(() => {
+              order += "a";
+              event.emit(AREA_REGISTRY_UPDATED);
+            }, 5);
+            await response;
+            order += "b";
+            expect(order).toEqual("ab");
+          });
+        });
+      });
+    });
+  });
+});

package/src/testing/backup.spec.ts

@@ -0,0 +1,157 @@
+import { SINGLE } from "@digital-alchemy/core";
+
+import { BackupResponse } from "../helpers";
+import { hassTestRunner } from "../mock_assistant";
+
+describe("Backup", () => {
+  afterEach(async () => {
+    await hassTestRunner.teardown();
+    jest.restoreAllMocks();
+  });
+
+  it("should format removes properly", async () => {
+    expect.assertions(1);
+    await hassTestRunner.run(({ lifecycle, hass }) => {
+      lifecycle.onReady(async () => {
+        const spy = jest.spyOn(hass.socket, "sendMessage");
+        await hass.backup.remove("test");
+        expect(spy).toHaveBeenCalledWith(
+          expect.objectContaining({
+            slug: "test",
+            type: "backup/remove",
+          }),
+        );
+      });
+    });
+  });
+
+  it("should format list requests properly", async () => {
+    expect.assertions(1);
+    await hassTestRunner.run(({ lifecycle, hass }) => {
+      lifecycle.onReady(async () => {
+        const spy = jest.spyOn(hass.socket, "sendMessage");
+        await hass.backup.list();
+        expect(spy).toHaveBeenCalledWith(
+          expect.objectContaining({
+            type: "backup/info",
+          }),
+        );
+      });
+    });
+  });
+
+  it("should first attempt to sign with downloads", async () => {
+    expect.assertions(1);
+    await hassTestRunner.run(({ lifecycle, hass }) => {
+      lifecycle.onReady(async () => {
+        const spy = jest
+          .spyOn(hass.socket, "sendMessage")
+          .mockImplementation(async () => undefined);
+        await hass.backup.download("test", "/foo/bar");
+        expect(spy).toHaveBeenCalledWith(
+          expect.objectContaining({
+            path: `/api/backup/download/test`,
+            type: "auth/sign_path",
+          }),
+        );
+      });
+    });
+  });
+
+  it("should use the sign path to download", async () => {
+    expect.assertions(1);
+    await hassTestRunner.run(({ lifecycle, hass }) => {
+      lifecycle.onReady(async () => {
+        const path = "/test/thing";
+        const destination = "/foo/bar";
+        jest.spyOn(hass.socket, "sendMessage").mockImplementation(async () => ({ path }));
+        const spy = jest.spyOn(hass.fetch, "download").mockImplementation(async () => undefined);
+        await hass.backup.download("test", destination);
+        expect(spy).toHaveBeenCalledWith(destination, expect.objectContaining({ url: path }));
+      });
+    });
+  });
+
+  it("should use the sign path to download", async () => {
+    expect.assertions(1);
+    await hassTestRunner.run(({ lifecycle, hass }) => {
+      lifecycle.onReady(async () => {
+        const path = "/test/thing";
+        const destination = "/foo/bar";
+        jest.spyOn(hass.socket, "sendMessage").mockImplementation(async () => ({ path }));
+        const spy = jest.spyOn(hass.fetch, "download").mockImplementation(async () => undefined);
+        await hass.backup.download("test", destination);
+        expect(spy).toHaveBeenCalledWith(destination, expect.objectContaining({ url: path }));
+      });
+    });
+  });
+
+  it("should not start a new backup if one is already in progress", async () => {
+    expect.assertions(1);
+    await hassTestRunner.configure({ hass: { RETRY_INTERVAL: 0 } }).run(({ lifecycle, hass }) => {
+      lifecycle.onReady(async () => {
+        const spy = jest.spyOn(hass.socket, "sendMessage");
+        const responses = [
+          { backing_up: true, backups: [] },
+          { backing_up: false, backups: [] },
+        ] as BackupResponse[];
+
+        jest.spyOn(hass.backup, "list").mockImplementation(async () => responses.shift());
+
+        await hass.backup.generate();
+        expect(spy).not.toHaveBeenCalledWith({ type: "backup/generate" });
+      });
+    });
+  });
+
+  it("should start a new backup if one is not already in progress", async () => {
+    expect.assertions(1);
+    await hassTestRunner.configure({ hass: { RETRY_INTERVAL: 0 } }).run(({ lifecycle, hass }) => {
+      lifecycle.onReady(async () => {
+        const spy = jest.spyOn(hass.socket, "sendMessage");
+        const responses = [
+          { backing_up: false, backups: [] },
+          { backing_up: true, backups: [] },
+          { backing_up: false, backups: [] },
+        ] as BackupResponse[];
+
+        jest.spyOn(hass.backup, "list").mockImplementation(async () => responses.shift());
+
+        await hass.backup.generate();
+        expect(spy).toHaveBeenCalledWith(expect.objectContaining({ type: "backup/generate" }));
+      });
+    });
+  });
+
+  it("should confirm a new backup is in progress before monitoring", async () => {
+    expect.assertions(1);
+    await hassTestRunner.configure({ hass: { RETRY_INTERVAL: 0 } }).run(({ lifecycle, hass }) => {
+      lifecycle.onReady(async () => {
+        const responses = [
+          // not backing up
+          { backing_up: false, backups: [] },
+          // waiting...
+          { backing_up: false, backups: [] },
+          // waiting...
+          { backing_up: false, backups: [] },
+          // waiting...
+          { backing_up: false, backups: [] },
+          // true breaks out of loop confirm loop
+          { backing_up: true, backups: [] },
+          // false breaks out of actively backing up loop
+          { backing_up: false, backups: [] },
+          // should never be sent
+          { backing_up: false, backups: [] },
+        ] as BackupResponse[];
+        const length = responses.length;
+
+        const spy = jest
+          .spyOn(hass.backup, "list")
+          .mockImplementation(async () => responses.shift());
+
+        await hass.backup.generate();
+        expect(spy).toHaveBeenCalledTimes(length - SINGLE);
+      });
+    });
+  });
+});

package/src/testing/config.spec.ts

@@ -0,0 +1,188 @@
+import { env } from "process";
+
+import { hassTestRunner } from "../mock_assistant";
+
+const TOKEN = "DEFAULTS";
+
+describe("Config", () => {
+  beforeEach(() => {
+    delete env.HASSIO_TOKEN;
+    delete env.SUPERVISOR_TOKEN;
+    delete env.HASS_SERVER;
+  });
+
+  afterEach(async () => {
+    await hassTestRunner.teardown();
+    jest.restoreAllMocks();
+  });
+
+  describe("Auto", () => {
+    // # Should do nothing if variables do not exist
+    it("should do nothing if variables do not exist", async () => {
+      expect.assertions(2);
+      const BASE_URL = "http://localhost:9123";
+      await hassTestRunner.configure({ hass: { BASE_URL, TOKEN } }).run(({ lifecycle, config }) => {
+        lifecycle.onPostConfig(() => {
+          expect(config.hass.BASE_URL).toBe(BASE_URL);
+          expect(config.hass.TOKEN).toBe(TOKEN);
+        });
+      });
+    });
+
+    // # Should set BASE_URL & TOKEN if provided env
+    it("should set BASE_URL & TOKEN if provided env", async () => {
+      expect.assertions(2);
+      env.HASSIO_TOKEN = "FOO";
+      await hassTestRunner
+        .configure({
+          hass: { BASE_URL: "http://localhost:9123", TOKEN: TOKEN },
+        })
+        .run(({ lifecycle, config }) => {
+          lifecycle.onPostConfig(() => {
+            expect(config.hass.BASE_URL).toBe("http://supervisor/core");
+            expect(config.hass.TOKEN).toBe("FOO");
+          });
+        });
+    });
+
+    // # Should use HASSIO_TOKEN over SUPERVISOR_TOKEN
+    it("should use HASSIO_TOKEN over SUPERVISOR_TOKEN", async () => {
+      expect.assertions(1);
+      env.HASSIO_TOKEN = "FOO";
+      env.SUPERVISOR_TOKEN = "BAR";
+
+      await hassTestRunner.run(({ lifecycle, config }) => {
+        lifecycle.onPostConfig(() => {
+          expect(config.hass.TOKEN).toBe("FOO");
+        });
+      });
+    });
+
+    // # Should allow SUPERVISOR_TOKEN
+    it("should allow SUPERVISOR_TOKEN", async () => {
+      expect.assertions(1);
+      env.SUPERVISOR_TOKEN = "BAR";
+      await hassTestRunner.run(({ lifecycle, config }) => {
+        lifecycle.onPostConfig(() => {
+          expect(config.hass.TOKEN).toBe("BAR");
+        });
+      });
+    });
+
+    // # Should allow HASS_SERVER
+    it("should allow HASS_SERVER", async () => {
+      expect.assertions(2);
+      env.HASSIO_TOKEN = "FOO";
+      env.HASS_SERVER = "http://test/url";
+
+      await hassTestRunner.run(({ lifecycle, config }) => {
+        lifecycle.onPostConfig(() => {
+          expect(config.hass.TOKEN).toBe("FOO");
+          expect(config.hass.BASE_URL).toBe("http://test/url");
+        });
+      });
+    });
+  });
+
+  describe("Validate Config", () => {
+    // # Should not exit if not set
+    it("should not exit if not set", async () => {
+      expect.assertions(1);
+      const exitSpy = jest
+        .spyOn(process, "exit")
+        // @ts-expect-error testing
+        .mockImplementation(() => {});
+
+      await hassTestRunner
+        .configure({
+          hass: { TOKEN: "TEST" },
+        })
+        .run(() => {});
+      expect(exitSpy).not.toHaveBeenCalled();
+    });
+
+    // # Should info log on success
+    it("should info log on success", async () => {
+      const exitSpy = jest
+        .spyOn(process, "exit")
+        // @ts-expect-error testing
+        .mockImplementation(() => {});
+      let spy: jest.SpyInstance;
+
+      await hassTestRunner
+        .configure({
+          hass: { VALIDATE_CONFIGURATION: true },
+        })
+        .run(({ internal, hass }) => {
+          const logger = internal.boilerplate.logger.getBaseLogger();
+          spy = jest.spyOn(logger, "info").mockImplementation(() => {});
+          jest
+            .spyOn(hass.fetch, "checkCredentials")
+            .mockImplementation(async () => ({ message: "ok" }));
+        });
+
+      expect(exitSpy).toHaveBeenCalledWith(1);
+      expect(spy).toHaveBeenCalledWith("hass:configure", { name: "onPostConfig" }, "ok");
+    });
+
+    // # Should error log on bad token
+    it("should error log on bad token", async () => {
+      let spy: jest.SpyInstance;
+      const exitSpy = jest
+        .spyOn(process, "exit")
+        // @ts-expect-error testing
+        .mockImplementation(() => {});
+
+      await hassTestRunner
+        .configure({ hass: { TOKEN: "TEST", VALIDATE_CONFIGURATION: true } })
+        .run(({ internal, hass }) => {
+          const logger = internal.boilerplate.logger.getBaseLogger();
+          spy = jest.spyOn(logger, "error").mockImplementation(() => {});
+          jest
+            .spyOn(hass.fetch, "checkCredentials")
+            // anything that isn't the success works
+            .mockImplementation(async () => ({ message: "big_bad_error" }));
+        });
+
+      expect(exitSpy).toHaveBeenCalledWith(0);
+      expect(spy).toHaveBeenCalledWith(
+        "hass:configure",
+        { name: "onPostConfig" },
+        String({ message: "big_bad_error" }),
+      );
+    });
+
+    // # Should error log on bad url
+    it("should error log on bad url", async () => {
+      const error = new Error("BOOM");
+      let spy: jest.SpyInstance;
+      const exitSpy = jest
+        .spyOn(process, "exit")
+        // @ts-expect-error testing
+        .mockImplementation(() => {});
+      jest.spyOn(console, "log").mockImplementation(() => {});
+
+      jest.spyOn(console, "error").mockImplementation(() => {});
+
+      await hassTestRunner
+        .configure({ hass: { TOKEN: "TEST", VALIDATE_CONFIGURATION: true } })
+        .run(({ internal, hass }) => {
+          const logger = internal.boilerplate.logger.getBaseLogger();
+          spy = jest.spyOn(logger, "error").mockImplementation(() => {});
+          jest
+            .spyOn(hass.fetch, "checkCredentials")
+            // anything that isn't the success works
+            .mockImplementation(async () => {
+              throw error;
+            });
+        });
+
+      expect(exitSpy).toHaveBeenCalledWith(0);
+      expect(spy).toHaveBeenCalledWith(
+        "hass:configure",
+        { error, name: "onPostConfig" },
+        "failed to send request",
+      );
+    });
+  });
+});