Add unit tests and docs for common/context (#25158)

src/common/entity/context/get_area_context.ts

@@ -7,6 +7,15 @@ interface AreaContext {
   floor: FloorRegistryEntry | null;
 }
 
+/**
+ * Retrieves the context of a specific area, including its associated area registry entry
+ * and floor registry entry, if available.
+ *
+ * @param areaId - The unique identifier of the area to retrieve context for.
+ * @param hass - The Home Assistant instance containing area and floor registry data.
+ * @returns An object containing the area registry entry and the associated floor registry entry,
+ *          or `null` values if the area or floor is not found.
+ */
 export const getAreaContext = (
   areaId: string,
   hass: HomeAssistant

src/common/entity/context/get_entity_context.ts

@@ -11,6 +11,19 @@ interface EntityContext {
   floor: FloorRegistryEntry | null;
 }
 
+/**
+ * Retrieves the context of an entity, including its associated device, area, and floor.
+ *
+ * @param entityId - The unique identifier of the entity to retrieve the context for.
+ * @param hass - The Home Assistant object containing the registry data for entities, devices, areas, and floors.
+ * @returns An object containing the entity, its associated device, area, and floor, or `null` for each if not found.
+ *
+ * The returned `EntityContext` object includes:
+ * - `entity`: The entity registry entry, or `null` if the entity is not found.
+ * - `device`: The device registry entry associated with the entity, or `null` if not found.
+ * - `area`: The area registry entry associated with the entity or device, or `null` if not found.
+ * - `floor`: The floor registry entry associated with the area, or `null` if not found.
+ */
 export const getEntityContext = (
   entityId: string,
   hass: HomeAssistant

test/common/entity/context/get_area_context.test.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from "vitest";
+import { getAreaContext } from "../../../../src/common/entity/context/get_area_context";
+import type { HomeAssistant } from "../../../../src/types";
+
+describe("getAreaContext", () => {
+  it("should return null values when the area does not exist", () => {
+    const hass = {
+      areas: {},
+      floors: {},
+    } as unknown as HomeAssistant;
+
+    const result = getAreaContext("nonexistent.area", hass);
+
+    expect(result).toEqual({
+      area: null,
+      floor: null,
+    });
+  });
+
+  it("should return the correct context when the area exists without a floor", () => {
+    const hass = {
+      areas: {
+        area_1: { id: "area_1" },
+      },
+      floors: {},
+    } as unknown as HomeAssistant;
+
+    const result = getAreaContext("area_1", hass);
+
+    expect(result).toEqual({
+      area: { id: "area_1" },
+      floor: null,
+    });
+  });
+
+  it("should return the correct context when the area exists with a floor", () => {
+    const hass = {
+      areas: {
+        area_2: { id: "area_2", floor_id: "floor_1" },
+      },
+      floors: {
+        floor_1: { id: "floor_1" },
+      },
+    } as unknown as HomeAssistant;
+
+    const result = getAreaContext("area_2", hass);
+
+    expect(result).toEqual({
+      area: { id: "area_2", floor_id: "floor_1" },
+      floor: { id: "floor_1" },
+    });
+  });
+});

test/common/entity/context/get_entity_context.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, expect } from "vitest";
+import type { HomeAssistant } from "../../../../src/types";
+import { getEntityContext } from "../../../../src/common/entity/context/get_entity_context";
+
+describe("getEntityContext", () => {
+  it("should return null values when the entity does not exist", () => {
+    const hass = {
+      entities: {},
+      devices: {},
+      areas: {},
+      floors: {},
+    } as unknown as HomeAssistant;
+
+    const result = getEntityContext("nonexistent.entity", hass);
+
+    expect(result).toEqual({
+      entity: null,
+      device: null,
+      area: null,
+      floor: null,
+    });
+  });
+
+  it("should return the correct context when the entity exists without device or area", () => {
+    const hass = {
+      entities: {
+        "light.living_room": { entity_id: "light.living_room" },
+      },
+      devices: {},
+      areas: {},
+      floors: {},
+    } as unknown as HomeAssistant;
+
+    const result = getEntityContext("light.living_room", hass);
+
+    expect(result).toEqual({
+      entity: { entity_id: "light.living_room" },
+      device: null,
+      area: null,
+      floor: null,
+    });
+  });
+
+  it("should return the correct context when the entity has a device and area", () => {
+    const hass = {
+      entities: {
+        "light.living_room": {
+          entity_id: "light.living_room",
+          device_id: "device_1",
+        },
+      },
+      devices: {
+        device_1: { id: "device_1", area_id: "area_1" },
+      },
+      areas: {
+        area_1: { id: "area_1", floor_id: "floor_1" },
+      },
+      floors: {
+        floor_1: { id: "floor_1" },
+      },
+    } as unknown as HomeAssistant;
+
+    const result = getEntityContext("light.living_room", hass);
+
+    expect(result).toEqual({
+      entity: { entity_id: "light.living_room", device_id: "device_1" },
+      device: { id: "device_1", area_id: "area_1" },
+      area: { id: "area_1", floor_id: "floor_1" },
+      floor: { id: "floor_1" },
+    });
+  });
+
+  it("should return the correct context when the entity has an area but no device", () => {
+    const hass = {
+      entities: {
+        "sensor.kitchen": { entity_id: "sensor.kitchen", area_id: "area_2" },
+      },
+      devices: {},
+      areas: {
+        area_2: { id: "area_2", floor_id: "floor_2" },
+      },
+      floors: {
+        floor_2: { id: "floor_2" },
+      },
+    } as unknown as HomeAssistant;
+
+    const result = getEntityContext("sensor.kitchen", hass);
+
+    expect(result).toEqual({
+      entity: { entity_id: "sensor.kitchen", area_id: "area_2" },
+      device: null,
+      area: { id: "area_2", floor_id: "floor_2" },
+      floor: { id: "floor_2" },
+    });
+  });
+
+  it("should return null for floor if area does not have a floor_id", () => {
+    const hass = {
+      entities: {
+        "sensor.bedroom": { entity_id: "sensor.bedroom", area_id: "area_3" },
+      },
+      devices: {},
+      areas: {
+        area_3: { id: "area_3" },
+      },
+      floors: {},
+    } as unknown as HomeAssistant;
+
+    const result = getEntityContext("sensor.bedroom", hass);
+
+    expect(result).toEqual({
+      entity: { entity_id: "sensor.bedroom", area_id: "area_3" },
+      device: null,
+      area: { id: "area_3" },
+      floor: null,
+    });
+  });
+});