rol-websocket-channel 1.4.2 → 1.4.8

package/dist/src/mqtt/mqtt.test.js

@@ -1,418 +1,418 @@
-/**
- * MQTT 模块测试
- *
- * 测试内容：
- *  1. 工具函数单元测试（parseUsernameFromTopic、generateClientId、getSubscribeTopic）
- *  2. 全局连接生命周期测试（使用 Mock MQTT 客户端注入）
- *  3. 订阅 / 发布集成测试
- *
- * 运行：npm test
- */
-import { test, describe, beforeEach, afterEach } from "node:test";
-import assert from "node:assert/strict";
-import { EventEmitter } from "node:events";
-import { parseUsernameFromTopic, generateClientId, getSubscribeTopic, createGlobalMqttConnection, closeGlobalConnection, isGlobalConnected, getGlobalConnection, publishGlobalMessage, _setMqttConnectFn, } from "./connection-manager.js";
-import { GlobalMqttClient } from "./mqtt-client.js";
-// ─────────────────────────────────────────────────────────────────────────────
-// Mock MQTT 客户端
-// 模拟 mqtt.js 的 MqttClient API（EventEmitter + subscribe / publish / end）
-// ─────────────────────────────────────────────────────────────────────────────
-class MockMqttClient extends EventEmitter {
-    constructor() {
-        super(...arguments);
-        this.connected = false;
-        this.clientId = "";
-        this.username = "";
-        this.subscribedTopics = [];
-        this.publishedMessages = [];
-        this.endCalled = false;
-    }
-    /** 模拟 broker 在 delayMs 毫秒后接受连接 */
-    simulateConnect(delayMs = 10) {
-        setTimeout(() => {
-            this.connected = true;
-            this.emit("connect");
-        }, delayMs);
-    }
-    /** 模拟 broker 推送一条消息给客户端 */
-    simulateMessage(topic, payload) {
-        this.emit("message", topic, payload);
-    }
-    // ── mqtt.js 兼容 API ───────────────────────────────────────────────────────
-    subscribe(topic, cb) {
-        this.subscribedTopics.push(topic);
-        cb(null);
-    }
-    publish(topic, message) {
-        this.publishedMessages.push({ topic, message });
-    }
-    end(_force) {
-        this.connected = false;
-        this.endCalled = true;
-        this.emit("close");
-    }
-}
-/**
- * 创建注入用的 mock connect 工厂。
- * 返回的函数签名与 mqtt.connect() 相同，会把连接选项写回 mockClient 以便断言。
- */
-function makeMockConnectFn(mockClient) {
-    return (_url, opts) => {
-        mockClient.clientId = opts.clientId ?? "";
-        mockClient.username = opts.username ?? "";
-        return mockClient;
-    };
-}
-// ─────────────────────────────────────────────────────────────────────────────
-// 测试辅助
-// ─────────────────────────────────────────────────────────────────────────────
-const waitMs = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-// ─────────────────────────────────────────────────────────────────────────────
-// 1. parseUsernameFromTopic — 单元测试
-// ─────────────────────────────────────────────────────────────────────────────
-describe("parseUsernameFromTopic", () => {
-    test("从完整的 announcement topic 中正确解析 user_name", () => {
-        const topic = "announcement/0b9a784d-e044-4c6f-9024-ef8799c131d1/ce627d3d-9e22-47f7-b1c6-a6ab69570fef/bot";
-        assert.equal(parseUsernameFromTopic(topic), "0b9a784d-e044-4c6f-9024-ef8799c131d1");
-    });
-    test("只有两段的 announcement topic 也能解析", () => {
-        assert.equal(parseUsernameFromTopic("announcement/myuser"), "myuser");
-    });
-    test("不同 agent_id 解析出相同 user_name", () => {
-        const base = "announcement/same-user";
-        assert.equal(parseUsernameFromTopic(`${base}/agent-A/bot`), "same-user");
-        assert.equal(parseUsernameFromTopic(`${base}/agent-B/bot`), "same-user");
-    });
-    test("非 announcement 前缀 → default_name", () => {
-        assert.equal(parseUsernameFromTopic("some/other/topic"), "default_name");
-    });
-    test("空字符串 → default_name", () => {
-        assert.equal(parseUsernameFromTopic(""), "default_name");
-    });
-    test("announcement 后无用户名段 → default_name", () => {
-        assert.equal(parseUsernameFromTopic("announcement/"), "default_name");
-    });
-    test("announcement 后仅有空白 → default_name", () => {
-        assert.equal(parseUsernameFromTopic("announcement/   "), "default_name");
-    });
-    test("null / undefined 输入 → default_name（边界情况）", () => {
-        // @ts-expect-error 故意传非法类型以测试边界
-        assert.equal(parseUsernameFromTopic(null), "default_name");
-        // @ts-expect-error 故意传非法类型以测试边界
-        assert.equal(parseUsernameFromTopic(undefined), "default_name");
-    });
-});
-// ─────────────────────────────────────────────────────────────────────────────
-// 2. generateClientId — 单元测试
-// ─────────────────────────────────────────────────────────────────────────────
-describe("generateClientId", () => {
-    test('以 "mqtt_client_" 开头', () => {
-        const id = generateClientId();
-        assert.ok(id.startsWith("mqtt_client_"), `期望 mqtt_client_ 前缀，实际得到: ${id}`);
-    });
-    test("长度大于 16 个字符", () => {
-        const id = generateClientId();
-        assert.ok(id.length > 16, `ID 过短: ${id}`);
-    });
-    test("连续 100 次调用生成的 ID 几乎全部唯一", () => {
-        const ids = new Set(Array.from({ length: 100 }, () => generateClientId()));
-        assert.ok(ids.size >= 90, `碰撞过多：100 次中仅有 ${ids.size} 个唯一 ID`);
-    });
-    test("只包含字母、数字和下划线", () => {
-        for (let i = 0; i < 30; i++) {
-            const id = generateClientId();
-            assert.match(id, /^[a-z0-9_]+$/i, `ID 含非法字符: ${id}`);
-        }
-    });
-});
-// ─────────────────────────────────────────────────────────────────────────────
-// 3. getSubscribeTopic — 单元测试
-// ─────────────────────────────────────────────────────────────────────────────
-describe("getSubscribeTopic", () => {
-    test("完整 announcement topic → announcement/{user_name}/#", () => {
-        const topic = "announcement/0b9a784d-e044-4c6f-9024-ef8799c131d1/ce627d3d-9e22-47f7-b1c6-a6ab69570fef/bot";
-        assert.equal(getSubscribeTopic(topic), "announcement/0b9a784d-e044-4c6f-9024-ef8799c131d1/#");
-    });
-    test("不同 agent_id 产生相同的通配符订阅 topic（不区分 id）", () => {
-        const t1 = "announcement/user123/agent-aaa/bot";
-        const t2 = "announcement/user123/agent-bbb/bot";
-        assert.equal(getSubscribeTopic(t1), "announcement/user123/#");
-        assert.equal(getSubscribeTopic(t1), getSubscribeTopic(t2));
-    });
-    test("非 announcement topic → 原 topic + /#", () => {
-        assert.equal(getSubscribeTopic("some/topic"), "some/topic/#");
-    });
-    test("已以 # 结尾的 topic 不重复添加通配符", () => {
-        assert.equal(getSubscribeTopic("some/topic/#"), "some/topic/#");
-    });
-    test("末尾有斜杠的 topic → 补 # 而非 /#", () => {
-        assert.equal(getSubscribeTopic("some/topic/"), "some/topic/#");
-    });
-});
-// ─────────────────────────────────────────────────────────────────────────────
-// 4. 全局连接生命周期测试（Mock 注入）
-// ─────────────────────────────────────────────────────────────────────────────
-describe("全局连接生命周期（createGlobalMqttConnection / closeGlobalConnection）", () => {
-    let mockClient;
-    beforeEach(() => {
-        mockClient = new MockMqttClient();
-        _setMqttConnectFn(makeMockConnectFn(mockClient));
-        closeGlobalConnection(); // 清理上次残留
-    });
-    afterEach(() => {
-        closeGlobalConnection();
-        _setMqttConnectFn(null);
-    });
-    // ── 连接对象字段 ──────────────────────────────────────────────────────────
-    test("createGlobalMqttConnection 返回的连接对象包含正确字段", async () => {
-        const topic = "announcement/0b9a784d-e044-4c6f-9024-ef8799c131d1/ce627d3d-9e22-47f7-b1c6-a6ab69570fef/bot";
-        const conn = await createGlobalMqttConnection("mqtt://localhost:1883", topic, {});
-        assert.equal(conn.topic, topic, "topic 字段");
-        assert.equal(conn.username, "0b9a784d-e044-4c6f-9024-ef8799c131d1", "username 字段");
-        assert.equal(conn.subscribeTopic, "announcement/0b9a784d-e044-4c6f-9024-ef8799c131d1/#", "subscribeTopic 字段");
-    });
-    // ── clientId / username ───────────────────────────────────────────────────
-    test("连接时传递随机生成的 clientId", async () => {
-        await createGlobalMqttConnection("mqtt://localhost:1883", "announcement/user/agent/bot", {});
-        assert.ok(mockClient.clientId.startsWith("mqtt_client_"), `期望 mqtt_client_ 前缀，实际: ${mockClient.clientId}`);
-    });
-    test("连接时 username 使用从 topic 解析的用户名", async () => {
-        await createGlobalMqttConnection("mqtt://localhost:1883", "announcement/myuser/agent/bot", {});
-        assert.equal(mockClient.username, "myuser");
-    });
-    // ── isGlobalConnected ─────────────────────────────────────────────────────
-    test("连接前 isGlobalConnected() = false，成功连接后 = true", async () => {
-        assert.equal(isGlobalConnected(), false);
-        const onConnectPromise = new Promise((resolve) => {
-            createGlobalMqttConnection("mqtt://localhost:1883", "announcement/u/a/bot", {
-                onConnect: resolve,
-            });
-        });
-        mockClient.simulateConnect(20);
-        await onConnectPromise;
-        assert.equal(isGlobalConnected(), true);
-    });
-    // ── 订阅 topic ────────────────────────────────────────────────────────────
-    test("连接后自动订阅正确的通配符 topic", async () => {
-        const onConnectPromise = new Promise((resolve) => {
-            createGlobalMqttConnection("mqtt://localhost:1883", "announcement/testuser/agent/bot", { onConnect: resolve });
-        });
-        mockClient.simulateConnect(10);
-        await onConnectPromise;
-        assert.ok(mockClient.subscribedTopics.includes("announcement/testuser/#"), `订阅 topic 错误，实际订阅: ${mockClient.subscribedTopics.join(", ")}`);
-    });
-    // ── 复用已有连接 ──────────────────────────────────────────────────────────
-    test("连接已存在时重复调用 createGlobalMqttConnection 复用同一对象", async () => {
-        const onConnectPromise = new Promise((resolve) => {
-            createGlobalMqttConnection("mqtt://localhost:1883", "announcement/u/a/bot", { onConnect: resolve });
-        });
-        mockClient.simulateConnect(10);
-        await onConnectPromise;
-        const conn1 = getGlobalConnection();
-        // 第二次调用
-        const conn2 = await createGlobalMqttConnection("mqtt://localhost:1883", "announcement/u/a/bot", {});
-        assert.strictEqual(conn1, conn2, "应返回同一个连接对象引用");
-    });
-    // ── closeGlobalConnection ─────────────────────────────────────────────────
-    test("closeGlobalConnection 后 isGlobalConnected() = false 且 getGlobalConnection() = null", async () => {
-        const onConnectPromise = new Promise((resolve) => {
-            createGlobalMqttConnection("mqtt://localhost:1883", "announcement/u/a/bot", { onConnect: resolve });
-        });
-        mockClient.simulateConnect(10);
-        await onConnectPromise;
-        assert.equal(isGlobalConnected(), true);
-        closeGlobalConnection();
-        assert.equal(isGlobalConnected(), false);
-        assert.equal(getGlobalConnection(), null);
-        assert.equal(mockClient.endCalled, true);
-    });
-});
-// ─────────────────────────────────────────────────────────────────────────────
-// 5. GlobalMqttClient 订阅 & 发布测试（Mock 注入）
-// ─────────────────────────────────────────────────────────────────────────────
-describe("GlobalMqttClient — 订阅 & 发布", () => {
-    let mockClient;
-    beforeEach(() => {
-        mockClient = new MockMqttClient();
-        _setMqttConnectFn(makeMockConnectFn(mockClient));
-        closeGlobalConnection();
-    });
-    afterEach(() => {
-        closeGlobalConnection();
-        _setMqttConnectFn(null);
-    });
-    // ─────────────────────────────────────────────────────────────────────────
-    // 辅助：快速建立一个已连接的 GlobalMqttClient
-    // ─────────────────────────────────────────────────────────────────────────
-    async function makeConnectedClient(mqttTopic, onMessage, abortController) {
-        let client;
-        const onConnectPromise = new Promise((resolve) => {
-            client = new GlobalMqttClient({
-                mqttUrl: "mqtt://localhost:1883",
-                mqttTopic,
-                abortSignal: abortController.signal,
-                onMessage,
-                onConnect: resolve,
-            });
-        });
-        // connect() 挂起到 abort，在后台跑
-        client.connect().catch(() => { });
-        mockClient.simulateConnect(10);
-        await onConnectPromise;
-        return client;
-    }
-    // ── publish ───────────────────────────────────────────────────────────────
-    test("连接成功后 publish() 返回 true 且消息到达 broker", async () => {
-        const ac = new AbortController();
-        const client = await makeConnectedClient("announcement/user/agent/bot", async () => { }, ac);
-        const topic = "announcement/user/agent/bot";
-        const payload = JSON.stringify({ type: "message", content: "hello" });
-        const ok = client.publish(topic, payload);
-        assert.equal(ok, true);
-        assert.equal(mockClient.publishedMessages.length, 1);
-        assert.equal(mockClient.publishedMessages[0].topic, topic);
-        assert.deepEqual(JSON.parse(mockClient.publishedMessages[0].message), {
-            type: "message",
-            content: "hello",
-        });
-        ac.abort();
-    });
-    test("未连接时 publish() 返回 false", () => {
-        const ac = new AbortController();
-        const client = new GlobalMqttClient({
-            mqttUrl: "mqtt://localhost:1883",
-            mqttTopic: "announcement/user/agent/bot",
-            abortSignal: ac.signal,
-            onMessage: async () => { },
-        });
-        // 没有调用 connect()，连接未建立
-        const ok = client.publish("announcement/user/agent/bot", "test");
-        assert.equal(ok, false);
-        ac.abort();
-    });
-    test("连续 publish 多条消息，全部到达 broker，顺序正确", async () => {
-        const ac = new AbortController();
-        const client = await makeConnectedClient("announcement/userC/agent/bot", async () => { }, ac);
-        const topic = "announcement/userC/agent/bot";
-        client.publish(topic, "first");
-        client.publish(topic, "second");
-        client.publish(topic, "third");
-        assert.equal(mockClient.publishedMessages.length, 3);
-        assert.deepEqual(mockClient.publishedMessages.map((m) => m.message), ["first", "second", "third"]);
-        ac.abort();
-    });
-    // ── 订阅 / 接收消息 ───────────────────────────────────────────────────────
-    test("订阅的 topic 是通配符形式（不区分 agent_id）", async () => {
-        const ac = new AbortController();
-        await makeConnectedClient("announcement/userA/agentX/bot", async () => { }, ac);
-        assert.ok(mockClient.subscribedTopics.includes("announcement/userA/#"), `订阅 topic 不正确，实际: ${mockClient.subscribedTopics.join(", ")}`);
-        ac.abort();
-    });
-    test("broker 推送消息时 onMessage 回调被正确触发", async () => {
-        const ac = new AbortController();
-        const received = [];
-        const client = await makeConnectedClient("announcement/userA/agentX/bot", async (topic, payload) => {
-            received.push({ topic, payload: payload.toString() });
-        }, ac);
-        mockClient.simulateMessage("announcement/userA/agentX/bot", Buffer.from(JSON.stringify({ type: "message", content: "world" })));
-        await waitMs(30);
-        assert.equal(received.length, 1);
-        assert.equal(received[0].topic, "announcement/userA/agentX/bot");
-        assert.deepEqual(JSON.parse(received[0].payload), {
-            type: "message",
-            content: "world",
-        });
-        ac.abort();
-    });
-    test("通配符订阅能收到同一 user_name 下不同 agent_id 的消息", async () => {
-        const ac = new AbortController();
-        const receivedTopics = [];
-        const client = await makeConnectedClient("announcement/userB/agent-001/bot", async (topic) => {
-            receivedTopics.push(topic);
-        }, ac);
-        // 来自不同 agent_id 的消息（通配符 announcement/userB/# 都应匹配）
-        mockClient.simulateMessage("announcement/userB/agent-001/bot", Buffer.from("msg-from-agent-001"));
-        mockClient.simulateMessage("announcement/userB/agent-002/bot", Buffer.from("msg-from-agent-002"));
-        mockClient.simulateMessage("announcement/userB/agent-003/command", Buffer.from("msg-from-agent-003"));
-        await waitMs(30);
-        assert.equal(receivedTopics.length, 3);
-        assert.ok(receivedTopics.includes("announcement/userB/agent-001/bot"));
-        assert.ok(receivedTopics.includes("announcement/userB/agent-002/bot"));
-        assert.ok(receivedTopics.includes("announcement/userB/agent-003/command"));
-        ac.abort();
-    });
-    test("连续收到多条消息，每条都触发 onMessage，顺序正确", async () => {
-        const ac = new AbortController();
-        const payloads = [];
-        await makeConnectedClient("announcement/userC/agent/bot", async (_topic, payload) => {
-            payloads.push(payload.toString());
-        }, ac);
-        for (const msg of ["alpha", "beta", "gamma"]) {
-            mockClient.simulateMessage("announcement/userC/agent/bot", Buffer.from(msg));
-        }
-        await waitMs(30);
-        assert.deepEqual(payloads, ["alpha", "beta", "gamma"]);
-        ac.abort();
-    });
-    // ── getSubscribeTopic / getUsername ───────────────────────────────────────
-    test("getUsername() 返回从 topic 中解析的用户名", () => {
-        const ac = new AbortController();
-        const client = new GlobalMqttClient({
-            mqttUrl: "mqtt://localhost:1883",
-            mqttTopic: "announcement/0b9a784d-e044-4c6f-9024-ef8799c131d1/ce627d3d-9e22-47f7-b1c6-a6ab69570fef/bot",
-            abortSignal: ac.signal,
-            onMessage: async () => { },
-        });
-        assert.equal(client.getUsername(), "0b9a784d-e044-4c6f-9024-ef8799c131d1");
-        ac.abort();
-    });
-    test("getSubscribeTopic() 返回通配符形式的订阅 topic", () => {
-        const ac = new AbortController();
-        const client = new GlobalMqttClient({
-            mqttUrl: "mqtt://localhost:1883",
-            mqttTopic: "announcement/0b9a784d-e044-4c6f-9024-ef8799c131d1/ce627d3d-9e22-47f7-b1c6-a6ab69570fef/bot",
-            abortSignal: ac.signal,
-            onMessage: async () => { },
-        });
-        assert.equal(client.getSubscribeTopic(), "announcement/0b9a784d-e044-4c6f-9024-ef8799c131d1/#");
-        ac.abort();
-    });
-    // ── AbortController / 生命周期 ────────────────────────────────────────────
-    test("abort 触发后 isConnected() = false，connect() Promise 正常 resolve", async () => {
-        const ac = new AbortController();
-        let client;
-        const onConnectPromise = new Promise((resolve) => {
-            client = new GlobalMqttClient({
-                mqttUrl: "mqtt://localhost:1883",
-                mqttTopic: "announcement/userD/agent/bot",
-                abortSignal: ac.signal,
-                onMessage: async () => { },
-                onConnect: resolve,
-            });
-        });
-        const done = client.connect(); // 挂起中
-        mockClient.simulateConnect(10);
-        await onConnectPromise;
-        assert.equal(client.isConnected(), true);
-        ac.abort();
-        await done; // 应在 abort 后正常 resolve（不应 reject）
-        assert.equal(client.isConnected(), false);
-    });
-    // ── publishGlobalMessage 直接 API ─────────────────────────────────────────
-    test("publishGlobalMessage() 使用全局连接发布消息", async () => {
-        const ac = new AbortController();
-        await makeConnectedClient("announcement/userE/agent/bot", async () => { }, ac);
-        const ok = publishGlobalMessage("announcement/userE/agent/bot", JSON.stringify({ type: "ping" }));
-        assert.equal(ok, true);
-        assert.equal(mockClient.publishedMessages.length, 1);
-        assert.deepEqual(JSON.parse(mockClient.publishedMessages[0].message), {
-            type: "ping",
-        });
-        ac.abort();
-    });
-    test("publishGlobalMessage() 在无连接时返回 false", () => {
-        // 没有任何连接
-        const ok = publishGlobalMessage("some/topic", "data");
-        assert.equal(ok, false);
-    });
-});
+/**
+ * MQTT 模块测试
+ *
+ * 测试内容：
+ *  1. 工具函数单元测试（parseUsernameFromTopic、generateClientId、getSubscribeTopic）
+ *  2. 全局连接生命周期测试（使用 Mock MQTT 客户端注入）
+ *  3. 订阅 / 发布集成测试
+ *
+ * 运行：npm test
+ */
+import { test, describe, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import { parseUsernameFromTopic, generateClientId, getSubscribeTopic, createGlobalMqttConnection, closeGlobalConnection, isGlobalConnected, getGlobalConnection, publishGlobalMessage, _setMqttConnectFn, } from "./connection-manager.js";
+import { GlobalMqttClient } from "./mqtt-client.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Mock MQTT 客户端
+// 模拟 mqtt.js 的 MqttClient API（EventEmitter + subscribe / publish / end）
+// ─────────────────────────────────────────────────────────────────────────────
+class MockMqttClient extends EventEmitter {
+    constructor() {
+        super(...arguments);
+        this.connected = false;
+        this.clientId = "";
+        this.username = "";
+        this.subscribedTopics = [];
+        this.publishedMessages = [];
+        this.endCalled = false;
+    }
+    /** 模拟 broker 在 delayMs 毫秒后接受连接 */
+    simulateConnect(delayMs = 10) {
+        setTimeout(() => {
+            this.connected = true;
+            this.emit("connect");
+        }, delayMs);
+    }
+    /** 模拟 broker 推送一条消息给客户端 */
+    simulateMessage(topic, payload) {
+        this.emit("message", topic, payload);
+    }
+    // ── mqtt.js 兼容 API ───────────────────────────────────────────────────────
+    subscribe(topic, cb) {
+        this.subscribedTopics.push(topic);
+        cb(null);
+    }
+    publish(topic, message) {
+        this.publishedMessages.push({ topic, message });
+    }
+    end(_force) {
+        this.connected = false;
+        this.endCalled = true;
+        this.emit("close");
+    }
+}
+/**
+ * 创建注入用的 mock connect 工厂。
+ * 返回的函数签名与 mqtt.connect() 相同，会把连接选项写回 mockClient 以便断言。
+ */
+function makeMockConnectFn(mockClient) {
+    return (_url, opts) => {
+        mockClient.clientId = opts.clientId ?? "";
+        mockClient.username = opts.username ?? "";
+        return mockClient;
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// 测试辅助
+// ─────────────────────────────────────────────────────────────────────────────
+const waitMs = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// ─────────────────────────────────────────────────────────────────────────────
+// 1. parseUsernameFromTopic — 单元测试
+// ─────────────────────────────────────────────────────────────────────────────
+describe("parseUsernameFromTopic", () => {
+    test("从完整的 announcement topic 中正确解析 user_name", () => {
+        const topic = "announcement/0b9a784d-e044-4c6f-9024-ef8799c131d1/ce627d3d-9e22-47f7-b1c6-a6ab69570fef/bot";
+        assert.equal(parseUsernameFromTopic(topic), "0b9a784d-e044-4c6f-9024-ef8799c131d1");
+    });
+    test("只有两段的 announcement topic 也能解析", () => {
+        assert.equal(parseUsernameFromTopic("announcement/myuser"), "myuser");
+    });
+    test("不同 agent_id 解析出相同 user_name", () => {
+        const base = "announcement/same-user";
+        assert.equal(parseUsernameFromTopic(`${base}/agent-A/bot`), "same-user");
+        assert.equal(parseUsernameFromTopic(`${base}/agent-B/bot`), "same-user");
+    });
+    test("非 announcement 前缀 → default_name", () => {
+        assert.equal(parseUsernameFromTopic("some/other/topic"), "default_name");
+    });
+    test("空字符串 → default_name", () => {
+        assert.equal(parseUsernameFromTopic(""), "default_name");
+    });
+    test("announcement 后无用户名段 → default_name", () => {
+        assert.equal(parseUsernameFromTopic("announcement/"), "default_name");
+    });
+    test("announcement 后仅有空白 → default_name", () => {
+        assert.equal(parseUsernameFromTopic("announcement/   "), "default_name");
+    });
+    test("null / undefined 输入 → default_name（边界情况）", () => {
+        // @ts-expect-error 故意传非法类型以测试边界
+        assert.equal(parseUsernameFromTopic(null), "default_name");
+        // @ts-expect-error 故意传非法类型以测试边界
+        assert.equal(parseUsernameFromTopic(undefined), "default_name");
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// 2. generateClientId — 单元测试
+// ─────────────────────────────────────────────────────────────────────────────
+describe("generateClientId", () => {
+    test('以 "mqtt_client_" 开头', () => {
+        const id = generateClientId();
+        assert.ok(id.startsWith("mqtt_client_"), `期望 mqtt_client_ 前缀，实际得到: ${id}`);
+    });
+    test("长度大于 16 个字符", () => {
+        const id = generateClientId();
+        assert.ok(id.length > 16, `ID 过短: ${id}`);
+    });
+    test("连续 100 次调用生成的 ID 几乎全部唯一", () => {
+        const ids = new Set(Array.from({ length: 100 }, () => generateClientId()));
+        assert.ok(ids.size >= 90, `碰撞过多：100 次中仅有 ${ids.size} 个唯一 ID`);
+    });
+    test("只包含字母、数字和下划线", () => {
+        for (let i = 0; i < 30; i++) {
+            const id = generateClientId();
+            assert.match(id, /^[a-z0-9_]+$/i, `ID 含非法字符: ${id}`);
+        }
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// 3. getSubscribeTopic — 单元测试
+// ─────────────────────────────────────────────────────────────────────────────
+describe("getSubscribeTopic", () => {
+    test("完整 announcement topic → announcement/{user_name}/#", () => {
+        const topic = "announcement/0b9a784d-e044-4c6f-9024-ef8799c131d1/ce627d3d-9e22-47f7-b1c6-a6ab69570fef/bot";
+        assert.equal(getSubscribeTopic(topic), "announcement/0b9a784d-e044-4c6f-9024-ef8799c131d1/#");
+    });
+    test("不同 agent_id 产生相同的通配符订阅 topic（不区分 id）", () => {
+        const t1 = "announcement/user123/agent-aaa/bot";
+        const t2 = "announcement/user123/agent-bbb/bot";
+        assert.equal(getSubscribeTopic(t1), "announcement/user123/#");
+        assert.equal(getSubscribeTopic(t1), getSubscribeTopic(t2));
+    });
+    test("非 announcement topic → 原 topic + /#", () => {
+        assert.equal(getSubscribeTopic("some/topic"), "some/topic/#");
+    });
+    test("已以 # 结尾的 topic 不重复添加通配符", () => {
+        assert.equal(getSubscribeTopic("some/topic/#"), "some/topic/#");
+    });
+    test("末尾有斜杠的 topic → 补 # 而非 /#", () => {
+        assert.equal(getSubscribeTopic("some/topic/"), "some/topic/#");
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// 4. 全局连接生命周期测试（Mock 注入）
+// ─────────────────────────────────────────────────────────────────────────────
+describe("全局连接生命周期（createGlobalMqttConnection / closeGlobalConnection）", () => {
+    let mockClient;
+    beforeEach(() => {
+        mockClient = new MockMqttClient();
+        _setMqttConnectFn(makeMockConnectFn(mockClient));
+        closeGlobalConnection(); // 清理上次残留
+    });
+    afterEach(() => {
+        closeGlobalConnection();
+        _setMqttConnectFn(null);
+    });
+    // ── 连接对象字段 ──────────────────────────────────────────────────────────
+    test("createGlobalMqttConnection 返回的连接对象包含正确字段", async () => {
+        const topic = "announcement/0b9a784d-e044-4c6f-9024-ef8799c131d1/ce627d3d-9e22-47f7-b1c6-a6ab69570fef/bot";
+        const conn = await createGlobalMqttConnection("mqtt://localhost:1883", topic, {});
+        assert.equal(conn.topic, topic, "topic 字段");
+        assert.equal(conn.username, "0b9a784d-e044-4c6f-9024-ef8799c131d1", "username 字段");
+        assert.equal(conn.subscribeTopic, "announcement/0b9a784d-e044-4c6f-9024-ef8799c131d1/#", "subscribeTopic 字段");
+    });
+    // ── clientId / username ───────────────────────────────────────────────────
+    test("连接时传递随机生成的 clientId", async () => {
+        await createGlobalMqttConnection("mqtt://localhost:1883", "announcement/user/agent/bot", {});
+        assert.ok(mockClient.clientId.startsWith("mqtt_client_"), `期望 mqtt_client_ 前缀，实际: ${mockClient.clientId}`);
+    });
+    test("连接时 username 使用从 topic 解析的用户名", async () => {
+        await createGlobalMqttConnection("mqtt://localhost:1883", "announcement/myuser/agent/bot", {});
+        assert.equal(mockClient.username, "myuser");
+    });
+    // ── isGlobalConnected ─────────────────────────────────────────────────────
+    test("连接前 isGlobalConnected() = false，成功连接后 = true", async () => {
+        assert.equal(isGlobalConnected(), false);
+        const onConnectPromise = new Promise((resolve) => {
+            createGlobalMqttConnection("mqtt://localhost:1883", "announcement/u/a/bot", {
+                onConnect: resolve,
+            });
+        });
+        mockClient.simulateConnect(20);
+        await onConnectPromise;
+        assert.equal(isGlobalConnected(), true);
+    });
+    // ── 订阅 topic ────────────────────────────────────────────────────────────
+    test("连接后自动订阅正确的通配符 topic", async () => {
+        const onConnectPromise = new Promise((resolve) => {
+            createGlobalMqttConnection("mqtt://localhost:1883", "announcement/testuser/agent/bot", { onConnect: resolve });
+        });
+        mockClient.simulateConnect(10);
+        await onConnectPromise;
+        assert.ok(mockClient.subscribedTopics.includes("announcement/testuser/#"), `订阅 topic 错误，实际订阅: ${mockClient.subscribedTopics.join(", ")}`);
+    });
+    // ── 复用已有连接 ──────────────────────────────────────────────────────────
+    test("连接已存在时重复调用 createGlobalMqttConnection 复用同一对象", async () => {
+        const onConnectPromise = new Promise((resolve) => {
+            createGlobalMqttConnection("mqtt://localhost:1883", "announcement/u/a/bot", { onConnect: resolve });
+        });
+        mockClient.simulateConnect(10);
+        await onConnectPromise;
+        const conn1 = getGlobalConnection();
+        // 第二次调用
+        const conn2 = await createGlobalMqttConnection("mqtt://localhost:1883", "announcement/u/a/bot", {});
+        assert.strictEqual(conn1, conn2, "应返回同一个连接对象引用");
+    });
+    // ── closeGlobalConnection ─────────────────────────────────────────────────
+    test("closeGlobalConnection 后 isGlobalConnected() = false 且 getGlobalConnection() = null", async () => {
+        const onConnectPromise = new Promise((resolve) => {
+            createGlobalMqttConnection("mqtt://localhost:1883", "announcement/u/a/bot", { onConnect: resolve });
+        });
+        mockClient.simulateConnect(10);
+        await onConnectPromise;
+        assert.equal(isGlobalConnected(), true);
+        closeGlobalConnection();
+        assert.equal(isGlobalConnected(), false);
+        assert.equal(getGlobalConnection(), null);
+        assert.equal(mockClient.endCalled, true);
+    });
+});
+// ─────────────────────────────────────────────────────────────────────────────
+// 5. GlobalMqttClient 订阅 & 发布测试（Mock 注入）
+// ─────────────────────────────────────────────────────────────────────────────
+describe("GlobalMqttClient — 订阅 & 发布", () => {
+    let mockClient;
+    beforeEach(() => {
+        mockClient = new MockMqttClient();
+        _setMqttConnectFn(makeMockConnectFn(mockClient));
+        closeGlobalConnection();
+    });
+    afterEach(() => {
+        closeGlobalConnection();
+        _setMqttConnectFn(null);
+    });
+    // ─────────────────────────────────────────────────────────────────────────
+    // 辅助：快速建立一个已连接的 GlobalMqttClient
+    // ─────────────────────────────────────────────────────────────────────────
+    async function makeConnectedClient(mqttTopic, onMessage, abortController) {
+        let client;
+        const onConnectPromise = new Promise((resolve) => {
+            client = new GlobalMqttClient({
+                mqttUrl: "mqtt://localhost:1883",
+                mqttTopic,
+                abortSignal: abortController.signal,
+                onMessage,
+                onConnect: resolve,
+            });
+        });
+        // connect() 挂起到 abort，在后台跑
+        client.connect().catch(() => { });
+        mockClient.simulateConnect(10);
+        await onConnectPromise;
+        return client;
+    }
+    // ── publish ───────────────────────────────────────────────────────────────
+    test("连接成功后 publish() 返回 true 且消息到达 broker", async () => {
+        const ac = new AbortController();
+        const client = await makeConnectedClient("announcement/user/agent/bot", async () => { }, ac);
+        const topic = "announcement/user/agent/bot";
+        const payload = JSON.stringify({ type: "message", content: "hello" });
+        const ok = client.publish(topic, payload);
+        assert.equal(ok, true);
+        assert.equal(mockClient.publishedMessages.length, 1);
+        assert.equal(mockClient.publishedMessages[0].topic, topic);
+        assert.deepEqual(JSON.parse(mockClient.publishedMessages[0].message), {
+            type: "message",
+            content: "hello",
+        });
+        ac.abort();
+    });
+    test("未连接时 publish() 返回 false", () => {
+        const ac = new AbortController();
+        const client = new GlobalMqttClient({
+            mqttUrl: "mqtt://localhost:1883",
+            mqttTopic: "announcement/user/agent/bot",
+            abortSignal: ac.signal,
+            onMessage: async () => { },
+        });
+        // 没有调用 connect()，连接未建立
+        const ok = client.publish("announcement/user/agent/bot", "test");
+        assert.equal(ok, false);
+        ac.abort();
+    });
+    test("连续 publish 多条消息，全部到达 broker，顺序正确", async () => {
+        const ac = new AbortController();
+        const client = await makeConnectedClient("announcement/userC/agent/bot", async () => { }, ac);
+        const topic = "announcement/userC/agent/bot";
+        client.publish(topic, "first");
+        client.publish(topic, "second");
+        client.publish(topic, "third");
+        assert.equal(mockClient.publishedMessages.length, 3);
+        assert.deepEqual(mockClient.publishedMessages.map((m) => m.message), ["first", "second", "third"]);
+        ac.abort();
+    });
+    // ── 订阅 / 接收消息 ───────────────────────────────────────────────────────
+    test("订阅的 topic 是通配符形式（不区分 agent_id）", async () => {
+        const ac = new AbortController();
+        await makeConnectedClient("announcement/userA/agentX/bot", async () => { }, ac);
+        assert.ok(mockClient.subscribedTopics.includes("announcement/userA/#"), `订阅 topic 不正确，实际: ${mockClient.subscribedTopics.join(", ")}`);
+        ac.abort();
+    });
+    test("broker 推送消息时 onMessage 回调被正确触发", async () => {
+        const ac = new AbortController();
+        const received = [];
+        const client = await makeConnectedClient("announcement/userA/agentX/bot", async (topic, payload) => {
+            received.push({ topic, payload: payload.toString() });
+        }, ac);
+        mockClient.simulateMessage("announcement/userA/agentX/bot", Buffer.from(JSON.stringify({ type: "message", content: "world" })));
+        await waitMs(30);
+        assert.equal(received.length, 1);
+        assert.equal(received[0].topic, "announcement/userA/agentX/bot");
+        assert.deepEqual(JSON.parse(received[0].payload), {
+            type: "message",
+            content: "world",
+        });
+        ac.abort();
+    });
+    test("通配符订阅能收到同一 user_name 下不同 agent_id 的消息", async () => {
+        const ac = new AbortController();
+        const receivedTopics = [];
+        const client = await makeConnectedClient("announcement/userB/agent-001/bot", async (topic) => {
+            receivedTopics.push(topic);
+        }, ac);
+        // 来自不同 agent_id 的消息（通配符 announcement/userB/# 都应匹配）
+        mockClient.simulateMessage("announcement/userB/agent-001/bot", Buffer.from("msg-from-agent-001"));
+        mockClient.simulateMessage("announcement/userB/agent-002/bot", Buffer.from("msg-from-agent-002"));
+        mockClient.simulateMessage("announcement/userB/agent-003/command", Buffer.from("msg-from-agent-003"));
+        await waitMs(30);
+        assert.equal(receivedTopics.length, 3);
+        assert.ok(receivedTopics.includes("announcement/userB/agent-001/bot"));
+        assert.ok(receivedTopics.includes("announcement/userB/agent-002/bot"));
+        assert.ok(receivedTopics.includes("announcement/userB/agent-003/command"));
+        ac.abort();
+    });
+    test("连续收到多条消息，每条都触发 onMessage，顺序正确", async () => {
+        const ac = new AbortController();
+        const payloads = [];
+        await makeConnectedClient("announcement/userC/agent/bot", async (_topic, payload) => {
+            payloads.push(payload.toString());
+        }, ac);
+        for (const msg of ["alpha", "beta", "gamma"]) {
+            mockClient.simulateMessage("announcement/userC/agent/bot", Buffer.from(msg));
+        }
+        await waitMs(30);
+        assert.deepEqual(payloads, ["alpha", "beta", "gamma"]);
+        ac.abort();
+    });
+    // ── getSubscribeTopic / getUsername ───────────────────────────────────────
+    test("getUsername() 返回从 topic 中解析的用户名", () => {
+        const ac = new AbortController();
+        const client = new GlobalMqttClient({
+            mqttUrl: "mqtt://localhost:1883",
+            mqttTopic: "announcement/0b9a784d-e044-4c6f-9024-ef8799c131d1/ce627d3d-9e22-47f7-b1c6-a6ab69570fef/bot",
+            abortSignal: ac.signal,
+            onMessage: async () => { },
+        });
+        assert.equal(client.getUsername(), "0b9a784d-e044-4c6f-9024-ef8799c131d1");
+        ac.abort();
+    });
+    test("getSubscribeTopic() 返回通配符形式的订阅 topic", () => {
+        const ac = new AbortController();
+        const client = new GlobalMqttClient({
+            mqttUrl: "mqtt://localhost:1883",
+            mqttTopic: "announcement/0b9a784d-e044-4c6f-9024-ef8799c131d1/ce627d3d-9e22-47f7-b1c6-a6ab69570fef/bot",
+            abortSignal: ac.signal,
+            onMessage: async () => { },
+        });
+        assert.equal(client.getSubscribeTopic(), "announcement/0b9a784d-e044-4c6f-9024-ef8799c131d1/#");
+        ac.abort();
+    });
+    // ── AbortController / 生命周期 ────────────────────────────────────────────
+    test("abort 触发后 isConnected() = false，connect() Promise 正常 resolve", async () => {
+        const ac = new AbortController();
+        let client;
+        const onConnectPromise = new Promise((resolve) => {
+            client = new GlobalMqttClient({
+                mqttUrl: "mqtt://localhost:1883",
+                mqttTopic: "announcement/userD/agent/bot",
+                abortSignal: ac.signal,
+                onMessage: async () => { },
+                onConnect: resolve,
+            });
+        });
+        const done = client.connect(); // 挂起中
+        mockClient.simulateConnect(10);
+        await onConnectPromise;
+        assert.equal(client.isConnected(), true);
+        ac.abort();
+        await done; // 应在 abort 后正常 resolve（不应 reject）
+        assert.equal(client.isConnected(), false);
+    });
+    // ── publishGlobalMessage 直接 API ─────────────────────────────────────────
+    test("publishGlobalMessage() 使用全局连接发布消息", async () => {
+        const ac = new AbortController();
+        await makeConnectedClient("announcement/userE/agent/bot", async () => { }, ac);
+        const ok = publishGlobalMessage("announcement/userE/agent/bot", JSON.stringify({ type: "ping" }));
+        assert.equal(ok, true);
+        assert.equal(mockClient.publishedMessages.length, 1);
+        assert.deepEqual(JSON.parse(mockClient.publishedMessages[0].message), {
+            type: "ping",
+        });
+        ac.abort();
+    });
+    test("publishGlobalMessage() 在无连接时返回 false", () => {
+        // 没有任何连接
+        const ok = publishGlobalMessage("some/topic", "data");
+        assert.equal(ok, false);
+    });
+});