risei 1.0.0

package/public/javascript/TestRunner.js

@@ -0,0 +1,476 @@
+/**/
+
+/* 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 { SpoofClassMethodsFixture } from "./SpoofClassMethodsFixture.js";
+import { SpoofObjectMethodsFixture } from "./SpoofObjectMethodsFixture.js";
+import { SpoofTuple } from "./SpoofTuple.js";
+
+import { AComparer } from "./AComparer.js";
+import { TotalComparer } from "./TotalComparer.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;
+    
+    #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 comparer() {
+        return this.#comparer;
+    }
+    
+    set comparer(value) {
+        this.#comparer = value;
+    }
+
+    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.#numberRun = 0;
+        this.#numberPassed = 0;
+        this.#numberFailed = 0;
+
+        this.#allDidPass = true;
+
+        // Comparer is inited once for all tests, since compare() is reentrant.
+        this.#comparer = new TotalComparer();
+    }
+
+    // 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.#spoofObjects(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();
+
+        // Choosing the right test frame for the definition.
+        let testFrame = this.#supplyTestFrame(test);
+        testFrame = testFrame.bind(this);
+
+        // Actually running the test.
+        try {
+            testFrame(test);
+        }
+        catch (thrown) {
+            test.anyThrow = thrown;
+        }
+        
+        // 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.
+    #spoofObjects(test) {
+        this.#instanceSpoofer.spoof(test);
+    }
+    
+    #supplyTestFrame(test) {
+        // If `.and` includes "static", a call of a static member 
+        // is made, and the actual is its return value.
+        if (typeof test.and === "string") {
+            if (this.#doesAddressStatics(test)) {
+                // If .from, a static call is made, then the actual is 
+                // retrieved from a named code element or custom code.
+                if (test.from !== undefined) {
+                    return this.testCodeElementAfterStaticCall;
+                }
+            
+                // Otherwise, the return value 
+                // of the static call is used.
+                return this.testReturnValueOfStaticCall;
+            }
+        }
+    
+        // Constructors are a special case; no second call should 
+        // be made, and actual must be retrieved from property.
+        if (test.of === TestRunner.#constructorName) {
+            return this.testCodeElementAfterConstruction;
+        }
+
+        // If .from, a call of the target is made, then the actual 
+        // is retrieved from a named code element or custom code.
+        if (this.#isRetrievalTest(test.from)) {
+            return this.testCodeElementAfterCall;
+        }
+
+        // The most common case: the target is called, 
+        // and the actual is its return value.
+        return this.testReturnValueOfCall;
+    }
+    
+    #isRetrievalTest(testFrom) {
+        // Falsy code elements never are a retrieval.
+        if (!testFrom) {
+            return false;
+        }
+        
+        // If a (non-falsy) string, must be a retrieval.
+        if (typeof testFrom === "string") {
+            return true;
+        }
+        
+        // If a function, is a retrieval.
+        if (testFrom instanceof Function) {
+            return true;
+        }
+        
+        // Anything else is not a retrieval.
+        return false;
+    }
+    
+    #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
+
+    // region Test frames
+
+    // The most basic test: whether a call of 
+    // a method returns the expected value.
+    testReturnValueOfCall(test) {
+        /* Groundwork. */
+        this.#anyMethodSpoofing(test);
+
+        let prototype = test.on.prototype;
+        let target = new prototype.constructor(...test.with);  // Must use `...`.
+
+        /* Exercising the code. */
+        test.actual = target[test.of](...test.in);  // Must use `...`.
+
+        /* Restoring. */
+        this.#anyMethodRestoring(test);
+
+        /* Comparing. */
+        test.didPass = this.#compare(test.out, test.actual);
+    }
+
+    testReturnValueOfStaticCall(test) {
+        /* Groundwork. */
+        this.#anyMethodSpoofing(test);
+        
+        /* No instance is constructed. */
+        
+        /* Exercising the code. */
+        test.actual = test.on[test.of](...test.in);  // Must use `...`.
+        
+        /* Restoring. */
+        this.#anyMethodRestoring(test);
+        
+        /* Comparing. */
+        test.didPass = this.#compare(test.out, test.actual);
+    }
+
+    // The second-most basic test: whether a property 
+    // has the expected value after a method call.
+    testCodeElementAfterCall(test) {
+        /* Groundwork. */
+        this.#anyMethodSpoofing(test);
+
+        let prototype = test.on.prototype;
+        let target = new prototype.constructor(...test.with);  // Must use `...`.
+
+        /* Exercising the code. */
+        target[test.of](...test.in);  // Must use `...`.
+
+        /* Retrieving. */
+        // The `actual` is a property or other code element somewhere.
+        test.actual = this.#supplyNonReturnActual(test, target);
+
+        /* Restoring. */
+        this.#anyMethodRestoring(test);
+
+        /* Comparing. */
+        test.didPass = this.#compare(test.out, test.actual);
+    }
+    
+    testCodeElementAfterStaticCall(test) {
+        /* Groundwork. */
+        this.#anyMethodSpoofing(test);
+        
+        /* No instance is constructed. */
+        
+        /* Exercising the code. */
+        test.on[test.of](...test.in);  // Must use `...`.
+        
+        /* Retrieving. */
+        test.actual = this.#supplyNonReturnActual(test);  // No `target` here.
+        
+        /* Restoring. */
+        this.#anyMethodRestoring(test);
+        
+        /* Comparing. */
+        test.didPass = this.#compare(test.out, test.actual);
+    }
+
+    // The third-most basic test: whether a property has 
+    // the expected value after an object is constructed.
+    testCodeElementAfterConstruction(test) {
+        /* Groundwork. */
+        this.#anyMethodSpoofing(test);
+
+        /* Exercising the code. */
+        // For definition consistency, initing with test.in, not test.with.
+        let prototype = test.on.prototype;
+        let target = new prototype.constructor(...test.in);  // Must use `...`.
+
+        /* Retrieving. */
+        // The `actual` is a property or other code element somewhere.
+        test.actual = this.#supplyNonReturnActual(test, target);
+
+        /* Restoring. */
+        this.#anyMethodRestoring(test);
+
+        /* Comparing. */
+        test.didPass = this.#compare(test.out, test.actual);
+    }
+
+    // endregion Test frames
+
+    // region Dependencies of test frames
+
+    #anyMethodSpoofing(test) {
+        if (test.plus === undefined) {
+            return;
+        }
+
+        this.#classSpoofer.spoof(test);
+    }
+
+    #compare(expected, actual) {
+        return this.#comparer.compare(expected, actual);
+    }
+
+    #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 (this.#doesAddressStatics(test)) {
+                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;
+    }
+
+    #anyMethodRestoring(test) {
+        this.#classSpoofer.unspoof();
+        this.#classSpoofer.removeDefinitions();
+    }
+
+    // endregion Dependencies of test frames
+
+    // region Cross-region dependencies
+
+    #doesAddressStatics(test) {
+        if (typeof test.and === "string") {
+            if (test.and.includes("static")) {  /* &cruft, abstract */
+                return true;
+            }
+        }
+    
+        return false;
+    }
+
+    // endregion Cross-region dependencies
+
+}

package/public/javascript/TestSummary.js

@@ -0,0 +1,37 @@
+/**/
+
+export class TestSummary {
+    #summary;
+    #allDidPass;
+    #anyWereRun;
+    
+    get summary() {
+        return this.#summary;
+    }
+    
+    set summary(value) {
+        this.#summary = value;
+    }
+    
+    get allDidPass() {
+        return this.#allDidPass;
+    }
+    
+    set allDidPass(value) {
+        this.#allDidPass = value;
+    }
+    
+    get anyWereRun() {
+        return this.#anyWereRun;
+    }
+    
+    set anyWereRun(value) {
+        this.#anyWereRun = value;
+    }
+    
+    constructor(summary, allDidPass, anyWereRun) {
+        this.summary = summary;
+        this.allDidPass = allDidPass;
+        this.anyWereRun = anyWereRun;
+    }
+}