Implementation:Puppeteer Puppeteer BluetoothEmulation
| Sources | packages/puppeteer-core/src/api/BluetoothEmulation.ts |
|---|---|
| Domains | Bluetooth Emulation, Device Simulation, Web Bluetooth API |
| Last Updated | 2026-02-12 |
Overview
BluetoothEmulation is the interface that exposes bluetooth adapter emulation capabilities, allowing simulation of bluetooth adapters and preconnected peripherals for testing Web Bluetooth API interactions.
Description
The BluetoothEmulation interface provides three methods for controlling the emulated bluetooth environment. The emulateAdapter() method sets the bluetooth adapter state to one of three values defined by the AdapterState type: 'absent' (no adapter present), 'powered-off' (adapter present but powered down), or 'powered-on' (adapter active and ready). An optional leSupported parameter controls whether the adapter supports Bluetooth Low Energy.
The simulatePreconnectedPeripheral() method adds a simulated bluetooth peripheral to the environment. The peripheral is defined by the PreconnectedPeripheral interface, which requires an address string, a device name, an array of BluetoothManufacturerData objects (each with a company identifier key and base64-encoded data), and an array of known service UUIDs.
The disableEmulation() method removes all bluetooth simulation state.
This module also exports the BluetoothManufacturerData interface (containing key and data fields) and the PreconnectedPeripheral interface.
Important limitation: Per the Web Bluetooth specification, emulated adapters should be isolated per top-level navigable. However, Chromium's current implementation ties bluetooth emulation to the browser context rather than individual pages, meaning bluetooth emulation from different pages in the same browser context will interfere with each other.
Usage
The BluetoothEmulation interface is accessed through page.bluetooth. This feature is marked as experimental.
Code Reference
Source Location
packages/puppeteer-core/src/api/BluetoothEmulation.ts
Signature
export type AdapterState = 'absent' | 'powered-off' | 'powered-on';
export interface BluetoothManufacturerData {
key: number;
data: string;
}
export interface PreconnectedPeripheral {
address: string;
name: string;
manufacturerData: BluetoothManufacturerData[];
knownServiceUuids: string[];
}
export interface BluetoothEmulation {
emulateAdapter(state: AdapterState, leSupported?: boolean): Promise<void>;
disableEmulation(): Promise<void>;
simulatePreconnectedPeripheral(
preconnectedPeripheral: PreconnectedPeripheral,
): Promise<void>;
}
Import
import type {
BluetoothEmulation,
AdapterState,
PreconnectedPeripheral,
BluetoothManufacturerData,
} from 'puppeteer-core/src/api/BluetoothEmulation.js';
I/O Contract
Inputs
| Parameter | Type | Description |
|---|---|---|
| state (emulateAdapter) | AdapterState |
The desired adapter state: 'absent', 'powered-off', or 'powered-on' |
| leSupported (emulateAdapter) | undefined | Optional flag to mark if the adapter supports Bluetooth Low Energy |
| preconnectedPeripheral (simulatePreconnectedPeripheral) | PreconnectedPeripheral |
The peripheral to simulate, including address, name, manufacturer data, and service UUIDs |
Outputs
| Method | Return Type | Description |
|---|---|---|
| emulateAdapter() | Promise<void> |
Resolves when the adapter state has been set |
| disableEmulation() | Promise<void> |
Resolves when bluetooth emulation has been disabled |
| simulatePreconnectedPeripheral() | Promise<void> |
Resolves when the peripheral has been registered |
Usage Examples
// Enable bluetooth emulation and simulate a peripheral
await page.bluetooth.emulateAdapter('powered-on');
await page.bluetooth.simulatePreconnectedPeripheral({
address: '09:09:09:09:09:09',
name: 'SOME_NAME',
manufacturerData: [
{
key: 17,
data: 'AP8BAX8=',
},
],
knownServiceUuids: ['12345678-1234-5678-9abc-def123456789'],
});
// Test behavior with no bluetooth adapter
await page.bluetooth.emulateAdapter('absent');
// Web Bluetooth API calls will now fail as if no adapter is present
// Test behavior with powered-off adapter
await page.bluetooth.emulateAdapter('powered-off');
// Web Bluetooth API calls will behave as if adapter is powered down
// Clean up bluetooth emulation
await page.bluetooth.disableEmulation();