feat: Support GATT descriptor event (#3443)

chengweih001 · web-flow · commit 41eddf84d7d3 · 2025-05-26T10:10:33.000Z
diff --git a/src/bidiMapper/BidiNoOpParser.ts b/src/bidiMapper/BidiNoOpParser.ts
@@ -70,6 +70,11 @@ export class BidiNoOpParser implements BidiCommandParameterParser {
   ): Bluetooth.SimulateDescriptorParameters {
     return params as Bluetooth.SimulateDescriptorParameters;
   }
+  parseSimulateDescriptorResponseParameters(
+    params: unknown,
+  ): Bluetooth.SimulateDescriptorResponseParameters {
+    return params as Bluetooth.SimulateDescriptorResponseParameters;
+  }
   parseSimulateGattConnectionResponseParameters(
     params: unknown,
   ): Bluetooth.SimulateGattConnectionResponseParameters {
diff --git a/src/bidiMapper/BidiParser.ts b/src/bidiMapper/BidiParser.ts
@@ -54,6 +54,9 @@ export interface BidiCommandParameterParser {
   parseSimulateDescriptorParameters(
     params: unknown,
   ): Bluetooth.SimulateDescriptorParameters;
+  parseSimulateDescriptorResponseParameters(
+    params: unknown,
+  ): Bluetooth.SimulateDescriptorResponseParameters;
   parseSimulateGattConnectionResponseParameters(
     params: unknown,
   ): Bluetooth.SimulateGattConnectionResponseParameters;
diff --git a/src/bidiMapper/CommandProcessor.ts b/src/bidiMapper/CommandProcessor.ts
@@ -190,8 +190,10 @@ export class CommandProcessor extends EventEmitter<CommandProcessorEventsMap> {
           this.#parser.parseSimulateDescriptorParameters(command.params),
         );
       case 'bluetooth.simulateDescriptorResponse':
-        throw new UnknownErrorException(
-          `Method ${command.method} is not implemented.`,
+        return await this.#bluetoothProcessor.simulateDescriptorResponse(
+          this.#parser.parseSimulateDescriptorResponseParameters(
+            command.params,
+          ),
         );
       case 'bluetooth.simulateGattConnectionResponse':
         return await this.#bluetoothProcessor.simulateGattConnectionResponse(
diff --git a/src/bidiMapper/modules/bluetooth/BluetoothProcessor.ts b/src/bidiMapper/modules/bluetooth/BluetoothProcessor.ts
@@ -84,18 +84,18 @@ class BluetoothDevice {
 export class BluetoothProcessor {
   #eventManager: EventManager;
   #browsingContextStorage: BrowsingContextStorage;
-  #bluetoothDevices: Map<string, BluetoothDevice>;
+  #bluetoothDevices = new Map<string, BluetoothDevice>();
   // A map from a characteristic id from CDP to its BluetoothCharacteristic object.
-  #bluetoothCharacteristics: Map<string, BluetoothCharacteristic>;
+  #bluetoothCharacteristics = new Map<string, BluetoothCharacteristic>();
+  // A map from a descriptor id from CDP to its BluetoothDescriptor object.
+  #bluetoothDescriptors = new Map<string, BluetoothDescriptor>();
 
   constructor(
     eventManager: EventManager,
     browsingContextStorage: BrowsingContextStorage,
   ) {
     this.#eventManager = eventManager;
     this.#browsingContextStorage = browsingContextStorage;
-    this.#bluetoothDevices = new Map();
-    this.#bluetoothCharacteristics = new Map();
   }
 
   #getDevice(address: string): BluetoothDevice {
@@ -163,6 +163,7 @@ export class BluetoothProcessor {
     );
     this.#bluetoothDevices.clear();
     this.#bluetoothCharacteristics.clear();
+    this.#bluetoothDescriptors.clear();
     await context.cdpTarget.browserCdpClient.sendCommand(
       'BluetoothEmulation.enable',
       {
@@ -182,6 +183,7 @@ export class BluetoothProcessor {
     );
     this.#bluetoothDevices.clear();
     this.#bluetoothCharacteristics.clear();
+    this.#bluetoothDescriptors.clear();
     return {};
   }
 
@@ -334,14 +336,13 @@ export class BluetoothProcessor {
             descriptorUuid: params.descriptorUuid,
           },
         );
-        characteristic.descriptors.set(
+        const descriptor = new BluetoothDescriptor(
+          response.descriptorId,
           params.descriptorUuid,
-          new BluetoothDescriptor(
-            response.descriptorId,
-            params.descriptorUuid,
-            characteristic,
-          ),
+          characteristic,
         );
+        characteristic.descriptors.set(params.descriptorUuid, descriptor);
+        this.#bluetoothDescriptors.set(descriptor.id, descriptor);
         return {};
       }
       case 'remove': {
@@ -356,6 +357,7 @@ export class BluetoothProcessor {
           },
         );
         characteristic.descriptors.delete(params.descriptorUuid);
+        this.#bluetoothDescriptors.delete(descriptor.id);
         return {};
       }
       default:
@@ -365,6 +367,34 @@ export class BluetoothProcessor {
     }
   }
 
+  async simulateDescriptorResponse(
+    params: Bluetooth.SimulateDescriptorResponseParameters,
+  ): Promise<EmptyResult> {
+    const context = this.#browsingContextStorage.getContext(params.context);
+    const device = this.#getDevice(params.address);
+    const service = this.#getService(device, params.serviceUuid);
+    const characteristic = this.#getCharacteristic(
+      service,
+      params.characteristicUuid,
+    );
+    const descriptor = this.#getDescriptor(
+      characteristic,
+      params.descriptorUuid,
+    );
+    await context.cdpTarget.browserCdpClient.sendCommand(
+      'BluetoothEmulation.simulateDescriptorOperationResponse',
+      {
+        descriptorId: descriptor.id,
+        type: params.type,
+        code: params.code,
+        ...(params.data && {
+          data: btoa(String.fromCharCode(...params.data)),
+        }),
+      },
+    );
+    return {};
+  }
+
   async simulateGattConnectionResponse(
     params: Bluetooth.SimulateGattConnectionResponseParameters,
   ): Promise<EmptyResult> {
@@ -529,6 +559,33 @@ export class BluetoothProcessor {
         );
       },
     );
+    cdpTarget.browserCdpClient.on(
+      'BluetoothEmulation.descriptorOperationReceived',
+      (event) => {
+        if (!this.#bluetoothDescriptors.has(event.descriptorId)) {
+          return;
+        }
+        const descriptor = this.#bluetoothDescriptors.get(event.descriptorId)!;
+        this.#eventManager.registerEvent(
+          {
+            type: 'event',
+            method: 'bluetooth.descriptorEventGenerated',
+            params: {
+              context: cdpTarget.id,
+              address: descriptor.characteristic.service.device.address,
+              serviceUuid: descriptor.characteristic.service.uuid,
+              characteristicUuid: descriptor.characteristic.uuid,
+              descriptorUuid: descriptor.uuid,
+              type: event.type,
+              ...(event.data && {
+                data: Array.from(atob(event.data), (c) => c.charCodeAt(0)),
+              }),
+            },
+          },
+          cdpTarget.id,
+        );
+      },
+    );
   }
 
   async handleRequestDevicePrompt(
diff --git a/src/bidiTab/BidiParser.ts b/src/bidiTab/BidiParser.ts
@@ -69,6 +69,11 @@ export class BidiParser implements BidiCommandParameterParser {
   ): Bluetooth.SimulateDescriptorParameters {
     return Parser.Bluetooth.parseSimulateDescriptorParams(params);
   }
+  parseSimulateDescriptorResponseParameters(
+    params: unknown,
+  ): Bluetooth.SimulateDescriptorResponseParameters {
+    return Parser.Bluetooth.parseSimulateDescriptorResponseParams(params);
+  }
   parseSimulateGattConnectionResponseParameters(
     params: unknown,
   ): Bluetooth.SimulateGattConnectionResponseParameters {
diff --git a/src/protocol-parser/protocol-parser.ts b/src/protocol-parser/protocol-parser.ts
@@ -496,6 +496,15 @@ export namespace Bluetooth {
       WebDriverBidiBluetooth.Bluetooth.SimulateDescriptorParametersSchema,
     ) as Protocol.Bluetooth.SimulateDescriptorParameters;
   }
+  export function parseSimulateDescriptorResponseParams(
+    params: unknown,
+  ): Protocol.Bluetooth.SimulateDescriptorResponseParameters {
+    return parseObject(
+      params,
+      WebDriverBidiBluetooth.Bluetooth
+        .SimulateDescriptorResponseParametersSchema,
+    ) as Protocol.Bluetooth.SimulateDescriptorResponseParameters;
+  }
   export function parseSimulateGattConnectionResponseParams(
     params: unknown,
   ): Protocol.Bluetooth.SimulateGattConnectionResponseParameters {
diff --git a/src/protocol/chromium-bidi.ts b/src/protocol/chromium-bidi.ts
@@ -107,6 +107,7 @@ export namespace Bluetooth {
     RequestDevicePromptUpdated = 'bluetooth.requestDevicePromptUpdated',
     GattConnectionAttempted = 'bluetooth.gattConnectionAttempted',
     CharacteristicEventGenerated = 'bluetooth.characteristicEventGenerated',
+    DescriptorEventGenerated = 'bluetooth.descriptorEventGenerated',
   }
 }
 
@@ -137,7 +138,8 @@ export type CommandResponse =
 export type BluetoothEvent =
   | ExternalSpecEvent<WebDriverBidiBluetooth.Bluetooth.RequestDevicePromptUpdated>
   | ExternalSpecEvent<WebDriverBidiBluetooth.Bluetooth.GattConnectionAttempted>
-  | ExternalSpecEvent<WebDriverBidiBluetooth.Bluetooth.CharacteristicEventGenerated>;
+  | ExternalSpecEvent<WebDriverBidiBluetooth.Bluetooth.CharacteristicEventGenerated>
+  | ExternalSpecEvent<WebDriverBidiBluetooth.Bluetooth.DescriptorEventGenerated>;
 export type Event = WebDriverBidi.Event | Cdp.Event | BluetoothEvent;
 
 export const EVENT_NAMES = new Set([
diff --git a/tests/bluetooth/test_descriptor_emulation.py b/tests/bluetooth/test_descriptor_emulation.py
@@ -15,7 +15,8 @@
 
 import pytest
 import pytest_asyncio
-from test_helpers import execute_command
+from test_helpers import (execute_command, send_JSON_command, subscribe,
+                          wait_for_event)
 
 from . import (BATTERY_SERVICE_UUID,
                CHARACTERISTIC_USER_DESCRIPTION_DESCRIPTOR_UUID,
@@ -25,6 +26,25 @@
                create_gatt_connection, disable_simulation, setup_device,
                setup_granted_device, simulate_descriptor, simulate_service)
 
+DESCRIPTOR_EVENT_GENERATED = 'bluetooth.descriptorEventGenerated'
+
+
+async def setup_descriptor(websocket, context_id: str, html, service_uuid: str,
+                           characteristic_uuid: str, characteristic_properties,
+                           descriptor_uuid: str):
+    device_address = await setup_granted_device(websocket, context_id, html,
+                                                [service_uuid])
+    await create_gatt_connection(websocket, context_id)
+    await simulate_service(websocket, context_id, device_address, service_uuid,
+                           'add')
+    await add_characteristic(websocket, context_id, device_address,
+                             service_uuid, characteristic_uuid,
+                             characteristic_properties)
+    await simulate_descriptor(websocket, context_id, device_address,
+                              service_uuid, characteristic_uuid,
+                              descriptor_uuid, 'add')
+    return device_address
+
 
 async def get_descriptors(websocket, context_id: str, service_uuid: str,
                           characteristic_uuid: str) -> list[str]:
@@ -265,3 +285,137 @@ async def test_bluetooth_add_descriptor_to_unknown_characteristic(
             websocket, context_id, device_address, HEART_RATE_SERVICE_UUID,
             MEASUREMENT_INTERVAL_CHARACTERISTIC_UUID,
             CHARACTERISTIC_USER_DESCRIPTION_DESCRIPTOR_UUID, 'add')
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize('capabilities', [{
+    'goog:chromeOptions': {
+        'args': ['--enable-features=WebBluetooth']
+    }
+}],
+                         indirect=True)
+async def test_bluetooth_descriptor_write_event(websocket, context_id, html):
+    await setup_descriptor(websocket, context_id, html,
+                           HEART_RATE_SERVICE_UUID,
+                           MEASUREMENT_INTERVAL_CHARACTERISTIC_UUID,
+                           {'write': True},
+                           CHARACTERISTIC_USER_DESCRIPTION_DESCRIPTOR_UUID)
+    await subscribe(websocket, [DESCRIPTOR_EVENT_GENERATED])
+    expected_data = [42, 27]
+    await send_JSON_command(
+        websocket, {
+            'method': 'script.evaluate',
+            'params': {
+                'expression': f'''
+                    (async () => {{
+                        const service = await device.gatt.getPrimaryService('{HEART_RATE_SERVICE_UUID}');
+                        const characteristic = await service.getCharacteristic('{MEASUREMENT_INTERVAL_CHARACTERISTIC_UUID}');
+                        const descriptor = await characteristic.getDescriptor('{CHARACTERISTIC_USER_DESCRIPTION_DESCRIPTOR_UUID}');
+                        await descriptor.writeValue(new Uint8Array({expected_data}));
+                    }})();
+                ''',
+                'awaitPromise': False,
+                'target': {
+                    'context': context_id,
+                },
+                'userActivation': True
+            }
+        })
+    event = await wait_for_event(websocket, DESCRIPTOR_EVENT_GENERATED)
+    assert event['params'] == {
+        'context': context_id,
+        'address': FAKE_DEVICE_ADDRESS,
+        'serviceUuid': HEART_RATE_SERVICE_UUID,
+        'characteristicUuid': MEASUREMENT_INTERVAL_CHARACTERISTIC_UUID,
+        'descriptorUuid': CHARACTERISTIC_USER_DESCRIPTION_DESCRIPTOR_UUID,
+        'type': 'write',
+        'data': expected_data,
+    }
+
+    await execute_command(
+        websocket, {
+            'method': 'bluetooth.simulateDescriptorResponse',
+            'params': {
+                'context': context_id,
+                'address': FAKE_DEVICE_ADDRESS,
+                'serviceUuid': HEART_RATE_SERVICE_UUID,
+                'characteristicUuid': MEASUREMENT_INTERVAL_CHARACTERISTIC_UUID,
+                'descriptorUuid': CHARACTERISTIC_USER_DESCRIPTION_DESCRIPTOR_UUID,
+                'type': 'write',
+                'code': 0x0
+            }
+        })
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize('capabilities', [{
+    'goog:chromeOptions': {
+        'args': ['--enable-features=WebBluetooth']
+    }
+}],
+                         indirect=True)
+async def test_bluetooth_descriptor_read_event(websocket, context_id, html):
+    await setup_descriptor(websocket, context_id, html,
+                           HEART_RATE_SERVICE_UUID,
+                           MEASUREMENT_INTERVAL_CHARACTERISTIC_UUID,
+                           {'read': True},
+                           CHARACTERISTIC_USER_DESCRIPTION_DESCRIPTOR_UUID)
+    await subscribe(websocket, [DESCRIPTOR_EVENT_GENERATED])
+    await send_JSON_command(
+        websocket, {
+            'method': 'script.evaluate',
+            'params': {
+                'expression': f'''
+                    let readResult;
+                    (async () => {{
+                        const service = await device.gatt.getPrimaryService('{HEART_RATE_SERVICE_UUID}');
+                        const characteristic = await service.getCharacteristic('{MEASUREMENT_INTERVAL_CHARACTERISTIC_UUID}');
+                        const descriptor = await characteristic.getDescriptor('{CHARACTERISTIC_USER_DESCRIPTION_DESCRIPTOR_UUID}');
+                        readResult = await descriptor.readValue();
+                    }})();
+                ''',
+                'awaitPromise': False,
+                'target': {
+                    'context': context_id,
+                },
+                'userActivation': True
+            }
+        })
+    event = await wait_for_event(websocket, DESCRIPTOR_EVENT_GENERATED)
+    assert event['params'] == {
+        'context': context_id,
+        'address': FAKE_DEVICE_ADDRESS,
+        'serviceUuid': HEART_RATE_SERVICE_UUID,
+        'characteristicUuid': MEASUREMENT_INTERVAL_CHARACTERISTIC_UUID,
+        'descriptorUuid': CHARACTERISTIC_USER_DESCRIPTION_DESCRIPTOR_UUID,
+        'type': 'read',
+    }
+
+    expected_data = [1, 2]
+    await execute_command(
+        websocket, {
+            'method': 'bluetooth.simulateDescriptorResponse',
+            'params': {
+                'context': context_id,
+                'address': FAKE_DEVICE_ADDRESS,
+                'serviceUuid': HEART_RATE_SERVICE_UUID,
+                'characteristicUuid': MEASUREMENT_INTERVAL_CHARACTERISTIC_UUID,
+                'descriptorUuid': CHARACTERISTIC_USER_DESCRIPTION_DESCRIPTOR_UUID,
+                'type': 'read',
+                'code': 0x0,
+                'data': expected_data
+            }
+        })
+    response = await execute_command(
+        websocket, {
+            'method': 'script.evaluate',
+            'params': {
+                'expression': 'String.fromCharCode(...new Uint8Array(readResult.buffer))',
+                'awaitPromise': False,
+                'target': {
+                    'context': context_id,
+                },
+                'userActivation': True
+            }
+        })
+    assert [ord(c) for c in response['result']['value']] == expected_data
