feat: add SSE helper functions and tests for event streaming

Author: bjohansebas

test/helpers/sse.js

@@ -0,0 +1,108 @@
+import http from "node:http";
+
+/**
+ * @typedef {object} SseEvent
+ * @property {string=} action event action (building/built/sync/custom)
+ * @property {string=} name compilation name
+ * @property {string=} hash compilation hash
+ * @property {number=} time build time in ms
+ * @property {string[]=} errors errors
+ * @property {string[]=} warnings warnings
+ * @property {Record<string, string>=} modules module id → name map
+ */
+
+/**
+ * Open the SSE endpoint just long enough to capture the response headers, then
+ * force-close it (the stream never ends on its own).
+ * @param {import("supertest").Test} pending pending supertest request
+ * @returns {Promise<import("supertest").Response>} resolved response
+ */
+export async function readSseHandshake(pending) {
+  return new Promise((resolve, reject) => {
+    pending
+      .buffer(false)
+      .parse((res, cb) => {
+        res.on("data", () => {});
+        res.on("end", () => cb(null, ""));
+        // SSE never closes on its own; force-close after we have headers.
+        setTimeout(() => res.destroy(), 50);
+      })
+      .end((err, res) => {
+        if (err && err.code !== "ECONNRESET") {
+          reject(err);
+          return;
+        }
+        resolve(res);
+      });
+  });
+}
+
+/**
+ * Read the SSE stream directly over HTTP (supertest buffers streaming bodies
+ * differently per framework), then close it and return the parsed payloads
+ * (heartbeats and the initial handshake newline are skipped).
+ * @param {import("node:http").Server & { info?: { port: number }, listener?: import("node:http").Server }} listeningServer the running server
+ * @param {string} requestPath SSE endpoint path
+ * @param {number} waitMs how long to collect events before closing
+ * @returns {Promise<SseEvent[]>} parsed event payloads
+ */
+export async function readSseEvents(
+  listeningServer,
+  requestPath,
+  waitMs = 250,
+) {
+  const httpServer = listeningServer.listener || listeningServer;
+  const address =
+    typeof httpServer.address === "function" ? httpServer.address() : null;
+  const port =
+    address && typeof address === "object" && address.port
+      ? address.port
+      : listeningServer.info && listeningServer.info.port
+        ? listeningServer.info.port
+        : 3000;
+
+  return new Promise((resolve, reject) => {
+    let raw = "";
+    const pending = http.get(
+      { host: "127.0.0.1", port, path: requestPath },
+      (res) => {
+        res.setEncoding("utf8");
+        res.on("data", (chunk) => {
+          raw += chunk;
+        });
+      },
+    );
+    pending.on("error", (err) => {
+      if (err.code !== "ECONNRESET") reject(err);
+    });
+
+    setTimeout(() => {
+      pending.destroy();
+
+      /** @type {SseEvent[]} */
+      const events = [];
+      for (const block of raw.split("\n\n")) {
+        const line = block.split("\n").find((item) => item.startsWith("data:"));
+        if (!line) continue;
+        const payload = line.slice("data:".length).trim();
+        if (!payload || payload === "💓") continue;
+        try {
+          events.push(JSON.parse(payload));
+        } catch {
+          // Ignore non-JSON frames.
+        }
+      }
+      resolve(events);
+    }, waitMs);
+  });
+}
+
+/**
+ * @param {{ waitUntilValid: (callback: () => void) => void }} devMiddleware middleware instance
+ * @returns {Promise<void>} resolves once the first compilation is valid
+ */
+export async function waitUntilValid(devMiddleware) {
+  return new Promise((resolve) => {
+    devMiddleware.waitUntilValid(() => resolve());
+  });
+}

test/hot.test.js

@@ -105,6 +105,10 @@ describe("hot middleware (unit)", () => {
       expect(pathMatch("/bundle.js", "/__webpack_hmr")).toBe(false);
     });
 
+    it("returns false when the path has a trailing segment", () => {
+      expect(pathMatch("/__webpack_hmr/extra", "/__webpack_hmr")).toBe(false);
+    });
+
     it("returns false when url is undefined", () => {
       expect(pathMatch(undefined, "/__webpack_hmr")).toBe(false);
     });

test/middleware.test.js

@@ -32,6 +32,8 @@ import getCompiler from "./helpers/getCompiler";
 
 import getCompilerHooks from "./helpers/getCompilerHooks";
 
+import { readSseEvents, readSseHandshake, waitUntilValid } from "./helpers/sse";
+
 // Suppress unnecessary stats output
 jest.spyOn(globalThis.console, "log").mockImplementation();
 
@@ -6975,30 +6977,6 @@ describe.each([
     let server;
     let req;
 
-    /**
-     * @param {import("supertest").Test} pending pending supertest request
-     * @returns {Promise<import("supertest").Response>} resolved response
-     */
-    async function readSseHandshake(pending) {
-      return new Promise((resolve, reject) => {
-        pending
-          .buffer(false)
-          .parse((res, cb) => {
-            res.on("data", () => {});
-            res.on("end", () => cb(null, ""));
-            // SSE never closes on its own; force-close after we have headers.
-            setTimeout(() => res.destroy(), 50);
-          })
-          .end((err, res) => {
-            if (err && err.code !== "ECONNRESET") {
-              reject(err);
-              return;
-            }
-            resolve(res);
-          });
-      });
-    }
-
     afterEach(async () => {
       await close(server, instance);
     });
@@ -7084,5 +7062,101 @@ describe.each([
       expect(res.status).toBe(200);
       expect(res.headers["content-type"]).toMatch(/text\/event-stream/);
     });
+
+    it("sends a permissive CORS header", async () => {
+      const compiler = getCompiler(webpackConfig);
+      [server, req, instance] = await frameworkFactory(
+        name,
+        framework,
+        compiler,
+        { hot: true },
+      );
+
+      const res = await readSseHandshake(req.get("/__webpack_hmr"));
+
+      expect(res.headers["access-control-allow-origin"]).toBe("*");
+    });
+
+    describe("SSE payload", () => {
+      it("sends a sync event with the build hash to a client connecting after a build", async () => {
+        const compiler = getCompiler(webpackConfig);
+        [server, req, instance] = await frameworkFactory(
+          name,
+          framework,
+          compiler,
+          { hot: true },
+        );
+
+        await waitUntilValid(instance);
+
+        const events = await readSseEvents(server, "/__webpack_hmr");
+        const sync = events.find((event) => event.action === "sync");
+
+        expect(sync).toBeDefined();
+        expect(typeof sync.hash).toBe("string");
+        expect(sync.errors).toEqual([]);
+      });
+
+      it("sends a sync event per compilation for a MultiCompiler", async () => {
+        const compiler = getCompiler(webpackMultiConfig);
+        [server, req, instance] = await frameworkFactory(
+          name,
+          framework,
+          compiler,
+          { hot: true },
+        );
+
+        await waitUntilValid(instance);
+
+        const events = await readSseEvents(server, "/__webpack_hmr");
+        const syncs = events.filter((event) => event.action === "sync");
+
+        expect(syncs).toHaveLength(webpackMultiConfig.length);
+        for (const sync of syncs) {
+          expect(typeof sync.hash).toBe("string");
+        }
+      });
+
+      it("streams building and built events on recompilation", async () => {
+        const compiler = getCompiler({ ...webpackConfig, watch: true });
+        [server, req, instance] = await frameworkFactory(
+          name,
+          framework,
+          compiler,
+          { hot: true },
+        );
+
+        await waitUntilValid(instance);
+
+        const pending = readSseEvents(server, "/__webpack_hmr", 2000);
+        // Trigger a rebuild once the client is listening.
+        setTimeout(() => instance.invalidate(), 150);
+        const events = await pending;
+        const actions = events.map((event) => event.action);
+
+        expect(actions).toContain("building");
+        expect(actions).toContain("built");
+      });
+
+      it("broadcasts to every connected client", async () => {
+        const compiler = getCompiler(webpackConfig);
+        [server, req, instance] = await frameworkFactory(
+          name,
+          framework,
+          compiler,
+          { hot: true },
+        );
+
+        await waitUntilValid(instance);
+
+        const [first, second] = await Promise.all([
+          readSseEvents(server, "/__webpack_hmr"),
+          readSseEvents(server, "/__webpack_hmr"),
+        ]);
+
+        expect(first.some((event) => event.action === "sync")).toBe(true);
+        expect(second.some((event) => event.action === "sync")).toBe(true);
+      });
+    });
   });
 });