risei 1.0.0

package/public/javascript/TestFinder.js

@@ -0,0 +1,140 @@
+/**/
+
+/* TestFinder is an ATestFinder that finds tests in the places identified in package.json. */
+
+import { ATestFinder } from "./ATestFinder.js";
+import { ATestSource } from "./ATestSource.js";
+import fs from "node:fs";
+import path from "node:path";
+import { minimatch } from "minimatch";
+
+export class TestFinder extends ATestFinder {
+    // region Definitions
+
+    static NO_SUCH_FILE = "ENOENT";
+    static METADATA_FILE = "package.json";
+    
+    // These are never test locations.  Others like `bin` 
+    // probably aren't, either, but it's not 100% certain.
+    static ALWAYS_SKIPPED = [ ".git", "node_modules" ];
+
+    // endregion Definitions
+
+    // region Fields
+    
+    #sought;
+    
+    // endregion Fields
+
+    constructor() {
+        super();
+    }
+
+    async findAllTests() {
+        // Paths for test sources are listed in package.json, possibly with globbing.
+        let source = this.sourceBySearch();
+        this.#sought = source.tests;
+        let testPaths = this.pathsFromTargetingSource();
+        
+        let tests = [];
+
+        for (let testPath of testPaths) {
+            // Contents of test sources have to be loaded.
+            let sources = await this.convertPathToClassInstances(testPath);
+            
+            // Any test classes in each source have to be loaded.
+            for (let source of sources) {
+                let local = source.tests;
+                tests.push(...local);
+            }
+        }
+
+        return tests;
+    }
+
+    sourceBySearch() {
+        // App's package.json always found at process.cwd().
+        let packageSite = process.cwd();
+        let pathAndName = path.join(packageSite, TestFinder.METADATA_FILE);
+
+        // Contents of package.json are just a single JSON object.
+        let packageJson = fs.readFileSync(pathAndName, { encoding: "utf8" });
+        packageJson = JSON.parse(packageJson);
+
+        // Can't run or reasonably recover if this is not defined.
+        if (!packageJson.risei) {
+            throw new Error(
+                `For Risei tests to run, this app's package.json must contain `
+                + `a node like this: "risei": { tests: "path-or-glob-here" }.  `
+                + `One glob or path may be used, or an array of them.`);
+        }
+
+        // Only Risei's own metadata is needed.
+        return packageJson.risei;
+    }
+
+    pathsFromTargetingSource() {
+        let paths = [];
+        let root = process.cwd();        
+        
+        // Recursively add all test 
+        // files in tree to `paths`.
+        this.searchTree(root, paths);
+
+        return paths;
+    }
+    
+    searchTree(root, paths) {
+        let entries = fs.readdirSync(root, { withFileTypes: true });
+        
+        for (let entry of entries) {
+            // Working around a recent bug in fs of .path always undefined or wrong.
+            entry.path = path.join(root, entry.name);
+        
+            // These should never contain tests, and may not even be folders.
+            if (TestFinder.ALWAYS_SKIPPED.includes(entry.name)) {
+                continue;
+            }
+
+            // This level: any test files.
+            if (entry.isFile()) {
+                if (minimatch(entry.path, this.#sought, { matchBase: true })) {
+                    paths.push(entry.path);
+                }
+            }
+            
+            // Next level: recursion.
+            if (entry.isDirectory()) {
+                this.searchTree(entry.path, paths);
+            }
+        }
+    }
+
+    async convertPathToClassInstances(classPath) {
+        // Each test source may have multiple test classes.
+        let testSources = [];
+        
+        // Loading modules should load their dependencies.
+        try {
+            let module = await import(classPath);
+            
+            // A module may have many contents.
+            for (let moduleKey in module) {
+                let definition = module[moduleKey];
+                let local = new definition.prototype.constructor();
+                
+                // Non-test contents may exist in each test source.
+                if (local instanceof ATestSource) {
+                    testSources.push(local);
+                }
+            }
+
+            return testSources;
+        }
+        catch (e) {
+            let fileName = path.basename(classPath);
+            console.log(`Test loading failed for ${ fileName }.    ${ e }`);
+            return [];
+        }
+    }
+}

package/public/javascript/TestGroup.js

@@ -0,0 +1,25 @@
+/**/
+
+export class TestGroup {
+    // region Private fields
+
+    #group;
+
+    // endregion Private fields
+
+    // region Properties
+
+    get group() {
+        return this.#group;
+    }
+
+    set group(value) {
+        this.#group = value;
+    }
+
+    // endregion Properties
+
+    constructor(group) {
+        this.#group = group;
+    }
+}

package/public/javascript/TestResult.js

@@ -0,0 +1,338 @@
+/**/
+
+export class TestResult {
+    // region Fields
+    
+    #test;
+
+    #identityText;
+    #initorsText;
+    #inputsText;
+    #expectedText;
+    #actualText;
+
+    #didPass;
+    #actual;
+    #thrown;
+
+    // endregion Fields
+
+    // region Source properties
+
+    get test() {
+        return this.#test;
+    }
+    
+    set test(value) {
+        this.#test = value;
+    }
+
+    // endregion Source properties
+    
+    // region Nature properties
+
+    get identityText() {
+        return this.#identityText;
+    }
+    
+    set identityText(value) {
+        this.#identityText = value;
+    }
+    
+    get initorsText() {
+        return this.#initorsText;
+    }
+    
+    set initorsText(value) {
+        this.#initorsText = value;
+    }
+
+    get inputsText() {
+        return this.#inputsText;
+    }
+    
+    set inputsText(value) {
+        this.#inputsText = value;
+    }
+
+    get expectedText() {
+        return this.#expectedText;
+    }
+    
+    set expectedText(value) {
+        this.#expectedText = value;
+    }
+
+    // endregion Nature properties
+
+    // region Outcome properties
+
+    get actualText() {
+        return this.#actualText;
+    }
+    
+    set actualText(value) {
+        this.#actualText = value;
+    }
+
+    get didPass() {
+        return this.#didPass;
+    }
+
+    set didPass(value) {
+        this.#didPass = value;
+    }
+
+    get anyThrow() {
+        return this.#thrown;
+    }
+
+    set anyThrow(value) {
+        this.#thrown = value;
+    }
+
+    // endregion Outcome properties
+
+    // region Construction
+
+    constructor(test) {
+        this.#test = test;
+    }
+    
+    // endregion Construction
+
+    // region Before run: setNature() and dependencies
+
+    setNature() {
+        this.#identityText = this.#calculateIdentityText();
+        this.#initorsText = this.#calculateInitorsText();
+        this.#inputsText = this.#calculateInputsText();
+        this.#expectedText = this.#calculateExpectedText();
+    }
+    
+    #calculateIdentityText() {
+        let text = `${ this.test.for } `;
+        return text;
+    }
+    
+    #calculateInitorsText() {
+        let text = this.#improveValueRowDisplay(this.test.with);
+        text = `Initors: ${ text }. `;
+        return text;
+    }
+    
+    #calculateInputsText() {
+        let text = this.#improveValueRowDisplay(this.test.in);
+        text = `Inputs: ${ text }. `;
+        return text;
+    }
+    
+    #calculateExpectedText() {
+        let text = this.#improveValueDisplay(this.test.out);
+        text = `Expected: ${ text }. `;
+        return text;
+    }
+    
+    // endregion Before run: setNature() and dependencies
+    
+    // region After run: setResults() and dependencies
+
+    setResults() {
+        // Direct results.
+        this.#didPass = this.test.didPass;
+        this.#actual = this.test.actual;
+        this.#thrown = this.test.anyThrow;
+        
+        // Derived displayable results.
+        this.#actualText = this.#calculateActualText();
+    }
+
+    #calculateActualText() {
+        let text = this.#improveValueDisplay(this.test.actual);
+        text = `Actual: ${ text }. `;
+        return text;
+    }
+    
+    // endregion After run: setResults() and dependencies
+
+    // region Improving displaying
+
+    #improveValueRowDisplay(row) {
+        let items = row
+            .map(x => this.#improveValueDisplay(x));
+            
+        if (items.length === 0) {
+            return [ "\u2014" ];
+        }
+        
+        return items.join(`, `);
+    }
+    
+    #improveValueDisplay(value) {
+        let output = this.#addQuotesIfString(value);
+        output = this.#addArrayStyleIfArray(output);
+        output = this.#jsonifyIfMap(output);
+        output = this.#jsonifyIfSet(output);
+        output = this.#jsonifyIfClass(output);
+        output = this.#jsonifyIfFunction(output);
+        output = this.#jsonifyIfObject(output);
+        output = this.#stateUndefinedIfUndefined(output);
+        output = this.#stateNullIfNull(output);
+
+        return output;
+    }
+    
+    // endregion Improving displaying
+
+    // region Individual display improvements
+
+    #addQuotesIfString(value) {
+        let output = typeof value !== "string" ? value : `"${ value }"`;
+        return output;
+    }
+
+    #addArrayStyleIfArray(value) {
+        // Not-an-array path.
+        if (!Array.isArray(value)) {
+            return value;
+        }
+
+        // Each array value may be styled.
+        let outputs = value
+            .map(x => this.#improveValueDisplay(x));
+
+        // Brackets around, commas between.
+        let output = `[${ outputs.join(",") }]`;
+
+        // And back to caller.
+        return output;
+    }
+
+    #jsonifyIfMap(value) {
+        // Not-a-map path.
+        if (!(value instanceof Map)) {
+            return value;
+        }
+
+        let items = [];
+
+        // Each key-value pair is handled individually.
+        for (let key of value.keys()) {
+            // Keys are not styled.
+            let item = value.get(key);
+
+            // Cross-recursion for styling values.
+            items.push(`${ key }:${ this.#improveValueDisplay(item) }`);
+        }
+
+        // Key-value pairs are all listed together.
+        let output = `Map{${ items.join(",") }}`;
+        return output;
+    }
+    
+    #jsonifyIfSet(value) {
+        // Not-a-set path.
+        if (!(value instanceof Set)) {
+            return value;
+        }
+        
+        let items = [];
+        
+        // Each item is handled individually.
+        for (let item of value) {
+            // Cross-recursion for styling values.
+            let display = `${ this.#improveValueDisplay(item) }`;
+            items.push(display);
+        }
+
+        // Items are all listed together.
+        let output = `Set{${ items.join(",") }}`;
+        return output;
+    }
+
+    #jsonifyIfClass(value) {
+        let isAFunction = value instanceof Function;
+        
+        // If not a Function, also not a class.
+        if (!isAFunction) {
+            return value;
+        }
+
+        // Definition of a class always starts with `class` and space.
+        let definition = value.toString();
+        let isAClass = definition.startsWith(`class` + ` `);
+        
+        // Not-a-class path.
+        if (!isAClass) {
+            return value;
+        }
+
+        // Class definitions have a .name.
+        let output = value.name;
+        return output;
+    }
+
+    #jsonifyIfFunction(value) {
+        // Not-a-function path.
+        if (!(value instanceof Function)) {
+            return value;
+        }
+        
+        // toString() lists the definition, including code.
+        let output = value.toString();
+        
+        // Most whitespace is eliminated for readability.
+        output = output.replace(/(\r\n?)/g, "");
+        output = output.replace(/\s{2,}/g, " ");
+        
+        // Back to caller.
+        return output;
+    }
+    
+    #jsonifyIfObject(value) {
+        // Not-an-object path.
+        if (!(value instanceof Object)) {
+            return value;
+        }
+
+        /* Use any meaningful toString() text for the object. */
+        let asString = value.toString();
+        
+        if (asString !== "[object Object]") {
+            return asString;
+        }
+
+        /* If no meaningful toString() value, 
+           use a list of all public members. */
+        let items = [];
+
+        // Each property of the object is handled individually.
+        for (let p in value) {
+            if (value[p] instanceof Function) {
+                items.push(`${ p }:${ value[p].toString() }`);
+                continue;
+            }
+
+            // Cross-recursion for nested items.
+            let item = this.#improveValueDisplay(value[p]);
+            items.push(`${ p }:${ item }`);
+        }
+
+        // Properties are all listed together.
+        let output = `{ ${ items.join(", ") } }`;
+        return output;
+    }
+    
+    #stateUndefinedIfUndefined(value) {
+        let output = value !== undefined ? value : "undefined";
+        return output;
+    }
+
+    #stateNullIfNull(value) {
+        let output = value !== null ? value : "null";
+        return output;
+    }
+
+    // endregion Individual display improvements
+
+}