testeranto 0.49.10 → 0.62.0

package/.nvmrc

@@ -0,0 +1 @@
+v18.18.0

package/README.md

@@ -1,5 +1,7 @@
 # testeranto
 
+🚧 WARNING: Testeeranto is still under development and is not ready for production yet. 🚧
+
 home: [adamwong246.github.io/testeranto](https://adamwong246.github.io/testeranto/)
 
 source: [github.com/adamwong246/testeranto](https://github.com/adamwong246/testeranto)
@@ -12,9 +14,10 @@ example repo: [kokomo bay](https://github.com/ChromaPDX/kokomoBay)
 
 ## tl;dr
 
-- Do you like BDD?
+- Do you like TDD/BDD?
 - Do you love Typescript?
 - Do you hate Jira?
+- Do you tolerate electron?
 
 If so, then testeranto might be the testing tool you have been looking for!
 
@@ -22,20 +25,38 @@ If so, then testeranto might be the testing tool you have been looking for!
 
 Testeranto.ts an Acceptance Test Driven Development ([ATDD](https://en.wikipedia.org/wiki/Acceptance_test-driven_development)) framework. It focuses on strongly-typed tests, specified in a gherkin-like syntax. Testeranto includes a framework to help write your tests, a test runner to schedule the tests and a reporter to display the results.
 
-## 2 distinguishing features of testeranto
-
-1. Rather than testing your code directly, Testeranto requires you wrap your code with a semantic interface which is based on TS type signatures. These interfaces can be shared and your code is now tested through the gherkin-ish directives provided by that interface.
+## Getting started
 
-2. Testeranto tracks features and test results directly in the source code. You may be accustomed to using tools like Jira and Trello to define user stories and assign story points- Under Testeranto, this data lives within the code base _as_ typescript code. Features are defined as nodes within a directed graph, allowing the reporter to summarize these features and their test results.
+1) Write some code.
+2) Write some tests of that code.
+3) Write some features of that code.
+1) Write a `testeranto.mts`, which acts as a config file. 
+3) Launch testeranto. The test runner is now rebuilding the docs folder.
+4) Commit the results of those tests.
+5) Your github pages now shows your report, showing your features, linked with your test results. 
+6) Optionally add testeranto to your CI.
 
 ## tech of note
 
+- esm - Testeranto uses modern js.
 - typescript - tests are functions with type parameters
+- electron - provides both a node and chrome runtime
+- puppeteer - provides node-style tests with a handle to the browser
 - esbuild - used to quickly generate test bundles
 - graphology - used to store features within a semantic network
 
+## 3 distinguishing features of testeranto
+
+1. Rather than testing your code directly, Testeranto requires you wrap your code with a semantic interface which is based on TS type signatures. These interfaces can be shared and your code is now tested through the gherkin-ish directives provided by that interface.
+
+2. Testeranto tracks features and test results directly in the source code. You may be accustomed to using tools like Jira and Trello to define user stories and assign story points- Under Testeranto, this data lives within the code base _as_ typescript code. Features are defined as nodes within a directed graph, allowing the reporter to summarize these features and their test results.
+
+3. Testeranto is designed for both the backend and the frontend. It leverages electron to provide both of these runtimes. Each of your tests can be executed in the backend node runtime, within the frontend chromium browser runtime, or both.
+
 ## the good parts
 
+Your tests can be run in node, chromium, or both! For example, for a single react component, you could create 3 tests- 1 that runs with react-test-renderer on node, another on chromium which renders the component to the dom, and a 3rd node style test which invokes the component in the browser before interacting with it via puppeteer.
+
 Testeranto includes a test runner which bundles and executes your tests, taking care to only run the tests which have changed. It is designed to run most tests in parallel, though it has support for tests which require a shared resource, like a port.
 
 Testeranto includes a test reporter which displays the state of your code in a web app. ([see example](https://chromapdx.github.io/kokomoBay/report.html)) This reporter can also be run locally for the developer's convenience.
@@ -46,10 +67,51 @@ Rather than the traditional method of specifying tests in plain text, Testeranto
 
 ## the bad parts
 
-Testeranto does not (yet!) of a means of allowing non-coders to affect changes so, as they say, "get good 💪!"
+Testeranto is not designed to maximize performance. In dev mode, it runs multiple esbuild processes, electron, 1 node process for each node test and 1 chromium processes for each web test. 
+
+Testeranto does not (yet!) of a means of allowing non-coders to affect changes so, as they say, "get good 💪!" 
+
+Because Testeranto is so un-opinionated that it does not provide test infrastructure. You will need to find an existing recipe or implement it yourself, though a public repo of test interfaces exists.
+
+## How it works
+
+Testeranto is comprised of 3 parts
+1) The build process reads a config and builds the docs folder, then launches 3 esbuild build processes. 
+  a) Build the features for the html report
+  b) Build the node-style tests
+  c) Build the web-style tests
+2) The test runner is an electron app which watches the output of those build processes and launches the tests as those files change. 
+3) A Report which links your features, your tests and the results of those tests into a handy website.
+
+## Electron aka Node vs Chromium
+
+At the heart of testeranto is the dual runtime provided by electron. The electron test runner creates an UtilityProcess for each node test and a BrowserWindow for each web test. Each of these processes can communicate to other artifacts over IPC. That is, a node test can invoke a web artifact and send it messages over the IPC channel, and vice-versa. Furthermore, node tests are provided with a puppeteer, providing it access to the web environment, while web tests are provided the electron BrowserWindow, which allows it to similarly bridge the gap between the web runtime and the node runtime.
+
+## Hybrid tests
+
+Consider the a scenario: You have an http server which serves a frontend react component. You have multiple ways you can test this.
+
+- A node test of the logic of the http server
+- A node test of the full http server, tested over http request.
+- A node test of the react component with react-test-render
+- A web test of the react component rendering it to the dom.
+- A node test of the logic of the server, rending the component as a paired artifact and communicated over IPC.
+- A node test of the full server, invoking puppeteer to drive the browser.
+- A web test, invoking the server as a shared artifact, serving http to the browser.
+
+## API
+
+Testeranto's main API interface is 2 functions, 1 for each run time. You must pass to this function the following arguments
 
-Testeranto is not for testing pure functions. It's designed only to address _stateful_ logic.
+- The "shape" - a TS type signature to which the other arguments must conform.
+- The "input" - the test subject. The "thing that is to be tested"
+- the "specification" - This is the Cucumber-style Given/When/Then steps.
+- the "implementation" - This is the code which implements the "test specification" in code. 
+- the "interface" - The code which sets up the test. 
 
-Testeranto prefers TS and to be leveraged to it full potential requires at least some proficiency with the language.
+This is designed so that each piece can be worked upon separately. You can think of each argument as the responsibility of a different member of your team.
 
-Because Testeranto is so un-opinionated that it does not provide test infrastructure. You will need to find an existing recipe or implement it yourself, though I plan to have some sort of public repo of test interfaces someday 😅
+- "Senior Engineer" handles the "shape" and "input"
+- "Product Manager" handles the "specification"
+- "Middle Engineer" handles the "interface"
+- "Junior Engineer" handles the "implementation"

package/dist/cjs-shim.js

@@ -0,0 +1,12 @@
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import url from 'node:url';
+
+// globalThis.require = createRequire(import.meta.url);
+// globalThis.__filename = url.fileURLToPath(import.meta.url);
+// globalThis.__dirname = path.dirname(__filename);
+
+// const p = `${import.meta.url}/..`;
+// globalThis.require = createRequire(`${import.meta.url}/..`);
+// globalThis.__filename = url.fileURLToPath(`${import.meta.url}/..`);
+// globalThis.__dirname = path.dirname(`${__filename}/..`);

package/dist/common/Features.js

@@ -4,9 +4,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DirectedGraph = exports.TesterantoFeatures = exports.TesterantoGraphDirectedAcyclic = exports.TesterantoGraphDirected = exports.TesterantoGraphUndirected = exports.BaseFeature = void 0;
-const graphology_1 = __importDefault(require("graphology"));
-/* @ts-ignore:next-line */
-const { DirectedGraph, UndirectedGraph } = graphology_1.default;
+const graphology_umd_js_1 = __importDefault(require("graphology/dist/graphology.umd.js"));
+const { DirectedGraph, UndirectedGraph } = graphology_umd_js_1.default;
 exports.DirectedGraph = DirectedGraph;
 class TesterantoGraph {
     constructor(name) {

package/dist/common/Node.js

@@ -3,72 +3,64 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-const core_js_1 = require("./core.js");
-const core_js_2 = __importDefault(require("./core.js"));
+const http_1 = __importDefault(require("http"));
+const puppeteer_core_1 = __importDefault(require("puppeteer-core"));
+const core_js_1 = __importDefault(require("./lib/core.js"));
+const index_js_1 = require("./lib/index.js");
 const NodeWriter_js_1 = require("./NodeWriter.js");
-const receiveTestResourceConfigUnscheduled = async (t, testresource) => {
-    const { failed, artifacts, logPromise } = await t.receiveTestResourceConfig(testresource);
-    Promise.all([...artifacts, logPromise]).then(async () => {
-        process.exit(await failed ? 1 : 0);
+const Types_js_1 = require("./Types.js");
+const readJson = async (port) => new Promise((resolve, reject) => {
+    let json = "";
+    const request = http_1.default.request({
+        host: "127.0.0.1",
+        path: "/json/version",
+        port,
+    }, (response) => {
+        response.on("error", reject);
+        response.on("data", (chunk) => {
+            json += chunk.toString();
+        });
+        response.on("end", () => {
+            resolve(JSON.parse(json));
+        });
     });
-};
-const receiveTestResourceConfigScheduled = async (t, testresource) => {
-    const { failed, artifacts, logPromise } = await t.receiveTestResourceConfig(testresource);
-    /* @ts-ignore:next-line */
-    process.send({
-        type: "testeranto:adios",
-        data: {
-            failed,
-            testResourceConfiguration: t.test.testResourceConfiguration,
-            results: t.toObj(),
-        },
-    }, async (err) => {
-        if (!err) {
-            Promise.all([...artifacts, logPromise]).then(async () => {
-                process.exit(await failed ? 1 : 0);
-            });
-        }
-        else {
-            console.error(err);
-            process.exit(1);
-        }
-    });
-};
-exports.default = async (input, testSpecification, testImplementation, testInterface, testResourceRequirement = core_js_1.defaultTestResourceRequirement) => {
-    const mrt = new core_js_2.default(input, testSpecification, testImplementation, testInterface, testResourceRequirement, testInterface.assertioner || (async (t) => t), testInterface.beforeEach || async function (subject, initialValues, testResource) {
-        return subject;
-    }, testInterface.afterEach || (async (s) => s), testInterface.afterAll || ((store) => undefined), testInterface.butThen || (async (a) => a), testInterface.andWhen, testInterface.actionHandler ||
-        function (b) {
-            return b;
-        }, NodeWriter_js_1.NodeWriter);
-    const tl2 = mrt;
-    const t = tl2.testJobs[0];
-    const testResourceArg = process.argv[2] || `{}`;
-    try {
-        const partialTestResource = JSON.parse(testResourceArg);
-        if (partialTestResource.scheduled) {
-            console.log("test is scheduled", partialTestResource);
-            console.log("requesting test resources via IPC ...", testResourceRequirement);
-            /* @ts-ignore:next-line */
-            process.send({
-                type: "testeranto:hola",
-                data: {
-                    requirement: Object.assign(Object.assign({}, testResourceRequirement), { name: partialTestResource.name })
-                },
-            });
-            console.log("awaiting test resources via IPC...");
-            process.on("message", async function (packet) {
-                const resourcesFromPm2 = packet.data.testResourceConfiguration;
-                const secondTestResource = Object.assign(Object.assign({ fs: "." }, JSON.parse(JSON.stringify(partialTestResource))), JSON.parse(JSON.stringify(resourcesFromPm2)));
-                receiveTestResourceConfigScheduled(t, secondTestResource);
-            });
+    request.on("error", reject);
+    request.end();
+});
+class NodeTesteranto extends core_js_1.default {
+    constructor(input, testSpecification, testImplementation, testResourceRequirement, testInterface) {
+        super(input, testSpecification, testImplementation, testResourceRequirement, NodeWriter_js_1.NodeWriter, testInterface);
+        if (process.argv[2]) {
+            const testResourceArg = process.argv[2];
+            try {
+                const partialTestResource = JSON.parse(testResourceArg);
+                this.receiveTestResourceConfig(this.testJobs[0], partialTestResource);
+            }
+            catch (e) {
+                console.error(e);
+                // process.exit(-1);
+            }
         }
         else {
-            receiveTestResourceConfigUnscheduled(t, partialTestResource);
+            // no-op
         }
     }
-    catch (e) {
-        console.error(e);
-        process.exit(-1);
+    async receiveTestResourceConfig(t, partialTestResource) {
+        const browser = await readJson("2999").then(async (json) => {
+            const b = await puppeteer_core_1.default.connect({
+                browserWSEndpoint: json.webSocketDebuggerUrl,
+                defaultViewport: null,
+            });
+            console.log("connected!", b.isConnected());
+            return b;
+        });
+        const { failed, artifacts, logPromise } = await t.receiveTestResourceConfig(partialTestResource, new Types_js_1.TBrowser(browser));
+        Promise.all([...artifacts, logPromise]).then(async () => {
+            // process.exit(await failed ? 1 : 0);
+        });
     }
+}
+;
+exports.default = async (input, testSpecification, testImplementation, testInterface, testResourceRequirement = index_js_1.defaultTestResourceRequirement) => {
+    return new NodeTesteranto(input, testSpecification, testImplementation, testResourceRequirement, testInterface);
 };