@switchbot/homebridge-switchbot 5.0.0-beta.7 → 5.0.0-beta.71

package/test/accessory-restore.spec.ts

@@ -0,0 +1,73 @@
+import { describe, it, expect } from 'vitest'
+import { SwitchBotHAPPlatform, SwitchBotMatterPlatform } from '../src/platform'
+
+const log = { info: () => {}, warn: () => {}, error: () => {}, debug: () => {} }
+
+describe('accessory restore', () => {
+  it('reuses restored HAP accessory by context.deviceId and avoids re-register', async () => {
+    const registered: any[] = []
+    const hap = { uuid: { generate: (s: string) => `uuid-${s}` }, Service: {}, Characteristic: {} }
+
+    function PlatformAccessory(name: string, uuid: string) {
+      this.displayName = name
+      this.UUID = uuid
+      this.context = {}
+      this.getService = () => undefined
+      this.addService = () => undefined
+    }
+
+    const api: any = {
+      hap,
+      platformAccessory: PlatformAccessory as any,
+      registerPlatformAccessories: (_p: string, _n: string, accs: any[]) => registered.push(...accs),
+      on: (_ev: string, cb: Function) => {},
+    }
+
+    const platform = new SwitchBotHAPPlatform(log as any, { devices: [{ id: 'dev1', type: 'light', name: 'NewName' }] }, api)
+
+    // Simulate restored accessory with different uuid but correct deviceId in context
+    const restored = new (api.platformAccessory)('OldName', 'old-uuid')
+    restored.context = { deviceId: 'dev1', type: 'light' }
+    platform.configureAccessory(restored)
+
+    // Load devices should reuse restored accessory by context.deviceId
+    await (platform as any).loadDevices()
+
+    // No new registration for this device because restored accessory was reused
+    expect(registered.length).toBe(0)
+    // The restored accessory should remain in the platform's accessory map
+    const keys = Array.from((platform as any).accessories.keys())
+    expect(keys).toContain('old-uuid')
+    const acc = (platform as any).accessories.get('old-uuid')
+    expect(acc.context.deviceId).toBe('dev1')
+  })
+
+  it('reuses restored Matter accessory by context.deviceId when registering', async () => {
+    const captured: any[] = []
+    const matter = { uuid: { generate: (s: string) => `uuid-${s}` }, clusterNames: {} }
+    const api: any = {
+      matter,
+      isMatterAvailable: () => true,
+      isMatterEnabled: () => true,
+      on: (_ev: string, cb: Function) => {},
+    }
+
+    const platform = new SwitchBotMatterPlatform(log as any, { devices: [{ id: 'm1', type: 'light', name: 'M1' }] }, api)
+
+    // Simulate restored Matter accessory with a different uuid but matching deviceId
+    const restored = { uuid: 'restored-uuid', displayName: 'OldM', context: { deviceId: 'm1', type: 'light' } }
+    ;(platform as any).accessories.set(restored.uuid, restored)
+
+    // stub matter.registerPlatformAccessories to capture what is registered
+    api.matter.registerPlatformAccessories = async (_p: string, _n: string, accs: any[]) => captured.push(...accs)
+
+    // call registerMatterAccessories
+    await (platform as any).registerMatterAccessories()
+
+    // The restored accessory should still be present and associated with deviceId
+    const keys = Array.from((platform as any).accessories.keys())
+    expect(keys).toContain(restored.uuid)
+    const acc = (platform as any).accessories.get(restored.uuid)
+    expect(acc.context.deviceId).toBe('m1')
+  })
+})

package/test/device-mapping.spec.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest'
+import { createDevice } from '../src/deviceFactory'
+
+const DEVICE_TYPES = [
+  'bot',
+  'curtain',
+  'fan',
+  'light',
+  'lightstrip',
+  'motion',
+  'contact',
+  'vacuum',
+  'lock',
+  'humidifier',
+  'temperature',
+]
+
+describe('device mapping', () => {
+  it('maps known device types to device descriptors (HAP)', async () => {
+    for (const t of DEVICE_TYPES) {
+      const created = await createDevice({ id: `dev-${t}`, type: t, name: `Name-${t}` }, {}, false)
+      expect(created).toHaveProperty('instance')
+      expect(created).toHaveProperty('createAccessory')
+      const acc = created.createAccessory?.(undefined)
+      expect(acc).toBeDefined()
+      // descriptor should include services for HAP devices
+      if (created.protocol === 'hap') {
+        expect(acc).toHaveProperty('services')
+      }
+    }
+  })
+
+  it('returns matter protocol when requested', async () => {
+    const created = await createDevice({ id: 'm1', type: 'light', name: 'M1' }, { preferMatter: true, enableMatter: true }, true)
+    expect(created.protocol).toBe('matter')
+  })
+})

package/test/deviceFactory.spec.ts

@@ -0,0 +1,18 @@
+import { describe, it, expect } from 'vitest'
+import { createDevice } from '../src/deviceFactory'
+
+describe('deviceFactory', () => {
+  it('creates HAP device descriptor for light', async () => {
+    const created = await createDevice({ id: 'dev1', type: 'light', name: 'L1' }, {}, false)
+    expect(created).toHaveProperty('instance')
+    expect(created).toHaveProperty('createAccessory')
+    expect(created.protocol).toBe('hap')
+    const acc = created.createAccessory?.(undefined)
+    expect(acc).toHaveProperty('services')
+  })
+
+  it('creates Matter descriptor when useMatter=true', async () => {
+    const created = await createDevice({ id: 'dev2', type: 'light', name: 'L2' }, { preferMatter: true, enableMatter: true }, true)
+    expect(created.protocol).toBe('matter')
+  })
+})

package/test/e2e/run-e2e.spec.ts

@@ -0,0 +1,50 @@
+import { describe, test } from 'vitest'
+import { promisify } from 'util'
+import { execFile } from 'child_process'
+import path from 'path'
+
+const execFileP = promisify(execFile)
+
+describe('E2E scripts (manual-run harness)', () => {
+  if (!process.env.RUN_E2E) {
+    test.skip('E2E disabled - set RUN_E2E=true to enable', () => {})
+    return
+  }
+
+  test('run configured E2E scripts sequentially', async () => {
+    const repoRoot = path.resolve(__dirname, '../../')
+    const scriptsDir = path.join(repoRoot, 'scripts', 'e2e')
+
+    const scriptsToRun: { envVar: string; script: string }[] = [
+      { envVar: 'LIGHT_ACCESSORY_ID', script: 'light-e2e.sh' },
+      { envVar: 'FAN_ACCESSORY_ID', script: 'fan-e2e.sh' },
+      { envVar: 'CURTAIN_ACCESSORY_ID', script: 'curtain-e2e.sh' },
+      { envVar: 'LOCK_ACCESSORY_ID', script: 'lock-e2e.sh' },
+    ]
+
+    for (const s of scriptsToRun) {
+      if (!process.env[s.envVar]) {
+        // skip script if no accessory id configured
+        // eslint-disable-next-line no-console
+        console.log(`Skipping ${s.script} because ${s.envVar} not set`)
+        continue
+      }
+
+      const scriptPath = path.join(scriptsDir, s.script)
+      // Forward environment so scripts can read HB_URL / HB_TOKEN / <ACCESSORY_ID>
+      const env = Object.assign({}, process.env)
+
+      try {
+        // eslint-disable-next-line no-console
+        console.log(`Running ${s.script}...`)
+        const { stdout, stderr } = await execFileP('bash', [scriptPath], { env })
+        // eslint-disable-next-line no-console
+        console.log(stdout)
+        if (stderr) console.error(stderr)
+      } catch (e: any) {
+        // bubble up as test failure
+        throw new Error(`Script ${s.script} failed: ${e.message}`)
+      }
+    }
+  })
+})

package/test/fan-swing.spec.ts

@@ -0,0 +1,29 @@
+import { describe, it, expect, vi } from 'vitest'
+import { FanDevice } from '../src/devices/genericDevice'
+
+describe('Fan swing commands', () => {
+  it('sends setSwing on boolean swing', async () => {
+    const mockClient = { setDeviceState: vi.fn(async (id: string, body: any) => ({ id, body })) }
+    const d = new FanDevice({ id: 'fan1', type: 'fan', name: 'F' }, { _client: mockClient } as any)
+    await d.init()
+    const res = await d.setState({ swing: true })
+    expect(mockClient.setDeviceState).toHaveBeenCalled()
+    expect((mockClient.setDeviceState as any).mock.calls[0][1]).toEqual({ command: 'setSwing', parameter: 'on', commandType: 'command' })
+  })
+
+  it('sends setSwing with angle', async () => {
+    const mockClient = { setDeviceState: vi.fn(async (id: string, body: any) => ({ id, body })) }
+    const d = new FanDevice({ id: 'fan2', type: 'fan', name: 'F2' }, { _client: mockClient } as any)
+    await d.init()
+    await d.setState({ swingAngle: 45 })
+    expect((mockClient.setDeviceState as any).mock.calls[0][1]).toEqual({ command: 'setSwing', parameter: '45', commandType: 'command' })
+  })
+
+  it('sends setSwing with mode', async () => {
+    const mockClient = { setDeviceState: vi.fn(async (id: string, body: any) => ({ id, body })) }
+    const d = new FanDevice({ id: 'fan3', type: 'fan', name: 'F3' }, { _client: mockClient } as any)
+    await d.init()
+    await d.setState({ swingMode: 'vertical' })
+    expect((mockClient.setDeviceState as any).mock.calls[0][1]).toEqual({ command: 'setSwing', parameter: 'vertical', commandType: 'command' })
+  })
+})

package/test/helpers/matter-harness.ts

@@ -0,0 +1,53 @@
+export function makeFakeMatterApi() {
+  const registered: any[] = []
+  return {
+    uuid: { generate: (s: string) => `m-${s}` },
+    registerPlatformAccessories: async (_plugin: string, _name: string, accs: any[]) => {
+      registered.push(...accs)
+    },
+    getRegistered: () => registered,
+  }
+}
+
+export function makeFakeHap() {
+  return {
+    uuid: { generate: (s: string) => `h-${s}` },
+    Service: { Switch: 'Switch', Lightbulb: 'Lightbulb', Fan: 'Fan', WindowCovering: 'WindowCovering', LockMechanism: 'LockMechanism', HumiditySensor: 'HumiditySensor' },
+    Characteristic: { On: 'On', Brightness: 'Brightness', RotationSpeed: 'RotationSpeed', CurrentPosition: 'CurrentPosition', TargetPosition: 'TargetPosition' },
+  }
+}
+
+export function makeFakeApiWithMatter(matterApi?: any) {
+  const matter = matterApi || makeFakeMatterApi()
+  const api: any = {
+    matter,
+    isMatterAvailable: () => true,
+    isMatterEnabled: () => true,
+    hap: makeFakeHap(),
+  }
+  return api
+}
+
+export function makeFakeApiWithoutMatter() {
+  // Provide a minimal platformAccessory constructor and registerPlatformAccessories
+  function PlatformAccessory(name: string, uuid: string) {
+    this.displayName = name
+    this.UUID = uuid
+    this.services = []
+    this.getService = (type: any) => this.services.find((s: any) => s.type === type)
+    this.addService = (type: any) => {
+      const s: any = { type, characteristics: {} }
+      this.services.push(s)
+      return s
+    }
+  }
+
+  return {
+    isMatterAvailable: () => false,
+    isMatterEnabled: () => false,
+    hap: makeFakeHap(),
+    platformAccessory: PlatformAccessory,
+    registerPlatformAccessories: (_p: string, _n: string, accs: any[]) => {},
+    on: (_ev: string, cb: Function) => {},
+  }
+}

package/test/lock-users.spec.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect, vi } from 'vitest'
+import { LockDevice } from '../src/devices/genericDevice'
+
+describe('Lock user management', () => {
+  it('sets lock pin via pin field', async () => {
+    const mockClient = { setDeviceState: vi.fn(async (id: string, body: any) => ({ id, body })) }
+    const d = new LockDevice({ id: 'lock1', type: 'lock', name: 'L1' }, { _client: mockClient } as any)
+    await d.init()
+    await d.setState({ pin: '1234' })
+    expect((mockClient.setDeviceState as any).mock.calls[0][1]).toEqual({ command: 'setLockPin', parameter: '1234', commandType: 'command' })
+  })
+
+  it('adds a user code with addUser action', async () => {
+    const mockClient = { setDeviceState: vi.fn(async (id: string, body: any) => ({ id, body })) }
+    const d = new LockDevice({ id: 'lock2', type: 'lock', name: 'L2' }, { _client: mockClient } as any)
+    await d.init()
+    await d.setState({ action: 'addUser', user: 'user1', pin: '9999' })
+    expect((mockClient.setDeviceState as any).mock.calls[0][1]).toEqual({ command: 'addUserCode', parameter: 'user1:9999', commandType: 'command' })
+  })
+
+  it('removes a user code with removeUser action', async () => {
+    const mockClient = { setDeviceState: vi.fn(async (id: string, body: any) => ({ id, body })) }
+    const d = new LockDevice({ id: 'lock3', type: 'lock', name: 'L3' }, { _client: mockClient } as any)
+    await d.init()
+    await d.setState({ action: 'removeUser', user: 'user1' })
+    expect((mockClient.setDeviceState as any).mock.calls[0][1]).toEqual({ command: 'removeUserCode', parameter: 'user1', commandType: 'command' })
+  })
+
+  it('lists users with listUsers action', async () => {
+    const mockClient = { setDeviceState: vi.fn(async (id: string, body: any) => ({ id, body })) }
+    const d = new LockDevice({ id: 'lock4', type: 'lock', name: 'L4' }, { _client: mockClient } as any)
+    await d.init()
+    await d.setState({ action: 'listUsers' })
+    expect((mockClient.setDeviceState as any).mock.calls[0][1]).toEqual({ command: 'listUsers', parameter: 'default', commandType: 'command' })
+  })
+
+  it('unlocks with pin using unlockWithPin action', async () => {
+    const mockClient = { setDeviceState: vi.fn(async (id: string, body: any) => ({ id, body })) }
+    const d = new LockDevice({ id: 'lock5', type: 'lock', name: 'L5' }, { _client: mockClient } as any)
+    await d.init()
+    await d.setState({ action: 'unlockWithPin', pin: '5555' })
+    expect((mockClient.setDeviceState as any).mock.calls[0][1]).toEqual({ command: 'unlockWithPin', parameter: '5555', commandType: 'command' })
+  })
+})

package/test/matter-childbridge.spec.ts

@@ -0,0 +1,55 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import SwitchBotPlatform from '../src/platform'
+import { createPlatformProxy } from '../src/utils'
+
+// This is a lightweight integration-style unit test that verifies the
+// platform will attempt Matter registration when MatterPlatform is
+// provided by the proxy and will still restore cached accessories.
+
+describe('platform integration (Matter)', () => {
+  it('creates Matter descriptors when useMatter=true and restores accessories', async () => {
+    // Create a fake MatterPlatform class that records register calls
+    class FakeMatterPlatform {
+      public registered: any[] = []
+      constructor(public log: any, public cfg: any, public api: any) {}
+      async registerMatterAccessories(accessories: any[]) {
+        this.registered.push(...accessories)
+        return
+      }
+      // simulate configureAccessory hook for restored matter accessories
+      configureMatterAccessory(accessory: any) {
+        // no-op
+      }
+      // lightweight loadDevices implementation that uses an injected discover hook if present
+      async loadDevices() {
+        const devices = (this.cfg?.devices) || (this as any)._discoverDevices ? await (this as any)._discoverDevices() : []
+        // Simulate preparing descriptors and immediately registering them
+        const serialized = devices.map((d: any) => ({ id: d.id ?? d.deviceId ?? d, protocol: 'matter', name: d.name }))
+        if (serialized.length > 0) await this.registerMatterAccessories(serialized)
+      }
+    }
+
+    // Create proxy that would choose the fake matter platform when preferred
+    const Proxy = createPlatformProxy(function HAP() {}, FakeMatterPlatform)
+    const platform = new (Proxy as any)(console, { preferMatter: true, enableMatter: true }, {})
+
+    // Make a small device descriptor to load
+    const device = { id: 'dev-m-1', type: 'light', name: 'MatterLight' }
+    // Simulate platform method that loads devices (use same method name used in code)
+    if (typeof platform.loadDevices === 'function') {
+      // Add an internal method to return our single device for creation
+      platform._discoverDevices = async () => [device]
+      // Call loadDevices which should call the MatterPlatform.registerMatterAccessories
+      await platform.loadDevices()
+
+      // Verify FakeMatterPlatform received the accessory
+      expect(platform).toBeInstanceOf(FakeMatterPlatform)
+      expect((platform as any).registered.length).toBeGreaterThanOrEqual(1)
+      const registered = (platform as any).registered[0]
+      expect(registered).toHaveProperty('protocol', 'matter')
+      expect(registered).toHaveProperty('id', device.id)
+    } else {
+      throw new Error('platform.loadDevices not implemented')
+    }
+  })
+})

package/test/matter-descriptors.spec.ts

@@ -0,0 +1,97 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { FanDevice, LightDevice, CurtainDevice, LockDevice } from '../src/devices/genericDevice'
+
+describe('Matter descriptors and translations (per-device)', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  it('Fan: maps oscillation and swing to setDeviceState commands', async () => {
+    const calls: any[] = []
+    const fakeClient: any = { setDeviceState: async (id: string, body: any) => { calls.push({ id, body }); return { ok: true } } }
+    const d = new FanDevice({ id: 'f1', type: 'fan' } as any, { _client: fakeClient } as any)
+
+    // Oscillate
+    await d.setState({ oscillate: true })
+    expect(calls.pop()?.body.command).toBe('setOscillation')
+
+    // Swing boolean
+    await d.setState({ swing: true })
+    expect(calls.pop()?.body.command).toBe('setSwing')
+
+    // Swing angle
+    await d.setState({ swingAngle: 45 })
+    const last = calls.pop()
+    expect(last.body.command).toBe('setSwing')
+    expect(last.body.parameter).toBe('45')
+  })
+
+  it('Light: color/CT mapping and setState commands', async () => {
+    const calls: any[] = []
+    const fakeClient: any = { setDeviceState: async (id: string, body: any) => { calls.push(body); return { ok: true } } }
+    const d = new LightDevice({ id: 'l1', type: 'light' } as any, { _client: fakeClient } as any)
+
+    // color temperature (mired)
+    await d.setState({ colorTemperature: 300 })
+    expect(calls.pop()?.command).toBe('setColorTemperature')
+
+    // hue + saturation
+    await d.setState({ hue: 120, saturation: 50 })
+    const c = calls.pop()
+    expect(c.command).toBe('setColor')
+    expect(c.parameter).toBe('120,50')
+
+    // hex color string
+    await d.setState({ color: '#ff0000' })
+    expect(calls.pop()?.command).toBe('setColor')
+  })
+
+  it('Curtain: position mapping and Matter attribute writes', async () => {
+    const calls: any[] = []
+    const fakeClient: any = { setDeviceState: async (id: string, body: any) => { calls.push(body); return { ok: true } } }
+    const d = new CurtainDevice({ id: 'c1', type: 'curtain' } as any, { _client: fakeClient } as any)
+
+    // Setting position via HAP-style setState
+    await d.setState({ position: 25 })
+    expect(calls.pop()?.command).toBe('setPosition')
+
+    // Matter descriptor write: call targetPosition write handler
+    const matter = d.createMatterAccessory({})
+    const cluster = matter.clusters.find((c: any) => c.type === 'Shade')
+    // targetPosition attribute exists and has a write function
+    expect(cluster.attributes.targetPosition.write).toBeTypeOf('function')
+    await cluster.attributes.targetPosition.write(80)
+    expect(calls.pop()?.command).toBe('setPosition')
+  })
+
+  it('Lock: user management actions map to correct commands', async () => {
+    const calls: any[] = []
+    const fakeClient: any = { setDeviceState: async (id: string, body: any) => { calls.push(body); return { ok: true } } }
+    const d = new LockDevice({ id: 'lock1', type: 'lock' } as any, { _client: fakeClient } as any)
+
+    // addUser via setState
+    await d.setState({ action: 'addUser', user: 'u1', pin: '1234' })
+    let last = calls.pop()
+    expect(last.command).toBe('addUserCode')
+    expect(last.parameter).toBe('u1:1234')
+
+    // removeUser
+    await d.setState({ action: 'removeUser', user: 'u1' })
+    last = calls.pop()
+    expect(last.command).toBe('removeUserCode')
+
+    // unlockWithPin
+    await d.setState({ action: 'unlockWithPin', pin: '0000' })
+    last = calls.pop()
+    expect(last.command).toBe('unlockWithPin')
+
+    // Matter descriptor write for addUser
+    const matter = d.createMatterAccessory({})
+    const mgmt = matter.clusters.find((c: any) => c.type === 'DoorLockUserManagement')
+    expect(mgmt.attributes.addUser.write).toBeTypeOf('function')
+    await mgmt.attributes.addUser.write({ user: 'u2', pin: '4321' })
+    last = calls.pop()
+    expect(last.command).toBe('addUserCode')
+    expect(last.parameter).toBe('u2:4321')
+  })
+})

package/test/matter-device-state.spec.ts

@@ -0,0 +1,101 @@
+import { describe, it, expect } from 'vitest'
+import { LightDevice, FanDevice, CurtainDevice, LockDevice, HumidifierMatterDevice } from '../src/devices/genericDevice'
+import { makeFakeApiWithMatter } from './helpers/matter-harness'
+
+const api = makeFakeApiWithMatter()
+
+describe('Matter device state translations', () => {
+  it('Light: reads and writes map to setState/getState', async () => {
+    const device = new LightDevice({ id: 'l-1', type: 'light', name: 'L1' }, {})
+    let lastSet: any = null
+    device.getState = async () => ({ on: true, brightness: 75, hue: 120, saturation: 50, colorTemperature: 350 })
+    device.setState = async (c: any) => { lastSet = c; return { success: true } }
+
+    const desc = device.createMatterAccessory(api)
+    const levelCluster = desc.clusters.find((c: any) => c.clusterId === 0x0008 || c.type === 'LevelControl')
+    expect(levelCluster).toBeDefined()
+    const levelAttr = levelCluster.attributes.currentLevel || levelCluster.attributes["0x0000"] || Object.values(levelCluster.attributes)[0]
+    const read = await levelAttr.read()
+    expect(read).toBe(75)
+
+    // write should call setState with brightness
+    await levelAttr.write(30)
+    expect(lastSet).toMatchObject({ brightness: 30 })
+  })
+
+  it('Fan: reads speed and writes speed/oscillation', async () => {
+    const device = new FanDevice({ id: 'f-1', type: 'fan', name: 'F1' }, {})
+    let last: any = null
+    device.getState = async () => ({ on: false, speed: 45, oscillating: true, swingMode: 'auto' })
+    device.setState = async (c: any) => { last = c; return { success: true } }
+
+    const desc = device.createMatterAccessory(api)
+    const fanCluster = desc.clusters.find((c: any) => c.clusterId === 0x0202 || c.type === 'FanControl')
+    expect(fanCluster).toBeDefined()
+    const speedAttr = fanCluster.attributes.rotationSpeed || Object.values(fanCluster.attributes)[0]
+    const speed = await speedAttr.read()
+    expect(speed).toBe(45)
+
+    await speedAttr.write(80)
+    expect(last).toMatchObject({ speed: 80 })
+
+    // oscillation write
+    const osc = fanCluster.attributes.oscillation
+    await osc.write(true)
+    expect(last).toMatchObject({ oscillate: true })
+  })
+
+  it('Curtain: reads and writes position', async () => {
+    const device = new CurtainDevice({ id: 'c-1', type: 'curtain', name: 'C1' }, {})
+    let last: any = null
+    device.getState = async () => ({ position: 42 })
+    device.setState = async (c: any) => { last = c; return { success: true } }
+
+    const desc = device.createMatterAccessory(api)
+    const shade = desc.clusters.find((c: any) => c.clusterId === 0x0102 || c.type === 'Shade')
+    expect(shade).toBeDefined()
+    const current = shade.attributes.currentPosition || shade.attributes["0x0000"]
+    const v = await current.read()
+    expect(v).toBe(42)
+
+    const target = shade.attributes.targetPosition || shade.attributes["0x0001"]
+    await target.write(10)
+    expect(last).toMatchObject({ position: 10 })
+  })
+
+  it('Lock: reads and writes locked state', async () => {
+    const device = new LockDevice({ id: 'k-1', type: 'lock', name: 'K1' }, {})
+    let last: any = null
+    device.getState = async () => ({ locked: true })
+    device.setState = async (c: any) => { last = c; return { success: true } }
+
+    const desc = device.createMatterAccessory(api)
+    const lock = desc.clusters.find((c: any) => c.clusterId === 0x0101 || c.type === 'DoorLock')
+    expect(lock).toBeDefined()
+    const lockAttr = lock.attributes.lockState || lock.attributes["0x0000"]
+    const v = await lockAttr.read()
+    expect(v).toBe(true)
+
+    await lockAttr.write(false)
+    expect(last).toMatchObject({ locked: false })
+  })
+
+  it('Humidifier: reads humidity and toggles on/off', async () => {
+    const device = new HumidifierMatterDevice({ id: 'h-1', type: 'humidifier', name: 'H1' }, {})
+    let last: any = null
+    device.getState = async () => ({ humidity: 55, on: false })
+    device.setState = async (c: any) => { last = c; return { success: true } }
+
+    const desc = device.createMatterAccessory(api)
+    const rh = desc.clusters.find((c: any) => c.clusterId === 0x0405 || c.type === 'RelativeHumiditySensor')
+    expect(rh).toBeDefined()
+    const humAttr = rh.attributes.currentRelativeHumidity || rh.attributes["0x0000"]
+    const hv = await humAttr.read()
+    expect(hv).toBe(55)
+
+    const onCluster = desc.clusters.find((c: any) => c.clusterId === 0x0006 || c.type === 'OnOff')
+    const onAttr = onCluster.attributes.onOff || onCluster.attributes["0x0000"]
+    await onAttr.write(true)
+    expect(last).toMatchObject({ on: true })
+  })
+})

package/test/matter-integration.spec.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect } from 'vitest'
+import { createPlatformProxy } from '../src/utils'
+import { makeFakeApiWithMatter, makeFakeApiWithoutMatter, makeFakeMatterApi } from './helpers/matter-harness'
+import SwitchBotHAPPlatform, { SwitchBotMatterPlatform } from '../src/platform'
+
+// Expanded Matter integration harness tests
+
+describe('Matter integration harness', () => {
+  it('registers Matter accessories when Matter API available', async () => {
+    // Instantiate the real Matter platform directly to test its registration path
+    const matterApi = makeFakeMatterApi()
+    const api = makeFakeApiWithMatter(matterApi)
+
+    const platform = new SwitchBotMatterPlatform(console as any, { devices: [{ id: 'm-1', type: 'light', name: 'L1' }], enableMatter: true, preferMatter: true } as any, api as any)
+
+    // Call register path directly
+    if (typeof (platform as any).registerMatterAccessories === 'function') {
+      await (platform as any).registerMatterAccessories()
+    } else if (typeof (platform as any).loadDevices === 'function') {
+      await (platform as any).loadDevices()
+    }
+
+    const regs = matterApi.getRegistered()
+    expect(regs.length).toBeGreaterThanOrEqual(1)
+    // The platform registers serialized accessories; ensure deviceId is present in context
+    expect(regs[0]).toHaveProperty('context')
+    expect(regs[0].context).toHaveProperty('deviceId', 'm-1')
+  })
+
+  it('falls back to HAP when Matter API unavailable', async () => {
+    // Directly instantiate the HAP platform to exercise HAP fallback
+    const api = makeFakeApiWithoutMatter()
+    const platform = new SwitchBotHAPPlatform(console as any, { devices: [{ id: 'h-1', type: 'light', name: 'H1' }], enableMatter: true, preferMatter: true } as any, api as any)
+
+    // call loadDevices for HAP flow
+    if (typeof (platform as any).loadDevices === 'function') await (platform as any).loadDevices()
+
+    // Platform should have an accessories map populated
+    const accMap = (platform as any).accessories
+    expect(accMap).toBeDefined()
+    const keys = Array.from(accMap.keys())
+    expect(keys.length).toBeGreaterThanOrEqual(1)
+  })
+
+  it('reuses restored Matter accessories instead of registering duplicates', async () => {
+    const matterApi = makeFakeMatterApi()
+    const api = makeFakeApiWithMatter(matterApi)
+
+    const platform = new SwitchBotMatterPlatform(console as any, { devices: [{ id: 'r-1', type: 'light', name: 'R1' }], enableMatter: true, preferMatter: true } as any, api as any)
+
+    // Simulate a restored accessory present before registration
+    const restored = { uuid: matterApi.uuid.generate('r-1'), displayName: 'Restored R1', context: { deviceId: 'r-1' } }
+    if (typeof (platform as any).configureMatterAccessory === 'function') {
+      await (platform as any).configureMatterAccessory(restored)
+    } else if (typeof (platform as any).configureAccessory === 'function') {
+      await (platform as any).configureAccessory(restored)
+    }
+
+    // Now call register path
+    if (typeof (platform as any).registerMatterAccessories === 'function') await (platform as any).registerMatterAccessories()
+    else if (typeof (platform as any).loadDevices === 'function') {
+      await (platform as any).loadDevices()
+      if (typeof (platform as any).registerMatterAccessories === 'function') await (platform as any).registerMatterAccessories()
+    }
+
+    const accs = (platform as any).accessories
+    const found = Array.from(accs.values()).some((a: any) => a && (a.uuid === restored.uuid || a.UUID === restored.uuid))
+    expect(found).toBeTruthy()
+  })
+})