Chrome 56 版開始支援網路藍牙,讓開發人員編寫網頁應用程式,直接與使用者對話藍牙裝置。例如,Espruino 網頁編輯器可將程式碼上傳到相容的藍牙裝置。現在可以使用 Puppeteer 測試這些應用程式。
這篇網誌文章會逐步說明如何使用 Puppeteer 來操作及測試支援藍牙的網頁應用程式。這項改善的關鍵在於 Puppeteer 能夠操作 Chrome 的藍牙裝置選擇工具。
如果您不熟悉在 Chrome 中使用網路藍牙的方式,請觀看以下影片,瞭解 Espruino 網頁編輯器中的藍牙提示:
如要追蹤這篇網誌文章,您需要具備藍牙功能的網頁應用程式、可與 Puppeteer v21.4.0 以上版本通訊的藍牙裝置。
啟動瀏覽器
和大多數 Puppeteer 指令碼一樣,請先使用 Puppeteer.launch()
啟動瀏覽器。為了存取藍牙功能,您必須提供幾個額外引數:
- 停用無頭模式:這樣 Puppeteer 會開啟可見的 Chrome 瀏覽器視窗來執行測試。如果想在沒有 UI 的情況下執行,請使用新的無頭模式。舊版無頭模式不支援顯示藍牙提示。
- Chromium 的其他引數:傳遞「啟用網路藍牙」引數。
import puppeteer from 'puppeteer';
const browser = await puppeteer.launch({
headless: false,
args: ["--enable-features=WebBluetooth"],
});
開啟第一個網頁時,通常建議使用無痕模式的瀏覽器內容。這有助於避免使用指令碼執行的測試之間洩露權限 (但 Puppeteer 無法防止某些 OS 層級的共用狀態)。請參考下列程式碼:
const browserContext = await browser.createIncognitoBrowserContext();
const page = await browserContext.newPage();
然後,您就可以前往目前使用 Page.goto()
測試的網頁應用程式網址。
開啟藍牙裝置提示
使用 Puppeteer 開啟網頁應用程式的 Puppeteer 頁面後,即可連上藍牙裝置讀取資料。此步驟假設您網頁應用程式有一個可執行 JavaScript 的按鈕 (包括呼叫 navigator.bluetooth.requestDevice()
)。
使用 Page.locator().click()
按下該按鈕,並使用 Page.waitForDevicePrompt()
辨識藍牙裝置選擇器是否顯示。您必須在點選按鈕前呼叫 waitForDevicePrompt()
,否則提示已經開啟,且無法偵測到。
由於這兩種 Puppeteer 方法都傳回承諾,因此使用 Promise.all()
時,能以正確順序同時呼叫這些方法,既簡單又方便:
const [devicePrompt] = await Promise.all([
page.waitForDevicePrompt(),
page.locator("#start-test-button").click(),
]);
waitForDevicePrompt()
傳回的承諾會解析為 DeviceRequestPrompt
物件,您可以在稍後選取要連結的藍牙裝置。
選取裝置
使用 DeviceRequestPrompt.waitForDevice()
和 DeviceRequestPrompt.select()
尋找並連線至正確的藍牙裝置。
每當 Chrome 找到含有裝置基本資訊的藍牙裝置時,DeviceRequestPrompt.waitForDevice()
就會呼叫提供的回呼。當回呼第一次傳回 true 時,waitForDevice()
會解析為相符的 DeviceRequestPromptDevice
。將該裝置傳送至「DeviceRequestPrompt.select()
」,即可選取該藍牙裝置並連線。
const bluetoothDevice = await devicePrompt.waitForDevice(
(d) => d.name == wantedDeviceName,
);
await devicePrompt.select(bluetoothDevice);
DeviceRequestPrompt.select()
問題解決後,Chrome 就會連線至裝置,且網頁可以存取裝置。
從裝置閱讀
此時,你的網頁應用程式將連線至指定的藍牙裝置,以便讀取裝置中的資訊。如下所示:
const serviceId = "6e400001-b5a3-f393-e0a9-e50e24dcca9e";
const device = await navigator.bluetooth.requestDevice({
filters: [{ services: [serviceId] }],
});
const gattServer = await device.gatt.connect();
const service = await gattServer.getPrimaryService(serviceId);
const characteristic = await service.getCharacteristic(
"0b30afd0-193e-11eb-adc1-0242ac120002",
);
const dataView = await characteristic.readValue();
如需深入瞭解此一系列 API 呼叫的逐步操作說明,請參閱透過 JavaScript 與藍牙裝置通訊。
此時,您已瞭解如何運用 Puppeteer 自動使用支援藍牙的網頁應用程式,將原先的人為從藍牙裝置選擇工具選單中選取裝置。雖然這種做法通常很實用,但您也可以直接為這類網頁應用程式撰寫端對端測試。
建立測試
從目前為止擷取程式碼到撰寫完整測試,缺少的部分是從網頁應用程式擷取資訊,並放入 Puppeteer 指令碼中。取得測試後,您就可以直接使用測試程式庫 (例如 TAP 或 mocha) 來驗證是否已讀取和回報正確資料。
最簡單的做法是將資料寫入 DOM。JavaScript 在不使用額外的程式庫的情況下,有很豐富的方法可以執行此操作。回到假設性網頁應用程式,當狀態指標讀取藍牙裝置中的資料,或輸出欄位中的常值資料時,狀態指標顏色可能會變更。例如:
const dataDisplayElement = document.querySelector('#data-display');
dataDisplayElement.innerText = dataView.getUint8();
您可以透過 Puppeteer 使用 Page.$eval()
,將這項資料從頁面的 DOM 提取,並匯入測試指令碼。$eval()
會使用與 document.querySelector()
相同的邏輯尋找元素,然後以該元素做為引數執行提供的回呼函式。將這個變數做為變數後,請使用斷言程式庫測試資料是否符合預期。
const dataText = await page.$eval('#data-display', (el) => el.innerText);
equal(17, dataText);
其他資源
如要查看更複雜的範例,瞭解如何使用 Puppeteer 為支援藍牙的網頁應用程式編寫測試,請前往這個存放區:https://github.com/WebBluetoothCG/manual-tests/。網路藍牙社群群組負責維護這一系列的測試,而所有測試都可以透過瀏覽器或本機執行。「唯讀特性」test 與這篇網誌文章所使用的範例最為相似。
特別銘謝
感謝 Vincent Scheib 開始進行這項專案,並為這篇文章提供寶貴意見。