Add clear substitute (#233)

resolves #46 

* implement clearSubstitute

* add clearSubstitute spec

Author: notanengineercom

spec/ClearSubstitute.spec.ts

@@ -0,0 +1,65 @@
+import test from 'ava'
+
+import { Substitute, SubstituteOf } from '../src'
+import { SubstituteBase } from '../src/SubstituteBase'
+import { SubstituteNode } from '../src/SubstituteNode'
+
+interface Calculator {
+  add(a: number, b: number): number
+  subtract(a: number, b: number): number
+  divide(a: number, b: number): number
+  isEnabled: boolean
+}
+
+type InstanceReturningSubstitute<T> = SubstituteOf<T> & {
+  [SubstituteBase.instance]: Substitute
+}
+
+test('clears everything on a substitute', t => {
+  const calculator = Substitute.for<Calculator>() as InstanceReturningSubstitute<Calculator>
+  calculator.add(1, 1)
+  calculator.received().add(1, 1)
+  calculator.clearSubstitute()
+
+  t.is(calculator[Substitute.instance].recorder.records.size, 0)
+  t.is(calculator[Substitute.instance].recorder.indexedRecords.size, 0)
+
+  t.throws(() => calculator.received().add(1, 1))
+
+  // explicitly using 'all'
+  calculator.add(1, 1)
+  calculator.received().add(1, 1)
+  calculator.clearSubstitute('all')
+
+  t.is(calculator[Substitute.instance].recorder.records.size, 0)
+  t.is(calculator[Substitute.instance].recorder.indexedRecords.size, 0)
+
+  t.throws(() => calculator.received().add(1, 1))
+})
+
+test('clears received calls on a substitute', t => {
+  const calculator = Substitute.for<Calculator>() as InstanceReturningSubstitute<Calculator>
+  calculator.add(1, 1)
+  calculator.add(1, 1).returns(2)
+  calculator.clearSubstitute('receivedCalls')
+
+  t.is(calculator[Substitute.instance].recorder.records.size, 2)
+  t.is(calculator[Substitute.instance].recorder.indexedRecords.size, 2)
+
+  t.throws(() => calculator.received().add(1, 1))
+  t.is(calculator.add(1, 1), 2)
+})
+
+test('clears return values on a substitute', t => {
+  const calculator = Substitute.for<Calculator>() as InstanceReturningSubstitute<Calculator>
+  calculator.add(1, 1)
+  calculator.add(1, 1).returns(2)
+  calculator.clearSubstitute('substituteValues')
+
+  t.is(calculator[Substitute.instance].recorder.records.size, 2)
+  t.is(calculator[Substitute.instance].recorder.indexedRecords.size, 2)
+
+  t.notThrows(() => calculator.received().add(1, 1))
+  // @ts-expect-error
+  t.true(calculator.add(1, 1)[SubstituteBase.instance] instanceof SubstituteNode)
+})

src/Recorder.ts

@@ -35,6 +35,16 @@ export class Recorder {
     return siblingNodes.filter(siblingNode => siblingNode !== node)
   }
 
+  public clearRecords(filterFunction: (node: SubstituteNodeBase) => boolean) {
+    const recordsToRemove = this.records.filter(filterFunction)
+    for (const record of recordsToRemove) {
+      const indexedRecord = this.indexedRecords.get(record.key)
+      indexedRecord.delete(record)
+      if (indexedRecord.size === 0) this.indexedRecords.delete(record.key)
+      this.records.delete(record)
+    }
+  }
+
   public [inspect.custom](_: number, options: InspectOptions): string {
     const entries = [...this.indexedRecords.entries()]
     return entries.map(

src/SubstituteNode.ts

@@ -1,13 +1,19 @@
 import { inspect, InspectOptions } from 'util'
 
-import { PropertyType, isSubstitutionMethod, isAssertionMethod, AssertionMethod, SubstitutionMethod, textModifier, isSubstituteMethod } from './Utilities'
+import { PropertyType, isSubstitutionMethod, isAssertionMethod, AssertionMethod, SubstitutionMethod, textModifier, ConfigurationMethod, isSubstituteMethod } from './Utilities'
 import { SubstituteException } from './SubstituteException'
 import { RecordedArguments } from './RecordedArguments'
 import { SubstituteNodeBase } from './SubstituteNodeBase'
 import { SubstituteBase } from './SubstituteBase'
 import { createSubstituteProxy } from './SubstituteProxy'
+import { ClearType } from './Transformations'
 
-type SubstituteContext = SubstitutionMethod | AssertionMethod | 'none'
+type SubstituteContext = SubstitutionMethod | AssertionMethod | ConfigurationMethod | 'none'
+const clearTypeToFilterMap: Record<ClearType, (node: SubstituteNode) => boolean> = {
+  all: () => true,
+  receivedCalls: node => !node.hasContext,
+  substituteValues: node => node.isSubstitution
+}
 
 export class SubstituteNode extends SubstituteNodeBase<SubstituteNode> {
   private _proxy: SubstituteNode
@@ -31,6 +37,7 @@ export class SubstituteNode extends SubstituteNodeBase<SubstituteNode> {
         },
         apply: (node, _, rawArguments) => {
           node.handleMethod(rawArguments)
+          if (node.context === 'clearSubstitute') return node.clear()
           return node.parent?.isAssertion ?? false ? node.executeAssertion() : node.read()
         }
       }
@@ -100,6 +107,12 @@ export class SubstituteNode extends SubstituteNodeBase<SubstituteNode> {
     this._recordedArguments = RecordedArguments.from([value])
   }
 
+  public clear() {
+    const clearType: ClearType = this.recordedArguments.value[0] ?? 'all'
+    const filter = clearTypeToFilterMap[clearType] as (node: SubstituteNodeBase) => boolean
+    this.root.recorder.clearRecords(filter)
+  }
+
   public executeSubstitution(contextArguments: RecordedArguments) {
     const substitutionMethod = this.context as SubstitutionMethod
     const substitutionValue = this.child.recordedArguments.value.length > 1

src/Transformations.ts

@@ -1,4 +1,4 @@
-import { AllArguments } from "./Arguments";
+import { AllArguments } from './Arguments';
 
 type FunctionSubstituteWithOverloads<TFunc, Terminating = false> =
     TFunc extends {
@@ -70,6 +70,7 @@ export type ObjectSubstitute<T extends Object, K extends Object = T> = ObjectSub
     received(amount?: number): TerminatingObject<K>;
     didNotReceive(): TerminatingObject<K>;
     mimick(instance: T): void;
+    clearSubstitute(clearType?: ClearType): void;
 }
 
 type TerminatingFunction<TArguments extends any[]> = ((...args: TArguments) => void) & ((arg: AllArguments<TArguments>) => void)
@@ -92,5 +93,6 @@ type ObjectSubstituteTransformation<T extends Object> = {
 
 type Omit<T, K extends keyof any> = Pick<T, Exclude<keyof T, K>>;
 
-export type OmitProxyMethods<T extends any> = Omit<T, 'mimick' | 'received' | 'didNotReceive'>;
+export type ClearType = 'all' | 'receivedCalls' | 'substituteValues';
+export type OmitProxyMethods<T extends any> = Omit<T, 'mimick' | 'received' | 'didNotReceive' | 'clearSubstitute'>;
 export type DisabledSubstituteObject<T> = T extends ObjectSubstitute<OmitProxyMethods<infer K>, infer K> ? K : never;

src/Utilities.ts

@@ -10,12 +10,15 @@ export type AssertionMethod = 'received' | 'didNotReceive'
 export const isAssertionMethod = (property: PropertyKey): property is AssertionMethod =>
   property === 'received' || property === 'didNotReceive'
 
+export type ConfigurationMethod = 'clearSubstitute'
+export const isConfigurationMethod = (property: PropertyKey): property is ConfigurationMethod => property === 'clearSubstitute'
+
 export type SubstitutionMethod = 'mimicks' | 'throws' | 'returns' | 'resolves' | 'rejects'
 export const isSubstitutionMethod = (property: PropertyKey): property is SubstitutionMethod =>
   property === 'mimicks' || property === 'returns' || property === 'throws' || property === 'resolves' || property === 'rejects'
 
-export const isSubstituteMethod = (property: PropertyKey): property is SubstitutionMethod | AssertionMethod =>
-  isSubstitutionMethod(property) || isAssertionMethod(property)
+export const isSubstituteMethod = (property: PropertyKey): property is SubstitutionMethod | ConfigurationMethod | AssertionMethod =>
+  isSubstitutionMethod(property) || isConfigurationMethod(property) || isAssertionMethod(property)
 
 export const stringifyArguments = (args: RecordedArguments) => textModifier.faint(
   args.hasNoArguments