@yamf/test 0.1.0

package/src/assert.js

@@ -0,0 +1,504 @@
+import {
+  AssertionFailure,
+  AssertionFailureDetail,
+  MultiAssertionFailure,
+} from './assertion-errors.js'
+
+// TODO @yamf/core
+import { Logger } from '../../core/src/index.js'
+const logger = new Logger()
+
+
+function isAsyncOrPromise(arg) {
+  return arg instanceof Promise || arg?.constructor?.name === 'AsyncFunction'
+}
+
+// used to check what mode to run in
+function scanAllArgumentsForAsyncOrPromise(args, assertFns) {
+  if (!Array.isArray(args)) {
+    if (isAsyncOrPromise(args)) return true
+  } else {
+    for (let arg of args) if (isAsyncOrPromise(arg)) return true
+    for (let fn of assertFns) if (isAsyncOrPromise(fn)) return true
+  }
+  return false
+}
+
+// validator for sequence fns (expects a matching assertionFn length)
+function validateSequenceAssertionCount(targets, assertFns) {
+  if (!Array.isArray(targets) || !Array.isArray(assertFns))
+    throw new Error('Expected sequence assertion arguments to be arrays')
+  if (targets.length !== assertFns.length)
+    throw new Error('Expected sequence assertion arguments to be the same length')
+}
+
+// for multi-assertion meta-helpers (each, sequence)
+function checkFailuresAndThrowMultiAssertionFailure(assertionName, failures) {
+  if (failures.length === 0) return
+  if (failures.length > 1) {
+    throw new MultiAssertionFailure(assertionName, failures)
+  } else if (failures.length === 1) {
+    throw failures[0]
+  }
+}
+
+function distillValueFromTestArgument(val) {
+  try {
+    if (typeof val === 'function') val = val()
+  } catch (err) {
+    val = err
+  }
+  // if we find a promise, throw so we can attempt to run as async
+  if (val instanceof Promise) {
+    let err = new Error('Found Promise in Sync Fn')
+    err.promise = val
+    throw err
+  }
+  
+  return val
+}
+
+async function distillValueFromTestArgumentAsync(val) {
+  try {
+    if (typeof val === 'function') {
+      val = await val()
+    } else if (val instanceof Promise) {
+      return val.then(a => val = a).catch(e => val = e)
+    }
+  } catch (err) {
+    val = err
+  }
+  return val
+}
+
+
+function getAssertionFailuresForValue(val, ...assertFns) {
+  let assertionFailures = []
+  if (!(val instanceof Error)) {
+    let failedAssertFns = []
+    assertFns.forEach(assertFn => {
+      try {
+        let isValid
+        if (typeof assertFn === 'function') {
+          isValid = assertFn(val)
+        } else {
+          isValid = val === assertFn
+        }
+        if (!isValid) {
+          failedAssertFns.push(assertFn)
+        }
+      } catch (assertionErr) {
+        failedAssertFns.push(assertionErr)
+      }
+    })
+    if (failedAssertFns.length > 0) {
+      assertionFailures.push(new AssertionFailureDetail(val, failedAssertFns))
+    }
+  } else {
+    assertionFailures.push(new AssertionFailureDetail(val, 'expected no error'))
+  }
+  return assertionFailures
+}
+
+async function getAssertionFailuresForValueAsync(val, ...assertFns) {
+  let assertionFailures = []
+  if (!(val instanceof Error)) {
+    let failedAssertFns = []
+    await Promise.all(assertFns.map(async assertFn => {
+      try {
+        let isValid
+        if (typeof assertFn === 'function') {
+          isValid = await assertFn(val)
+        } else {
+          isValid = val === assertFn
+        }
+        if (!isValid) {
+          failedAssertFns.push(assertFn)
+        }
+      } catch (assertionErr) {
+        failedAssertFns.push(assertionErr)
+      }
+    }))
+    if (failedAssertFns.length > 0) {
+      assertionFailures.push(new AssertionFailureDetail(val, failedAssertFns))
+    }
+  } else {
+    assertionFailures.push(new AssertionFailureDetail(val, 'expected no error'))
+  }
+  return assertionFailures
+}
+
+function getErrorAssertionFailuresForValue(val, ...assertFns) {
+  let assertionFailures = []
+  if (val instanceof Error) {
+    let failedAssertFns = []
+    assertFns.forEach(assertFn => {
+      try {
+        let isValid = assertFn(val)
+        if (!isValid) {
+          failedAssertFns.push(assertFn)
+        }
+      } catch (assertionErr) {
+        failedAssertFns.push(assertionErr)
+      }
+    })
+    if (failedAssertFns.length > 0) {
+      assertionFailures.push(new AssertionFailureDetail(val, failedAssertFns))
+    }
+  } else {
+    assertionFailures.push(new AssertionFailureDetail(val, 'expected an error'))
+  }
+  return assertionFailures
+}
+
+async function getErrorAssertionFailuresForValueAsync(val, ...assertFns) {
+  let assertionFailures = []
+  if (val instanceof Error) {
+    let failedAssertFns = []
+    await Promise.all(assertFns.map(async assertFn => {
+      try {
+        let isValid = await assertFn(val)
+        if (!isValid) {
+          failedAssertFns.push(assertFn)
+        }
+      } catch (assertionErr) {
+        failedAssertFns.push(assertionErr)
+      }
+    }))
+    if (failedAssertFns.length > 0) {
+      assertionFailures.push(new AssertionFailureDetail(val, failedAssertFns))
+    }
+  } else {
+    assertionFailures.push(new AssertionFailureDetail(val, 'expected an error'))
+  }
+  return assertionFailures
+}
+
+function getTransformedAssertionFailuresforValue(val, ...assertFns) {
+  let assertionFailures = getAssertionFailuresForValue(val, ...assertFns)
+  let failure = checkAndTransformErrorsToMultiAssertError(val, assertionFailures)
+  return failure
+}
+
+async function getTransformedAssertionFailuresforValueAsync(val, ...assertFns) {
+  let assertionFailures = await getAssertionFailuresForValueAsync(val, ...assertFns)
+  let failure = checkAndTransformErrorsToMultiAssertError(val, assertionFailures)
+  return failure
+}
+
+function getTransformedErrorAssertionFailuresforValue(val, ...assertFns) {
+  let assertionFailures = getErrorAssertionFailuresForValue(val, ...assertFns)
+  let failure = checkAndTransformErrorsToMultiAssertError(val, assertionFailures)
+  return failure
+}
+
+async function getTransformedErrorAssertionFailuresforValueAsync(val, ...assertFns) {
+  let assertionFailures = await getErrorAssertionFailuresForValueAsync(val, ...assertFns)
+  let failure = checkAndTransformErrorsToMultiAssertError(val, assertionFailures)
+  return failure
+}
+
+function checkAndTransformErrorsToMultiAssertError(val, assertionFailures) {
+  if (Array.isArray(assertionFailures) && assertionFailures.length > 0) {
+    let failure
+    if (assertionFailures.length === 1) {
+      failure = new AssertionFailure(val, assertionFailures[0])
+    } else {
+      failure = new AssertionFailure(val, assertionFailures)
+    }
+    return failure
+  }
+}
+
+// main assertion helper entry-point
+function processAssertionAndChooseSyncOrAsyncPath(assertionHelper, target, ...assertFns) {
+  const doAsyncPath = (thrownPromise) => new Promise((resolve, reject) => assertionHelper
+    // use the val from the (sync) thrown promise target
+    .async(thrownPromise || target, ...assertFns)
+    .catch(reject)
+    .finally(resolve)
+  )
+  if (scanAllArgumentsForAsyncOrPromise(target, assertFns)) {
+    return doAsyncPath()
+  } else try {
+    return assertionHelper.sync(target, ...assertFns)
+  } catch (err) {
+    if (err.message?.includes('Found Promise')) {
+      return doAsyncPath(err.promise)
+    } else throw err
+  }
+}
+
+/**
+ * Assert that a value or function result passes all assertion functions
+ * 
+ * Automatically detects and handles async when needed:
+ * - Direct Promise: `await assert(promise, fn)`
+ * - Async function: `await assert(async () => await fetchData(), fn)`
+ * - Promise-returning function: `await assert(() => fetchData(), fn)`
+ * - Sync function: `assert(() => getValue(), fn)`
+ * - Direct value: `assert(5, fn)`
+ * 
+ * @param {*|Function|Promise} valOrFn - Value, function, or Promise to test
+ * @param {...Function} assertFns - Assertion functions returning true/false
+ * @returns {void|Promise<void>} - Throws AssertError or MultiAssertError on failure
+ * 
+ * @example
+ * // Sync usage
+ * assert(5, n => n > 0)
+ * assert(() => getValue(), n => n > 0)
+ * 
+ * // Async usage (auto-detected, just add await)
+ * await assert(promise, v => v !== null)
+ * await assert(async () => await fetchData(), d => d.status === 'ok')
+ * await assert(() => fetchData(), d => d.status === 'ok') // Promise-returning
+ */
+
+export function assert(valOrFn, ...assertFns) {
+  return processAssertionAndChooseSyncOrAsyncPath(assert, valOrFn, ...assertFns)
+}
+
+assert.sync = function assertSync(valOrFn, ...assertFns) {
+  let val = distillValueFromTestArgument(valOrFn)
+  let failure = getTransformedAssertionFailuresforValue(val, ...assertFns)
+  if (failure) throw failure
+}
+
+assert.async = async function assertAsync(valOrFn, ...assertFns) {
+  let val = await distillValueFromTestArgumentAsync(valOrFn)
+  let failure = await getTransformedAssertionFailuresforValueAsync(val, ...assertFns)
+  if (failure) throw failure
+}
+
+/**
+ * Assert that a function throws an error matching all assertion functions
+ * 
+ * Automatically detects and handles async when needed:
+ * - Direct Error: `assertErr(error, fn)`
+ * - Sync throwing function: `assertErr(() => throwingFn(), fn)`
+ * - Async throwing function: `await assertErr(async () => await failingFn(), fn)`
+ * - Promise-rejecting function: `await assertErr(() => rejectingFn(), fn)`
+ * 
+ * @param {Error|Function} errOrFn - Error object or function that should throw
+ * @param {...Function} assertFns - Assertion functions returning true/false
+ * @returns {void|Promise<void>} - Throws AssertError or MultiAssertError on failure
+ * 
+ * @example
+ * // Sync usage
+ * assertErr(() => throwingFn(), err => err.message.includes('expected'))
+ * assertErr(new Error('test'), err => err.message === 'test')
+ * 
+ * // Async usage (auto-detected, just add await)
+ * await assertErr(async () => await failingAsyncFn(), err => err.status === 400)
+ * await assertErr(() => rejectingPromiseFn(), err => err.message === 'rejected')
+ */
+export function assertErr(errOrFn, ...assertFns) {
+  return processAssertionAndChooseSyncOrAsyncPath(assertErr, errOrFn, ...assertFns)
+}
+
+assertErr.sync = function assertErrSync(errOrFn, ...assertFns) {
+  let val = distillValueFromTestArgument(errOrFn)
+  let failure = getTransformedErrorAssertionFailuresforValue(val, ...assertFns)
+  if (failure) throw failure
+}
+
+assertErr.async = async function assertErrAsync(errOrFn, ...assertFns) {
+  let val = await distillValueFromTestArgumentAsync(errOrFn)
+  let failure = await getTransformedErrorAssertionFailuresforValueAsync(val, ...assertFns)
+  if (failure) throw failure
+}
+
+
+/**
+ * Assert that each value in an array passes all assertion functions
+ * 
+ * Automatically detects and handles async when needed.
+ * Applies each assertion function to each value in the array.
+ * 
+ * @param {Array} values - Array of values to test
+ * @param {...Function} assertFns - Assertion functions returning true/false
+ * @returns {void|Promise<void>} - Throws AssertError or MultiAssertError on failure
+ * 
+ * @example
+ * // Sync usage
+ * assertEach([1, 2, 3], 
+ *   n => n > 0,
+ *   n => n < 10
+ * )
+ * 
+ * // Async usage (auto-detected, just add await)
+ * await assertEach([promise1, promise2], 
+ *   val => val !== null,
+ *   val => val.status === 'ok'
+ * )
+ */
+export function assertEach(values, ...assertFns) {
+  return processAssertionAndChooseSyncOrAsyncPath(assertEach, values, ...assertFns)
+}
+
+assertEach.sync = function assertEachSync(values, ...assertFns) {
+  let failures = []
+  for (let val of values) {
+    val = distillValueFromTestArgument(val)
+    let failure = getTransformedAssertionFailuresforValue(val, ...assertFns)
+    if (failure) failures.push(failure)
+  }
+  checkFailuresAndThrowMultiAssertionFailure('assertEachSync', failures)
+}
+
+assertEach.async = async function assertEachAsync(values, ...assertFns) {
+  let failures = []
+  for (let val of values) {
+    val = await distillValueFromTestArgumentAsync(val)
+    let failure = await getTransformedAssertionFailuresforValueAsync(val, ...assertFns)
+    if (failure) failures.push(failure)
+  }
+  checkFailuresAndThrowMultiAssertionFailure('assertEachAsync', failures)
+}
+
+/**
+ * Assert that each value in an array passes the corresponding assertion function
+ * 
+ * Automatically detects and handles async when needed.
+ * Applies the corresponding assertion function to each value in the array.
+ * Errors early if the number of values and assertion functions do not match.
+ * 
+ * @param {Array} values - Array of values to test
+ * @param {...Function} assertFns - Assertion functions returning true/false
+ * @returns {void|Promise<void>} - Throws AssertError or MultiAssertError on failure
+ * 
+ * @example
+ * // Sync usage
+ * assertSequence([1, 2, 3], 
+ *   n => n === 1,
+ *   n => n === 2,
+ *   n => n === 3
+ * )
+ * 
+ * // Async usage (auto-detected, just add await)
+ * await assertSequence([promise1, promise2, promise3], 
+ *   val => val !== null,
+ *   val => val.status === 'ok',
+ *   val => val.count > 0
+ * )
+ */
+export function assertSequence(values, ...assertFns) {
+  validateSequenceAssertionCount(values, assertFns)
+  return processAssertionAndChooseSyncOrAsyncPath(assertSequence, values, ...assertFns)
+}
+
+assertSequence.sync = function assertSequenceSync(values, ...assertFns) {
+  let failures = []
+  let index = 0
+  for (let val of values) {
+    val = distillValueFromTestArgument(val)
+    let failure = getTransformedAssertionFailuresforValue(val, assertFns[index])
+    if (failure) failures.push(failure)
+    index++
+  }
+  checkFailuresAndThrowMultiAssertionFailure('assertSequenceSync', failures)
+}
+
+assertSequence.async = async function assertSequenceAsync(values, ...assertFns) {
+  let failures = []
+  let index = 0
+  for (let val of values) {
+    val = await distillValueFromTestArgumentAsync(val)
+    let failure = await getTransformedAssertionFailuresforValueAsync(val, assertFns[index])
+    if (failure) failures.push(failure)
+    index++
+  }
+  checkFailuresAndThrowMultiAssertionFailure('assertSequenceAsync', failures)
+}
+
+
+/**
+ * Assert that each error in an array passes all assertion functions
+ * Assert that each function in an array throws an error matching all assertion functions
+ * 
+ * Automatically detects and handles async when needed.
+ * 
+ * @param {Array} errsOrFns - Array of errors or functions that should throw
+ * @param {...Function} assertFns - Assertion functions returning true/false
+ * @returns {void|Promise<void>} - Throws AssertError or MultiAssertError on failure
+ * 
+ * @example
+ * // Sync usage with error objects
+ * assertErrEach([new Error('test'), new Error('test2')], 
+ *   err => err instanceof Error,
+ *   err => err.message.includes('test')
+ * )
+ * 
+ * // Sync usage with throwing functions
+ * assertErrEach([
+ *   () => { throw new Error('error1') },
+ *   () => { throw new Error('error2') }
+ * ], 
+ *   err => err instanceof Error,
+ *   err => err.message.includes('error')
+ * )
+ * 
+ * // Async usage (auto-detected, just add await)
+ * await assertErrEach([
+ *   async () => { throw new Error('async1') },
+ *   async () => { throw new Error('async2') }
+ * ], 
+ *   err => err instanceof Error,
+ *   err => err.message.includes('async')
+ * )
+ */
+export function assertErrEach(errsOrFns, ...assertFns) {
+  return processAssertionAndChooseSyncOrAsyncPath(assertErrEach, errsOrFns, ...assertFns)
+}
+
+assertErrEach.sync = function assertErrEachSync(errsOrFns, ...assertFns) {
+  let failures = []
+  for (let errOrFn of errsOrFns) {
+    let val = distillValueFromTestArgument(errOrFn)
+    let failure = getTransformedErrorAssertionFailuresforValue(val, ...assertFns)
+    if (failure) failures.push(failure)
+  }
+  checkFailuresAndThrowMultiAssertionFailure('assertErrEachSync', failures)
+}
+
+assertErrEach.async = async function assertErrEachAsync(errsOrFns, ...assertFns) {
+  let failures = []
+  for (let errOrFn of errsOrFns) {
+    let val = await distillValueFromTestArgumentAsync(errOrFn)
+    let failure = await getTransformedErrorAssertionFailuresforValueAsync(val, ...assertFns)
+    if (failure) failures.push(failure)
+  }
+  checkFailuresAndThrowMultiAssertionFailure('assertErrEachAsync', failures)
+}
+
+
+/* TODO documentation comment
+*/
+export function assertErrSequence(errsOrFns, ...assertFns) {
+  validateSequenceAssertionCount(errsOrFns, assertFns)
+  return processAssertionAndChooseSyncOrAsyncPath(assertErrSequence, errsOrFns, ...assertFns)
+}
+
+assertErrSequence.sync = function assertErrSequenceSync(errsOrFns, ...assertFns) {
+  let failures = []
+  let index = 0
+  for (let errOrFn of errsOrFns) {
+    let val = distillValueFromTestArgument(errOrFn)
+    let failure = getTransformedErrorAssertionFailuresforValue(val, assertFns[index])
+    if (failure) failures.push(failure)
+    index++
+  }
+  checkFailuresAndThrowMultiAssertionFailure('assertErrSequenceSync', failures)
+}
+
+assertErrSequence.async = async function assertErrSequenceAsync(errsOrFns, ...assertFns) {
+  let failures = []
+  let index = 0
+  for (let errOrFn of errsOrFns) {
+    let val = await distillValueFromTestArgumentAsync(errOrFn)
+    let failure = await getTransformedErrorAssertionFailuresforValueAsync(val, assertFns[index])
+    if (failure) failures.push(failure)
+    index++
+  }
+  checkFailuresAndThrowMultiAssertionFailure('assertErrSequenceAsync', failures)
+}

package/src/assertion-errors.js

@@ -0,0 +1,114 @@
+
+const getType = (val) => {
+  if (val instanceof Error) {
+    return `error`
+  } else return typeof val
+}
+
+const getTargetString = (val, pad) => {
+  if (val instanceof Error) {
+    return `"${val.message}"`
+  } else if (Array.isArray(val) && val.some(v => v instanceof Error)) {
+    return `[${val.map(v => `\n${pad+pad}${getValOrErrString(v)}`).join()}\n${pad}]`
+  } else if (typeof val === 'object') {
+    return JSON.stringify(val)
+  } else {
+    return val.toString()
+  }
+}
+
+export class AssertionFailureDetail {
+  constructor(distilledTargetValue, failingAssertionFns, childDetails) {
+    this.target = distilledTargetValue
+    this.assertFns = (
+      Array.isArray(failingAssertionFns)
+      && failingAssertionFns.length > 1
+    ) ? failingAssertionFns : [failingAssertionFns]
+    if (!this.assertFns) this.assertFns = []
+    this.children = childDetails
+  }
+
+  toString(depth = 1) {
+    let pad = Array.from({ length: depth }, () => '  ').join('')
+    let type = getType(this.target)
+    let val = getTargetString(this.target, pad)
+    let childMessages = this.children?.map(c => {
+      `${pad}${c.toString(depth).split('\n').map(l => `${pad}${l}`).join('\n')}`
+    })
+    childMessages = childMessages || ''
+    return `${pad}for target (${type}) value = ${val}`
+    + this.assertFns.map(fn =>
+      `\n${pad}failed -> ${fn?.name || fn.toString().replace(/^\s?.+\=\>\s?/, '')}`
+    ).join('')
+    + childMessages
+  }
+
+  get message() {
+    return this.toString()
+  }
+
+  get assertMessage() {
+    // 0 for no padding, runner will print this on the same initial line
+    return this.toString(0)
+  }
+}
+
+export class AssertionFailure extends Error {
+  constructor(distilledTargetObject, assertionFailureDetails) {
+    super() // don't care about original message
+    this.target = distilledTargetObject
+    this.assertionFailureDetails = (
+      Array.isArray(assertionFailureDetails)
+      && assertionFailureDetails.length > 1
+    ) ? assertionFailureDetails : [assertionFailureDetails]
+  }
+
+  toString(depth = 1) {
+    let pad = Array.from({ length: depth }, () => '  ').join('')
+    return `${pad}AssertionFailure\n`
+    + this.assertionFailureDetails?.map(d =>
+      `${d.toString(depth+1).split('\n').map(l => `${l}`).join('\n')}`
+    ).join('\n')
+  }
+
+  get message() {
+    return this.toString()
+  }
+
+  get assertMessage() {
+    // 0 for no padding, runner will print this on the same initial line
+    return this.toString(0)
+  }
+}
+
+
+export class MultiAssertionFailure extends Error {
+  constructor(assertType, failures) {
+    super() // don't care about normal error message
+
+    if (!failures) {
+      failures = assertType
+      assertType = ''
+    }
+    this.assertType = assertType
+    this.failures = failures
+    this.name = 'MultiAssertionFailure'
+  }
+
+  toString() {
+    let typeMessage = this.assertType
+      ? `: "${this.assertType}" failed`
+      : ''
+
+    return `${this.name}${typeMessage}\n`
+      + this.failures.map(f => f.toString(1)).join('\n')
+  }
+
+  get message() {
+    return this.toString()
+  }
+
+  get assertMessage() {
+    return this.toString()
+  }
+}

package/src/cli.js

@@ -0,0 +1,49 @@
+
+/* TODO add cli options and flags
+
+--name <name> (matching text or wildcard)
+--file <file> (matching file name text or wildcard; is a test suite by default)
+
+
+---TODO determine features and flags from the following suggested list---
+
+Essential test CLI options and flags vary significantly depending on the specific testing framework or tool being used. However, common categories of options and flags found across many testing CLIs include:
+Execution Control:
+
+    Running specific tests:
+        --test-name <name> or similar: Executes a single test or a group of tests matching a pattern.
+        --grep <pattern>: Filters tests based on a regular expression pattern in their names.
+        --file <path>: Runs tests only from specified files. 
+    Controlling execution flow:
+        --fail-fast or --first: Stops test execution immediately upon the first failure.
+        --bail: Similar to fail-fast, often with more granular control over how many failures are tolerated before stopping.
+        --retries <n>: Reruns failed tests a specified number of times. 
+
+Output and Reporting:
+
+    Verbosity levels:
+        --verbose or -v: Provides more detailed output during test execution.
+        --quiet or -q: Suppresses most output, showing only essential information like summaries. 
+    Reporting formats:
+        --reporter <format>: Specifies the output format for test results (e.g., json, junit, html).
+        --output <file>: Redirects test output to a specified file. 
+    Code coverage:
+        --coverage: Enables code coverage analysis and reporting.
+        --coverage-report <format>: Specifies the format for coverage reports. 
+
+Configuration and Setup:
+
+    Configuration files:
+        --config <file>: Specifies an alternative configuration file for the test runner. 
+    Environment variables:
+        --env <key=value>: Sets environment variables for the test process. 
+    Setup/Teardown scripts:
+        --pre-flight <script>: Runs a script or command before any tests execute.
+        --post-flight <script>: Runs a script or command after all tests have completed. 
+
+Debugging and Development:
+
+    Debugging tools:
+        --inspect or --debug: Enables debugging features, often allowing attachment of a debugger.
+        --watch: Reruns tests automatically when relevant files change.
+*/