@switchbot/homebridge-switchbot 5.0.0-beta.6 → 5.0.0-beta.60

package/src/test/matter/platform-matter.cleanup.test.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { formatDeviceIdAsMac } from '../../utils.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
+
+describe('platform-matter lifecycle cleanup', () => {
+  it('clearDeviceResources removes timers, instances and BLE handler entries', async () => {
+    // Setup stubbed API and logs
+    const handlers: Record<string, (...args: any[]) => any> = {}
+    const api: any = makeApiStub({ registerPlatformAccessories: vi.fn(), unregisterPlatformAccessories: vi.fn(), clusterNames: { OnOff: 'OnOff' } })
+    api._handlers = handlers
+    // keep api.on as a single-statement arrow to satisfy lint
+    api.on = (ev: string, fn: (...args: any[]) => any) => (handlers[ev] = fn)
+
+    const log = makeLogStub()
+
+    const platform = new SwitchBotMatterPlatform(log as any, {} as any, api)
+
+    // Insert a fake timer, accessory instance, and BLE handler
+    const deviceId = 'AA:BB:CC:11:22:33'
+    const nid = (platform as any).normalizeDeviceId(deviceId)
+
+    const timer = setInterval(() => {}, 100000)
+    ;(platform as any).refreshTimers.set(nid, timer)
+    ;(platform as any).accessoryInstances.set(nid, { dummy: true })
+    ;(platform as any).bleEventHandler[deviceId.toLowerCase()] = () => {}
+
+    // Ensure they exist prior
+    expect((platform as any).refreshTimers.get(nid)).toBeDefined()
+    expect((platform as any).accessoryInstances.get(nid)).toBeDefined()
+    expect((platform as any).bleEventHandler[deviceId.toLowerCase()]).toBeDefined()
+
+    // Call the private helper
+    ;(platform as any).clearDeviceResources(deviceId)
+
+    // Now they should be removed
+    expect((platform as any).refreshTimers.get(nid)).toBeUndefined()
+    expect((platform as any).accessoryInstances.get(nid)).toBeUndefined()
+    expect((platform as any).bleEventHandler[deviceId.toLowerCase()]).toBeUndefined()
+  })
+
+  it('shutdown handler clears all timers and handlers when invoked', async () => {
+    // Setup stubbed API and logs
+    const handlers: Record<string, (...args: any[]) => any> = {}
+    const api: any = makeApiStub({ registerPlatformAccessories: vi.fn(), unregisterPlatformAccessories: vi.fn(), clusterNames: { OnOff: 'OnOff' } })
+    api._handlers = handlers
+    // keep api.on as a single-statement arrow to satisfy lint
+    api.on = (ev: string, fn: (...args: any[]) => any) => (handlers[ev] = fn)
+
+    const log = makeLogStub()
+
+    const platform = new SwitchBotMatterPlatform(log as any, {} as any, api)
+
+    // Add two timers to the platform (using normalized ids)
+    const ids = ['devA', 'devB']
+    for (const id of ids) {
+      const nid = (platform as any).normalizeDeviceId(id)
+      const t = setInterval(() => {}, 100000)
+      ;(platform as any).refreshTimers.set(nid, t)
+      ;(platform as any).accessoryInstances.set(nid, { dummy: true })
+      try {
+        const mac = formatDeviceIdAsMac(id).toLowerCase()
+        ;(platform as any).bleEventHandler[mac] = () => {}
+      } catch {
+        // ignore formatting errors in this test
+      }
+    }
+
+    // Invoke didFinishLaunching to ensure the platform registered its shutdown handler
+    await Promise.resolve(api._handlers.didFinishLaunching?.())
+
+    // Shutdown handler should now be registered on api._handlers.shutdown
+    expect(typeof api._handlers.shutdown).toBe('function')
+
+    // Call the shutdown handler
+    await Promise.resolve(api._handlers.shutdown())
+
+    // All refresh timers should be cleared
+    for (const id of ids) {
+      const nid = (platform as any).normalizeDeviceId(id)
+      expect((platform as any).refreshTimers.get(nid)).toBeUndefined()
+      expect((platform as any).accessoryInstances.get(nid)).toBeUndefined()
+    }
+  })
+})

package/src/test/matter/platform-matter.keepstale.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
+
+describe('keepStaleAccessories config flag behavior', () => {
+  it('keeps previously-registered accessories when options.keepStaleAccessories=true', async () => {
+    const unregister = vi.fn()
+    const register = vi.fn()
+    const api: any = makeApiStub({ unregisterPlatformAccessories: unregister, registerPlatformAccessories: register })
+
+    const log: any = makeLogStub()
+
+    // Create platform with keepStaleAccessories = true
+    const platform = new SwitchBotMatterPlatform(log as any, { options: { keepStaleAccessories: true } } as any, api)
+
+    // Seed discovered devices (one device)
+    ;(platform as any).discoveredDevices = [{ deviceId: 'DEV1', deviceType: 'Plug', deviceName: 'Device 1' }]
+
+    // Insert a stale accessory into matterAccessories
+    const staleUuid = api.matter.uuid.generate('stale-device')
+    const staleAcc: any = { uuid: staleUuid, displayName: 'Stale', context: { deviceId: 'STALE_DEVICE' } }
+    ;(platform as any).matterAccessories.set(staleUuid, staleAcc)
+
+    // Mock createAccessoryFromDevice to return a simple accessory for DEV1
+    vi.spyOn(platform as any, 'createAccessoryFromDevice').mockResolvedValue({ displayName: 'Device 1', uuid: 'uuid-DEV1', context: { deviceId: 'DEV1' } } as any)
+
+    // Run registration which includes stale-removal logic
+    await (platform as any).registerMatterAccessories()
+
+    // Expect unregister NOT called (we kept stale accessory)
+    expect(unregister).not.toHaveBeenCalled()
+
+    // Stale accessory should still be present in matterAccessories
+    expect((platform as any).matterAccessories.get(staleUuid)).toBeDefined()
+  })
+})

package/src/test/matter/platform-matter.logging.test.ts

@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest'
+
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
+
+/**
+ * Verifies that debug logger formats arguments so that accessory displayName
+ * appears in the output for cached accessory load logs.
+ */
+describe('platform-matter logging', () => {
+  it('prints accessory name when loading cached Matter accessory', async () => {
+    const api: any = makeApiStub()
+    const log: any = makeLogStub()
+
+    const platform = new SwitchBotMatterPlatform(log as any, {
+      name: 'SwitchBot',
+      credentials: {},
+      options: { logging: 'debug' },
+    } as any, api)
+
+    // Simulate Homebridge restoring a cached Matter accessory
+    const acc: any = { uuid: 'uuid-TEST', displayName: 'Test Device', context: { deviceId: 'DEV1' } }
+    ;(platform as any).configureMatterAccessory(acc)
+    // debugLog is async and gated; yield to allow the logger to run
+    await new Promise(resolve => setTimeout(resolve, 0))
+
+    // In 'debug' mode, debugLog uses log.info with a [DEBUG] prefix
+    // Ensure one of the info calls contains the message with the device name
+    const calls = (log.info as any).mock.calls as Array<string[]>
+    const hasLine = calls.some(args => String(args[0]).includes('Loading cached Matter accessory: Test Device'))
+    expect(hasLine).toBe(true)
+  })
+})

package/src/test/matter/platform-matter.mapping.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
+
+describe('platform-matter mapping helper', () => {
+  it('prefers accessory instance update methods for battery and falls back to api.matter.updateAccessoryState', async () => {
+    const updateAccessoryState = vi.fn()
+    const api: any = makeApiStub({ updateAccessoryState, clusterNames: { OnOff: 'OnOff', LevelControl: 'LevelControl', ColorControl: 'ColorControl', PowerSource: 'powerSource' } })
+
+    const log: any = makeLogStub()
+    const platform = new SwitchBotMatterPlatform(log as any, {} as any, api)
+
+    // Create a fake accessory instance with updateBatteryPercentage
+    const deviceId = 'DEV123'
+    const nid = (platform as any).normalizeDeviceId(deviceId)
+    const fakeInstance = { updateBatteryPercentage: vi.fn() }
+    ;(platform as any).accessoryInstances.set(nid, fakeInstance)
+
+    // Call the private helper with different battery field names
+    await (platform as any).applyStatusToAccessory('uuid-test', { deviceId } as any, { batteryPercentage: 55 })
+    expect(fakeInstance.updateBatteryPercentage).toHaveBeenCalled()
+
+    // Remove instance to force fallback
+    ;(platform as any).accessoryInstances.delete(nid)
+    await (platform as any).applyStatusToAccessory('uuid-test', { deviceId } as any, { battery: 30 })
+    expect(updateAccessoryState).toHaveBeenCalled()
+  })
+
+  it('handles temperature and humidity synonyms', async () => {
+    const updateAccessoryState = vi.fn()
+    const api: any = makeApiStub({ updateAccessoryState })
+
+    const log: any = makeLogStub()
+    const platform = new SwitchBotMatterPlatform(log as any, {} as any, api)
+
+    const deviceId = 'DEV-TEMP'
+    await (platform as any).applyStatusToAccessory('uuid-temp', { deviceId } as any, { temp: 21.5, humid: 48 })
+
+    // Expect updateAccessoryState to have been called for temperature and humidity
+    expect(updateAccessoryState).toHaveBeenCalled()
+  })
+
+  it('applies VOC and PM10 mappings when present', async () => {
+    const updateAccessoryState = vi.fn()
+    const api: any = makeApiStub({ updateAccessoryState })
+
+    const log: any = makeLogStub()
+    const platform = new SwitchBotMatterPlatform(log as any, {} as any, api)
+
+    const deviceId = 'DEV-AQ'
+    await (platform as any).applyStatusToAccessory('uuid-aq', { deviceId } as any, { voc: 123, pm10: 56 })
+
+    // Expect updateAccessoryState (or safeUpdate fallback) to have been called for voc and pm10
+    expect(updateAccessoryState).toHaveBeenCalled()
+  })
+})

package/src/test/matter/platform-matter.openapi-mapping.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
+
+describe('platform-matter OpenAPI -> Matter mapping', () => {
+  it('maps light OpenAPI status (on/off, brightness, color, battery) to accessory instance helpers', async () => {
+    const api: any = makeApiStub()
+    const log = makeLogStub()
+    const platform = new SwitchBotMatterPlatform(log as any, {} as any, api)
+
+    const deviceId = 'LIGHT-1'
+    const nid = (platform as any).normalizeDeviceId(deviceId)
+
+    const instance = {
+      updateOnOffState: vi.fn(),
+      updateBrightness: vi.fn(),
+      updateHueSaturation: vi.fn(),
+      updateBatteryPercentage: vi.fn(),
+    }
+    ;(platform as any).accessoryInstances.set(nid, instance)
+
+    const status = { power: true, brightness: 80, color: '255:128:64', battery: 92 }
+    await (platform as any).applyStatusToAccessory('uuid-light', { deviceId } as any, status)
+
+    expect(instance.updateOnOffState).toHaveBeenCalled()
+    expect(instance.updateBrightness).toHaveBeenCalled()
+    expect(instance.updateHueSaturation).toHaveBeenCalled()
+    expect(instance.updateBatteryPercentage).toHaveBeenCalled()
+  })
+
+  it('maps MeterPro OpenAPI status (temp, humid, co2, pm25, voc) to accessory instance helpers', async () => {
+    const api: any = makeApiStub()
+    const log = makeLogStub()
+    const platform = new SwitchBotMatterPlatform(log as any, {} as any, api)
+
+    const deviceId = 'METERPRO-1'
+    const nid = (platform as any).normalizeDeviceId(deviceId)
+
+    const instance = {
+      updateTemperature: vi.fn(),
+      updateHumidity: vi.fn(),
+      updateCO2: vi.fn(),
+      updatePM25: vi.fn(),
+      updateVOC: vi.fn(),
+    }
+    ;(platform as any).accessoryInstances.set(nid, instance)
+
+    const status = { temp: 21.4, humid: 45, co2: 410, pm25: 12, voc: 85 }
+    await (platform as any).applyStatusToAccessory('uuid-meter', { deviceId } as any, status)
+
+    expect(instance.updateTemperature).toHaveBeenCalled()
+    expect(instance.updateHumidity).toHaveBeenCalled()
+    expect(instance.updateCO2).toHaveBeenCalled()
+    expect(instance.updatePM25).toHaveBeenCalled()
+    expect(instance.updateVOC).toHaveBeenCalled()
+  })
+
+  it('maps lock OpenAPI status to lock helper', async () => {
+    const api: any = makeApiStub()
+    const log = makeLogStub()
+    const platform = new SwitchBotMatterPlatform(log as any, {} as any, api)
+
+    const deviceId = 'LOCK-1'
+    const nid = (platform as any).normalizeDeviceId(deviceId)
+
+    const instance = { updateLockState: vi.fn() }
+    ;(platform as any).accessoryInstances.set(nid, instance)
+
+    const status = { lock: true }
+    await (platform as any).applyStatusToAccessory('uuid-lock', { deviceId } as any, status)
+
+    expect(instance.updateLockState).toHaveBeenCalled()
+  })
+
+  it('maps curtain position synonyms to lift position helper', async () => {
+    const api: any = makeApiStub()
+    const log = makeLogStub()
+    const platform = new SwitchBotMatterPlatform(log as any, {} as any, api)
+
+    const deviceId = 'CURTAIN-1'
+    const nid = (platform as any).normalizeDeviceId(deviceId)
+
+    const instance = { updateLiftPosition: vi.fn() }
+    ;(platform as any).accessoryInstances.set(nid, instance)
+
+    await (platform as any).applyStatusToAccessory('uuid-cur', { deviceId, deviceType: 'Curtain' } as any, { position: 25 })
+    await (platform as any).applyStatusToAccessory('uuid-cur', { deviceId, deviceType: 'Curtain' } as any, { slidePosition: 75 })
+
+    expect(instance.updateLiftPosition).toHaveBeenCalled()
+  })
+
+  it('maps robot vacuum run state / on to updateRunMode or updateOperationalState', async () => {
+    const api: any = makeApiStub()
+    const log = makeLogStub()
+    const platform = new SwitchBotMatterPlatform(log as any, {} as any, api)
+
+    const deviceId = 'RVC-1'
+    const nid = (platform as any).normalizeDeviceId(deviceId)
+
+    const instance: any = { updateRunMode: vi.fn(), updateOperationalState: vi.fn() }
+    ;(platform as any).accessoryInstances.set(nid, instance)
+
+    await (platform as any).applyStatusToAccessory('uuid-rvc', { deviceId, deviceType: 'K10+' } as any, { runState: 'cleaning', power: true })
+
+    const calls = (instance.updateRunMode.mock?.calls?.length || 0) + (instance.updateOperationalState.mock?.calls?.length || 0)
+    expect(calls).toBeGreaterThan(0)
+  })
+})

package/src/test/matter/platform-matter.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { PLATFORM_NAME, PLUGIN_NAME } from '../../settings.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
+
+describe('platform-matter discovered devices', () => {
+  it('uses discovered devices and registers them (platform + robotic)', async () => {
+    const mockRegister = vi.fn()
+    const api: any = makeApiStub({
+      registerPlatformAccessories: mockRegister,
+      clusterNames: { OnOff: 'OnOff', LevelControl: 'LevelControl', ColorControl: 'ColorControl' },
+      deviceTypes: { RoboticVacuumCleaner: 'rvc' },
+    })
+
+    const log: any = makeLogStub()
+
+    const config: any = {}
+
+    const platform = new SwitchBotMatterPlatform(log, config, api)
+
+    // Provide discovered devices
+    ;(platform as any).discoveredDevices = [
+      { deviceId: 'dev1', deviceName: 'Lamp', deviceType: 'Plug' },
+      { deviceId: 'vac1', deviceName: 'Vac', deviceType: 'K10+' },
+    ] as any
+
+    // Stub accessory creation to avoid instantiating full device classes
+    ;(platform as any).createAccessoryFromDevice = async (dev: any) => ({ displayName: dev.deviceName, uuid: api.matter.uuid.generate(dev.deviceId) } as any)
+
+    await (platform as any).registerMatterAccessories()
+
+    // Ensure registerPlatformAccessories was called at least once
+    expect(mockRegister).toHaveBeenCalled()
+
+    // Sum total accessories registered across all calls
+    const totalRegistered = mockRegister.mock.calls.reduce((sum: number, call: any) => sum + ((call[2] && call[2].length) || 0), 0)
+    expect(totalRegistered).toBe(2)
+
+    // Verify PLUGIN_NAME and PLATFORM_NAME were used in the calls
+    for (const call of mockRegister.mock.calls) {
+      expect(call[0]).toBe(PLUGIN_NAME)
+      expect(call[1]).toBe(PLATFORM_NAME)
+    }
+  })
+
+  it('applies per-device config overrides when deviceId matches discovered device', async () => {
+    const mockRegister = vi.fn()
+
+    const api: any = {
+      matter: {
+        uuid: { generate: (s: string) => `uuid-${s}` },
+        registerPlatformAccessories: mockRegister,
+        clusterNames: { OnOff: 'OnOff', LevelControl: 'LevelControl', ColorControl: 'ColorControl' },
+        deviceTypes: { RoboticVacuumCleaner: 'rvc' },
+      },
+      isMatterAvailable: () => true,
+      isMatterEnabled: () => true,
+      on: () => {},
+    }
+
+    const log: any = { info: vi.fn(), warn: vi.fn(), debug: vi.fn(), error: vi.fn() }
+
+    const config: any = {
+      options: {
+        devices: [{ deviceId: 'dev1', configDeviceName: 'Configured Lamp', logging: 'debug' }],
+      },
+    }
+
+    const platform = new SwitchBotMatterPlatform(log, config, api)
+
+    ;(platform as any).discoveredDevices = [{ deviceId: 'dev1', deviceName: 'Lamp', deviceType: 'Plug' }] as any
+
+    const seen: any[] = []
+    ;(platform as any).createAccessoryFromDevice = async (dev: any) => {
+      seen.push(dev)
+      return {
+        displayName: dev.deviceName ?? dev.configDeviceName,
+        uuid: api.matter.uuid.generate(dev.deviceId),
+      } as any
+    }
+
+    await (platform as any).registerMatterAccessories()
+
+    // createAccessoryFromDevice should have been called once with merged config
+    expect(seen.length).toBe(1)
+    expect(seen[0].deviceId).toBe('dev1')
+    // per-device config values should be present on the merged device
+    expect(seen[0].configDeviceName).toBe('Configured Lamp')
+    expect(seen[0].logging).toBe('debug')
+  })
+
+  it('ignores config-only devices by default but includes them when allowConfigOnlyDevices=true', async () => {
+    const mockRegister = vi.fn()
+
+    const api: any = {
+      matter: {
+        uuid: { generate: (s: string) => `uuid-${s}` },
+        registerPlatformAccessories: mockRegister,
+        clusterNames: { OnOff: 'OnOff', LevelControl: 'LevelControl', ColorControl: 'ColorControl' },
+        deviceTypes: { RoboticVacuumCleaner: 'rvc' },
+      },
+      isMatterAvailable: () => true,
+      isMatterEnabled: () => true,
+      on: () => {},
+    }
+
+    const log: any = { info: vi.fn(), warn: vi.fn(), debug: vi.fn(), error: vi.fn() }
+
+    // config-only device (cfg1) and one discovered device (dev1)
+    const cfgOnly = { deviceId: 'cfg1', configDeviceName: 'OnlyInConfig', deviceType: 'Plug' }
+    const configDefault: any = { options: { devices: [cfgOnly] } }
+
+    const platformDefault = new SwitchBotMatterPlatform(log, configDefault, api)
+    ;(platformDefault as any).discoveredDevices = [{ deviceId: 'dev1', deviceName: 'Lamp', deviceType: 'Plug' }] as any
+    const seenDefault: any[] = []
+    ;(platformDefault as any).createAccessoryFromDevice = async (dev: any) => {
+      seenDefault.push(dev)
+      return {
+        displayName: dev.deviceName ?? dev.configDeviceName,
+        uuid: api.matter.uuid.generate(dev.deviceId),
+      } as any
+    }
+    await (platformDefault as any).registerMatterAccessories()
+    // Should only see discovered device (cfg1 ignored)
+    expect(seenDefault.find((d: any) => d.deviceId === 'cfg1')).toBeUndefined()
+
+    // Now opt-in to include config-only devices
+    const configOptIn: any = { options: { devices: [cfgOnly], allowConfigOnlyDevices: true } }
+    const platformOptIn = new SwitchBotMatterPlatform(log, configOptIn, api)
+    ;(platformOptIn as any).discoveredDevices = [{ deviceId: 'dev1', deviceName: 'Lamp', deviceType: 'Plug' }] as any
+    const seenOptIn: any[] = []
+    ;(platformOptIn as any).createAccessoryFromDevice = async (dev: any) => {
+      seenOptIn.push(dev)
+      return {
+        displayName: dev.deviceName ?? dev.configDeviceName,
+        uuid: api.matter.uuid.generate(dev.deviceId),
+      } as any
+    }
+    await (platformOptIn as any).registerMatterAccessories()
+    // Should include the config-only device now
+    expect(seenOptIn.find((d: any) => d.deviceId === 'cfg1')).toBeDefined()
+  })
+})

package/src/test/matter/platform-matter.unregister.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
+
+describe('removeDisabledAccessories and unregister edge cases', () => {
+  it('clears resources and unregisters accessory even with invalid timer and non-MAC deviceId', async () => {
+    // Prepare API stub
+    const unregister = vi.fn()
+    const api: any = makeApiStub({ unregisterPlatformAccessories: unregister })
+    const log: any = makeLogStub()
+    const platform = new SwitchBotMatterPlatform(log as any, { enableOnOffLight: false } as any, api)
+
+    // Build a fake serialized accessory matching the generated UUID for OnOff Light
+    const uuid = api.matter.uuid.generate('matter-onoff-light')
+    const accessory: any = { uuid, displayName: 'OnOff Light', context: { deviceId: 'NOT-A-MAC' } }
+
+    // Put invalid timer object into refreshTimers to ensure code handles it
+    const nid = (platform as any).normalizeDeviceId(accessory.context.deviceId)
+    ;(platform as any).refreshTimers.set(nid, null as any)
+    ;(platform as any).accessoryInstances.set(nid, { dummy: true })
+
+    // Insert accessory into matterAccessories so removeDisabledAccessories will see it
+    ;(platform as any).matterAccessories.set(uuid, accessory)
+
+    // Spy on clearDeviceResources
+    const spyClear = vi.spyOn(platform as any, 'clearDeviceResources')
+
+    // Call removeDisabledAccessories directly
+    await (platform as any).removeDisabledAccessories()
+
+    // Expect unregister was called and matterAccessories cleared
+    expect(unregister).toHaveBeenCalled()
+    expect((platform as any).matterAccessories.get(uuid)).toBeUndefined()
+
+    // clearDeviceResources should have been called with the accessory.deviceId
+    expect(spyClear).toHaveBeenCalledWith(accessory.context.deviceId)
+  })
+})

package/src/test/matter/platform-matter.webhook.test.ts

@@ -0,0 +1,54 @@
+import { describe, expect, it } from 'vitest'
+
+import { SwitchBotMatterPlatform } from '../../platform-matter.js'
+import { makeApiStub, makeLogStub } from '../helpers/platform-fixtures.js'
+
+/**
+ * Verify that Matter accessories receive the effective webhook flag
+ * in their context when a global webhook option is enabled and the
+ * per-device webhook setting is undefined.
+ */
+describe('platform-matter webhook context propagation', () => {
+  it('sets context.webhook=true when global webhook is enabled and device.webhook is undefined', async () => {
+    const api: any = makeApiStub()
+    const log: any = makeLogStub()
+
+    const platform = new SwitchBotMatterPlatform(log as any, {
+      name: 'SwitchBot',
+      options: { webhook: true },
+    } as any, api)
+
+    // Minimal device that maps to a known Matter accessory constructor
+    const dev: any = {
+      deviceId: 'DEV-WH-1',
+      deviceName: 'Webhook Plug',
+      deviceType: 'Plug',
+      // webhook intentionally undefined to test fallback
+    }
+
+    const acc = await (platform as any).createAccessoryFromDevice(dev)
+    expect(acc).toBeDefined()
+    expect((acc as any).context?.webhook).toBe(true)
+  })
+
+  it('keeps explicit device.webhook=false even when global webhook is true', async () => {
+    const api: any = makeApiStub()
+    const log: any = makeLogStub()
+
+    const platform = new SwitchBotMatterPlatform(log as any, {
+      name: 'SwitchBot',
+      options: { webhook: true },
+    } as any, api)
+
+    const dev: any = {
+      deviceId: 'DEV-WH-2',
+      deviceName: 'No Webhook Plug',
+      deviceType: 'Plug',
+      webhook: false,
+    }
+
+    const acc = await (platform as any).createAccessoryFromDevice(dev)
+    expect(acc).toBeDefined()
+    expect((acc as any).context?.webhook).toBe(false)
+  })
+})

package/src/test/utils.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { createPlatformProxy, detectMatter } from '../utils.js'
+
+describe('detectMatter', () => {
+  it('returns enabled true when api.isMatterEnabled is a function that returns true', () => {
+    const api: any = { isMatterEnabled: () => true }
+    const info = detectMatter(api)
+    expect(info.enabled).toBe(true)
+    expect(info.reason).toMatch(/isMatterEnabled\(\)/)
+  })
+
+  it('returns enabled true when api.isMatterEnabled is a truthy property', () => {
+    const api: any = { isMatterEnabled: true }
+    const info = detectMatter(api)
+    expect(info.enabled).toBe(true)
+    expect(info.reason).toMatch(/property present/)
+  })
+
+  it('uses server fallback when present', () => {
+    const api: any = { server: { isMatterEnabled: () => false } }
+    const info = detectMatter(api)
+    expect(info.enabled).toBe(false)
+    expect(info.reason).toMatch(/server.isMatterEnabled\(\)/)
+  })
+
+  it('returns enabled false with a reason when no API is present', () => {
+    const api: any = {}
+    const info = detectMatter(api)
+    expect(info.enabled).toBe(false)
+    expect(typeof info.reason).toBe('string')
+  })
+})
+
+describe('createPlatformProxy', () => {
+  it('selects HAP platform when Matter is disabled and delegates configureAccessory', () => {
+    class HapStub {
+      public static created = false
+      public configured: any = undefined
+      constructor(public log: any, public config: any, public api: any) {
+        HapStub.created = true
+      }
+
+      configureAccessory(acc: any) {
+        this.configured = acc
+      }
+    }
+
+    class MatterStub {
+      constructor() {
+        throw new Error('should not be constructed')
+      }
+    }
+
+    const ProxyCtor = createPlatformProxy(HapStub as any, MatterStub as any)
+    const log = { info: vi.fn() }
+    const api = { isMatterEnabled: false }
+    const proxy = new (ProxyCtor as any)(log, {}, api)
+
+    // delegate should be instance of HapStub
+    expect(HapStub.created).toBe(true)
+    expect(typeof proxy.delegate.configureAccessory).toBe('function')
+    proxy.configureAccessory('accessory')
+    expect(proxy.delegate.configured).toBe('accessory')
+    // log should mention HAP
+    expect((log.info as any).mock.calls[0][0]).toMatch(/HAP/)
+  })
+
+  it('selects Matter platform when isMatterEnabled is true', () => {
+    class HapStub2 {
+      constructor() {
+        throw new Error('should not be constructed')
+      }
+    }
+
+    class MatterStub2 {
+      public configured: any = undefined
+      constructor(public log: any, public config: any, public api: any) {}
+
+      configureMatterAccessory(acc: any) {
+        this.configured = acc
+      }
+    }
+
+    const ProxyCtor = createPlatformProxy(HapStub2 as any, MatterStub2 as any)
+    const log = { info: vi.fn() }
+    const api = { isMatterEnabled: () => true }
+    const proxy = new (ProxyCtor as any)(log, {}, api)
+
+    // delegate should be instance of MatterStub2
+    expect(typeof proxy.delegate.configureMatterAccessory).toBe('function')
+    ;(proxy as any).configureMatterAccessory('macc')
+    expect(proxy.delegate.configured).toBe('macc')
+    expect((log.info as any).mock.calls[0][0]).toMatch(/Matter/)
+  })
+})