@rvoh/psychic-spec-helpers 3.2.2 → 3.4.0

package/dist/esm/src/feature/helpers/launchDevServer.js

@@ -2,7 +2,7 @@ import { spawn } from 'child_process';
 import { createServer } from 'net';
 import sleep from '../../shared/sleep.js';
 const devServerProcesses = {};
-export default async function launchDevServer(key, { port = 3000, cmd = 'pnpm client', timeout = 5000, } = {}) {
+export default async function launchDevServer(key, { port = 3000, cmd = 'pnpm client', timeout = 30000, } = {}) {
     if (devServerProcesses[key])
         return;
     if (process.env.DEBUG === '1')
@@ -17,9 +17,14 @@ export default async function launchDevServer(key, { port = 3000, cmd = 'pnpm cl
         },
     });
     devServerProcesses[key] = proc;
-    await waitForPort(key, port, timeout);
+    let spawnError;
+    let exited = false;
+    let exitCode = null;
+    // attached before any await so that an immediate spawn failure (e.g. ENOENT)
+    // cannot emit 'error' with no listener and crash the process
     proc.on('error', err => {
-        throw err;
+        spawnError = err;
+        console.error(`Dev server "${key}" (\`${cmd}\`) process error: ${err.message}`);
     });
     proc.stdout.on('data', data => {
         if (process.env.DEBUG === '1')
@@ -29,13 +34,37 @@ export default async function launchDevServer(key, { port = 3000, cmd = 'pnpm cl
         if (process.env.DEBUG === '1')
             console.error(`Server error: ${data}`);
     });
-    proc.on('error', err => {
-        console.error(`Server process error: ${err}`);
-    });
     proc.on('close', code => {
-        if (process.env.DEBUG === '1')
+        exited = true;
+        exitCode = code;
+        if (devServerProcesses[key] === proc) {
+            // the process died on its own (it was not stopped via stopDevServer); evict it
+            // so it is not treated as still running, and log unconditionally so specs that
+            // subsequently fail on a dead dev server are comprehensible
+            delete devServerProcesses[key];
+            if (!spawnError)
+                console.error(`Dev server "${key}" (\`${cmd}\`) exited unexpectedly with code ${code}`);
+        }
+        else if (process.env.DEBUG === '1') {
             console.log(`Server process exited with code ${code}`);
+        }
     });
+    try {
+        await waitForPort(key, cmd, port, timeout, () => {
+            if (spawnError)
+                return new Error(`Dev server "${key}" (\`${cmd}\`) failed to start: ${spawnError.message}`, {
+                    cause: spawnError,
+                });
+            if (exited)
+                return new Error(`Dev server "${key}" (\`${cmd}\`) exited with code ${exitCode} before listening on port ${port}`);
+            return undefined;
+        });
+    }
+    catch (err) {
+        if (devServerProcesses[key] === proc)
+            delete devServerProcesses[key];
+        throw err;
+    }
 }
 export function stopDevServer(key) {
     const proc = devServerProcesses[key];
@@ -45,9 +74,11 @@ export function stopDevServer(key) {
     if (proc?.pid) {
         if (process.env.DEBUG === '1')
             console.log('Stopping server...');
+        // delete before killing so the 'close' listener can distinguish an intentional
+        // stop from the dev server dying on its own
+        delete devServerProcesses[key];
         // serverProcess.kill('SIGINT')
         process.kill(-proc.pid, 'SIGKILL');
-        delete devServerProcesses[key];
         if (process.env.DEBUG === '1')
             console.log('server stopped');
     }
@@ -75,21 +106,19 @@ async function isPortAvailable(port) {
             .listen(port, '127.0.0.1');
     });
 }
-async function waitForPort(key, port, timeout = 5000) {
-    if (await isPortAvailable(port)) {
-        return true;
-    }
+async function waitForPort(key, cmd, port, timeout, abortError) {
     const startTime = Date.now();
-    async function recursiveWaitForPort() {
-        if (await isPortAvailable(port)) {
-            return true;
-        }
+    // the port being available means nothing is listening on it yet,
+    // so keep waiting until the dev server has actually bound it
+    while (await isPortAvailable(port)) {
+        const error = abortError();
+        if (error)
+            throw error;
         if (Date.now() > startTime + timeout) {
-            stopDevServer(key);
-            throw new Error('waited too long for port: ' + port);
+            if (devServerProcesses[key])
+                stopDevServer(key);
+            throw new Error(`Dev server "${key}" (\`${cmd}\`) did not listen on port ${port} within ${timeout}ms`);
         }
         await sleep(50);
-        return await recursiveWaitForPort();
     }
-    return await recursiveWaitForPort();
 }

package/dist/esm/src/feature/matchers/toHaveSelector.js

@@ -1,7 +1,14 @@
 import applyDefaultWaitForOpts from '../helpers/applyDefaultWaitForOpts.js';
 export default async function toHaveSelector(page, selector, opts) {
+    // Presence-only contract: this matcher asserts that the selector is
+    // attached to the DOM, regardless of visibility. Strip visible/hidden so
+    // a caller-passed { visible: true } can't narrow the check to also
+    // require visibility.
+    const waitForOpts = applyDefaultWaitForOpts(opts);
+    delete waitForOpts.visible;
+    delete waitForOpts.hidden;
     try {
-        await page.waitForSelector(selector, applyDefaultWaitForOpts(opts));
+        await page.waitForSelector(selector, waitForOpts);
         return {
             pass: true,
             message: () => {

package/dist/esm/src/feature/matchers/toNotHaveSelector.js

@@ -1,18 +1,35 @@
 import applyDefaultWaitForOpts from '../helpers/applyDefaultWaitForOpts.js';
+import sleep from '../../shared/sleep.js';
 export default async function toNotHaveSelector(page, selector, opts) {
-    try {
-        await page.waitForSelector(selector, { hidden: true, ...applyDefaultWaitForOpts(opts) });
-        return {
-            pass: true,
-            message: () => {
-                throw new Error('Cannot negate toNotHaveSelector, use toHaveSelector instead');
-            },
-        };
-    }
-    catch {
-        return {
-            pass: false,
-            message: () => `Expected page to not have visible selector, but it did: ${selector}`,
-        };
+    // Presence-only contract: this matcher asserts that the selector is
+    // absent from the DOM, regardless of visibility. A present-but-hidden
+    // element must FAIL this matcher, so we poll for true DOM absence via
+    // page.$ (rather than relying on waitForSelector({ hidden: true }),
+    // which only asserts invisibility). page.$ (not document.querySelector)
+    // is used so Puppeteer's extended selectors like ::-p-text keep working.
+    const timeout = applyDefaultWaitForOpts(opts).timeout ?? 5000;
+    const interval = 50;
+    const startTime = Date.now();
+    async function poll() {
+        const element = await page.$(selector);
+        if (!element) {
+            return {
+                pass: true,
+                message: () => {
+                    throw new Error('Cannot negate toNotHaveSelector, use toHaveSelector instead');
+                },
+            };
+        }
+        if (Date.now() >= startTime + timeout) {
+            await element.dispose();
+            return {
+                pass: false,
+                message: () => `Expected page to not have selector, but it did: ${selector}`,
+            };
+        }
+        await element.dispose();
+        await sleep(interval);
+        return await poll();
     }
+    return await poll();
 }

package/dist/types/src/index.d.ts

@@ -17,7 +17,6 @@ export { default as providePuppeteerViteMatchers } from './feature/helpers/provi
 export { default as resetBrowserState } from './feature/helpers/resetBrowserState.js';
 export { default as visit } from './feature/helpers/visit.js';
 declare global {
-    const context: (typeof import('vitest'))['describe'];
     const page: InstanceType<typeof Page>;
     const visit: (typeof import('./feature/helpers/visit.js'))['default'];
     const check: (typeof import('./feature/helpers/matcher-globals/check.js'))['default'];
@@ -30,9 +29,7 @@ declare global {
     const uncheck: (typeof import('./feature/helpers/matcher-globals/uncheck.js'))['default'];
 }
 declare module 'vitest' {
-    interface ExpectStatic extends PuppeteerAssertions {
-    }
-    interface Assertion extends PuppeteerAssertions {
+    interface Matchers<T = any> extends PuppeteerAssertions {
     }
 }
 interface PuppeteerAssertions {

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@rvoh/psychic-spec-helpers",
-  "version": "3.2.2",
+  "version": "3.4.0",
   "description": "psychic framework spec helpers",
   "author": "RVO Health",
   "publishConfig": {
@@ -33,7 +33,7 @@
     "uspec": "vitest --config ./spec/unit/vite.config.ts",
     "fspec": "vitest --config ./spec/features/vite.config.ts",
     "build": "echo \"building psychic-spec-helpers...\" && rm -rf dist && tsc -p ./tsconfig.esm.build.json",
-    "build:test-app": "rm -rf dist && echo \"building test app to esm...\" && tsc -p ./tsconfig.esm.build.test-app.json && echo \"building test app to cjs...\" && npx tsc -p ./tsconfig.cjs.build.test-app.json",
+    "build:test-app": "rm -rf dist && echo \"building test app to esm...\" && tsc -p ./tsconfig.esm.build.test-app.json",
     "lint": "pnpm eslint --no-warn-ignored \"src/**/*.ts\" \"spec/**/*.ts\" && pnpm prettier . --check",
     "format": "pnpm prettier . --write",
     "prepack": "pnpm build"
@@ -83,5 +83,5 @@
     "dotenv": "^17.2.3",
     "pluralize-esm": "^9.0.5"
   },
-  "packageManager": "pnpm@11.1.3+sha512.c85357fe17ca12dd23dd7071822666dfd7e3cb76fe214e3370b5ea2fb34f2a231185509b63e717f3cd0acb38dd3f8d82bcd5e8172400ae678b70ea4fbed0896d"
+  "packageManager": "pnpm@11.9.0+sha512.bd682d5d03fe525ef7c9fd6780c6884d1e756ac4c9c9fe00c538782824310dcf90e3ddc4f53835f06dfaebd5085e41855e0bcbb3b60de2ac5bbab89e5036f03b"
 }

package/src/feature/helpers/launchDevServer.ts

@@ -9,7 +9,7 @@ export default async function launchDevServer(
   {
     port = 3000,
     cmd = 'pnpm client',
-    timeout = 5000,
+    timeout = 30000,
   }: { port?: number; cmd?: string; timeout?: number } = {}
 ) {
   if (devServerProcesses[key]) return
@@ -28,10 +28,15 @@ export default async function launchDevServer(
 
   devServerProcesses[key] = proc
 
-  await waitForPort(key, port, timeout)
+  let spawnError: Error | undefined
+  let exited = false
+  let exitCode: number | null = null
 
+  // attached before any await so that an immediate spawn failure (e.g. ENOENT)
+  // cannot emit 'error' with no listener and crash the process
   proc.on('error', err => {
-    throw err
+    spawnError = err
+    console.error(`Dev server "${key}" (\`${cmd}\`) process error: ${err.message}`)
   })
 
   proc.stdout.on('data', data => {
@@ -42,13 +47,43 @@ export default async function launchDevServer(
     if (process.env.DEBUG === '1') console.error(`Server error: ${data}`)
   })
 
-  proc.on('error', err => {
-    console.error(`Server process error: ${err as unknown as string}`)
-  })
-
   proc.on('close', code => {
-    if (process.env.DEBUG === '1') console.log(`Server process exited with code ${code}`)
+    exited = true
+    exitCode = code
+
+    if (devServerProcesses[key] === proc) {
+      // the process died on its own (it was not stopped via stopDevServer); evict it
+      // so it is not treated as still running, and log unconditionally so specs that
+      // subsequently fail on a dead dev server are comprehensible
+      delete devServerProcesses[key]
+      if (!spawnError)
+        console.error(`Dev server "${key}" (\`${cmd}\`) exited unexpectedly with code ${code}`)
+    } else if (process.env.DEBUG === '1') {
+      console.log(`Server process exited with code ${code}`)
+    }
   })
+
+  try {
+    await waitForPort(key, cmd, port, timeout, () => {
+      if (spawnError)
+        return new Error(
+          `Dev server "${key}" (\`${cmd}\`) failed to start: ${spawnError.message}`,
+          {
+            cause: spawnError,
+          }
+        )
+
+      if (exited)
+        return new Error(
+          `Dev server "${key}" (\`${cmd}\`) exited with code ${exitCode} before listening on port ${port}`
+        )
+
+      return undefined
+    })
+  } catch (err) {
+    if (devServerProcesses[key] === proc) delete devServerProcesses[key]
+    throw err
+  }
 }
 
 export function stopDevServer(key: string) {
@@ -59,9 +94,11 @@ export function stopDevServer(key: string) {
 
   if (proc?.pid) {
     if (process.env.DEBUG === '1') console.log('Stopping server...')
+    // delete before killing so the 'close' listener can distinguish an intentional
+    // stop from the dev server dying on its own
+    delete devServerProcesses[key]
     // serverProcess.kill('SIGINT')
     process.kill(-proc.pid, 'SIGKILL')
-    delete devServerProcesses[key]
 
     if (process.env.DEBUG === '1') console.log('server stopped')
   }
@@ -91,26 +128,28 @@ async function isPortAvailable(port: number): Promise<boolean> {
   })
 }
 
-async function waitForPort(key: string, port: number, timeout: number = 5000) {
-  if (await isPortAvailable(port)) {
-    return true
-  }
-
+async function waitForPort(
+  key: string,
+  cmd: string,
+  port: number,
+  timeout: number,
+  abortError: () => Error | undefined
+) {
   const startTime = Date.now()
 
-  async function recursiveWaitForPort() {
-    if (await isPortAvailable(port)) {
-      return true
-    }
+  // the port being available means nothing is listening on it yet,
+  // so keep waiting until the dev server has actually bound it
+  while (await isPortAvailable(port)) {
+    const error = abortError()
+    if (error) throw error
 
     if (Date.now() > startTime + timeout) {
-      stopDevServer(key)
-      throw new Error('waited too long for port: ' + port)
+      if (devServerProcesses[key]) stopDevServer(key)
+      throw new Error(
+        `Dev server "${key}" (\`${cmd}\`) did not listen on port ${port} within ${timeout}ms`
+      )
     }
 
     await sleep(50)
-    return await recursiveWaitForPort()
   }
-
-  return await recursiveWaitForPort()
 }

package/src/feature/matchers/toHaveSelector.ts

@@ -6,8 +6,16 @@ export default async function toHaveSelector(
   selector: string,
   opts?: WaitForSelectorOptions
 ) {
+  // Presence-only contract: this matcher asserts that the selector is
+  // attached to the DOM, regardless of visibility. Strip visible/hidden so
+  // a caller-passed { visible: true } can't narrow the check to also
+  // require visibility.
+  const waitForOpts = applyDefaultWaitForOpts(opts)
+  delete waitForOpts.visible
+  delete waitForOpts.hidden
+
   try {
-    await page.waitForSelector(selector, applyDefaultWaitForOpts(opts))
+    await page.waitForSelector(selector, waitForOpts)
     return {
       pass: true,
       message: () => {

package/src/feature/matchers/toNotHaveSelector.ts

@@ -1,23 +1,45 @@
 import { Page, WaitForSelectorOptions } from 'puppeteer'
 import applyDefaultWaitForOpts from '../helpers/applyDefaultWaitForOpts.js'
+import sleep from '../../shared/sleep.js'
 
 export default async function toNotHaveSelector(
   page: Page,
   selector: string,
   opts?: WaitForSelectorOptions
 ) {
-  try {
-    await page.waitForSelector(selector, { hidden: true, ...applyDefaultWaitForOpts(opts) })
-    return {
-      pass: true,
-      message: () => {
-        throw new Error('Cannot negate toNotHaveSelector, use toHaveSelector instead')
-      },
+  // Presence-only contract: this matcher asserts that the selector is
+  // absent from the DOM, regardless of visibility. A present-but-hidden
+  // element must FAIL this matcher, so we poll for true DOM absence via
+  // page.$ (rather than relying on waitForSelector({ hidden: true }),
+  // which only asserts invisibility). page.$ (not document.querySelector)
+  // is used so Puppeteer's extended selectors like ::-p-text keep working.
+  const timeout = applyDefaultWaitForOpts(opts).timeout ?? 5000
+  const interval = 50
+  const startTime = Date.now()
+
+  async function poll(): Promise<{ pass: boolean; message: () => string }> {
+    const element = await page.$(selector)
+    if (!element) {
+      return {
+        pass: true,
+        message: () => {
+          throw new Error('Cannot negate toNotHaveSelector, use toHaveSelector instead')
+        },
+      }
     }
-  } catch {
-    return {
-      pass: false,
-      message: () => `Expected page to not have visible selector, but it did: ${selector}`,
+
+    if (Date.now() >= startTime + timeout) {
+      await element.dispose()
+      return {
+        pass: false,
+        message: () => `Expected page to not have selector, but it did: ${selector}`,
+      }
     }
+
+    await element.dispose()
+    await sleep(interval)
+    return await poll()
   }
+
+  return await poll()
 }

package/src/index.ts

@@ -36,7 +36,11 @@ export { default as resetBrowserState } from './feature/helpers/resetBrowserStat
 export { default as visit } from './feature/helpers/visit.js'
 
 declare global {
-  const context: (typeof import('vitest'))['describe']
+  // `context` is deliberately NOT declared here: @rvoh/dream-spec-helpers (always
+  // present alongside this package in a psychic app) already declares it, and a
+  // second declaration is a TS2451 redeclare error whenever both declarations are
+  // checked in one program (e.g. this repo's own test-app build, where this file
+  // is source rather than a skipLibCheck-suppressed .d.ts).
 
   const page: InstanceType<typeof Page>
   const visit: (typeof import('./feature/helpers/visit.js'))['default']
@@ -51,10 +55,10 @@ declare global {
 }
 
 declare module 'vitest' {
+  // vitest >= 3.2 matcher augmentation point (covers expect(), expect.soft, asymmetric
+  // matchers); augmenting Assertion/ExpectStatic no longer merges under vitest 4
   // eslint-disable-next-line
-  interface ExpectStatic extends PuppeteerAssertions {}
-  // eslint-disable-next-line
-  interface Assertion extends PuppeteerAssertions {}
+  interface Matchers<T = any> extends PuppeteerAssertions {}
 }
 
 interface PuppeteerAssertions {