risei 1.3.4 → 2.0.0

package/system/TestRunner.js

@@ -2,41 +2,24 @@
 
 /* Runs tests one by one as an ATestCaller requests them. */
 
-import { TestDefinition } from "./TestDefinition.js";
-import { TestGroup } from "./TestGroup.js";
-import { ClassTestGroup } from "./ClassTestGroup.js";
-import { MethodTestGroup } from "./MethodTestGroup.js";
-import { TestResult } from "./TestResult.js";
-import { TestSummary } from "./TestSummary.js";
+import TestDef from "./TestDef.js";
+import TestGroup from "./TestGroup.js";
+import ClassTestGroup from "./ClassTestGroup.js";
+import MethodTestGroup from "./MethodTestGroup.js";
+import TestResult from "./TestResult.js";
+import TestSummary from "./TestSummary.js";
 
-import { TestFrameChooser } from "./TestFrameChooser.js";
-import { TestFrames } from "./TestFrames.js";
+import TestFrame from "./TestFrame.js";
 
-import { ClassMethodSpoofer } from "./ClassMethodSpoofer.js";
-import { ObjectMethodSpoofer } from "./ObjectMethodSpoofer.js";
-import { SpoofDefinition } from "./SpoofDefinition.js";
-
-export class TestRunner {
-    // region Static definition fields
-
-    // Used for a special test structural case;
-    // classes have one constructor by this name.
-    static #constructorName = "constructor";
-
-    // endregion Static definition fields
+import MethodSpoofer from "./MethodSpoofer.js";
+import SpoofDef from "./SpoofDef.js";
 
+export default class TestRunner {
     // region Private fields
 
     // Components and state.
     #tests;
-    
-    #classSpoofer;
-    #instanceSpoofer;
-    
-    #frameSource;
-    #frameChooser;
-    
-    #comparer;
+    #frame;
 
     // Results summary.
     #numberRun;
@@ -48,6 +31,8 @@ export class TestRunner {
     
     // region Properties
 
+    /* inputs */
+
     get tests() {
         return this.#tests;
     }
@@ -56,25 +41,7 @@ export class TestRunner {
         this.#tests = value;
     }
 
-    // region Spoofing
-
-    get classSpoofer() {
-        return this.#classSpoofer;
-    }
-
-    set classSpoofer(value) {
-        this.#classSpoofer = value;
-    }
-    
-    get instanceSpoofer() {
-        return this.#instanceSpoofer;
-    }
-    
-    set instanceSpoofer(value) {
-        this.#instanceSpoofer = value;
-    }
-
-    // endregion Spoofing
+    /* outputs */
 
     get numberRun() {
         return this.#numberRun;
@@ -112,11 +79,8 @@ export class TestRunner {
 
     constructor() {
         this.#tests = [];
-        this.#classSpoofer = new ClassMethodSpoofer();
-        this.#instanceSpoofer = new ObjectMethodSpoofer();
-        
-        this.#frameSource = new TestFrames();
-        this.#frameChooser = new TestFrameChooser(this.#frameSource);
+
+        this.#frame = new TestFrame();
 
         this.#numberRun = 0;
         this.#numberPassed = 0;
@@ -143,7 +107,7 @@ export class TestRunner {
         }
     
         // Converting so that property names can be relied on.
-        this.#tests = TestDefinition.fromNonceTuples(this.tests);
+        this.#tests = TestDef.fromNonceTuples(this.tests);
 
         // Needed for displaying classes and methods as groups.
         let classGroup = new ClassTestGroup();
@@ -160,10 +124,10 @@ export class TestRunner {
                 yield classGroup;
             }
 
-            // Each new method name should be a group, 
-            // and so should each method for a class.
-            if (test.of !== methodGroup.group || atFirstClassMethod) {
-                methodGroup.group = test.of;
+            // Each new method / prop name should be a group, 
+            // and so should the first method for a class.
+            if (test.runName !== methodGroup.group || atFirstClassMethod) {
+                methodGroup.group = test.runName;
                 atFirstClassMethod = false;
                 yield methodGroup;
             }
@@ -181,35 +145,14 @@ export class TestRunner {
         test.didPass = false;
         test.anyThrow = null;
 
-        // Spoofing based on any spoof 
-        // definitions in .with and .of.
-        this.#anyObjectSpoofing(test);
-
         // Gathering facts defining the nature of the test, 
         // some of which might change after the test is run.
         let result = new TestResult(test);
         result.setNature();
 
-        // Aspects of the test determine the right test frame,
-        // bound back to its class to use private class members.
-        let testFrame = this.#frameChooser.supplyTestFrame(test);
-        testFrame = testFrame.bind(this.#frameSource);
-
-        // Done in every test.
-        this.#anyMethodSpoofing(test);
-
         // Actually running the test.
-        try {
-            testFrame(test);
-        }
-        catch (thrown) {
-            test.anyThrow = thrown;
-            test.didPass = false;
-        }
-        
-        // Done in every test, whether passed, failed, or thrown.
-        this.#anyMethodRestoring(test);
-        
+        this.#frame.run(test);
+
         // Gathering facts based on the test run.
         result.setResults();
 
@@ -222,33 +165,6 @@ export class TestRunner {
     
     // region Dependencies of runOneTest()
     
-    // Spoofs objects as defined in TestDefinition's 
-    // .with and .in, which can contain spoofs.
-    #anyObjectSpoofing(test) {
-        // Spoofing objects may be skipped for self-testing.
-        if (typeof test.and === "string") {
-            if (test.and.includes("nospoof")) {
-                return;
-            }
-        }
-    
-        // Actually spoofing, if any is defined.
-        this.#instanceSpoofer.spoof(test);
-    }
-
-    #anyMethodSpoofing(test) {
-        if (test.plus === undefined) {
-            return;
-        }
-
-        this.#classSpoofer.spoof(test);
-    }
-
-    #anyMethodRestoring(test) {
-        this.#classSpoofer.unspoof();
-        this.#classSpoofer.removeDefinitions();
-    }
-
     #retainTestResults(test) {
         this.#numberRun++;
 

package/system/TestStages.js

@@ -1,22 +1,32 @@
 /**/
 
-import { TestDefinition } from "./TestDefinition.js";
-import { TotalComparer } from "./TotalComparer.js";
-import { TotalCopier } from "./TotalCopier.js";
+import TestDef from "./TestDef.js";
+import MethodSpoofer from "./MethodSpoofer.js";
+import PropertySpoofer from "./PropertySpoofer.js";
+import TypeAnalyzer from "./TypeAnalyzer.js";
+import NameAnalyzer from "./NameAnalyzer.js";
+import TotalComparer from "./TotalComparer.js";
 
-export class TestStages {
-    /* &cruft, implement all of these under test, and eventually factor them */
+export default class TestStages {
+    /* &cruft, ? factor these to more classes */
 
     /* These methods hold operations carried out in the test frame, 
        or before / after all test frames, in the test runner.  
        Not necessarily all test steps are found here. */
 
+    static #methodSpoofer = new MethodSpoofer();
+    static #propertySpoofer = new PropertySpoofer();
     static #comparer = new TotalComparer();
-    static #copier = new TotalCopier();
 
-    anyPreTargetingGroundwork(test) {
-        // Spoofing of class members here.
-        // Setting any static properties here.
+    anyPreTargetingGroundwork(test) /* passed */ {
+        // Spoofing methods; properties spoofed later.
+        TestStages.#methodSpoofer.spoof(test);
+
+        // Arbitrary user-defined actions. 
+        // Only spoofed methods available.
+        if (test.doesHaveDoEarly) {
+            test.do.early(test);
+        }
     }
     
     setTarget(test) /* passed */ {
@@ -25,58 +35,50 @@ export class TestStages {
            static or instance properties. */
 
         if (test.isConstructorTest) {
-            test.target = test.on.prototype;
+            test.target = new test.on.prototype.constructor(...test.in);
             return;
         }
 
-        let callable = TestDefinition.plainNameOf(test.of);
-
         let target = test.isInstanceTest 
-            ? this.#supplyInstanceTarget(test, callable) 
-            : this.#supplyStaticTarget(test, callable);
+            ? new test.on.prototype.constructor(...test.with) 
+            : test.on;
 
         test.target = target;
     }
     
-    // region Dependencies of setTarget()
-    
-    #supplyStaticTarget(test, callable) /* verified */ {
-        let type = test.on;
-        
-        // Methods are called on class directly.  
-        // Properties are called on class in nonce.
-        let target = test.isMethodTest 
-            ? type 
-            : { localCallable: () => { return type[callable]; } };
+    supplyLocalTarget(test) /* passed */ {
+        /* Methods are called on instance / type / prototype directly.  
+           Properties are called on instance / type in a nonce. */
 
-        return target;
-    }
+        let callable = NameAnalyzer.plainNameOf(test.method);
 
-    #supplyInstanceTarget(test, callable) /* verified */ {
-        let instance = new test.on.prototype.constructor(...test.with);
-        
-        // Methods are called on instance directly.  
-        // Properties are called on instance in nonce.
-        let target = test.isMethodTest  
-            ? instance 
-            : { localCallable: () => { return instance[callable]; } };
-            
-        return target; 
+        let localTarget = test.isMethodTest
+            ? test.target
+            : { nonce: () => { return test.target[callable]; } };
+
+        return localTarget;
     }
-    
-    // endregion Dependencies of setTarget()
 
-    setLocalCallable(test) /* passed */ {
+    supplyCallableName(test) /* passed */ {
         /* Method under test is a method named in test, 
            or a nonce method for a property test. */
         
-        test.localCallable = test.isMethodTest 
-            ? TestDefinition.plainNameOf(test.method) 
-            : TestDefinition.nonceLocalCallableName;
+        let name = test.isMethodTest 
+            ? NameAnalyzer.plainNameOf(test.method) 
+            : TestDef.nonceLocalCallableName;
+
+        return name;
     }
     
-    anyPostTargetingGroundwork(test) {
-        // Setting instance properties.
+    anyPostTargetingGroundwork(test) /* passed */ {
+        // Spoofing properties; methods spoofed earlier.
+        TestStages.#propertySpoofer.spoof(test);
+
+        // Arbitrary user-defined actions. 
+        // All spoofs normally available.
+        if (test.doesHaveDoLate) {
+            test.do.late(test);
+        }
     }
     
     anyModifyActual(test) /* passed */ {
@@ -97,52 +99,54 @@ export class TestStages {
         return TestStages.#comparer.compare(expected, actual);
     }
     
-    anyGroundworkReversion(test) {
-        // Unspoofing.
-        // Unsetting static properties.
-        // Undoing any other groundwork changes made.
+    anyGroundworkReversal(test) /* passed */ {
+        // Unspoofing methods and properties.
+        TestStages.#methodSpoofer.unspoof(test);
+        TestStages.#propertySpoofer.unspoof(test);
+
+        // Arbitrary user-defined operations.
+        // No spoofs are available here.
+        if (test.doesHaveUndo) {
+            test.undo(test);
+        }
     }
 
     // region Dependencies of test stages
 
-    #compare(expected, actual) {
-        return this.#comparer.compare(expected, actual);
-    }
-
-    supplyNonReturnActual(test) {
-        // When there is a .from that's a string, 
-        // the actual is the named target member.
+    supplyNonReturnActual(test) /* passed */ {
+        // When .from is a string, the actual 
+        // is the named target or type member.
         if (typeof test.from === "string") {
-            /* &cruft, maybe explain how this differs from setting .target, 
-                       which can be a nonce, or else maybe make them the same */
-
-            // Common member host; 
-            // undefined if static.
-            let host = test.target;
-            
-            // When .and defines static.
-            if (test.isStaticTest) {
-                host = test.on;
-            }
-        
-            return host[test.from];
+            // Removing any sigil.
+            let name = NameAnalyzer.plainNameOf(test.from);
+
+            // Determining which exposes the property.
+            let host = TypeAnalyzer.isInstanceMember(test.type, name)
+                ? test.target
+                : test.type;
+
+            // Actually supplying value.
+            return host[name];
         }
-        
-        /* &cruft, possibly change all .from syntax to (actual, test), 
-                   or maybe to (test), or else switch back args here */
+
+        /* &cruft, possibly change all .from syntax 
+                   to ? (actual, test), or ? (test) */
         // When there is a .from that's a function, 
         // the actual is the result of calling it, 
         // given everything that might be needed.
         if (test.from instanceof Function) {
-            return test.from(test.actual, test.target);
+            // Actually supplying value.
+            return test.from(test.target, test);
         }
 
-        /* &cruft, probably drop this, change maybe to a throw */
-        // When there is any other .from, the actual is the
-        // value of the code element provided as .from.
-        return test.from;
+        // Only property names and functions make sense to support.
+        throw new Error("The test.from value was not a usable type.  It must be either a property name or a function to work.");
     }
     
+    #compare(expected, actual) /* verified */ {
+        return this.#comparer.compare(expected, actual);
+    }
+
     // endregion Dependencies of test stages
 
 }

package/system/TestSummary.js

@@ -1,6 +1,6 @@
 /**/
 
-export class TestSummary {
+export default class TestSummary {
     #summary;
     #allDidPass;
     #anyWereRun;

package/system/TotalComparer.js

@@ -1,10 +1,10 @@
 /**/
 
-import { AComparer } from "./AComparer.js";
+import ATestSource from "./ATestSource.js";
 
-export class TotalComparer extends AComparer {
+export default class TotalComparer {
     constructor() {
-        super();
+        /* No operations. */
     }
     
     compare(expected, actual) /* passed */ {
@@ -20,33 +20,43 @@ export class TotalComparer extends AComparer {
             /* Traverse / recurse to leaves. */
             return this.#recurseOverArrays(expected, actual);
         }
-        
+
         if (expected instanceof Map) {
             /* Traverse / recurse to leaves. */
             return this.#recurseOverMaps(expected, actual);
         }
-        
+
         if (expected instanceof Set) {
             /* Traverse / recurse to leaves. */
             return this.#recurseOverSets(expected, actual);
         }
-        
+
         if (expected instanceof Function) {
             /* Leaf to compare directly. */
             return this.#compareFunctions(expected, actual);
         }
-        
+
         if (expected instanceof Date) {
             return this.#compareDates(expected, actual);
         }
-        
+
+        if (expected instanceof Error) {
+            return this.#compareErrors(expected, actual);
+        }
+
         if (expected instanceof Object) {
             /* Traverse / recurse to leaves. */
             return this.#recurseOverObjects(expected, actual);
         }
-        
-        /* If neither a function leaf nor any 
-           fork type, compare as a leaf value. */
+
+        /* If a special symbol to support undefined 
+           as expected, see if actual is undefined. */
+        if (expected === ATestSource.undefSymbol) {
+            return this.#compareUndefs(expected, actual);
+        }
+
+        /* If none of the above things, 
+           compare as a leaf value. */
         return this.#compareValues(expected, actual);
     }
     
@@ -203,6 +213,21 @@ export class TotalComparer extends AComparer {
         return false;
     }
 
+    #compareUndefs(expected, actual) /* verified */ {
+        // The rare case of comparing undef symbols.
+        if (actual === expected) {
+            return true;
+        }
+
+        // The common case of using the undef symbol 
+        // to see if the actual is undefined.
+        if (actual === undefined) {
+            return true;
+        }
+        
+        return false;
+    }
+
     #compareFunctions(expected, actual) /* verified */ {
         // `expected` is already known to be a function / method.
         if (!(actual instanceof Function)) {
@@ -235,6 +260,30 @@ export class TotalComparer extends AComparer {
         return expected.valueOf() === actual.valueOf();
     }
 
+    #compareErrors(expected, actual) /* verified */ {
+        /* Compares Errors and subclasses accurately apart from .stack, 
+           which is ignored because it rarely makes sense to compare it. */
+
+        // Most common difference.
+        if (expected.message != actual.message) {
+            return false;
+        }
+
+        // Different Error subtypes.
+        if (expected.name !== actual.name) {
+            return false;
+        }
+
+        // Recursion for causes, which may not be Errors.
+        if (!this.compare(expected.cause, actual.cause)) {
+            return false;
+        }
+
+        // If nothing failed, they are the same 
+        // (apart, probably from .stack).
+        return true;
+    }
+
     // endregion Dependencies of compare()
 
 }

package/system/TotalDisplayer.js

@@ -1,17 +1,12 @@
 /**/
 
-import { TypeIdentifier } from "./TypeIdentifier.js";
-import { Types } from "./Types.js";
+import TypeIdentifier from "./TypeIdentifier.js";
+import Types from "./Types.js";
+import ATestSource from "./ATestSource.js";
 
-export class TotalDisplayer {
-    #identifier;
-
-    constructor() /* verified */ {
-        this.#identifier = new TypeIdentifier();
-    }
-
-    display(value) /* passed */ {
-        let typeId = this.#identifier.identify(value);
+export default class TotalDisplayer {
+    display(value) /* good */ {
+        let typeId = TypeIdentifier.identify(value);
 
         switch (typeId) {
             case Types.isValue: return this.displayValue(value);
@@ -19,11 +14,13 @@ export class TotalDisplayer {
             case Types.isArray: return this.displayArray(value);
             case Types.isMap: return this.displayMap(value);
             case Types.isSet: return this.displaySet(value);
+            case Types.isError: return this.displayError(value);
             case Types.isClass: return this.displayClass(value);
             case Types.isFunction: return this.displayFunction(value);
             case Types.isObject: return this.displayObject(value);
             case Types.isDate: return this.displayValue(value);
             case Types.isUndefined: return this.displayUndefined(value);
+            case Types.isUndefSymbol: return this.displayUndefined(value);
             case Types.isNull: return this.displayNull(value);
         }
     }
@@ -85,6 +82,30 @@ export class TotalDisplayer {
         return output;
     }
 
+    displayError(value) /* passed */ {
+        // Subtype can't be found with typeof.
+        let type = value.name;
+
+        // No "" when no message.
+        let message = value.message !== "" 
+            ? `\"${ value.message }\"` 
+            : "";
+
+        // Inter-property punctuation only when needed.
+        let inter 
+            = value.message !== "" && value.cause !== undefined 
+            ? ", " 
+            : "";
+
+        // Normally an Error / subtype, but not necessarily.
+        let cause = value.cause !== undefined 
+            ? `cause:${ this.display(value.cause) }` 
+            : "";
+
+        let output = `${ type }{${ message }${ inter }${ cause }}`;
+        return output;
+    }
+
     displayClass(value) /* passed */ {
         // Class definitions have a .name.
         let output = value.name;
@@ -124,7 +145,7 @@ export class TotalDisplayer {
     }
 
     displayUndefined(value) /* passed */ {
-        return "undefined";
+        return "undef";
     }
 
     displayNull(value) /* passed */ {