@zgeoff/atc 3.4.1 → 3.5.0

package/src/test-utils/start-test-daemon.ts

@@ -42,31 +42,67 @@ interface TestDaemonConfig {
   // The temp directory's name prefix.
   readonly prefix?: string;
   readonly options?: TestDaemonOptionsBuilder;
+
+  // Whether each boot opens the main client; it does unless this is false.
+  readonly mainClient?: boolean;
+}
+
+/**
+ * A running test daemon and the calls that drive it.
+ */
+interface TestDaemon extends TestDaemonPaths {
+  readonly build: string;
+  readonly logs: string[];
+  readonly events: EventMsg[];
+  readonly daemon: DaemonHandle;
+  readonly client: DaemonClient;
+  readonly openClient: (hello?: Readonly<Record<string, unknown>>) => Promise<DaemonClient>;
+  readonly openTCPClient: () => Promise<DaemonClient>;
+  readonly sendHookLines: (...lines: readonly Readonly<Record<string, unknown>>[]) => Promise<void>;
+  readonly stop: () => Promise<void>;
+  readonly restart: (options?: TestDaemonOptionsBuilder) => Promise<void>;
+  readonly dispose: () => Promise<void>;
+}
+
+/**
+ * The harness a config starts: one that opens no main client has neither
+ * that client nor the events it would collect.
+ */
+type StartedTestDaemon<Config extends TestDaemonConfig> = Config extends {
+  readonly mainClient: false;
 }
+  ? Omit<TestDaemon, 'client' | 'events'>
+  : TestDaemon;
 
 // The build string the daemon and every client the harness opens send in
 // their handshake.
 const BUILD = 'atc/test-build';
 
 /**
- * A real daemon in a fresh temp directory, with a client that has already
- * sent its handshake. The options builder chooses what the daemon wires;
- * the harness sets the paths and the build, and collects the daemon's log
- * lines unless the options set their own log. `events` collects every event
- * the main client receives, across restarts. `openClient` opens another
- * client over the unix socket and sends its handshake with the given
- * params; `openTCPClient` connects to the TCP listener and sends nothing, so
- * the test drives that handshake itself. `sendHookLines` writes reporter
- * lines to the reporter socket and resolves once the daemon has closed the
- * connection. `stop` closes every client and stops the daemon; `restart`
- * does the same, then boots on the same paths and state with the options
- * given or the last ones, and opens a new main client. Disposal stops what
- * is running and removes the directory. That disposal runs once the current
- * test finishes, so it must run inside a test; disposing sooner runs it
- * then, and a second disposal does nothing. A first boot that fails runs it
+ * A real daemon in a fresh temp directory, with a main client that has
+ * already sent its handshake unless the config turns that client off, which
+ * leaves every connection the daemon counts to the test. The options
+ * builder chooses what the daemon wires; the harness sets the paths and the
+ * build, and collects the daemon's log lines unless the options set their
+ * own log. `events` collects every event the main client receives, across
+ * restarts. `openClient` opens another client over the unix socket and
+ * sends its handshake with the given params; `openTCPClient` connects to
+ * the TCP listener and sends nothing, so the test drives that handshake
+ * itself. `sendHookLines` writes reporter lines to the reporter socket and
+ * resolves once the daemon has closed the connection. `stop` closes every
+ * client and stops the daemon; `restart` does the same, then boots on the
+ * same paths and state with the options given or the last ones, and opens
+ * a new main client unless the config turns it off. `dispose` stops what is
+ * running and removes the directory. It runs once the current test
+ * finishes, so the harness must start inside a test; calling it sooner runs
+ * it then, and a second call does nothing. A first boot that fails runs it
  * before the start rejects.
  */
-export async function startTestDaemon(config: TestDaemonConfig = {}) {
+export function startTestDaemon<const Config extends TestDaemonConfig = TestDaemonConfig>(
+  config?: Config,
+): Promise<StartedTestDaemon<Config>>;
+
+export async function startTestDaemon(config: TestDaemonConfig = {}): Promise<TestDaemon> {
   const tmp = setupTempDir(config.prefix ?? 'atc-test-daemon-');
 
   // Registered after the directory, so it releases first: the daemon stops
@@ -75,7 +111,7 @@ export async function startTestDaemon(config: TestDaemonConfig = {}) {
 
   const dispose = registerTestCleanup(() => stack.disposeAsync());
 
-  stack.use(tmp);
+  stack.defer(tmp.teardown);
 
   const paths: TestDaemonPaths = {
     dir: tmp.dir,
@@ -142,6 +178,10 @@ export async function startTestDaemon(config: TestDaemonConfig = {}) {
 
     live = daemon;
 
+    if (config.mainClient === false) {
+      return { daemon, client: null };
+    }
+
     const client = await openClient();
 
     client.onEvent = (event) => {
@@ -168,6 +208,10 @@ export async function startTestDaemon(config: TestDaemonConfig = {}) {
       return current.daemon;
     },
     get client(): DaemonClient {
+      if (current.client === null) {
+        throw new Error('the test daemon started without a main client');
+      }
+
       return current.client;
     },
     openClient,
@@ -224,6 +268,6 @@ export async function startTestDaemon(config: TestDaemonConfig = {}) {
 
       current = await boot();
     },
-    [Symbol.asyncDispose]: dispose,
+    dispose,
   };
 }

package/src/test-utils/start-tui-harness.ts

@@ -32,16 +32,17 @@ interface TUIHarnessOptions {
  * starts a new client on the same home and stops capturing the old one.
  * `read` returns every byte the client drew since the last `reset`, and
  * `waitFor` polls that capture for a needle. The client appends what it
- * decides without drawing to a log: `markClientLog` returns a cursor into
- * it, and `waitForClientLog` polls for a line written after that cursor.
+ * decides without drawing to a log: `countClientLogLines` returns how many
+ * lines it holds, and `waitForClientLog` polls for a line written after
+ * that many.
  * `writeConfig` writes the home's config: the stand-in binaries and the git
  * transports the fixture repositories need, with the fields given laid over
  * them. `env` is the environment the client runs with, so a daemon started
  * with it serves the client. A wait made before the client draws anything
- * gets `bootMs` for that first byte. Disposal stops the client and the
- * daemon in the home and removes it. That disposal runs once the current
- * test finishes, so it must run inside a test; disposing sooner runs it
- * then, and a second disposal does nothing.
+ * gets `bootMs` for that first byte. `stop` kills every client a boot
+ * started, stops the daemon in the home, and removes the home. That stop runs once the current test
+ * finishes, so it must run inside a test; calling `stop` sooner runs it
+ * then, and a second stop does nothing.
  */
 export function startTUIHarness(options: TUIHarnessOptions = {}) {
   const tmp = setupTempDir('atc-tui-');
@@ -50,9 +51,9 @@ export function startTUIHarness(options: TUIHarnessOptions = {}) {
   // daemon stop before their home is removed.
   const owned = new AsyncDisposableStack();
 
-  const dispose = registerTestCleanup(() => owned.disposeAsync());
+  const stop = registerTestCleanup(() => owned.disposeAsync());
 
-  owned.use(tmp);
+  owned.defer(tmp.teardown);
 
   // The client boots with this home as its cwd and lists it first in the
   // picker, so the path is resolved the way the client reports it.
@@ -129,6 +130,12 @@ export function startTUIHarness(options: TUIHarnessOptions = {}) {
         env,
       });
 
+      // Every client a boot starts is killed before the daemon stops, so a
+      // client a later boot replaced never outlives the test.
+      owned.defer(() => {
+        booted.kill();
+      });
+
       const exit = Promise.withResolvers<number>();
 
       booted.onExit((event) => {
@@ -206,7 +213,7 @@ export function startTUIHarness(options: TUIHarnessOptions = {}) {
       return exited;
     },
 
-    markClientLog(): number {
+    countClientLogLines(): number {
       return readClientLog(clientLogPath).length;
     },
 
@@ -225,7 +232,7 @@ export function startTUIHarness(options: TUIHarnessOptions = {}) {
       );
     },
 
-    [Symbol.asyncDispose]: dispose,
+    stop,
   };
 }
 

package/src/test-utils/subscribe-to-socket-lines.ts

@@ -11,7 +11,7 @@ interface SocketLines {
 
   readonly write: (data: string) => void;
   readonly waitForLine: (count?: number, timeoutMs?: number) => Promise<string[]>;
-  readonly [Symbol.asyncDispose]: () => Promise<void>;
+  readonly unsubscribe: () => void;
 }
 
 interface SocketLinesOptions {
@@ -35,8 +35,8 @@ interface SocketLinesOptions {
  * the lines, throwing when `timeoutMs` passes first or the connection
  * closes short of the count; a stub clock passed as `now` and `wait` steps
  * that timeout without waiting it out. The connection ends once the current
- * test finishes, so it must run inside a test; disposal ends it sooner, and
- * a second end does nothing.
+ * test finishes, so it must run inside a test; `unsubscribe` ends it
+ * sooner, and a second end does nothing.
  */
 export async function subscribeToSocketLines(
   path: string,
@@ -72,7 +72,7 @@ export async function subscribeToSocketLines(
     },
   });
 
-  const stop = registerTestCleanup(() => {
+  const unsubscribe = registerTestCleanup(() => {
     socket.end();
   });
 
@@ -118,10 +118,6 @@ export async function subscribeToSocketLines(
 
       return requireLines(count);
     },
-    [Symbol.asyncDispose]: () => {
-      stop();
-
-      return Promise.resolve();
-    },
+    unsubscribe,
   };
 }

package/src/test-utils/{can-bind-addresses.ts → try-bind-addresses.ts}

@@ -1,10 +1,11 @@
 /**
- * Whether this host can bind a socket to every given address, tried by
- * listening on a kernel-chosen port of each and closing it at once. A host
+ * Tries to bind a socket to every given address on this host, by listening
+ * on a kernel-chosen port of each and closing it at once, and returns whether
+ * every bind succeeded. A host
  * without an address, such as stock macOS for any loopback address past
  * 127.0.0.1, refuses the bind with EADDRNOTAVAIL.
  */
-export function canBindAddresses(hostnames: readonly string[]): boolean {
+export function tryBindAddresses(hostnames: readonly string[]): boolean {
   for (const hostname of hostnames) {
     try {
       const listener = Bun.listen({ hostname, port: 0, socket: { data() {} } });