diff --git a/src/common/entity/context/get_area_context.ts b/src/common/entity/context/get_area_context.ts index 6b05bf5d63..88927f87df 100644 --- a/src/common/entity/context/get_area_context.ts +++ b/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 diff --git a/src/common/entity/context/get_entity_context.ts b/src/common/entity/context/get_entity_context.ts index 1ad2aa8312..ee7d35b701 100644 --- a/src/common/entity/context/get_entity_context.ts +++ b/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 diff --git a/test/common/entity/context/get_area_context.test.ts b/test/common/entity/context/get_area_context.test.ts new file mode 100644 index 0000000000..d3e26631d3 --- /dev/null +++ b/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" }, + }); + }); +}); diff --git a/test/common/entity/context/get_entity_context.test.ts b/test/common/entity/context/get_entity_context.test.ts new file mode 100644 index 0000000000..af0077225c --- /dev/null +++ b/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, + }); + }); +});