@plugjs/expect5 0.4.0

package/src/expectation/void.ts

@@ -0,0 +1,80 @@
+import { ExpectationError, stringifyValue } from './types'
+
+import type { Expectation, Expectations } from './expect'
+
+/** A simple {@link Expectation} performing a basic true/false check */
+abstract class VoidExpectation implements Expectation {
+  constructor(
+      private _details: string,
+      private _check: (value: unknown) => boolean,
+  ) {}
+
+  expect(context: Expectations, negative: boolean): void {
+    const check = this._check(context.value)
+    if (check === negative) {
+      throw new ExpectationError(context, negative, this._details)
+    }
+  }
+}
+
+/* ========================================================================== */
+
+export class ToBeDefined extends VoidExpectation {
+  constructor() {
+    super('to be defined', (value) => (value !== null) && (value !== undefined))
+  }
+}
+
+export class ToBeFalse extends VoidExpectation {
+  constructor() {
+    super(`to be ${stringifyValue(false)}`, (value) => value === false)
+  }
+}
+
+export class ToBeFalsy extends VoidExpectation {
+  constructor() {
+    super('to be falsy', (value) => ! value)
+  }
+}
+
+export class ToBeNaN extends VoidExpectation {
+  constructor() {
+    super(`to be ${stringifyValue(NaN)}`, (value) => (typeof value === 'number') && isNaN(value))
+  }
+}
+
+export class ToBeNegativeInfinity extends VoidExpectation {
+  constructor() {
+    super(`to equal ${stringifyValue(Number.NEGATIVE_INFINITY)}`, (value) => value === Number.NEGATIVE_INFINITY)
+  }
+}
+
+export class ToBeNull extends VoidExpectation {
+  constructor() {
+    super(`to be ${stringifyValue(null)}`, (value) => value === null)
+  }
+}
+
+export class ToBePositiveInfinity extends VoidExpectation {
+  constructor() {
+    super(`to equal ${stringifyValue(Number.POSITIVE_INFINITY)}`, (value) => value === Number.POSITIVE_INFINITY)
+  }
+}
+
+export class ToBeTrue extends VoidExpectation {
+  constructor() {
+    super(`to be ${stringifyValue(true)}`, (value) => value === true)
+  }
+}
+
+export class ToBeTruthy extends VoidExpectation {
+  constructor() {
+    super('to be truthy', (value) => !! value)
+  }
+}
+
+export class ToBeUndefined extends VoidExpectation {
+  constructor() {
+    super(`to be ${stringifyValue(undefined)}`, (value) => value === undefined)
+  }
+}

package/src/globals.ts

@@ -0,0 +1,30 @@
+import type * as setup from './execution/setup'
+import type { skip as SkipFunction } from './execution/executable'
+import type { expect as ExpectFunction } from './expectation/expect'
+import type { logging } from '@plugjs/plug'
+
+declare global {
+  const describe: setup.SuiteFunction
+  const fdescribe: setup.SuiteSetup
+  const xdescribe: setup.SuiteSetup
+
+  const it: setup.SpecFunction
+  const fit: setup.SpecSetup
+  const xit: setup.SpecSetup
+
+  const afterAll: setup.HookFunction
+  const afterEach: setup.HookFunction
+  const beforeAll: setup.HookFunction
+  const beforeEach: setup.HookFunction
+
+  const xafterAll: setup.HookSetup
+  const xafterEach: setup.HookSetup
+  const xbeforeAll: setup.HookSetup
+  const xbeforeEach: setup.HookSetup
+
+  const skip: typeof SkipFunction
+
+  const expect: typeof ExpectFunction
+
+  const log: logging.LogFunction
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+import { installForking } from '@plugjs/plug/fork'
+import { requireResolve } from '@plugjs/plug/paths'
+
+import type { ForkOptions } from '@plugjs/plug/fork'
+
+/* ========================================================================== *
+ * EXPORTED VARIABLES (for when globals is false)                             *
+ * ========================================================================== */
+
+export {
+  it, fit, xit,
+  describe, fdescribe, xdescribe,
+  afterAll, afterEach, xafterAll, xafterEach,
+  beforeAll, beforeEach, xbeforeAll, xbeforeEach,
+} from './execution/setup'
+export { skip } from './execution/executable'
+export { expect } from './expectation/expect'
+
+/* ========================================================================== *
+ * EXPORTED OPTIONS TYPE AND PLUG DEFINITION                                  *
+ * ========================================================================== */
+
+/** Options to construct our {@link Jasmine} plug. */
+export interface TestOptions extends ForkOptions {
+  /** Report up to the specified amount of failures (default: `+Infinity`) */
+  maxFailures?: number,
+  /**
+   * Specify whether the variables (`describe`, `it`, `expect`, ...) will be
+   * exposed as _global_ variables to tests or not (default: `true`)
+   */
+  globals?: boolean,
+  /**
+   * Print differences between expected and actual values from generic errors
+   * (e.g. `AssertionError` or _Chai_ expectations) (default: `true`)
+   */
+  genericErrorDiffs?: boolean,
+}
+
+declare module '@plugjs/plug' {
+  export interface Pipe {
+    /**
+     * Run tests.
+     *
+     * @param options Optional {@link TestOptions | options}.
+     */
+    test(options?: TestOptions): Promise<undefined>
+  }
+}
+
+/* ========================================================================== *
+ * INSTALL FORKING PLUG                                                       *
+ * ========================================================================== */
+
+installForking('test', requireResolve(__fileurl, './test'), 'Test')

package/src/test.ts

@@ -0,0 +1,239 @@
+// Reference ourselves, so that the constructor's parameters are correct
+/// <reference path="./index.ts"/>
+
+import { AssertionError } from 'node:assert'
+
+import { BuildFailure } from '@plugjs/plug'
+import { $blu, $grn, $gry, $ms, $red, $wht, $ylw, log, ERROR, NOTICE, WARN } from '@plugjs/plug/logging'
+import { assert } from '@plugjs/plug/asserts'
+
+import { skip, Suite } from './execution/executable'
+import { runSuite } from './execution/executor'
+import { expect } from './expectation/expect'
+import { ExpectationError, stringifyObjectType } from './expectation/types'
+import { printDiff } from './expectation/print'
+import { diff } from './expectation/diff'
+import * as setup from './execution/setup'
+
+import type { Files } from '@plugjs/plug/files'
+import type { Logger } from '@plugjs/plug/logging'
+import type { Context, PipeParameters, Plug } from '@plugjs/plug/pipe'
+import type { TestOptions } from './index'
+
+const _pending = '\u22EF' // middle ellipsis
+const _success = '\u2714' // heavy check mark
+const _failure = '\u2718' // heavy ballot x
+const _details = '\u2192' // rightwards arrow
+
+/** Writes some info about the current {@link Files} being passed around. */
+export class Test implements Plug<void> {
+  constructor(...args: PipeParameters<'test'>)
+  constructor(private readonly _options: TestOptions = {}) {}
+
+  async pipe(files: Files, context: Context): Promise<void> {
+    assert(files.length, 'No files available for running tests')
+
+    const {
+      globals = true,
+      genericErrorDiffs = true,
+      maxFailures = Number.POSITIVE_INFINITY,
+    } = this._options
+
+    // Inject globals if we were told to do so...
+    if (globals) {
+      const anyGlobal = globalThis as any
+
+      anyGlobal['describe'] = setup.describe
+      anyGlobal['fdescribe'] = setup.fdescribe
+      anyGlobal['xdescribe'] = setup.xdescribe
+      anyGlobal['it'] = setup.it
+      anyGlobal['fit'] = setup.fit
+      anyGlobal['xit'] = setup.xit
+      anyGlobal['afterAll'] = setup.afterAll
+      anyGlobal['afterEach'] = setup.afterEach
+      anyGlobal['beforeAll'] = setup.beforeAll
+      anyGlobal['beforeEach'] = setup.beforeEach
+      anyGlobal['xafterAll'] = setup.xafterAll
+      anyGlobal['xafterEach'] = setup.xafterEach
+      anyGlobal['xbeforeAll'] = setup.xbeforeAll
+      anyGlobal['xbeforeEach'] = setup.xbeforeEach
+      anyGlobal['skip'] = skip
+      anyGlobal['expect'] = expect
+      anyGlobal['log'] = log
+    }
+
+    // Create our _root_ Suite
+    const suite = new Suite(undefined, '', async () => {
+      for (const file of files.absolutePaths()) await import(file)
+    })
+
+    // Setup our suite counts
+    await suite.setup()
+
+    const snum = suite.specs
+    const fnum = files.length
+    const smsg = snum === 1 ? 'spec' : 'specs'
+    const fmsg = fnum === 1 ? 'file' : 'files'
+
+    assert(snum, 'No specs configured by test files')
+
+    // Run our suite and setup listeners
+    const execution = runSuite(suite)
+
+    execution.on('suite:start', (current) => {
+      if (current.parent === suite) {
+        if (suite.flag !== 'only') context.log.notice('')
+        context.log.enter(NOTICE, `${$wht(current.name)}`)
+        context.log.notice('')
+      } else if (current.parent) {
+        context.log.enter(NOTICE, `${$blu(_details)} ${$wht(current.name)}`)
+      } else {
+        context.log.notice(`Running ${$ylw(snum)} ${smsg} from ${$ylw(fnum)} ${fmsg}`)
+        if (suite.flag === 'only') context.log.notice('')
+      }
+    })
+
+    execution.on('suite:done', (current) => {
+      if (current.parent) context.log.leave()
+    })
+
+    execution.on('spec:start', (spec) => {
+      context.log.enter(NOTICE, `${$blu(_pending)} ${spec.name}`)
+    })
+
+    execution.on('spec:skip', (spec, ms) => {
+      if (suite.flag === 'only') return context.log.leave()
+      context.log.leave(WARN, `${$ylw(_pending)} ${spec.name} ${$ms(ms)} ${$gry('[')}${$ylw('skipped')}${$gry(']')}`)
+    })
+
+    execution.on('spec:pass', (spec, ms) => {
+      context.log.leave(NOTICE, `${$grn(_success)} ${spec.name} ${$ms(ms)}`)
+    })
+
+    execution.on('spec:fail', (spec, ms, { number }) => {
+      context.log.leave(ERROR,
+          `${$red(_failure)} ${spec.name} ${$ms(ms)} ` +
+          `${$gry('[')}${$red('failed')}${$gry('|')}${$red(`${number}`)}${$gry(']')}`)
+    })
+
+    execution.on('hook:fail', (hook, ms, { number }) => {
+      context.log.error(`${$red(_failure)} Hook "${hook.name}" ${$ms(ms)} ` +
+          `${$gry('[')}${$red('failed')}${$gry('|')}${$red(`${number}`)}${$gry(']')}`)
+    })
+
+    // Await execution
+    const { failed, passed, skipped, failures, time } = await execution.result
+
+    // Dump all (or a limited number of) failures
+    const limit = Math.min(failures.length, maxFailures)
+    for (let i = 0; i < limit; i ++) {
+      if (i === 0) context.log.error('')
+      const { source, error, number } = failures[i]!
+
+      const names: string[] = [ '' ]
+      for (let p = source.parent; p?.parent; p = p.parent) {
+        if (p) names.unshift(p.name)
+      }
+      const details = names.join(` ${$gry(_details)} `) + $wht(source.name)
+
+      context.log.enter(ERROR, `${$gry('[')}${$red(number)}${$gry(']:')} ${details}`)
+      dumpError(context.log, error, genericErrorDiffs)
+      context.log.leave()
+    }
+
+    // Epilogue
+    const summary: string[] = [ `${passed} ${$gry('passed')}` ]
+    if (skipped) summary.push(`${skipped} ${$gry('skipped')}`)
+    if (failed) summary.push(`${failed} ${$gry('failed')}`)
+    if (failures.length) summary.push(`${failures.length} ${$gry('total failures')}`)
+
+    const epilogue = ` ${$gry('(')}${summary.join($gry(', '))}${$gry(')')}`
+    const message = `Ran ${$ylw(snum)} ${smsg} from ${$ylw(fnum)} ${fmsg}${epilogue} ${$ms(time)}`
+
+    if (failures.length) {
+      context.log.error(message)
+      throw new BuildFailure()
+    } else if (suite.flag === 'only') {
+      context.log.error('')
+      context.log.error(message)
+      throw new BuildFailure('Suite running in focus ("only") mode')
+    } else if (skipped) {
+      context.log.warn('')
+      context.log.warn(message)
+    } else {
+      context.log.notice('')
+      context.log.notice(message)
+    }
+  }
+}
+
+/* ========================================================================== *
+ * ERROR REPORTING                                                            *
+ * ========================================================================== */
+
+function dumpError(log: Logger, error: any, genericErrorDiffs: boolean): void {
+  // First and foremost, our own expectation errors
+  if (error instanceof ExpectationError) {
+    log.enter(ERROR, `${$gry('Expectation Error:')} ${$red(error.message)}`)
+    try {
+      dumpStack(log, error)
+      if (error.diff) printDiff(log, error.diff)
+    } finally {
+      log.error('')
+      log.leave()
+    }
+
+  // Assertion errors are another kind of exception we support
+  } else if (error instanceof AssertionError) {
+    const [ message = 'Unknown Error', ...lines ] = error.message.split('\n')
+    log.enter(ERROR, `${$gry('Assertion Error:')} ${$red(message)}`)
+    try {
+      dumpStack(log, error)
+
+      // If we print diffs from generic errors, we take over
+      if (genericErrorDiffs) {
+        // if this is a generated message ignore all extra lines
+        if (! error.generatedMessage) for (const line of lines) log.error(' ', line)
+        printDiff(log, diff(error.actual, error.expected))
+      } else {
+        // trim initial empty lines
+        while (lines.length && (! lines[0])) lines.shift()
+        for (const line of lines) log.error(' ', line)
+      }
+    } finally {
+      log.error('')
+      log.leave()
+    }
+
+  // Any other error also gets printed somewhat nicely
+  } else if (error instanceof Error) {
+    const message = error.message || 'Unknown Error'
+    const type = stringifyObjectType(error)
+    log.enter(ERROR, `${$gry(type)}: ${$red(message)}`)
+    try {
+      dumpStack(log, error)
+
+      // if there are "actual" or "expected" properties on the error, diff!
+      if (genericErrorDiffs && (('actual' in error) || ('expected' in error))) {
+        printDiff(log, diff((error as any).actual, (error as any).expected))
+      }
+    } finally {
+      log.error('')
+      log.leave()
+    }
+
+  // Anthing else just gets dumped out...
+  } else /* coverage ignore next */ {
+    // This should never happen, as executor converts evertything to errors...
+    log.error($gry('Uknown error:'), error)
+  }
+}
+
+function dumpStack(log: Logger, error: Error): void {
+  if (! error.stack) return log.error('<no stack trace>')
+  error.stack
+      .split('\n')
+      .filter((line) => line.match(/^\s+at\s+/))
+      .map((line) => line.trim())
+      .forEach((line) => log.error(line))
+}