wrangler 0.0.0-e88a54e → 0.0.0-e95e5a0

package/src/__tests__/dev.test.tsx

@@ -1,6 +1,6 @@
 import * as fs from "node:fs";
-import { readFileSync } from "node:fs";
 import patchConsole from "patch-console";
+import dedent from "ts-dedent";
 import Dev from "../dev/dev";
 import { mockAccountId, mockApiToken } from "./helpers/mock-account-id";
 import { setMockResponse, unsetAllMocks } from "./helpers/mock-cfetch";
@@ -9,7 +9,7 @@ import { runInTempDir } from "./helpers/run-in-tmp";
 import { runWrangler } from "./helpers/run-wrangler";
 import writeWranglerToml from "./helpers/write-wrangler-toml";
 
-describe("Dev component", () => {
+describe("wrangler dev", () => {
   mockAccountId();
   mockApiToken();
   runInTempDir();
@@ -20,6 +20,56 @@ describe("Dev component", () => {
     unsetAllMocks();
   });
 
+  describe("compatibility-date", () => {
+    it("should not warn if there is no wrangler.toml and no compatibility-date specified", async () => {
+      fs.writeFileSync("index.js", `export default {};`);
+      await runWrangler("dev index.js");
+      expect(std.out).toMatchInlineSnapshot(`""`);
+      expect(std.warn).toMatchInlineSnapshot(`""`);
+      expect(std.err).toMatchInlineSnapshot(`""`);
+    });
+
+    it("should warn if there is a wrangler.toml but no compatibility-date", async () => {
+      writeWranglerToml({
+        main: "index.js",
+        compatibility_date: undefined,
+      });
+      fs.writeFileSync("index.js", `export default {};`);
+      await runWrangler("dev");
+      const currentDate = new Date().toISOString().substring(0, 10);
+      expect(std.out).toMatchInlineSnapshot(`""`);
+      expect(std.warn.replaceAll(currentDate, "<current-date>"))
+        .toMatchInlineSnapshot(`
+        "▲ [WARNING] No compatibility_date was specified. Using today's date: <current-date>.
+
+          Add one to your wrangler.toml file:
+          \`\`\`
+          compatibility_date = \\"<current-date>\\"
+          \`\`\`
+          or pass it in your terminal:
+          \`\`\`
+          --compatibility-date=<current-date>
+          \`\`\`
+          See https://developers.cloudflare.com/workers/platform/compatibility-dates for more information.
+
+        "
+      `);
+      expect(std.err).toMatchInlineSnapshot(`""`);
+    });
+
+    it("should not warn if there is a wrangler.toml but compatibility-date is specified at the command line", async () => {
+      writeWranglerToml({
+        main: "index.js",
+        compatibility_date: undefined,
+      });
+      fs.writeFileSync("index.js", `export default {};`);
+      await runWrangler("dev --compatibility-date=2020-01-01");
+      expect(std.out).toMatchInlineSnapshot(`""`);
+      expect(std.warn).toMatchInlineSnapshot(`""`);
+      expect(std.err).toMatchInlineSnapshot(`""`);
+    });
+  });
+
   describe("entry-points", () => {
     it("should error if there is no entry-point specified", async () => {
       writeWranglerToml();
@@ -30,11 +80,14 @@ describe("Dev component", () => {
         `"Missing entry-point: The entry-point should be specified via the command line (e.g. \`wrangler dev path/to/script\`) or the \`main\` config field."`
       );
 
-      expect(std.out).toMatchInlineSnapshot(`""`);
+      expect(std.out).toMatchInlineSnapshot(`
+        "
+        If you think this is a bug then please create an issue at https://github.com/cloudflare/wrangler2/issues/new."
+      `);
       expect(std.err).toMatchInlineSnapshot(`
-        "Missing entry-point: The entry-point should be specified via the command line (e.g. \`wrangler dev path/to/script\`) or the \`main\` config field.
+        "X [ERROR] Missing entry-point: The entry-point should be specified via the command line (e.g. \`wrangler dev path/to/script\`) or the \`main\` config field.
 
-        %s If you think this is a bug then please create an issue at https://github.com/cloudflare/wrangler2/issues/new."
+        "
       `);
     });
 
@@ -171,6 +224,38 @@ describe("Dev component", () => {
       );
     });
 
+    it("should, when provided, use a configured zone_id", async () => {
+      writeWranglerToml({
+        main: "index.js",
+        routes: [
+          { pattern: "https://some-domain.com/*", zone_id: "some-zone-id" },
+        ],
+      });
+      fs.writeFileSync("index.js", `export default {};`);
+      await runWrangler("dev");
+      expect((Dev as jest.Mock).mock.calls[0][0].zone).toEqual({
+        host: "some-domain.com",
+        id: "some-zone-id",
+      });
+    });
+
+    it("should, when provided, use a zone_name to get a zone_id", async () => {
+      writeWranglerToml({
+        main: "index.js",
+        routes: [
+          { pattern: "https://some-domain.com/*", zone_name: "some-zone.com" },
+        ],
+      });
+      fs.writeFileSync("index.js", `export default {};`);
+      mockGetZones("some-zone.com", [{ id: "a-zone-id" }]);
+      await runWrangler("dev");
+      expect((Dev as jest.Mock).mock.calls[0][0].zone).toEqual({
+        // note that it uses the provided zone_name as a host too
+        host: "some-zone.com",
+        id: "a-zone-id",
+      });
+    });
+
     it("given a long host, it should use the longest subdomain that resolves to a zone", async () => {
       writeWranglerToml({
         main: "index.js",
@@ -277,6 +362,15 @@ describe("Dev component", () => {
         `"Could not find zone for some-host.com"`
       );
     });
+
+    it("should not try to resolve a zone when starting in local mode", async () => {
+      writeWranglerToml({
+        main: "index.js",
+      });
+      fs.writeFileSync("index.js", `export default {};`);
+      await runWrangler("dev --host some-host.com --local");
+      expect((Dev as jest.Mock).mock.calls[0][0].zone).toEqual(undefined);
+    });
   });
 
   describe("custom builds", () => {
@@ -289,19 +383,19 @@ describe("Dev component", () => {
 
       await runWrangler("dev index.js");
 
-      expect(readFileSync("index.js", "utf-8")).toMatchInlineSnapshot(
+      expect(fs.readFileSync("index.js", "utf-8")).toMatchInlineSnapshot(
         `"export default { fetch(){ return new Response(123) } }"`
       );
 
       // and the command would pass through
-      expect((Dev as jest.Mock).mock.calls[0][0].buildCommand).toEqual({
+      expect((Dev as jest.Mock).mock.calls[0][0].build).toEqual({
         command:
           "node -e \"console.log('custom build'); require('fs').writeFileSync('index.js', 'export default { fetch(){ return new Response(123) } }')\"",
         cwd: undefined,
         watch_dir: "src",
       });
       expect(std.out).toMatchInlineSnapshot(
-        `"running: node -e \\"console.log('custom build'); require('fs').writeFileSync('index.js', 'export default { fetch(){ return new Response(123) } }')\\""`
+        `"Running custom build: node -e \\"console.log('custom build'); require('fs').writeFileSync('index.js', 'export default { fetch(){ return new Response(123) } }')\\""`
       );
       expect(std.err).toMatchInlineSnapshot(`""`);
       expect(std.warn).toMatchInlineSnapshot(`""`);
@@ -317,13 +411,13 @@ describe("Dev component", () => {
 
         await runWrangler("dev index.js");
 
-        expect(readFileSync("index.js", "utf-8")).toMatchInlineSnapshot(`
+        expect(fs.readFileSync("index.js", "utf-8")).toMatchInlineSnapshot(`
           "export default { fetch(){ return new Response(123) } }
           "
         `);
 
         expect(std.out).toMatchInlineSnapshot(
-          `"running: echo \\"custom build\\" && echo \\"export default { fetch(){ return new Response(123) } }\\" > index.js"`
+          `"Running custom build: echo \\"custom build\\" && echo \\"export default { fetch(){ return new Response(123) } }\\" > index.js"`
         );
         expect(std.err).toMatchInlineSnapshot(`""`);
         expect(std.warn).toMatchInlineSnapshot(`""`);
@@ -343,13 +437,15 @@ describe("Dev component", () => {
       ).rejects.toThrowErrorMatchingInlineSnapshot(
         `"Could not resolve \\"index.js\\" after running custom build: node -e \\"console.log('custom build');\\""`
       );
-      expect(std.out).toMatchInlineSnapshot(
-        `"running: node -e \\"console.log('custom build');\\""`
-      );
+      expect(std.out).toMatchInlineSnapshot(`
+        "Running custom build: node -e \\"console.log('custom build');\\"
+
+        If you think this is a bug then please create an issue at https://github.com/cloudflare/wrangler2/issues/new."
+      `);
       expect(std.err).toMatchInlineSnapshot(`
-        "Could not resolve \\"index.js\\" after running custom build: node -e \\"console.log('custom build');\\"
+        "X [ERROR] Could not resolve \\"index.js\\" after running custom build: node -e \\"console.log('custom build');\\"
 
-        %s If you think this is a bug then please create an issue at https://github.com/cloudflare/wrangler2/issues/new."
+        "
       `);
       expect(std.warn).toMatchInlineSnapshot(`""`);
     });
@@ -381,9 +477,12 @@ describe("Dev component", () => {
       );
       expect(std.out).toMatchInlineSnapshot(`""`);
       expect(std.warn).toMatchInlineSnapshot(`
-        "Setting upstream-protocol to http is not currently implemented.
-        If this is required in your project, please add your use case to the following issue:
-        https://github.com/cloudflare/wrangler2/issues/583."
+        "▲ [WARNING] Setting upstream-protocol to http is not currently implemented.
+
+          If this is required in your project, please add your use case to the following issue:
+          https://github.com/cloudflare/wrangler2/issues/583.
+
+        "
       `);
       expect(std.err).toMatchInlineSnapshot(`""`);
     });
@@ -480,6 +579,173 @@ describe("Dev component", () => {
       expect(std.err).toMatchInlineSnapshot(`""`);
     });
   });
+
+  describe("durable_objects", () => {
+    it("should warn if there is one or more remote Durable Object", async () => {
+      writeWranglerToml({
+        main: "index.js",
+        durable_objects: {
+          bindings: [
+            { name: "NAME_1", class_name: "CLASS_1" },
+            {
+              name: "NAME_2",
+              class_name: "CLASS_2",
+              script_name: "SCRIPT_A",
+            },
+            { name: "NAME_3", class_name: "CLASS_3" },
+            {
+              name: "NAME_4",
+              class_name: "CLASS_4",
+              script_name: "SCRIPT_B",
+            },
+          ],
+        },
+      });
+      fs.writeFileSync("index.js", `export default {};`);
+      await runWrangler("dev");
+      expect((Dev as jest.Mock).mock.calls[0][0].ip).toEqual("localhost");
+      expect(std.out).toMatchInlineSnapshot(`""`);
+      expect(std.warn).toMatchInlineSnapshot(`
+        "▲ [WARNING] WARNING: You have Durable Object bindings that are not defined locally in the worker being developed.
+
+          Be aware that changes to the data stored in these Durable Objects will be permanent and affect the
+          live instances.
+          Remote Durable Objects that are affected:
+          - {\\"name\\":\\"NAME_2\\",\\"class_name\\":\\"CLASS_2\\",\\"script_name\\":\\"SCRIPT_A\\"}
+          - {\\"name\\":\\"NAME_4\\",\\"class_name\\":\\"CLASS_4\\",\\"script_name\\":\\"SCRIPT_B\\"}
+
+        "
+      `);
+      expect(std.err).toMatchInlineSnapshot(`""`);
+    });
+  });
+
+  describe(".dev.vars", () => {
+    it("should override `vars` bindings from `wrangler.toml` with values in `.dev.vars`", async () => {
+      fs.writeFileSync("index.js", `export default {};`);
+
+      const localVarsEnvContent = dedent`
+      # Preceding comment
+      VAR_1="var #1 value" # End of line comment
+      VAR_3="var #3 value"
+      VAR_MULTI_LINE_1="A: line 1
+      line 2"
+      VAR_MULTI_LINE_2="B: line 1\\nline 2"
+      EMPTY=
+      UNQUOTED= unquoted value
+      `;
+      fs.writeFileSync(".dev.vars", localVarsEnvContent, "utf8");
+
+      writeWranglerToml({
+        main: "index.js",
+        vars: {
+          VAR_1: "original value 1",
+          VAR_2: "original value 2", // should not get overridden
+          VAR_3: "original value 3",
+          VAR_MULTI_LINE_1: "original multi-line 1",
+          VAR_MULTI_LINE_2: "original multi-line 2",
+          EMPTY: "original empty",
+          UNQUOTED: "original unquoted",
+        },
+      });
+      await runWrangler("dev");
+      const varBindings: Record<string, unknown> = (Dev as jest.Mock).mock
+        .calls[0][0].bindings.vars;
+
+      expect(varBindings).toEqual({
+        VAR_1: "var #1 value",
+        VAR_2: "original value 2",
+        VAR_3: "var #3 value",
+        VAR_MULTI_LINE_1: "A: line 1\nline 2",
+        VAR_MULTI_LINE_2: "B: line 1\nline 2",
+        EMPTY: "",
+        UNQUOTED: "unquoted value", // Note that whitespace is trimmed
+      });
+      expect(std.out).toMatchInlineSnapshot(
+        `"Using vars defined in .dev.vars"`
+      );
+      expect(std.warn).toMatchInlineSnapshot(`""`);
+      expect(std.err).toMatchInlineSnapshot(`""`);
+    });
+  });
+
+  describe("site", () => {
+    it("should error if --site is used with no value", async () => {
+      await expect(
+        runWrangler("dev --site")
+      ).rejects.toThrowErrorMatchingInlineSnapshot(
+        `"Not enough arguments following: site"`
+      );
+
+      expect(std).toMatchInlineSnapshot(`
+        Object {
+          "debug": "",
+          "err": "wrangler dev [script]
+
+        👂 Start a local server for developing your worker
+
+        Positionals:
+          script  The path to an entry point for your worker  [string]
+
+        Flags:
+          -c, --config      Path to .toml configuration file  [string]
+          -h, --help        Show help  [boolean]
+          -v, --version     Show version number  [boolean]
+              --legacy-env  Use legacy environments  [boolean]
+
+        Options:
+              --name                                       Name of the worker  [string]
+              --format                                     Choose an entry type  [deprecated] [choices: \\"modules\\", \\"service-worker\\"]
+          -e, --env                                        Perform on a specific environment  [string]
+              --compatibility-date                         Date to use for compatibility checks  [string]
+              --compatibility-flags, --compatibility-flag  Flags to use for compatibility checks  [array]
+              --latest                                     Use the latest version of the worker runtime  [boolean] [default: true]
+              --ip                                         IP address to listen on, defaults to \`localhost\`  [string]
+              --port                                       Port to listen on  [number]
+              --inspector-port                             Port for devtools to connect to  [number]
+              --routes, --route                            Routes to upload  [array]
+              --host                                       Host to forward requests to, defaults to the zone of project  [string]
+              --local-protocol                             Protocol to listen to requests on, defaults to http.  [choices: \\"http\\", \\"https\\"]
+              --experimental-public                        Static assets to be served  [string]
+              --site                                       Root folder of static assets for Workers Sites  [string]
+              --site-include                               Array of .gitignore-style patterns that match file or directory names from the sites directory. Only matched items will be uploaded.  [array]
+              --site-exclude                               Array of .gitignore-style patterns that match file or directory names from the sites directory. Matched items will not be uploaded.  [array]
+              --upstream-protocol                          Protocol to forward requests to host on, defaults to https.  [choices: \\"http\\", \\"https\\"]
+              --jsx-factory                                The function that is called for each JSX element  [string]
+              --jsx-fragment                               The function that is called for each JSX fragment  [string]
+              --tsconfig                                   Path to a custom tsconfig.json file  [string]
+          -l, --local                                      Run on my machine  [boolean] [default: false]
+              --minify                                     Minify the script  [boolean]
+              --node-compat                                Enable node.js compatibility  [boolean]
+              --experimental-enable-local-persistence      Enable persistence for this session (only for local mode)  [boolean]
+              --inspect                                    Enable dev tools  [deprecated] [boolean]
+        X [ERROR] Not enough arguments following: site
+
+        ",
+          "out": "
+        ",
+          "warn": "",
+        }
+      `);
+    });
+  });
+
+  describe("--inspect", () => {
+    it("should warn if --inspect is used", async () => {
+      fs.writeFileSync("index.js", `export default {};`);
+      await runWrangler("dev index.js --inspect");
+      expect(std).toMatchInlineSnapshot(`
+        Object {
+          "debug": "",
+          "err": "",
+          "out": "",
+          "warn": "▲ [WARNING] Passing --inspect is unnecessary, now you can always connect to devtools.
+
+        ",
+        }
+      `);
+    });
+  });
 });
 
 function mockGetZones(domain: string, zones: { id: string }[] = []) {

package/src/__tests__/guess-worker-format.test.ts

@@ -1,10 +1,12 @@
 import { writeFile } from "fs/promises";
 import path from "path";
 import guessWorkerFormat from "../entry";
+import { mockConsoleMethods } from "./helpers/mock-console";
 import { runInTempDir } from "./helpers/run-in-tmp";
 
 describe("guess worker format", () => {
   runInTempDir();
+  const std = mockConsoleMethods();
   it('should detect a "modules" worker', async () => {
     await writeFile("./index.ts", "export default {};");
     // Note that this isn't actually a valid worker, because it's missing
@@ -39,7 +41,7 @@ describe("guess worker format", () => {
         "service-worker"
       )
     ).rejects.toThrow(
-      "You configured this worker to be a 'service-worker', but the file you are trying to build appears to have ES module exports. Please pass `--format modules`, or simply remove the configuration."
+      "You configured this worker to be a 'service-worker', but the file you are trying to build appears to have a `default` export like a module worker. Please pass `--format modules`, or simply remove the configuration."
     );
   });
 
@@ -55,4 +57,29 @@ describe("guess worker format", () => {
       "You configured this worker to be 'modules', but the file you are trying to build doesn't export a handler. Please pass `--format service-worker`, or simply remove the configuration."
     );
   });
+
+  it("should not error if a .js entry point has jsx", async () => {
+    await writeFile("./index.js", "console.log(<div/>)");
+    const guess = await guessWorkerFormat(
+      path.join(process.cwd(), "./index.js"),
+      process.cwd(),
+      undefined
+    );
+    expect(guess).toBe("service-worker");
+  });
+
+  it("logs a warning when a worker has exports, but not a default one", async () => {
+    await writeFile("./index.ts", "export const foo = 1;");
+    const guess = await guessWorkerFormat(
+      path.join(process.cwd(), "./index.ts"),
+      process.cwd(),
+      undefined
+    );
+    expect(guess).toBe("service-worker");
+    expect(std.warn).toMatchInlineSnapshot(`
+      "▲ [WARNING] The entrypoint index.ts has exports like an ES Module, but hasn't defined a default export like a module worker normally would. Building the worker using \\"service-worker\\" format...
+
+      "
+    `);
+  });
 });

package/src/__tests__/helpers/mock-cfetch.ts

@@ -181,6 +181,9 @@ export function unsetAllMocks() {
 
 const kvGetMocks = new Map<string, string>();
 
+/**
+ * @mocked typeof fetchKVGetValue
+ */
 export function mockFetchKVGetValue(
   accountId: string,
   namespaceId: string,
@@ -188,7 +191,8 @@ export function mockFetchKVGetValue(
 ) {
   const mapKey = `${accountId}/${namespaceId}/${key}`;
   if (kvGetMocks.has(mapKey)) {
-    return kvGetMocks.get(mapKey);
+    const value = kvGetMocks.get(mapKey);
+    if (value !== undefined) return Promise.resolve(value);
   }
   throw new Error(`no mock value found for \`kv:key get\` - ${mapKey}`);
 }

package/src/__tests__/helpers/mock-console.ts

@@ -1,15 +1,20 @@
 import * as util from "node:util";
+import { logger } from "../../logger";
 
 /**
  * We use this module to mock console methods, and optionally
  * assert on the values they're called with in our tests.
  */
 
-let logSpy: jest.SpyInstance,
+let debugSpy: jest.SpyInstance,
+  logSpy: jest.SpyInstance,
   errorSpy: jest.SpyInstance,
   warnSpy: jest.SpyInstance;
 
 const std = {
+  get debug() {
+    return normalizeOutput(debugSpy);
+  },
   get out() {
     return normalizeOutput(logSpy);
   },
@@ -22,8 +27,8 @@ const std = {
 };
 
 function normalizeOutput(spy: jest.SpyInstance): string {
-  return stripTrailingWhitespace(
-    normalizeSlashes(stripTimings(captureCalls(spy)))
+  return normalizeErrorMarkers(
+    stripTrailingWhitespace(normalizeSlashes(stripTimings(captureCalls(spy))))
   );
 }
 
@@ -35,11 +40,14 @@ function captureCalls(spy: jest.SpyInstance): string {
 
 export function mockConsoleMethods() {
   beforeEach(() => {
+    logger.columns = 100;
+    debugSpy = jest.spyOn(console, "debug").mockImplementation();
     logSpy = jest.spyOn(console, "log").mockImplementation();
     errorSpy = jest.spyOn(console, "error").mockImplementation();
     warnSpy = jest.spyOn(console, "warn").mockImplementation();
   });
   afterEach(() => {
+    debugSpy.mockRestore();
     logSpy.mockRestore();
     errorSpy.mockRestore();
     warnSpy.mockRestore();
@@ -47,6 +55,15 @@ export function mockConsoleMethods() {
   return std;
 }
 
+/**
+ * Normalize error `X` markers.
+ *
+ * Windows gets a different character.
+ */
+function normalizeErrorMarkers(str: string): string {
+  return str.replaceAll("✘", "X");
+}
+
 /**
  * Ensure slashes in the `str` are OS file-system agnostic.
  *

package/src/__tests__/helpers/mock-dialogs.ts

@@ -1,4 +1,5 @@
 import { confirm, prompt } from "../../dialogs";
+import { normalizeSlashes } from "./mock-console";
 
 /**
  * The expected values for a confirmation request.
@@ -20,7 +21,7 @@ export interface ConfirmExpectation {
 export function mockConfirm(...expectations: ConfirmExpectation[]) {
   (confirm as jest.Mock).mockImplementation((text: string) => {
     for (const { text: expectedText, result } of expectations) {
-      if (text === expectedText) {
+      if (normalizeSlashes(text) === normalizeSlashes(expectedText)) {
         return Promise.resolve(result);
       }
     }
@@ -28,6 +29,18 @@ export function mockConfirm(...expectations: ConfirmExpectation[]) {
   });
 }
 
+export function clearConfirmMocks() {
+  (confirm as jest.Mock).mockReset();
+  // Because confirm was originally a spy, calling mockReset will simply reset
+  // it as a function with no return value (!), so we need to accitionally reset
+  // the mock implementation to the one that throws (from jest.setup.js).
+  (confirm as jest.Mock).mockImplementation((text: string) => {
+    throw new Error(
+      `Unexpected call to \`confirm("${text}")\`.\nYou should use \`mockConfirm()\` to mock calls to \`confirm()\` with expectations. Search the codebase for \`mockConfirm\` to learn more.`
+    );
+  });
+}
+
 /**
  * The expected values for a prompt request.
  */
@@ -63,3 +76,15 @@ export function mockPrompt(...expectations: PromptExpectation[]) {
     }
   );
 }
+
+export function clearPromptMocks() {
+  (prompt as jest.Mock).mockReset();
+  // Because prompt was originally a spy, calling mockReset will simply reset
+  // it as a function with no return value (!), so we need to accitionally reset
+  // the mock implementation to the one that throws (from jest.setup.js).
+  (prompt as jest.Mock).mockImplementation((text: string) => {
+    throw new Error(
+      `Unexpected call to \`prompt(${text}, ...)\`.\nYou should use \`mockPrompt()\` to mock calls to \`prompt()\` with expectations. Search the codebase for \`mockPrompt\` to learn more.`
+    );
+  });
+}

package/src/__tests__/helpers/mock-http-server.ts

@@ -0,0 +1,46 @@
+import http from "node:http";
+import type { Request } from "undici";
+
+/**
+ * Setup a mock HTTP server that can be triggered directly without interacting with any network.
+ *
+ * @returns a `fetch`-like function that will trigger the mock server to handle the request.
+ */
+export function mockHttpServer() {
+  let listener: http.RequestListener;
+
+  beforeEach(() => {
+    jest
+      .spyOn(http, "createServer")
+      .mockImplementation((...args: unknown[]) => {
+        listener = args.pop() as http.RequestListener;
+        return {
+          listen: jest.fn(),
+          close(callback?: (err?: Error) => void) {
+            callback?.();
+            return this;
+          },
+        } as unknown as http.Server;
+      });
+  });
+
+  return async (req: Request) => {
+    const resp = new http.ServerResponse(
+      // If you squint you can just about see that an `IncomingMessages` is like a `Request`!
+      req as unknown as http.IncomingMessage
+    );
+
+    // The listener will attache a callback to the response by calling `resp.end(callback)`.
+    // We want to capture that so that we can trigger it after the listener has completed its work.
+    const endSpy = jest.spyOn(resp, "end");
+
+    // The `await` here is important to allow the listener to complete its async work before we end the response.
+    await listener(req as unknown as http.IncomingMessage, resp);
+
+    // Now trigger the end callback.
+    const endCallback = endSpy.mock.calls[0].pop();
+    endCallback?.();
+
+    return resp;
+  };
+}

package/src/__tests__/helpers/mock-istty.ts

@@ -0,0 +1,27 @@
+const ORIGINAL_STDOUT_ISTTY = process.stdout.isTTY;
+const ORIGINAL_STDIN_ISTTY = process.stdin.isTTY;
+
+/**
+ * Mock `process.stdout.isTTY`
+ */
+export function useMockIsTTY() {
+  /**
+   * Explicitly set `process.stdout.isTTY` to a given value
+   */
+  const setIsTTY = (isTTY: boolean) => {
+    process.stdout.isTTY = isTTY;
+    process.stdin.isTTY = isTTY;
+  };
+
+  beforeEach(() => {
+    process.stdout.isTTY = ORIGINAL_STDOUT_ISTTY;
+    process.stdin.isTTY = ORIGINAL_STDIN_ISTTY;
+  });
+
+  afterEach(() => {
+    process.stdout.isTTY = ORIGINAL_STDOUT_ISTTY;
+    process.stdin.isTTY = ORIGINAL_STDIN_ISTTY;
+  });
+
+  return { setIsTTY };
+}