risei 1.0.0

package/index.js

@@ -0,0 +1,122 @@
+/**/
+
+/* Copyright (c) 2023 Ed Fallin.  Published under the terms of the MIT license. */
+
+/* This index.js is the entry point for running Risei tests from 
+   other code.  It imports other modules to perform its work.
+   It also exports modules that should / can be subclassed. */
+
+// region Imports
+
+// region Test-running dependencies
+
+import { TestRunner } from "./public/javascript/TestRunner.js";
+import { LocalCaller } from "./public/javascript/LocalCaller.js";
+import { TerminalReporter } from "./public/javascript/TerminalReporter.js";
+import { TestFinder } from "./public/javascript/TestFinder.js";
+
+// endregion Test-running dependencies
+
+// region Display dependencies
+
+import chalk from "chalk";
+import { Moment } from "./public/javascript/Moment.js";
+
+// endregion Display dependencies
+
+// endregion Imports
+
+// region Exports
+
+// region Classes that users typically subclass
+
+export * from "./public/javascript/ATestSource.js";
+
+// endregion Classes that users typically subclass
+
+// region Classes that users might subclass for uncommon cases
+
+export * from "./public/javascript/ATestFinder.js";
+export * from "./public/javascript/ATestReporter.js";
+
+// endregion Classes that users might subclass for uncommon cases
+
+// endregion Exports
+
+// region Named styles
+
+/* Display styles for the start title and other general needs. */
+const title = chalk.hex("FFFFFF").bgHex("191970").bold;
+
+// endregion Named styles
+
+// region Styling for color stripes
+
+let wide = (text) => { 
+    let width = process.stdout.columns;
+    text = text || "";
+
+    return text.padEnd(width, "\u00A0");
+};
+
+// endregion Styling for color stripes
+
+// region Key callable, its scriptable call, and its export
+
+async function runRiseiTests(testFinderPath) {
+    // region Converting test-finder from path to class
+    
+    testFinderPath = testFinderPath || "./public/javascript/TestFinder.js";
+    let finderModule = await import(testFinderPath);
+    
+    let moduleKeys = Object.keys(finderModule);
+    let classKey = moduleKeys[0];
+    let finderClass = finderModule[classKey];
+    
+    // endregion Converting test-finder from path to class
+
+    // region Intro / title
+    
+    console.clear();
+    console.log();
+    console.log(title(wide()));
+    
+    let now = new Date();
+    now = new Moment(now);
+    
+    console.log(title(wide(` Risei tests run on ${ now.asReadable() } local time.`)));
+    console.log(title(wide()));
+    
+    console.log();
+    
+    // endregion Intro / title
+    
+    // region Running tests
+    
+    // Test-system objects and their relationships.
+    const finder = new finderClass.prototype.constructor();
+    const runner = new TestRunner();
+    const reporter = new TerminalReporter();
+    
+    const caller = new LocalCaller(finder, runner, reporter);
+
+    // Actually running the tests using this system.
+    await caller.runAllTests();
+    
+    // endregion Running tests
+    
+    // region Trailing formatting
+    
+    console.log();
+    console.log();
+    
+    // endregion Trailing formatting
+}
+
+/* Runs tests now. */
+await runRiseiTests();
+
+export default runRiseiTests;
+
+// endregion Key callable, its scriptable call, and its export
+

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "risei",
+  "version": "1.0.0",
+  "description": "RiseiJs is the framework that allows you to write unit tests as collections of values in JavaScript objects, so it's easy and fast, and tests don't serve as a drag on redesigns.",
+  "keywords":[ "unit test", "test", "values", "objects", "easy", "fast" ],
+  "author": "Ed Fallin <riseijsmaker@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "private": false,
+  "scripts": {
+    "start": "node ./bin/www",
+    "risei": "node ./index.js",
+    "rtest": "clear; node ./public/javascript/Risei.js",
+    "xtest": "clear; mocha **/*.tests.js",
+    "test": "clear; mocha **/*.tests.js; node ./public/javascript/Risei.js"
+  },
+  "risei": {
+    "tests": "**.rt.js"
+  },
+  "exports":{
+    ".": "./index.js",
+    "./ATestSource": "./public/javascript/ATestSource.js"
+  },
+  "dependencies": {
+    "chalk": "^5.0.0",
+    "fs": "^0.0.1-security",
+    "minimatch": "^9.0.1"
+  },
+  "devDependencies": {
+    "chai": "^4.3.6",
+    "chalk": "^5.0.0",
+    "cookie-parser": "~1.4.4",
+    "debug": "~2.6.9",
+    "express": "~4.16.1",
+    "fs": "^0.0.1-security",
+    "mocha": "^10.0.0",
+    "morgan": "~1.9.1"
+  }
+}

package/public/javascript/AComparer.js

@@ -0,0 +1,9 @@
+/**/
+
+/* Defines operations that a comparer must implement. */
+
+export class AComparer {
+    compare(expected, actual) {
+        throw new Error("Implement compare() on a subclass of AComparer.");
+    }
+}

package/public/javascript/ASpoofingFixture.js

@@ -0,0 +1,84 @@
+/**/
+
+import { ATestFixture } from "./ATestFixture.js";
+import { SpoofTuple } from "./SpoofTuple.js";
+
+export class ASpoofingFixture extends ATestFixture {
+    constructor(name, kind) {
+        super(name, kind);
+    }
+    
+    /* A spoof might be supplied as a custom function, 
+       but it might just be defined by a return value. */
+    spoofMethod(spoofOutput) {
+        // No spoof supplied, so spoof is an empty function.
+        if (spoofOutput === undefined) {
+            let empty = () => { };
+            return empty;
+        }
+        
+        // Spoof is a custom function to use as-is.
+        if (spoofOutput instanceof Function) {
+            return spoofOutput;
+        }
+        
+        // Recursive case: Spoof defines a whole object 
+        // tree to be returned as method output.
+        if (Array.isArray(spoofOutput)) {
+            if (spoofOutput.every(x => SpoofTuple.isASpoof(x))) {
+                spoofOutput = SpoofTuple.fromNonceTuples(spoofOutput);
+                spoofOutput = this.spoofObjectTree(spoofOutput);
+            }
+        }
+        
+        // Commonest case: Spoof is a value to be returned.
+        let spoof = () => { return spoofOutput; }
+        return spoof;
+    }
+
+    /* Returns an object with all spoofed methods, 
+       possibly with intermediate objects. */
+    spoofObjectTree(ofAsPairs) {
+        let spoof = {};
+    
+        for (let pair of ofAsPairs) {
+            let chain = pair.of;
+            let output = pair.as;
+
+            // Individual member names are needed.
+            let names = chain.split(".");
+
+            // Top object and traverser from it.
+            let top = spoof;
+            let next = top;
+            let name;
+
+            // New objects as members leafward.
+            while (names.length > 1) {
+                // Object member's name.
+                name = names.shift();
+
+                // Actually spoofing object.
+                if (!next[name]) {
+                    next[name] = {};
+                }
+
+                // Stepping leafward.
+                next = next[name];
+            }
+
+            // Final or only name is the leaf method; 
+            // name may mistakenly end with `()`.
+            name = names.shift();
+            name = name.replace("()", "");
+
+            // Actually spoofing method.
+            let method = this.spoofMethod(output);
+            next[name] = method;
+        }
+        
+        // And back to caller.
+        return spoof;
+    }
+
+}

package/public/javascript/ATestCaller.js

@@ -0,0 +1,61 @@
+/**/
+
+/*  Defines operations that a test caller (which requests 
+    the running / reporting of tests) must implement.  
+    Uses the ATestRunner to run all the tests via a generator, 
+    and the ATestReporter for out / formatting if needed.
+    A = abstract. */
+
+import { TestRunner } from "./TestRunner.js";
+import { ATestReporter } from "./ATestReporter.js";
+
+export class ATestCaller {
+    // region Private fields
+
+    #finder;
+    #runner;
+    #reporter;
+
+    // endregion Private fields
+
+    // region Properties
+
+    get finder() {
+        return this.#finder;
+    }
+    
+    set finder(value) {
+        this.#finder = value;
+    }
+
+    get runner() {
+        return this.#runner;
+    }
+
+    set runner(value) {
+        this.#runner = value;
+    }
+
+    get reporter() {
+        return this.#reporter;
+    }
+
+    set reporter(value) {
+        this.#reporter = value;
+    }
+
+    // endregion Properties
+
+    constructor(finder, runner, reporter) {
+        this.#finder = finder;
+        this.#runner = runner;
+        this.#reporter = reporter;
+    }
+
+    async runAllTests() {
+        throw new Error(
+            "Implement runAllTests() on a subclass, " +
+            "using .reporter for out / formatting if needed."
+        );
+    }
+}

package/public/javascript/ATestFinder.js

@@ -0,0 +1,25 @@
+/**/
+
+/* Defines operations that test-finding classes should implement.  A = abstract. */
+
+import { ATestSource } from "./ATestSource.js";
+
+export class ATestFinder {
+    #testSources;
+
+    get testSources() {
+        return this.#testSources;
+    }
+
+    set testSources(value) {
+        this.#testSources = value;
+    }
+
+    constructor() {
+        this.#testSources = [];
+    }
+
+    async findAllTests() {
+        throw new Error("Implement findAllTests() on a subclass of ATestFinder.");
+    }
+}

package/public/javascript/ATestFixture.js

@@ -0,0 +1,44 @@
+/**/
+
+export class ATestFixture {
+    // region Private fields
+
+    #name;
+    #kind;
+    #fixture;
+    
+    // endregion Private fields
+
+    // region Properties
+
+    get name() {
+        return this.#name;
+    }
+
+    set name(value) {
+        this.#name = value;
+    }
+
+    get kind() {
+        return this.#kind;
+    }
+
+    set kind(value) {
+        this.#kind = value;
+    }
+
+    get fixture() {
+        return this.#fixture;
+    }
+
+    set fixture(value) {
+        this.#fixture = value;
+    }
+
+    // endregion Properties
+
+    constructor(name, kind) {
+        this.#name = name;
+        this.#kind = kind;
+    }
+}

package/public/javascript/ATestReporter.js

@@ -0,0 +1,25 @@
+/**/
+
+/* Defines operations that a test reporter must implement.  A = abstract. */
+
+import chalk from "chalk";
+
+export class ATestReporter {
+    // Reports whatever was just provided by the TestRunner.
+    // Can delegate to the other report-x methods.
+    reportNext(result) {
+    }
+
+    reportGroup() {
+    }
+
+    reportPassed(result) {
+    }
+
+    reportFailed(result) {
+    }
+
+    reportSummary(summary) {
+    }
+
+}

package/public/javascript/ATestSource.js

@@ -0,0 +1,8 @@
+/**/
+
+/* Defines operations that a source of tests must (trivially) implement, basically listing tests and fixtures. */
+
+export class ATestSource {
+    /* Must be implemented by subclasses. */
+    tests = [];
+}

package/public/javascript/ChosenTestFinder.js

@@ -0,0 +1,30 @@
+/**/
+
+/* ChosenTestFinder is an ATestFinder that finds tests in the places coded in its constructor. */
+
+import { ATestFinder } from "./ATestFinder.js";
+import { Tests } from "./topic-tests/Tests.rt.js";
+import { SelfTests } from "./self-tests/SelfTests.rt.js";
+
+export class ChosenTestFinder extends ATestFinder {
+    constructor() {
+        super();
+        
+        let testSource = new Tests();
+        let selfTestSource = new SelfTests();
+        this.testSources = [ testSource, selfTestSource ];
+    }
+
+    async findAllTests() {
+        let tests = [];
+        
+        for (let source of this.testSources) {
+            let local = source.tests;
+            tests.push(...local);
+        }
+        
+        // Returning an awaitable value 
+        // to match async signature.
+        return Promise.resolve(tests);
+    }
+}

package/public/javascript/ClassTestGroup.js

@@ -0,0 +1,8 @@
+/**/
+
+import { TestGroup } from "./TestGroup.js";
+
+/* Identifies a grouping of tests by class.  No specialized workings. */
+
+export class ClassTestGroup extends TestGroup {
+}

package/public/javascript/LocalCaller.js

@@ -0,0 +1,22 @@
+/**/
+
+/* LocalCaller is an ATestCaller that invokes each available test in turn locally 
+   on the server, without HTTP calls from a browser or other external source. */
+
+import { ATestFinder } from "./ATestFinder.js";
+import { ATestCaller } from "./ATestCaller.js";
+import { TerminalReporter } from "./TerminalReporter.js";
+import { TestRunner } from "./TestRunner.js";
+
+export class LocalCaller extends ATestCaller {
+    async runAllTests() {
+        let tests = await this.finder.findAllTests();
+        this.runner.useTests(tests); 
+
+        // Getting each run test / summary result 
+        // and having it reported in the terminal.
+        for (let result of this.runner) {
+            this.reporter.reportNext(result);
+        }
+    }
+}

package/public/javascript/MethodTestGroup.js

@@ -0,0 +1,8 @@
+/**/
+
+import { TestGroup } from "./TestGroup.js";
+
+/* Identifies a grouping of tests by method.  No specialized workings. */
+
+export class MethodTestGroup extends TestGroup {
+}

package/public/javascript/Moment.js

@@ -0,0 +1,29 @@
+/**/
+
+export class Moment {
+    #now;
+
+    constructor(now) {
+        this.#now = now;
+    }
+
+    asReadable() /* passed */ {
+        let now = this.#now;
+        let asTwo = this.#asTwo;
+    
+        let day = `${ now.getMonth() + 1 }/${ asTwo(now.getDate()) }/${ now.getFullYear() }`;
+
+        let time = `${ now.getHours() % 12 || 12 }:${ asTwo(now.getMinutes()) }:${ asTwo(now.getSeconds()) } `
+            + `${ now.getHours() < 12 ? "AM" : "PM" }`;
+
+        return `${ day } at ${ time }`;
+    }
+
+    #asTwo(number) /* verified */ {
+        let text = `${ number }`;
+        text = text.padStart(2, "0");
+
+        return text;
+    }
+
+}

package/public/javascript/Risei.js

@@ -0,0 +1,88 @@
+/**/
+
+/* Risei.js is the entry point for running Kitten / Koneko / Risei tests.  
+   It imports other modules to do all of its work. */
+
+// region Test-running dependencies
+
+import { TestRunner } from "./TestRunner.js";
+import { ChosenTestFinder } from "./ChosenTestFinder.js";
+import { LocalCaller } from "./LocalCaller.js";
+import { TerminalReporter } from "./TerminalReporter.js";
+
+// endregion Test-running dependencies
+
+// region Display dependencies
+
+import chalk from "chalk";
+import { Moment } from "./Moment.js";
+
+// endregion Display dependencies
+
+// region Named styles
+
+/* Display styles for the start title and other general needs. */
+const cal = chalk.hex("0000FF").bgHex("EEEE00").bold;
+const onBlue = chalk.bgBlueBright;
+const onGreen = chalk.bgGreenBright;
+
+const future = chalk.hex("FFFFFF").bgHex("191970").bold;
+
+/* Display styles for tests. */
+const group = chalk.hex("FFFFFF").bgHex("0000CD");
+const passed = chalk.hex("000000").bgHex("90EE90");
+const failed = chalk.hex("000000").bgHex("F08080");
+
+// endregion Named styles
+
+// region Styling for color stripes
+
+let wide = (text) => { 
+    let width = process.stdout.columns;
+    text = text || "";
+
+    return text.padEnd(width, "\u00A0");
+};
+
+// endregion Styling for color stripes
+
+// region Intro / title
+
+/* To clear the console first, you can include `clear;` in the script 
+   ahead of calling this, or else restore console.clear() here, 
+   although the Risei output may then overwrite some prior output. */
+
+console.log();
+console.log(future(wide()));
+
+let now = new Date();
+now = new Moment(now);
+
+console.log(future(wide(` Risei tests run on ${ now.asReadable() } local time.`)));
+console.log(future(wide()));
+
+console.log();
+
+// endregion Intro / title
+
+// region Running tests
+
+// Test-system objects and their relationships.
+const finder = new ChosenTestFinder();
+const runner = new TestRunner(finder.findAllTests());
+const reporter = new TerminalReporter();
+
+const caller = new LocalCaller(finder, runner, reporter);
+
+// Actually running the tests using this system.
+await caller.runAllTests();
+
+// endregion Running tests
+
+// region Trailing formatting
+
+console.log();
+console.log();
+
+// endregion Trailing formatting
+