Principle:Puppeteer Puppeteer Bluetooth Emulation
| Knowledge Sources | |
|---|---|
| Domains | Emulation, Bluetooth |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
Bluetooth emulation is the principle of simulating Bluetooth adapter states and peripheral device interactions within the browser, enabling automated testing of Web Bluetooth API functionality without requiring physical hardware.
Description
Bluetooth Emulation enables automation scripts to simulate the presence and behavior of Bluetooth hardware and peripherals for the purpose of testing web applications that use the Web Bluetooth API. Without emulation, testing Bluetooth-dependent functionality requires physical Bluetooth adapters and nearby devices, making automated testing impractical. Bluetooth emulation removes this dependency by providing a virtual Bluetooth stack.
The emulation model provides three core capabilities:
- Adapter state simulation: The virtual Bluetooth adapter can be set to one of three states:
- absent: No Bluetooth adapter is present. The Web Bluetooth API will report that Bluetooth is unavailable.
- powered-off: An adapter exists but is disabled. The API can detect the adapter but cannot scan for devices.
- powered-on: An adapter is present and active. The API can perform device discovery and connection.
- Additionally, low-energy (LE) Bluetooth support can be toggled independently.
- Peripheral simulation: Virtual Bluetooth peripherals can be registered with specific properties:
- Address: A simulated MAC address for the device (e.g., "09:09:09:09:09:09").
- Name: The human-readable device name that appears in the browser's device chooser prompt.
- Manufacturer data: Key-value pairs representing manufacturer-specific data encoded as base64, following the Bluetooth SIG company identifier standard.
- Known service UUIDs: The GATT service UUIDs that the device advertises, enabling the browser to filter devices by service.
- Device request prompt interaction: When a web page calls navigator.bluetooth.requestDevice(), the browser displays a device chooser prompt. In automation, this prompt is intercepted as a DeviceRequestPrompt object, which lists the available simulated devices and allows the automation script to select a device programmatically, completing the pairing flow.
An important current limitation is that Chromium's Bluetooth emulation is scoped to the browser context rather than individual pages, meaning that multiple pages within the same context share the same emulated Bluetooth state.
Usage
Use Bluetooth emulation when testing web applications that use the Web Bluetooth API for communicating with IoT devices, fitness trackers, medical devices, or any Bluetooth-enabled peripherals. This principle is essential for CI/CD pipelines where no physical Bluetooth hardware is available, for regression testing of device pairing flows, and for simulating various Bluetooth states (adapter absent, powered off) to test error handling paths. Combine with device request prompt interaction to fully automate the device selection dialog.
Theoretical Basis
The Bluetooth emulation model creates a virtual Bluetooth stack that the browser's Web Bluetooth implementation interacts with as if it were real hardware:
BLUETOOTH EMULATION MODEL
Web Page Browser Engine Emulation Layer
+------------------+ +------------------+ +------------------+
| navigator | | Web Bluetooth | | Virtual Adapter |
| .bluetooth |---->| Implementation |------->| state: powered-on|
| .requestDevice()| | | | leSupported: true|
| | | Device Chooser | | |
| | | Prompt | | Virtual Peripherals:
+------------------+ +------------------+ | - Device A (addr)|
| | - Device B (addr)|
v +------------------+
+------------------+
| DeviceRequest |
| Prompt (auto) |
| .devices[] |
| .select(device) |
| .cancel() |
+------------------+
Pseudocode for Bluetooth emulation:
1. Configure adapter:
page.bluetooth.emulateAdapter('powered-on', leSupported=true)
// Sends protocol command to set simulated adapter state
// Browser's Web Bluetooth stack now sees a powered-on adapter
2. Register simulated peripheral:
page.bluetooth.simulatePreconnectedPeripheral({
address: "09:09:09:09:09:09",
name: "Heart Rate Monitor",
manufacturerData: [{ key: 0x004C, data: "base64data" }],
knownServiceUuids: ["heart_rate"]
})
// Peripheral appears in browser's device discovery results
3. Handle device request prompt:
promptPromise = page.waitForDevicePrompt()
page.click('#pair-device-button') // triggers requestDevice()
prompt = await promptPromise
device = await prompt.waitForDevice(d => d.name == "Heart Rate Monitor")
await prompt.select(device)
// Device is now "paired" in the emulated environment
4. Test error states:
page.bluetooth.emulateAdapter('absent')
// navigator.bluetooth.requestDevice() will now reject
// Application error handling can be verified
5. Clean up:
page.bluetooth.disableEmulation()
// Removes all simulated state, returns to default behavior
The key design insight is that the emulation layer sits below the browser's Web Bluetooth implementation, so the browser code exercises the same paths it would with real hardware. This ensures that emulated tests accurately represent real-world behavior.