[fix] Supertest attempts to bind a port that is already in use on a Mac, causing random failures

$ lsof -nP -iTCP -sTCP:LISTEN | grep -E '(idea|Code)'
idea        742 ... TCP 127.0.0.1:49490 (LISTEN)   <- port of a flaked 404
idea        742 ... TCP 127.0.0.1:49712 (LISTEN)   <- port of a flaked 404
Code     54231 ... TCP 127.0.0.1:60931 (LISTEN)   <- port of two timed-out tests
Code     55585 ... TCP 127.0.0.1:58535 (LISTEN)   <- port of a flaked 404

use strict';

/**
 * Failing test for: supertest's serverAddress() binds the wildcard address,
 * so on macOS another process's 127.0.0.1 listener on the same ephemeral
 * port silently answers the test's requests.
 *
 * A `before` hook starts a SEPARATE PROCESS that binds 127.0.0.1-specific
 * "foreign" listeners (answering 404) on the ephemeral ports the kernel is
 * about to hand out — the role IDE helper processes play on real developer
 * machines. The test then makes plain supertest requests against an
 * always-200 canary app and asserts every response came from that app.
 *
 * Expected: passes everywhere once supertest binds its ephemeral servers to
 *           127.0.0.1 explicitly.
 * Actual:   fails on macOS — requests are answered by the foreign process.
 *           Passes on Linux, where the kernel refuses to hand a wildcard
 *           bind a port that is already held on loopback.
 *
 * Run:  npm i supertest && node --test failing-test-shadowed-port.test.js
 * (Uses node's built-in test runner; the describe/it/before/after shape maps
 * directly onto mocha for inclusion in supertest's own suite.)
 */

const { describe, it, before, after } = require('node:test');
const assert = require('node:assert');
const net = require('node:net');
const { spawn } = require('node:child_process');
const request = require('supertest');

const FOREIGN_COUNT = 100;
const REQUESTS = 20;
const CANARY = `supertest-canary-${process.pid}`;

const app = (req, res) => {
  res.statusCode = 200;
  res.end(CANARY);
};

// Child: bind 127.0.0.1-specific listeners on every second upcoming
// ephemeral port (client source ports consume the gaps), print the bound
// ports as JSON when ready, stay alive until killed.
const CHILD_SRC = `
  const http = require('http');
  const base = Number(process.argv[1]);
  let pending = ${FOREIGN_COUNT};
  const bound = [];
  for (let i = 0; i < ${FOREIGN_COUNT}; i++) {
    const done = () => { if (--pending === 0) console.log(JSON.stringify(bound)); };
    const srv = http.createServer((req, res) => {
      res.statusCode = 404;
      res.end('foreign-server');
    });
    srv.once('error', done); // port taken by a real process — skip it
    srv.listen(base + 1 + i * 2, '127.0.0.1', () => { bound.push(srv.address().port); done(); });
  }
  setInterval(() => {}, 1 << 30);
`;

describe('supertest ephemeral test server', () => {
  let child;

  before(async () => {
    // Find where the kernel's ephemeral port counter currently is.
    const probe = net.createServer().listen(0);
    await new Promise(resolve => probe.once('listening', resolve));
    const base = probe.address().port;
    await new Promise(resolve => probe.close(resolve));

    // Start the foreign process and wait until its listeners are up.
    child = spawn(process.execPath, ['-e', CHILD_SRC, String(base)], {
      stdio: ['ignore', 'pipe', 'inherit'],
    });
    await new Promise(resolve => child.stdout.once('data', resolve));
  });

  after(() => {
    if (child) child.kill();
  });

  it('every request is served by the server supertest started', async () => {
    for (let i = 1; i <= REQUESTS; i++) {
      const test = request(app)
        .get('/ping')
        .timeout({ response: 2500, deadline: 4000 });
      const port = Number(new URL(test.url).port);

      let res;
      try {
        res = await test;
      } catch (err) {
        // superagent may deliver foreign non-2xx responses as errors
        assert.ok(
          err.response,
          `request ${i} to 127.0.0.1:${port} failed without a response: ${err.message}`
        );
        res = err.response;
      }

      assert.strictEqual(
        `${res.status} ${res.text}`,
        `200 ${CANARY}`,
        `request ${i} to 127.0.0.1:${port} was answered by a foreign process, ` +
          `not the server supertest started (got HTTP ${res.status} ${JSON.stringify(res.text)})`
      );
    }
  });
});