@yamf/test 0.1.4 → 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 mcbrumagin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,7 +2,7 @@
 
 A minimal, zero-dependency testing library with polymorphic async/await and simultaneous assertion reports.
 
-[![Node](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)]()
+[![Node](https://img.shields.io/badge/node-%3E%3D22.0.0-brightgreen)]()
 [![License](https://img.shields.io/badge/license-MIT-blue)]()
 
 ## Features
@@ -46,6 +46,10 @@ runTests({ testAddition, testAsyncFetch })
 
 Assert that a value or function result passes all assertion functions.
 
+**Failure output:** the runner prints the distilled **first argument** (`for target … value = …`) and each failing predicate (`failed -> …`). Put the value under test first and express expectations in the callbacks — avoid `assert(expr, x => x === true)` where `expr` is already a boolean, or failures only show `true`/`false` with no useful predicate text.
+
+**Errors:** for `Error` values (e.g. a caught `execSync` failure), use **`assertErr(error, …)`** instead of `assert` — see below.
+
 ```javascript
 // Direct value
 assert(5, n => n > 0, n => n < 10)
@@ -248,16 +252,52 @@ import { registryServer, createService } from '@yamf/core'
 
 async function testServices() {
   await terminateAfter(
-    registryServer(),
-    createService(function myService(p) { return { ok: true } }),
+    () => registryServer(),
+    () => createService('my-service', (p) => ({ ok: true })),
     async (registry, service) => {
-      const result = await callService('myService', {})
+      const result = await callService('my-service', {})
       assert(result.ok, v => v === true)
     }
   )
 }
 ```
 
+**Single-callback form** — when the test only needs a registry (and services register against it), you can pass one async function; teardown uses `terminateActiveRegistryServers()` from `@yamf/core` (no need to return the registry instance):
+
+```javascript
+export async function myTestCaseFunction() {
+  await terminateAfter(async () => {
+    await registryServer()
+    await createService('my-service', (p) => ({ ok: true }))
+    const result = await callService('my-service', {})
+    assert(result.ok, (v) => v === true)
+  })
+}
+```
+
+Prefer **named `async function …`** for that body (and for multi-arg factory thunks) so stack traces read clearly; avoid `() =>` wrappers for routine registry/service setup.
+
+### `withInlineRegistry(...factories, testFn)`
+
+Shorthand for `terminateAfter(() => registryServer(), ...)`.
+
+### `pickListenPort()`
+
+Returns a free TCP port on `127.0.0.1`. Use with `withEnv({ YAMF_REGISTRY_URL: \`http://127.0.0.1:${port}\` }, …)` when fixed ports from `.env.test` conflict (e.g. parallel runs or drain races).
+
+```javascript
+import { pickListenPort, withEnv, terminateAfter } from '@yamf/test'
+import { registryServer } from '@yamf/core'
+
+const port = await pickListenPort()
+await withEnv({ YAMF_REGISTRY_URL: `http://127.0.0.1:${port}` }, async () => {
+  await terminateAfter(
+    () => registryServer(),
+    async () => { /* … */ }
+  )
+})
+```
+
 ### `withEnv(envVars, testFn)`
 
 Run a test with temporary environment variables that are restored after.
@@ -277,6 +317,8 @@ async function testWithEnv() {
 }
 ```
 
+**YAMF integration tests:** Prefer defaults from the suite’s `.env.test` and `terminateAfter` for cleanup. Use `withEnv` only when a case must *change* the environment (missing vars, feature flags, per-test secrets, etc.). See [../../docs/TESTING.md](../../docs/TESTING.md) in the YAMF repo.
+
 ## Solo and Mute Flags
 
 Focus on specific tests or skip others during development.
@@ -361,7 +403,7 @@ function TODOtestNewFeature() {
 ✔ testDirectValue (1ms)
 ✔ testFunctionResult (0ms)
 ✔ testAsyncFunction (15ms)
-✘ testFailingAssertion
+✘ testFailingAssertion (12ms)
 
 ----- Testing Complete -----
 ✔ ✔ ✔  Success Report  ✔ ✔ ✔
@@ -385,6 +427,8 @@ testFailingAssertion failed with error: AssertionFailure: ...
 ℹ duration_ms 42
 ```
 
+Each `✔` / `✘` line includes wall time for that test. For a **slowest-first table** (e.g. profiling), run `yamf test --timings` or set `YAMF_TEST_TIMINGS=true`, then use `-f` / `-n` to focus one file or test: `yamf test -d packages/cli -f cli-rolling --timings -n testRestart`.
+
 ## API Reference
 
 ### Assertions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yamf/test",
-  "version": "0.1.4",
+  "version": "0.9.0",
   "type": "module",
   "description": "Functional testing module - with polymorphic async/await and simultaneous assertion reports",
   "main": "src/index.js",
@@ -11,7 +11,7 @@
     "./utils": "./src/utils.js"
   },
   "engines": {
-    "node": ">=20.0.0"
+    "node": ">=22.0.0"
   },
   "keywords": [
     "testing",
@@ -31,9 +31,10 @@
     "url": "https://github.com/mcbrumagin/yamf"
   },
   "peerDependencies": {
-    "@yamf/core": "0.4.0"
+    "@yamf/core": "0.9.0"
   },
   "scripts": {
-    "test": "yamf test -d ."
+    "test": "yamf test -d .",
+    "test:all": "yamf test -d . --include-e2e"
   }
 }

package/src/example-helpers.js

@@ -0,0 +1,29 @@
+import { createServer } from 'node:net'
+import { registryServer } from '@yamf/core'
+import { terminateAfter } from './helpers.js'
+
+/**
+ * Returns an ephemeral TCP port on 127.0.0.1 for examples/tests that must avoid
+ * fixed ports (EADDRINUSE / drain races).
+ * @returns {Promise<number>}
+ */
+export async function pickListenPort () {
+  return new Promise((resolve, reject) => {
+    const s = createServer()
+    s.once('error', reject)
+    s.listen(0, '127.0.0.1', () => {
+      const addr = s.address()
+      const port = typeof addr === 'object' && addr ? addr.port : null
+      s.close((err) => (err ? reject(err) : resolve(port)))
+    })
+  })
+}
+
+/**
+ * Run a test body with a local registry and optional service factories (thunks).
+ * Same argument order as {@link terminateAfter}: `() => registryServer()`, `() => createX()`, …, `async (reg, x) => {}`.
+ * @param  {...(function|function[])} serviceFactoriesAndTestFn
+ */
+export async function withInlineRegistry (...args) {
+  return terminateAfter(() => registryServer(), ...args)
+}

package/src/helpers.js

@@ -1,39 +1,107 @@
-import { Logger, envConfig } from '@yamf/core'
+import { Logger, envConfig, envTruthy, terminateActiveRegistryServers } from '@yamf/core'
 
 const logger = new Logger()
 
 export const sleep = ms => new Promise(resolve => setTimeout(resolve, ms))
 
-export async function terminateAfter(...args /* ...serverFns, testFn */) {
-  args.unshift(args.pop()) // rearrange for spread
-  let [testFn, ...serverFns] = args
-  if (typeof testFn !== 'function') throw new Error('terminateAfter last argument must be a function')
-  
-  let servers = []
+function isThenable (x) {
+  return x != null && typeof x.then === 'function'
+}
+
+async function terminateAfterSingleFn (fn) {
+  let bodyError
   try {
-    servers = await Promise.all(serverFns)
-    for (let server of servers) {
-      if (server && server.length > 0) {
-        let index = servers.indexOf(server)
-        servers.splice(index, 1)
-        servers.push(...server)
+    await fn()
+  } catch (e) {
+    bodyError = e
+  } finally {
+    try {
+      await terminateActiveRegistryServers()
+    } catch (e) {
+      if (process.env.YAMF_TEST_VERBOSE_TEARDOWN != null && envTruthy(process.env.YAMF_TEST_VERBOSE_TEARDOWN)) {
+        console.warn(`[terminateAfter] registry shutdown failed: ${e.message}`)
       }
     }
+  }
+  if (bodyError) throw bodyError
+}
+
+/**
+ * Start servers, run the test, then terminate in a safe order (non-registry first, registry last).
+ *
+ * **Evaluation order (JavaScript):** `terminateAfter(() => registry(), () => create(), testFn)` *starts* all
+ * async tasks while building the argument list, before `terminateAfter` runs—so a later `createRoute()`
+ * can hit the registry before it is listening. **Pass thunks (zero-arg functions) so work starts
+ * in sequence** inside this helper, e.g. `terminateAfter(() => registryServer(), () => createService('x', fn), testFn)`.
+ * You can still pass an already-started Promise (a thenable) when you need parallel start
+ * outside this helper's sequential `for` loop.
+ *
+ * - Each server item is either: a **thenable** (awaited as-is), or a **function** (called with no
+ *   args; the return is awaited, then optional array flattening applies as below).
+ * - A single `Promise.all([...])` can be one argument: `() => Promise.all([...])` as a thunk, or
+ *   pass the Promise if you need parallel start outside the sequential `for` loop.
+ *
+ * @param  {...(Promise<unknown> | (() => unknown) | unknown | unknown[])} serverFns
+ *   Each item may be a thenable, a no-arg factory, a value, or (after await) a non-empty `Array` of
+ *   server-like objects.
+ * @param {Function} testFn
+ */
+export async function terminateAfter (...args) {
+  if (args.length === 1 && typeof args[0] === 'function') {
+    return await terminateAfterSingleFn(args[0])
+  }
+
+  const testFn = args[args.length - 1]
+  const serverInputs = args.slice(0, -1)
+  if (typeof testFn !== 'function') {
+    throw new Error('terminateAfter last argument must be a function')
+  }
 
-    let result = await testFn(...servers)
-    return result
+  const flatServers = []
+  try {
+    for (const item of serverInputs) {
+      let toAwait
+      if (isThenable(item)) {
+        toAwait = item
+      } else if (typeof item === 'function') {
+        const out = item()
+        toAwait = isThenable(out) ? out : Promise.resolve(out)
+      } else {
+        toAwait = Promise.resolve(item)
+      }
+      const resolved = await toAwait
+      if (Array.isArray(resolved) && resolved.length > 0) {
+        for (const s of resolved) {
+          flatServers.push(s)
+        }
+      } else {
+        flatServers.push(resolved)
+      }
+    }
+    return await testFn(...flatServers)
   } finally {
-    let registryIndex = servers.findIndex(s => s.isRegistry)
+    const registryIndex = flatServers.findIndex(s => s && s.isRegistry)
     if (registryIndex > -1) {
-      let registryServer = servers[registryIndex]
-      servers = servers.slice(0, registryIndex).concat(servers.slice(registryIndex + 1))
-      for (let server of servers) {
-        await server?.terminate()
-        logger.info(`terminated server ${server?.name} at port ${server?.port}`)
+      const registryServer_ = flatServers[registryIndex]
+      const otherServers = flatServers.filter((_, i) => i !== registryIndex)
+      for (const server of otherServers) {
+        if (!server) {
+          continue
+        }
+        await server.terminate()
+        logger.info(`terminated server ${server.name} at port ${server.port}`)
       }
-      await registryServer?.terminate()
-      logger.info(`terminated registry server at port ${registryServer?.port}`)
-    } else for (let server of servers) await server?.terminate()
+      await registryServer_?.terminate()
+      logger.info(`terminated registry server at port ${registryServer_?.port}`)
+    } else {
+      for (const server of flatServers) {
+        if (!server) {
+          continue
+        }
+        await server.terminate()
+        logger.info(`terminated server ${server.name} at port ${server.port}`)
+      }
+    }
   }
 }
 
@@ -42,8 +110,9 @@ function setEnv(key, value) {
     delete process.env[key]
     envConfig.config.delete(key)
   } else {
-    process.env[key] = value
-    envConfig.set(key, value)
+    const str = String(value)
+    process.env[key] = str
+    envConfig.set(key, envConfig.parseValue(str))
   }
 }
 

package/src/index.js

@@ -20,6 +20,7 @@ import {
   terminateAfter,
   withEnv
 } from './helpers.js'
+import { withInlineRegistry, pickListenPort } from './example-helpers.js'
 
 import runTests, {
   mergeAllTestsSafely,
@@ -45,5 +46,7 @@ export {
   runTests,
   runTestFnsSequentially,
   TestRunner,
-  withEnv
+  withEnv,
+  withInlineRegistry,
+  pickListenPort
 }

package/src/runner.js

@@ -24,7 +24,7 @@
  */
 
 import crypto from 'crypto'
-import { Logger } from '@yamf/core'
+import { Logger, envConfig, envTruthy } from '@yamf/core'
 
 const logger = new Logger({ includeLogLineNumbers: false })
 
@@ -91,6 +91,8 @@ export async function runTestFnsSequentially(testFns) {
   let failedCases = []
   let todoCases = []
   let testSuites = {}
+  /** @type {{ name: string, durationMs: number, ok: boolean }[]} */
+  let testTimings = []
 
   // Support arrays or objects
   testFns = Array.isArray(testFns) ? testFns : Object.values(testFns)
@@ -122,10 +124,24 @@ export async function runTestFnsSequentially(testFns) {
       if (fn.suite && !testSuites[fn.suite]) {
         testSuites[fn.suite] = true
       }
+      const startTime = Date.now()
       try {
-        let startTime = Date.now()
-        await fn()
-        let durationMs = Date.now() - startTime
+        const timeoutRaw = process.env.YAMF_TEST_CASE_TIMEOUT_MS
+        const timeoutMs = timeoutRaw != null && timeoutRaw !== '' ? Number(timeoutRaw) : NaN
+        const useTimeout = Number.isFinite(timeoutMs) && timeoutMs > 0
+        if (useTimeout) {
+          await new Promise((resolve, reject) => {
+            const t = setTimeout(() => reject(new Error(`Test timed out after ${timeoutMs}ms`)), timeoutMs)
+            Promise.resolve(fn()).then(
+              (v) => { clearTimeout(t); resolve(v) },
+              (e) => { clearTimeout(t); reject(e) }
+            )
+          })
+        } else {
+          await fn()
+        }
+        const durationMs = Date.now() - startTime
+        testTimings.push({ name: fn.name, durationMs, ok: true })
         logger.info(logger.writeColor('green', `✔ ${fn.name}`) + logger.writeColor('gray', ` (${durationMs}ms)`))
         testSuccess++
         successCases.push(fn.name)
@@ -134,7 +150,9 @@ export async function runTestFnsSequentially(testFns) {
           todoCases.push(fn.name)
           return
         }
-        logger.error(logger.writeColor('red', `✘ ${fn.name}`))
+        const durationMs = Date.now() - startTime
+        testTimings.push({ name: fn.name, durationMs, ok: false })
+        logger.error(logger.writeColor('red', `✘ ${fn.name}`) + logger.writeColor('gray', ` (${durationMs}ms)`))
         if (err.message.includes('terminateAfter')) {
           logger.error(logger.writeColor('magenta', 'Exiting early due to failure in terminateAfter: ', err.stack))
           process.exit(1)
@@ -165,11 +183,23 @@ export async function runTestFnsSequentially(testFns) {
     durationMs,
     isSoloRun,
     isMuteRun,
-    testSuitesCount: Object.keys(testSuites).length
+    testSuitesCount: Object.keys(testSuites).length,
+    testTimings
+  }
+}
+
+function printTimingTable (testTimings) {
+  if (!testTimings || testTimings.length === 0) return
+  const sorted = [...testTimings].sort((a, b) => b.durationMs - a.durationMs)
+  logger.info('----- Per-test timing (slowest first) -----')
+  for (const t of sorted) {
+    const tag = t.ok ? '✔' : '✘'
+    logger.info(`  ${tag} ${t.name}  ${t.durationMs}ms`)
   }
+  logger.info('')
 }
 
-function reportTestResults({
+function reportTestResults ({
   testSuccess, successCases,
   testFail, failedCases,
   testSuitesCount = 0,
@@ -177,13 +207,16 @@ function reportTestResults({
   todoCases = [],
   isSoloRun = false,
   isMuteRun = false,
-  durationMs
+  durationMs,
+  testTimings
 }) {
-
   logger.info('\n')
   logger.info(`----- Testing Complete -----`)
 
-  if (testSuccess > 0 && process.env.MUTE_SUCCESS_CASES !== 'true') {
+  if (
+    testSuccess > 0 &&
+    !envTruthy(envConfig.get('YAMF_TEST_QUIET_PASSES', false))
+  ) {
     logger.info(logger.writeColor('green', '✔ ✔ ✔  Success Report  ✔ ✔ ✔'))
     logger.info(logger.writeColor('green', '\n  ' + successCases.join('\n  ')))
     logger.info('')
@@ -207,6 +240,10 @@ function reportTestResults({
 
   if (isSoloRun) logger.warn(logger.writeColor('magenta', 'This was a solo test run, remove "solo" flags for a full test run'))
   if (isMuteRun) logger.warn(logger.writeColor('magenta', 'This was a partially muted test run, remove "mute" flags for a full test run'))
+
+  if (envTruthy(envConfig.get('YAMF_TEST_TIMINGS', false)) && testTimings && testTimings.length > 0) {
+    printTimingTable(testTimings)
+  }
 }
 
 // ============================================================================
@@ -261,7 +298,7 @@ export default async function runTests(testSuitesOrFns) {
   }
 }
 
-// Export for backwards compatibility
+// Named export mirrors the default export (`runTests`).
 export { runTests }
 
 // ============================================================================

package/src/tests/terminate-after-tests.js

@@ -0,0 +1,64 @@
+/**
+ * terminateAfter single-fn overload (in-process registry tracking from @yamf/core).
+ */
+import { assert, terminateAfter, withEnv, pickListenPort } from '@yamf/test'
+import { registryServer, createService } from '@yamf/core'
+
+export async function testTerminateAfterSingleFnStopsRegistryCascade () {
+  const port = await pickListenPort()
+  await withEnv({ YAMF_REGISTRY_URL: `http://127.0.0.1:${port}` }, async () => {
+    let ran = false
+    await terminateAfter(async () => {
+      await registryServer()
+      await createService('noop', function noop () {
+        return {}
+      })
+      ran = true
+    })
+    await assert(ran, r => r === true)
+  })
+}
+
+export async function testTerminateAfterSingleFnNoRegistryNoOp () {
+  await terminateAfter(async () => {
+    await assert(1 + 1, x => x === 2)
+  })
+}
+
+export async function testTerminateAfterSingleFnPropagatesBodyError () {
+  let saw = false
+  try {
+    await terminateAfter(async () => {
+      throw new Error('body-fail')
+    })
+  } catch (e) {
+    saw = e instanceof Error && e.message === 'body-fail'
+  }
+  await assert(saw, s => s === true)
+}
+
+export async function testTerminateAfterVerboseTeardownEnvSafe () {
+  const prev = process.env.YAMF_TEST_VERBOSE_TEARDOWN
+  process.env.YAMF_TEST_VERBOSE_TEARDOWN = 'true'
+  try {
+    await terminateAfter(async () => {})
+  } finally {
+    if (prev === undefined) delete process.env.YAMF_TEST_VERBOSE_TEARDOWN
+    else process.env.YAMF_TEST_VERBOSE_TEARDOWN = prev
+  }
+}
+
+export async function testTerminateAfterMultiArgUnchanged () {
+  const port = await pickListenPort()
+  await withEnv({ YAMF_REGISTRY_URL: `http://127.0.0.1:${port}` }, async () => {
+    await terminateAfter(
+      () => registryServer(),
+      () => createService('ex', function ex () {
+        return { ok: true }
+      }),
+      async () => {
+        await assert(1, n => n === 1)
+      }
+    )
+  })
+}