risei 1.0.4 → 1.1.1

package/system/TestRunner.js

@@ -0,0 +1,280 @@
+/**/
+
+/* Runs tests one by one as an ATestCaller requests them. */
+
+import { TestTuple } from "./TestTuple.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 { SpoofClassMethodsFixture } from "./SpoofClassMethodsFixture.js";
+import { SpoofObjectMethodsFixture } from "./SpoofObjectMethodsFixture.js";
+import { SpoofTuple } from "./SpoofTuple.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
+
+    // region Private fields
+
+    // Components and state.
+    #tests;
+    
+    #classSpoofer;
+    #instanceSpoofer;
+    
+    #frameSource;
+    #frameChooser;
+    
+    #comparer;
+
+    // Results summary.
+    #numberRun;
+    #numberPassed;
+    #numberFailed;
+    #allDidPass;
+
+    // endregion Private fields
+    
+    // region Properties
+
+    get tests() {
+        return this.#tests;
+    }
+
+    set tests(value) {
+        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
+
+    get numberRun() {
+        return this.#numberRun;
+    }
+
+    set numberRun(value) {
+        this.#numberRun = value;
+    }
+
+    get numberPassed() {
+        return this.#numberPassed;
+    }
+
+    set numberPassed(value) {
+        this.#numberPassed = value;
+    }
+
+    get numberFailed() {
+        return this.#numberFailed;
+    }
+
+    set numberFailed(value) {
+        this.#numberFailed = value;
+    }
+
+    get allDidPass() {
+        return this.#allDidPass;
+    }
+
+    set allDidPass(value) {
+        this.#allDidPass = value;
+    }
+
+    // endregion Properties
+
+    constructor() {
+        this.#tests = [];
+        this.#classSpoofer = new SpoofClassMethodsFixture();
+        this.#instanceSpoofer = new SpoofObjectMethodsFixture();
+        
+        this.#frameSource = new TestFrames();
+        this.#frameChooser = new TestFrameChooser(this.#frameSource);
+
+        this.#numberRun = 0;
+        this.#numberPassed = 0;
+        this.#numberFailed = 0;
+
+        this.#allDidPass = true;
+    }
+
+    // region Tests to run
+    
+    useTests(tests) {
+        this.#tests = tests;
+    }
+    
+    // endregion Tests to run
+
+    // region Running tests
+
+    // Generator for all test results, 
+    // including groups and summary.
+    * [Symbol.iterator]() {
+        if (!this.#tests) {
+            throw new Error("No tests available to run.  TestRunner's .tests must be set before an attempt to run is made.");
+        }
+    
+        // Converting so that property names can be relied on.
+        this.#tests = TestTuple.fromNonceTuples(this.tests);
+
+        // Needed for displaying classes and methods as groups.
+        let classGroup = new ClassTestGroup();
+        let methodGroup = new MethodTestGroup();
+        let atFirstClassMethod = false;
+
+        // Iterative running of all tests in current order.
+        for (let test of this.#tests) {
+            // Each new class should be a group, and its start 
+            // should be retained for grouping of methods.
+            if (test.on.name !== classGroup.group) {
+                classGroup.group = test.on.name;
+                atFirstClassMethod = true;
+                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;
+                atFirstClassMethod = false;
+                yield methodGroup;
+            }
+
+            let result = this.runOneTest(test);
+            yield result;
+        }
+
+        // Iterative returning of final results summary.
+        yield this.summarize();
+    }
+
+    runOneTest(test) {
+        // Default outputs.  Never left undefined.
+        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);
+        
+        // Gathering facts based on the test run.
+        result.setResults();
+
+        // For later summarizing.
+        this.#retainTestResults(test);
+
+        // Results and test back to the caller.
+        return result;
+    }
+    
+    // region Dependencies of runOneTest()
+    
+    // Spoofs objects as defined in TestTuple'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++;
+
+        if (test.didPass) {
+            this.#numberPassed++;
+        }
+        else {
+            this.#numberFailed++;
+        }
+
+        this.#allDidPass &= test.didPass;
+    }
+
+    // endregion Dependencies of runOneTest()
+
+    summarize() {
+        let summary = `Ran ${ this.#numberRun } test${ this.#numberRun !== 1 ? "s" : "" }.  `
+            + `${ this.#allDidPass ? "All tests passed.  " : "" }`
+            + `${ this.#numberPassed } passed.  `
+            + `${ this.#numberFailed } failed.`;
+
+        let anyWereRun = this.#numberRun > 0;
+
+        return new TestSummary(summary, this.#allDidPass, anyWereRun);
+    }
+
+    // endregion Running tests
+
+}

package/system/TestStages.js

@@ -0,0 +1,278 @@
+/**/
+
+import { TestTuple } from "./TestTuple.js";
+import { TotalComparer } from "./TotalComparer.js";
+import { TotalCopier } from "./TotalCopier.js";
+
+export class TestStages {
+    /* &cruft, implement all of these under test, and eventually factor them */
+
+    /* 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 #comparer = new TotalComparer();
+    static #copier = new TotalCopier();
+
+    setLocalInitorsAndInputs(test) /* passed */ {
+        /* Sets local__ of each to a copy of the original, 
+           so any mutated args aren't collapsed forward. */
+
+        test.localInitors = TestStages.#copier.copy(test.with);
+        test.localInputs = TestStages.#copier.copy(test.in);
+    }
+    
+    anyPreTargetingGroundwork(test) {
+        // Spoofing of class members here.
+        // Setting any static properties here.
+    }
+    
+    setLocalTarget(test) /* passed */ {
+        /* Target may be instance, prototype for constructors, 
+           the class itself for statics, or a nonce for either 
+           static or instance properties. */
+
+        if (test.isConstructorTest) {
+            test.localTarget = test.on.prototype;
+            return;
+        }
+
+        let callable = TestTuple.plainNameOf(test.of);
+        
+        let target = test.isInstanceTest 
+            ? this.#supplyInstanceLocalTarget(test, callable) 
+            : this.#supplyStaticLocalTarget(test, callable);
+
+        test.localTarget = target;
+    }
+    
+    // region Dependencies of setLocalTarget()
+    
+    #supplyStaticLocalTarget(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]; } };
+
+        return target;
+    }
+
+    #supplyInstanceLocalTarget(test, callable) /* verified */ {
+        let instance = new test.on.prototype.constructor(...test.localInitors);
+        
+        // Methods are called on instance directly.  
+        // Properties are called on instance in nonce.
+        let target = test.isMethodTest  
+            ? instance 
+            : { localCallable: () => { return instance[callable]; } };
+            
+        return target; 
+    }
+    
+    // endregion Dependencies of setLocalTarget()
+
+    setLocalCallable(test) /* passed */ {
+        /* Method under test is a method named in test, 
+           or a nonce method for a property test. */
+        
+        test.localCallable = test.isMethodTest 
+            ? TestTuple.plainNameOf(test.method) 
+            : TestTuple.nonceLocalCallableName;
+    }
+    
+    anyPostTargetingGroundwork(test) {
+        // Setting instance properties.
+    }
+    
+    anyModifyActual(test) /* passed */ {
+        /* Original test.actual is used if a normal test, but replaced with .thrown 
+           if a throw test, or result of supplier method if a retrieval test. */
+
+        if (test.isThrowTest) {
+            // May be undefined, if no throw.
+            test.actual = test.thrown;
+        }
+
+        if (test.isRetrievalTest) {
+            test.actual = this.supplyNonReturnActual(test);
+        }
+    }
+    
+    compareResults(expected, actual) /* passed */ {
+        return TestStages.#comparer.compare(expected, actual);
+    }
+    
+    anyGroundworkReversion(test) {
+        // Unspoofing.
+        // Unsetting static properties.
+        // Undoing any other groundwork changes made.
+    }
+
+
+    // region Dependencies of test stages
+
+    #anyOriginalPropertyGetting(target, settables) {
+        if (!Array.isArray(settables)) {
+            return;
+        }
+    
+        let unsettables = [ ];
+        
+        for (let settable of settables) {
+            // Not a setter tuple.
+            if (!settable.of) {
+                continue;
+            }
+            
+            // Retaining original.
+            let original = target[settable.of];
+            let unsettable = { of: settable.of, as: original };
+            unsettables.push(unsettable);
+        }
+        
+        return unsettables;
+    }
+
+    #anyPropertySetting(target, settables) {
+        // No properties to set.
+        if (!Array.isArray(settables)) {
+            return;
+        }
+    
+        for (let settable of settables) {
+            // Not a setter tuple.
+            if (!settable.of) {
+                continue;
+            }
+
+            // Actually setting property.
+            target[settable.of] = settable.as;
+        }
+    }
+    
+    #anyPropertyUnsetting(target, unsettables) {
+        // Unsetting is the same as setting, 
+        // but with tuples of original values.
+        return this.#anyPropertySetting(target, unsettables);
+    }
+
+    #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.
+        if (typeof test.from === "string") {
+            /* &cruft, maybe explain how this differs from setting .localTarget, 
+                       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];
+        }
+        
+        /* &cruft, possibly change all .from syntax to (actual, test), 
+                   or maybe to (test), or else switch back args here */
+        // 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.localTarget);
+        }
+
+        /* &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;
+    }
+    
+    // endregion Dependencies of test stages
+
+
+    /* &cruft, remove or use this code... */
+
+    // anyOriginalPropertyGetting(target, settables) {
+    //     if (!Array.isArray(settables)) {
+    //         return;
+    //     }
+    //
+    //     let unsettables = [ ];
+    //    
+    //     for (let settable of settables) {
+    //         // Not a setter tuple.
+    //         if (!settable.of) {
+    //             continue;
+    //         }
+    //        
+    //         // Retaining original.
+    //         let original = target[settable.of];
+    //         let unsettable = { of: settable.of, as: original };
+    //         unsettables.push(unsettable);
+    //     }
+    //    
+    //     return unsettables;
+    // }
+    //
+    // anyPropertySetting(target, settables) {
+    //     // No properties to set.
+    //     if (!Array.isArray(settables)) {
+    //         return;
+    //     }
+    //
+    //     for (let settable of settables) {
+    //         // Not a setter tuple.
+    //         if (!settable.of) {
+    //             continue;
+    //         }
+    //
+    //         // Actually setting property.
+    //         target[settable.of] = settable.as;
+    //     }
+    // }
+    //
+    // anyPropertyUnsetting(target, unsettables) {
+    //     // Unsetting is the same as setting, 
+    //     // but with tuples of original values.
+    //     return this.anyPropertySetting(target, unsettables);
+    // }
+    //
+    // supplyNonReturnActual(test, target) {
+    //     // When there is a .from that's a string, 
+    //     // the actual is the named target member.
+    //     if (typeof test.from === "string") {
+    //         // Common member host; 
+    //         // undefined if static.
+    //         let host = target;
+    //        
+    //         // When .and defines static.
+    //         if (test.isStaticTest) {
+    //             host = test.on;
+    //         }
+    //    
+    //         return host[test.from];
+    //     }
+    //    
+    //     // 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(target, test);
+    //     }
+    //
+    //     // When there is any other .from, the actual is the
+    //     // value of the code element provided as .from.
+    //     return test.from;
+    // }
+    
+}