@plugjs/expect5 0.4.0

package/src/expectation/basic.ts

@@ -0,0 +1,209 @@
+import { diff } from './diff'
+import { assertType, ExpectationError, isType, prefixType, stringifyConstructor, stringifyValue } from './types'
+
+import type { Constructor, TypeName, StringMatcher } from './types'
+import type { Expectation, Expectations } from './expect'
+
+export class ToBeA implements Expectation {
+  expect(context: Expectations, negative: boolean, type: TypeName): void {
+    const match = isType(context, type)
+    if (match !== negative) return
+    throw new ExpectationError(context, negative, `to be ${prefixType(type)}`)
+  }
+}
+
+export class ToBeCloseTo implements Expectation {
+  expect(
+      context: Expectations,
+      negative: boolean,
+      ...[ value, delta ]:
+      | [ value: number, delta: number ]
+      | [ value: bigint, delta: bigint ]
+  ): void {
+    const min = (value as number) - (delta as number)
+    const max = (value as number) + (delta as number)
+    context.negated(negative).toBeWithinRange(min, max)
+  }
+}
+
+export class ToBeError implements Expectation {
+  expect(
+      context: Expectations,
+      negative: boolean,
+      ...args:
+      | []
+      | [ message: StringMatcher ]
+      | [ constructor: Constructor<Error> ]
+      | [ constructor: Constructor<Error>, message: StringMatcher ]
+  ): void {
+    const [ constructor, message ] =
+    typeof args[0] === 'function' ?
+      [ args[0], args[1] ] :
+      [ Error, args[0] ]
+
+    context.negated(negative).toBeInstanceOf(constructor)
+    if (negative || (message === undefined)) return // if "not.toBeError" ignore the message
+
+    context.toHaveProperty('message', (assert) => {
+      assertType(assert, 'string')
+      if (typeof message === 'string') assert.toStrictlyEqual(message)
+      else assert.toMatch(message)
+    })
+  }
+}
+
+export class ToBeGreaterThan implements Expectation {
+  expect(context: Expectations, negative: boolean, value: number | bigint): void {
+    assertType(context, typeof value as 'number' | 'bigint')
+    if ((context.value > value) !== negative) return
+    throw new ExpectationError(context, negative, `to be greater than ${stringifyValue(value)}`)
+  }
+}
+
+export class ToBeGreaterThanOrEqual implements Expectation {
+  expect(context: Expectations, negative: boolean, value: number | bigint): void {
+    assertType(context, typeof value as 'number' | 'bigint')
+    if ((context.value >= value) !== negative) return
+    throw new ExpectationError(context, negative, `to be greater than or equal to ${stringifyValue(value)}`)
+  }
+}
+
+export class ToBeInstanceOf implements Expectation {
+  expect(context: Expectations, negative: boolean, value: Constructor): void {
+    const match = context.value instanceof value
+    if (match !== negative) return
+    throw new ExpectationError(context, negative, `to be an instance of ${stringifyConstructor(value)}`)
+  }
+}
+
+export class ToBeLessThan implements Expectation {
+  expect(context: Expectations, negative: boolean, value: number | bigint): void {
+    assertType(context, typeof value as 'number' | 'bigint')
+    if ((context.value < value) !== negative) return
+    throw new ExpectationError(context, negative, `to be less than ${stringifyValue(value)}`)
+  }
+}
+
+export class ToBeLessThanOrEqual implements Expectation {
+  expect(context: Expectations, negative: boolean, value: number | bigint): void {
+    assertType(context, typeof value as 'number' | 'bigint')
+    if ((context.value <= value) !== negative) return
+    throw new ExpectationError(context, negative, `to be less than or equal to ${stringifyValue(value)}`)
+  }
+}
+
+export class ToBeWithinRange implements Expectation {
+  expect(
+      context: Expectations,
+      negative: boolean,
+      ...[ min, max ]:
+      | [ min: number, max: number ]
+      | [ min: bigint, max: bigint ]
+  ): void {
+    if (max < min) {
+      const num = max
+      max = min
+      min = num
+    }
+
+    assertType(context, typeof min as 'number' | 'bigint')
+    if (((context.value >= min) && (context.value <= max)) !== negative) return
+    throw new ExpectationError(context, negative, `to be within ${stringifyValue(min)}...${stringifyValue(max)}`)
+  }
+}
+
+export class ToEqual implements Expectation {
+  expect(context: Expectations, negative: boolean, expected: any): void {
+    const result = diff(context.value, expected)
+    if (result.diff === negative) return
+    throw new ExpectationError(context, negative, `to equal ${stringifyValue(expected)}`, result)
+  }
+}
+
+export class ToHaveLength implements Expectation {
+  expect(context: Expectations, negative: boolean, length: number): void {
+    context.toBeDefined()
+
+    const actualLength = (context.value as any).length
+    if (typeof actualLength !== 'number') {
+      throw new ExpectationError(context, false, 'to have a numeric "length" property')
+    }
+
+    if ((actualLength === length) === negative) {
+      throw new ExpectationError(context, negative, `to have length ${stringifyValue(length)}`)
+    }
+  }
+}
+
+export class ToHaveProperty implements Expectation {
+  expect(
+      context: Expectations,
+      negative: boolean,
+      prop: string | number | symbol,
+      assert?: (propertyExpectations: Expectations) => void,
+  ): void {
+    context.toBeDefined()
+
+    const match = (context.value as any)[prop] !== undefined
+    if (match === negative) {
+      throw new ExpectationError(context, negative, `to have property "${String(prop)}"`)
+    } else if (match && assert) {
+      try {
+        assert(context.forProperty(prop))
+      } catch (error) {
+        // any caught error difference gets remapped as a property diff
+        if ((error instanceof ExpectationError) && (error.diff)) {
+          error.diff = {
+            diff: true,
+            value: context.value,
+            props: { [prop]: error.diff },
+          }
+        }
+
+        // re-throw
+        throw error
+      }
+    }
+  }
+}
+
+export class ToHaveSize implements Expectation {
+  expect(context: Expectations, negative: boolean, size: number): void {
+    context.toBeDefined()
+
+    const actualSize = (context.value as any).size
+    if (typeof actualSize !== 'number') {
+      throw new ExpectationError(context, false, 'to have a numeric "size" property')
+    }
+
+    if ((actualSize === size) === negative) {
+      throw new ExpectationError(context, negative, `to have size ${stringifyValue(size)}`)
+    }
+  }
+}
+
+export class ToMatch implements Expectation {
+  expect(
+      context: Expectations,
+      negative: boolean,
+      expr: StringMatcher,
+  ): void {
+    assertType(context, 'string')
+
+    const match = !! context.value.match(expr as string | RegExp) // meh, overloads
+    if (match !== negative) return
+
+    throw new ExpectationError(context, negative, `to match ${stringifyValue(expr)}`)
+  }
+}
+
+export class ToStrictlyEqual implements Expectation {
+  expect(context: Expectations, negative: boolean, expected: any): void {
+    const value = context.value
+    const match = value === expected
+    if (match !== negative) return
+
+    const diff = negative ? undefined : { diff: true, value, expected }
+    throw new ExpectationError(context, negative, `to strictly equal ${stringifyValue(expected)}`, diff)
+  }
+}

package/src/expectation/diff.ts

@@ -0,0 +1,445 @@
+/* eslint-disable no-fallthrough */
+import { ExpectationError, isMatcher, stringifyConstructor, stringifyValue } from './types'
+
+import type { Constructor } from './types'
+
+export interface BaseDiff {
+  diff: boolean,
+  error?: string,
+}
+
+export interface ValueDiff extends BaseDiff {
+  value: any,
+}
+
+export interface ExpectedDiff extends ValueDiff {
+  diff: true,
+  expected: any,
+}
+
+export interface ExtraValueDiff extends BaseDiff {
+  diff: true,
+  extra: any,
+}
+
+export interface MissingValueDiff extends BaseDiff {
+  diff: true,
+  missing: any,
+}
+
+export interface ObjectDiff extends ValueDiff {
+  diff: boolean,
+  props?: Record<string, Diff>,
+  values?: Diff[],
+  mappings?: [ any, Diff ][]
+}
+
+export type Diff =
+  | ValueDiff
+  | ExpectedDiff
+  | ObjectDiff
+  | ExtraValueDiff
+  | MissingValueDiff
+
+/* ========================================================================== *
+ * IMPLEMENTATION INTERNALS                                                   *
+ * ========================================================================== */
+
+type Binary = Buffer | Uint8Array | ArrayBuffer | SharedArrayBuffer
+type BoxedPrimitive = Boolean | String | Number
+type Remarks = { actualMemos: any[], expectedMemos: any[] }
+
+/* ========================================================================== */
+
+function errorDiff(value: any, message: string): ValueDiff {
+  const error = `Expected ${stringifyValue(value)} ${message}`
+  return { diff: true, value, error }
+}
+
+/* ========================================================================== */
+
+function objectDiff<T extends Record<string, any>>(
+    actual: T,
+    expected: T,
+    remarks: Remarks,
+    keys?: Set<string>,
+): ObjectDiff | ValueDiff {
+  // default keys: all keys from both actual and expected objects
+  if (! keys) keys = new Set([ ...Object.keys(actual), ...Object.keys(expected) ])
+
+  // no keys? no diff!
+  if (! keys.size) return { diff: false, value: actual }
+
+  // evaluate differences between objects
+  let diff = false
+  const props: Record<string, Diff> = {}
+  for (const key of keys) {
+    const act = actual[key]
+    const exp = expected[key]
+
+    let result = diffValues(act, exp, remarks)
+
+    // if there is a difference, we _might_ have a missing/extra property
+    if (result.diff) {
+      if ((act === undefined) && (key in expected)) {
+        result = { diff: true, missing: exp }
+      } else if ((exp === undefined) && (key in actual)) {
+        result = { diff: true, extra: act }
+      }
+    }
+
+    props[key] = result
+    diff ||= result.diff
+  }
+
+  // return our differences
+  return { diff, value: actual, props }
+}
+
+/* ========================================================================== */
+
+function arrayDiff<T extends Record<number, any> & { length: number }>(
+    actual: T,
+    expected: T,
+    remarks: Remarks,
+): ObjectDiff {
+  // make sure that the length of both arrays is the same
+  if (actual.length !== expected.length) {
+    return errorDiff(actual, `to have length ${expected.length} (length=${actual.length})`)
+  }
+
+  // prepare a set with _all_ keys from both expected and actual object
+  const keys = new Set([ ...Object.keys(expected), ...Object.keys(actual) ])
+
+  // iterate through the array, checking equality for each item ad the given
+  // index, and _removing_ the index from the set of keys to further analyse
+  let valuesDiff = false
+  const values = new Array<Diff>(expected.length)
+  for (let i = 0; i < expected.length; i ++) {
+    const result = values[i] = diffValues(actual[i], expected[i], remarks)
+    valuesDiff = valuesDiff || result.diff
+    keys.delete(String(i))
+  }
+
+  // analyse the differences between leftover props (if any)
+  const result = objectDiff(actual, expected, remarks, keys)
+  const diff = result.diff || valuesDiff
+
+  // all done!
+  return { ...result, diff, values }
+}
+
+/* ========================================================================== */
+
+function setDiff<T>(
+    actual: Set<T>,
+    expected: Set<T>,
+    remarks: Remarks,
+): ObjectDiff {
+  // highlight if sets have different sizes... don't expand the returned error
+  // as this might inject an extra "error: undefined" property in the final diff
+  const error = actual.size === expected.size ? {} :
+    errorDiff(actual, `to have size ${expected.size} (size=${actual.size})`)
+
+  // check differences between sets
+  const values: Diff[] = []
+  const missing = new Set<T>(expected)
+  const extra = new Set<T>(actual)
+
+  for (const act of extra) {
+    for (const exp of missing) {
+      const diff = diffValues(act, exp, remarks)
+      if (diff.diff) continue
+
+      values.push(diff)
+      extra.delete(act)
+      missing.delete(exp)
+    }
+  }
+
+  // compare sets as "objects" (for extra properties)
+  const result = objectDiff(actual, expected, remarks)
+  const diff = !! (missing.size || extra.size || result.diff)
+
+  // inject all extra and missing properties
+  extra.forEach((value) => values.push({ diff: true, extra: value }))
+  missing.forEach((value) => values.push({ diff: true, missing: value }))
+
+  // done...
+  return { ...error, ...result, diff, values }
+}
+
+/* ========================================================================== */
+
+function mapDiff<K, V>(
+    actual: Map<K, V>,
+    expected: Map<K, V>,
+    remarks: Remarks,
+): ObjectDiff {
+  // check mappings
+  let diff = false
+  const mappings: [ any, Diff ][] = []
+  for (const key of new Set([ ...actual.keys(), ...expected.keys() ])) {
+    const act = actual.get(key)
+    const exp = expected.get(key)
+
+    if (! actual.has(key)) {
+      mappings.push([ key, { diff: true, missing: exp } ])
+      diff = true
+    } else if (! expected.has(key)) {
+      mappings.push([ key, { diff: true, extra: act } ])
+      diff = true
+    } else {
+      const result = diffValues(act, exp, remarks)
+      mappings.push([ key, result ])
+      diff = diff || result.diff
+    }
+  }
+
+  // check other properties
+  const result = objectDiff(actual, expected, remarks)
+  diff = diff || result.diff
+
+  // done...
+  return { ...result, diff, mappings }
+}
+
+/* ========================================================================== */
+
+function binaryDiff<T extends Binary>(
+    actual: T,
+    expected: T,
+    actualData: Buffer,
+    expectedData: Buffer,
+    remarks: Remarks,
+): ObjectDiff | ValueDiff {
+  // make sure that the length of both arrays is the same
+  if (actualData.length !== expectedData.length) {
+    return errorDiff(actual, `to have length ${expectedData.length} (length=${actualData.length})`)
+  }
+
+  // remember keys
+  const keys = new Set([ ...Object.keys(expected), ...Object.keys(actual) ])
+
+  // check for equality
+  const length = expectedData.length
+  for (let i = 0; i < length; i ++) {
+    keys.delete(String(i))
+    if (actualData[i] === expectedData[i]) continue
+
+    let act = actualData.toString('hex', i, i + 6)
+    let exp = expectedData.toString('hex', i, i + 6)
+    if (act.length > 10) {
+      act = act.substring(0, 10) + '\u2026'
+      exp = exp.substring(0, 10) + '\u2026'
+    }
+    if (i > 0) {
+      act = '\u2026' + act
+      exp = '\u2026' + exp
+    }
+
+    return errorDiff(actual, `to equal at index ${i} (actual=${act}, expected=${exp})`)
+  }
+
+  // same contents, check extra properties
+  return objectDiff(actual, expected, remarks, keys)
+}
+
+/* ========================================================================== */
+
+function primitiveDiff<T extends BoxedPrimitive>(
+    actual: T,
+    expected: T,
+    remarks: Remarks,
+): ObjectDiff | ExpectedDiff | ValueDiff {
+  if (actual.valueOf() !== expected.valueOf()) {
+    return {
+      diff: true,
+      value: actual,
+      expected: expected,
+    }
+  }
+
+  // remove string indexes from properties
+  const keys = new Set([ ...Object.keys(actual), ...Object.keys(expected) ])
+  if (actual instanceof String) {
+    const length = actual.valueOf().length
+    for (let i = 0; i < length; i ++) {
+      keys.delete(String(i))
+    }
+  }
+
+  // return either an object diff or no diff at all...
+  return keys.size ? objectDiff(actual, expected, remarks, keys) : {
+    diff: false,
+    value: actual,
+  }
+}
+
+/* ========================================================================== *
+ * MAIN "DIFF"                                                                *
+ * ========================================================================== */
+
+function diffValues(actual: any, expected: any, remarks: Remarks): Diff {
+  // strict equality
+  if (expected === actual) return { diff: false, value: expected }
+
+  // oh, javascript!
+  if (expected === null) {
+    return {
+      diff: true,
+      value: actual,
+      expected: null,
+    }
+  }
+
+  // matchers!
+  if (isMatcher(expected)) {
+    try {
+      expected.expect(actual)
+      return { diff: false, value: actual }
+    } catch (error) {
+      if (error instanceof ExpectationError) {
+        // if the error highlights a difference, simply return that
+        // otherwise wrap the error into a new ErrorDiff and return it
+        const { message, diff } = error
+        return diff?.diff ? diff : { diff: true, value: actual, error: message }
+      } else {
+        throw error
+      }
+    }
+  }
+
+  // inspect types of what to compare
+  const actualType = typeof actual
+  const expectedType = typeof expected
+
+  // if type is different then highlight the difference
+  if (actualType !== expectedType) {
+    return {
+      diff: true,
+      value: actual,
+      expected: expected,
+    }
+  }
+
+  // primitives
+  switch (actualType) {
+    // numbers are one-of-a-kind as NaN !== NaN
+    case 'number':
+      if (isNaN(expected as number) && isNaN(actual as number)) {
+        return { diff: false, value: NaN }
+      }
+    // primitives always must be strict ===
+    case 'bigint':
+    case 'boolean':
+    case 'function':
+    case 'string':
+    case 'symbol':
+    case 'undefined':
+      return {
+        diff: true,
+        value: actual,
+        expected: expected,
+      }
+    // everything else is an object and must be checked
+  }
+
+  // check for cyclical dependencies, see node's commit here:
+  // https://github.com/nodejs/node/commit/d3aafd02efd3a403d646a3044adcf14e63a88d32
+  const actualIndex = remarks.actualMemos.indexOf(actual)
+  if (actualIndex !== -1) {
+    if (actualIndex === remarks.expectedMemos.indexOf(expected)) {
+      return { diff: false, value: actual }
+    }
+  }
+
+  remarks.actualMemos.push(actual)
+  remarks.expectedMemos.push(expected)
+
+  // check that actual is _assignable_ from expected
+  const prototype = Object.getPrototypeOf(expected)
+  if (prototype && prototype.constructor) {
+    if (! (actual instanceof prototype.constructor)) {
+      return {
+        ...errorDiff(actual, `to be instance of ${stringifyConstructor(prototype.constructor)}`),
+        expected,
+      }
+    }
+  }
+
+  /* == ARRAYS ============================================================== */
+
+  const checkInstance = <T>(
+    ctor: Constructor<T>,
+    callback: (actual: T, expected: T, remarks: Remarks) => Diff,
+  ): Diff | undefined =>
+    (expected instanceof ctor) ?
+      callback(actual as InstanceType<typeof ctor>, expected, remarks) :
+    (actual instanceof ctor) ?
+      { diff: true, value: actual, expected } :
+    undefined
+
+  return (
+    /* == ARRAYS ============================================================ */
+    checkInstance(Array, arrayDiff) ||
+
+    /* == SETS ============================================================== */
+    checkInstance(Set, (act, exp) => setDiff(act, exp, remarks)) ||
+
+    /* == MAPS ============================================================== */
+    checkInstance(Map, (act, exp) => mapDiff(act, exp, remarks)) ||
+
+    /* == BOXED PRIMITIVES ================================================== */
+    checkInstance(Boolean, primitiveDiff) ||
+    checkInstance(String, primitiveDiff) ||
+    checkInstance(Number, primitiveDiff) ||
+
+    /* == PROMISES (always error, must be ===) ============================== */
+    checkInstance(Promise, (act, exp) => errorDiff(act, `to strictly equal ${stringifyValue(exp)}`)) ||
+
+    /* == DATES ============================================================= */
+    checkInstance(Date, (act, exp) =>
+      (act.getTime() !== exp.getTime()) ? {
+        diff: true,
+        value: act,
+        expected: exp,
+      } : objectDiff(act, exp, remarks)) ||
+
+    /* == REGULAR EXPRESSIONS =============================================== */
+    checkInstance(RegExp, (act, exp) =>
+      ((act.source !== exp.source) || (act.flags !== exp.flags)) ? {
+        diff: true,
+        value: act,
+        expected: exp,
+      } : objectDiff(act, exp, remarks)) ||
+
+    /* == BINARY ARRAYS ===================================================== */
+    checkInstance(Buffer, (act, exp) => binaryDiff(act, exp, act, exp, remarks)) ||
+    checkInstance(Uint8Array, (act, exp) => binaryDiff(act, exp, Buffer.from(act), Buffer.from(exp), remarks)) ||
+    checkInstance(ArrayBuffer, (act, exp) => binaryDiff(act, exp, Buffer.from(act), Buffer.from(exp), remarks)) ||
+    checkInstance(SharedArrayBuffer, (act, exp) => binaryDiff(act, exp, Buffer.from(act), Buffer.from(exp), remarks)) ||
+
+    /* == OTHER TYPED ARRAYS ================================================ */
+    checkInstance(BigInt64Array, arrayDiff) ||
+    checkInstance(BigUint64Array, arrayDiff) ||
+    checkInstance(Float32Array, arrayDiff) ||
+    checkInstance(Float64Array, arrayDiff) ||
+    checkInstance(Int16Array, arrayDiff) ||
+    checkInstance(Int32Array, arrayDiff) ||
+    checkInstance(Int8Array, arrayDiff) ||
+    checkInstance(Uint16Array, arrayDiff) ||
+    checkInstance(Uint32Array, arrayDiff) ||
+    checkInstance(Uint8ClampedArray, arrayDiff) ||
+
+    /* == DONE ============================================================== */
+    objectDiff(actual as any, expected, remarks))
+}
+
+/* ========================================================================== *
+ * EXPORTS                                                                    *
+ * ========================================================================== */
+
+export function diff(actual: any, expected: any): Diff {
+  return diffValues(actual, expected, { actualMemos: [], expectedMemos: [] })
+}