Merge pull request #71 from loginov-rocks/dev

v1.6.0

Author: loginov-rocks

.vscode/settings.json

@@ -1,7 +1,7 @@
 {
   "name": "bluetooth-terminal",
-  "version": "1.5.0",
-  "description": "ES6 class for serial communication with Bluetooth Low Energy (Smart) devices",
+  "version": "1.6.0",
+  "description": "Class that enables bidirectional serial communication between web browsers and Bluetooth Low Energy modules via the Web Bluetooth API",
   "main": "dist/BluetoothTerminal.js",
   "files": [
     "dist"
@@ -35,7 +35,7 @@
     "iot",
     "physical-web",
     "serial",
-    "smart"
+    "terminal"
   ],
   "author": "Danila Loginov <danila@loginov.rocks> (https://loginov.rocks)",
   "license": "MIT",
@@ -48,16 +48,16 @@
     "@babel/core": "^7.26.10",
     "@babel/preset-env": "^7.26.9",
     "@babel/preset-typescript": "^7.27.0",
-    "@eslint/js": "^9.24.0",
+    "@eslint/js": "^9.25.1",
     "@types/jest": "^29.5.14",
     "babel-jest": "^29.7.0",
-    "eslint": "^9.24.0",
+    "eslint": "^9.25.1",
     "eslint-config-google": "^0.14.0",
     "eslint-plugin-jsdoc": "^50.6.9",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
     "typescript": "^5.8.3",
-    "typescript-eslint": "^8.29.0",
+    "typescript-eslint": "^8.31.0",
     "web-bluetooth-mock": "^1.2.0"
   },
   "jest": {

README.md

@@ -0,0 +1,139 @@
+// Test file uses `require()` style imports because the BluetoothTerminal module is exported only as a CommonJS module.
+/* eslint-disable @typescript-eslint/no-require-imports */
+// Import the `TextEncoder` and `TextDecoder` from the Node.js `util` module and add them to the global scope. These
+// are natively available in browsers but need to be explicitly added in Node.js test environments. The
+// `BluetoothTerminal` class requires these for encoding/decoding messages sent to and received from Bluetooth devices.
+const util = require('util');
+global.TextDecoder = util.TextDecoder;
+global.TextEncoder = util.TextEncoder;
+
+const {DeviceMock, WebBluetoothMock} = require('web-bluetooth-mock');
+
+const BluetoothTerminal = require('./BluetoothTerminal');
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const changeCharacteristicValue = (bluetoothTerminal: any, value: string) => {
+  // Simulate Bluetooth characteristic value change: set value and dispatch the `characteristicvaluechanged` event to
+  // trigger the notification handler, mimicking how the Web Bluetooth API would behave when receiving data from the
+  // connected device.
+  const characteristic = bluetoothTerminal._characteristic;
+  characteristic.value = new TextEncoder().encode(value);
+  characteristic.dispatchEvent(new CustomEvent('characteristicvaluechanged'));
+};
+
+describe('Communication', () => {
+  // Using `any` type to access private members for testing purposes. This allows for thorough testing of the internal
+  // state and behavior while maintaining strong encapsulation in the production code.
+  let bt: any; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+  beforeEach(() => {
+    bt = new BluetoothTerminal();
+    const device = new DeviceMock('Simon', [0xFFE0]);
+    navigator.bluetooth = new WebBluetoothMock([device]);
+  });
+
+  describe('When sending a message...', () => {
+    it('should send the message with the send separator', async () => {
+      await bt.connect();
+
+      jest.spyOn(bt._characteristic, 'writeValue');
+
+      await bt.send('Hello, world!');
+
+      expect(bt._characteristic.writeValue).toHaveBeenCalledTimes(1);
+      expect(bt._characteristic.writeValue).toHaveBeenCalledWith(new TextEncoder().encode('Hello, world!\n'));
+    });
+
+    it('should send the message longer than the characteristic value size by splitting it into chunks', async () => {
+      await bt.connect();
+
+      jest.spyOn(bt._characteristic, 'writeValue');
+
+      await bt.send('This message is longer than the default characteristic value size of 20 chars, so it will be ' +
+        'split into 6 chunks');
+
+      expect(bt._characteristic.writeValue).toHaveBeenCalledTimes(6);
+      expect(bt._characteristic.writeValue).toHaveBeenNthCalledWith(1,
+          new TextEncoder().encode('This message is long'));
+      expect(bt._characteristic.writeValue).toHaveBeenNthCalledWith(2,
+          new TextEncoder().encode('er than the default '));
+      expect(bt._characteristic.writeValue).toHaveBeenNthCalledWith(3,
+          new TextEncoder().encode('characteristic value'));
+      expect(bt._characteristic.writeValue).toHaveBeenNthCalledWith(4,
+          new TextEncoder().encode(' size of 20 chars, s'));
+      expect(bt._characteristic.writeValue).toHaveBeenNthCalledWith(5,
+          new TextEncoder().encode('o it will be split i'));
+      expect(bt._characteristic.writeValue).toHaveBeenNthCalledWith(6, new TextEncoder().encode('nto 6 chunks\n'));
+    });
+
+    it('should throw an error when no message is provided', () => {
+      return expect(bt.send()).rejects.toThrow();
+    });
+
+    it('should throw an error when an empty string is provided', () => {
+      return expect(bt.send('')).rejects.toThrow();
+    });
+
+    it('should throw an error when no device is connected', () => {
+      return expect(bt.send('Hello, world!')).rejects.toThrow();
+    });
+
+    it('should throw an error when the device disconnects while sending the long message', async () => {
+      await bt.connect();
+
+      jest.spyOn(bt._characteristic, 'writeValue');
+
+      const promise = bt.send('This message is longer than the default characteristic value size of 20 chars');
+
+      expect(bt._characteristic.writeValue).toHaveBeenCalledTimes(1);
+      expect(bt._characteristic.writeValue).toHaveBeenCalledWith(new TextEncoder().encode('This message is long'));
+
+      // Disconnect the device while sending the long message split into chunks before the Promise resolves. This tests
+      // the error handling when the connection is lost after the first chunk is sent, but before the remaining chunks
+      // can be sent.
+      bt.disconnect();
+
+      await expect(promise).rejects.toThrow();
+    });
+  });
+
+  describe('When receiving a message...', () => {
+    let onReceiveCallback: jest.Func;
+
+    beforeEach(() => {
+      onReceiveCallback = jest.fn();
+      bt.onReceive(onReceiveCallback);
+
+      return bt.connect();
+    });
+
+    it('should not invoke the onReceive callback until the receive separator is received', () => {
+      changeCharacteristicValue(bt, 'Hello, world!');
+
+      expect(onReceiveCallback).not.toHaveBeenCalled();
+    });
+
+    it('should invoke the onReceive callback when data with the receive separator is received', () => {
+      changeCharacteristicValue(bt, 'Hello, world!\n');
+
+      expect(onReceiveCallback).toHaveBeenCalledTimes(1);
+      expect(onReceiveCallback).toHaveBeenCalledWith('Hello, world!');
+    });
+
+    it('should invoke the onReceive callback when data with multiple receive separators is received', () => {
+      changeCharacteristicValue(bt, 'Hello, world!\nCiao, mondo!\n');
+
+      expect(onReceiveCallback).toHaveBeenCalledTimes(2);
+      expect(onReceiveCallback).toHaveBeenNthCalledWith(1, 'Hello, world!');
+      expect(onReceiveCallback).toHaveBeenNthCalledWith(2, 'Ciao, mondo!');
+    });
+
+    it('should invoke the onReceive callback only with the complete message until the receive separator is received',
+        () => {
+          changeCharacteristicValue(bt, 'Hello, world!\nCiao, mondo!');
+
+          expect(onReceiveCallback).toHaveBeenCalledTimes(1);
+          expect(onReceiveCallback).toHaveBeenCalledWith('Hello, world!');
+        });
+  });
+});

package-lock.json

@@ -0,0 +1,189 @@
+// Test file uses `require()` style imports because the BluetoothTerminal module is exported only as a CommonJS module.
+/* eslint-disable @typescript-eslint/no-require-imports */
+const {DeviceMock, WebBluetoothMock} = require('web-bluetooth-mock');
+
+const BluetoothTerminal = require('./BluetoothTerminal');
+
+const unexpectedlyDisconnect = (device: any) => { // eslint-disable-line @typescript-eslint/no-explicit-any
+  // Simulate an unexpected disconnection by dispatching the corresponding Web Bluetooth API event.
+  device.dispatchEvent(new CustomEvent('gattserverdisconnected'));
+};
+
+describe('Connection', () => {
+  // Using `any` type to access private members for testing purposes. This allows for thorough testing of the internal
+  // state and behavior while maintaining strong encapsulation in the production code.
+  let bt: any; // eslint-disable-line @typescript-eslint/no-explicit-any
+  let device: any; // eslint-disable-line @typescript-eslint/no-explicit-any
+
+  beforeEach(() => {
+    bt = new BluetoothTerminal();
+    device = new DeviceMock('Simon', [0xFFE0]);
+    navigator.bluetooth = new WebBluetoothMock([device]);
+  });
+
+  describe('When connecting to the device...', () => {
+    beforeEach(() => {
+      jest.spyOn(navigator.bluetooth, 'requestDevice');
+      jest.spyOn(device.gatt, 'connect');
+    });
+
+    it('should open the browser Bluetooth device picker and connect to the selected device', async () => {
+      await expect(bt.connect()).resolves.toBeUndefined();
+      expect(navigator.bluetooth.requestDevice).toHaveBeenCalledTimes(1);
+      expect(device.gatt.connect).toHaveBeenCalledTimes(1);
+    });
+
+    it('should connect to the previously selected device on subsequent calls to avoid prompting the user multiple ' +
+      'times', async () => {
+      // The first connection should open the browser Bluetooth device picker.
+      await expect(bt.connect()).resolves.toBeUndefined();
+      // The second connection should connect to the previously selected device.
+      await expect(bt.connect()).resolves.toBeUndefined();
+      expect(navigator.bluetooth.requestDevice).toHaveBeenCalledTimes(1);
+      expect(device.gatt.connect).toHaveBeenCalledTimes(2);
+    });
+
+    it('should invoke the onConnect callback after connection', async () => {
+      const callback = jest.fn();
+      bt.onConnect(callback);
+
+      await expect(bt.connect()).resolves.toBeUndefined();
+
+      expect(callback).toHaveBeenCalledTimes(1);
+    });
+
+    it('should throw an error when no device with a matching service UUID is available', async () => {
+      device = new DeviceMock('Simon', [1234]);
+      navigator.bluetooth = new WebBluetoothMock([device]);
+      jest.spyOn(navigator.bluetooth, 'requestDevice');
+
+      await expect(bt.connect()).rejects.toThrow();
+      expect(navigator.bluetooth.requestDevice).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('When disconnecting from the device...', () => {
+    beforeEach(() => {
+      jest.spyOn(device.gatt, 'disconnect');
+
+      return bt.connect();
+    });
+
+    it('should disconnect only once despite subsequent calls', () => {
+      bt.disconnect();
+      bt.disconnect(); // The second call shouldn't trigger another disconnect.
+
+      expect(device.gatt.disconnect).toHaveBeenCalledTimes(1);
+    });
+
+    it('should invoke the onDisconnect callback after disconnection', () => {
+      const callback = jest.fn();
+      bt.onDisconnect(callback);
+
+      bt.disconnect();
+
+      expect(callback).toHaveBeenCalledTimes(1);
+    });
+
+    it('should avoid disconnecting when the device unexpectedly disconnects', () => {
+      // Simulate an unexpected disconnection by setting the Web Bluetooth API connection flag.
+      device.gatt.connected = false;
+
+      bt.disconnect();
+
+      expect(device.gatt.disconnect).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('When the device unexpectedly disconnects...', () => {
+    beforeEach(() => {
+      jest.spyOn(device.gatt, 'connect');
+
+      return bt.connect();
+    });
+
+    it('should invoke the onDisconnect callback', () => {
+      const callback = jest.fn();
+      bt.onDisconnect(callback);
+
+      unexpectedlyDisconnect(device);
+
+      expect(callback).toHaveBeenCalledTimes(1);
+    });
+
+    it('should attempt to reconnect to the device', () => {
+      // Verify that connect was already called once during test setup.
+      expect(device.gatt.connect).toHaveBeenCalledTimes(1);
+
+      unexpectedlyDisconnect(device);
+
+      // Verify that a reconnection attempt was made.
+      expect(device.gatt.connect).toHaveBeenCalledTimes(2);
+    });
+
+    it('should invoke the onConnect callback after reconnection', (done) => {
+      const callback = jest.fn();
+      bt.onConnect(callback);
+
+      unexpectedlyDisconnect(device);
+
+      // Using `setTimeout()` to defer verification until after the current call stack has completed. This allows the
+      // reconnection Promise chain to resolve before checking if the onConnect callback was triggered. Without this,
+      // the check can happen before the async reconnection process finishes.
+      setTimeout(() => {
+        expect(callback).toHaveBeenCalledTimes(1);
+        // Signal Jest that the asynchronous test is complete.
+        done();
+      }, 0);
+    });
+
+    it('should log an error when a reconnection attempt fails', (done) => {
+      jest.spyOn(bt, '_logError');
+
+      // Verify that connect was already called once during test setup.
+      expect(device.gatt.connect).toHaveBeenCalledTimes(1);
+
+      // Mock the connect method to simulate a connection failure.
+      device.gatt.connect = jest.fn(() => Promise.reject(new Error('Simulated error')));
+
+      unexpectedlyDisconnect(device);
+
+      // Verify that a reconnection attempt was made. Using `1` since the connect method was just mocked.
+      expect(device.gatt.connect).toHaveBeenCalledTimes(1);
+
+      // Using `setTimeout()` to wait for the Promise rejection to be processed. This allows for verifying asynchronous
+      // behavior after the reconnection failure.
+      setTimeout(() => {
+        // Verify that the error was properly logged.
+        expect(bt._logError).toHaveBeenLastCalledWith(
+            '_gattServerDisconnectedListener',
+            new Error('Simulated error'),
+            expect.any(Function),
+        );
+        // Signal Jest that the asynchronous test is complete.
+        done();
+      }, 0);
+    });
+  });
+
+  describe('When getting the device name...', () => {
+    it('should return an empty string when no device is connected', () => {
+      expect(bt.getDeviceName()).toBe('');
+    });
+
+    it('should return the device name after connection', async () => {
+      await bt.connect();
+
+      expect(bt.getDeviceName()).toBe('Simon');
+    });
+
+    it('should return the device name when the device unexpectedly disconnects', async () => {
+      await bt.connect();
+
+      // Simulate an unexpected disconnection by setting the Web Bluetooth API connection flag.
+      device.gatt.connected = false;
+
+      expect(bt.getDeviceName()).toBe('Simon');
+    });
+  });
+});