testeranto 0.143.0 → 0.146.1

package/docs/index.md

@@ -1,6 +1,6 @@
 # Testeranto docs and core concepts
 
-Testeranto's type system provides a rigorous framework for Behavior-Driven Development (BDD) testing. While powerful, the API can initially seem complex but everything you need to know can be summed up in **3 core functions and 5 essential types**. Follow these patterns, and TypeScript's type checker will guide you through the rest.
+Testeranto's type system provides a rigorous framework for Behavior-Driven Development (BDD) testing. The API may seem complex but everything you need to know can be summed up in **1 function, 3 runtimes and 5 essential types, and 1 optional type**. Follow these patterns, and TypeScript's type checker will guide you through the rest.
 
 ### ⚠️ this doc is a work in progress. It is 99% accurate but needs some attention to be complete. ⚠️
 
@@ -26,7 +26,21 @@ class Rectangle {
 }
 ```
 
-### Testeranto's 3 functions
+### Testeranto's 1 function
+
+Testeranto has 1 function. This function launches and runs the tests. It is here that all 5 types converge and if you can type this function call correctly, the TS type system should guide you through the rest.
+
+```ts
+async <I extends Ibdd_in_any, O extends Ibdd_out, M>(
+  input: I["iinput"],
+  testSpecification: ITestSpecification<I, O>,
+  testImplementation: ITestImplementation<I, O, M>,
+  testInterface: Partial<ITestInterface<I>>,
+  testResourceRequirement: ITTestResourceRequest = defaultTestResourceRequirement
+): Promise<Testeranto<I, O, M>>
+```
+
+### Testeranto's 3 runtimes
 
 For each of testeranto's runtime, there is a specific Testeranto main function. Each is it's own import but all 3 are called in the same way.
 
@@ -36,6 +50,10 @@ For each of testeranto's runtime, there is a specific Testeranto main function.
 import Testeranto from "testeranto/src/Node"; // <- import the Node main function
 // below this point, all runtimes are identical!
 
+import { implementation } from "./Rectangle.test.implementation";
+import { specification } from "./Rectangle.test.specification";
+import { interface } from "./Rectangle.test.interface";
+
 // Note the type parameters I, O, and M: these will be important later
 export default Testeranto<
   I extends Ibdd_in,
@@ -95,32 +113,9 @@ export default Testeranto<
 );
 ```
 
-### Testeranto's 5 Essential Types
-
-Every testeranto test is built around these 5 types that form a complete testing pipeline:
-
-1. **ITestSpecification** - The "what" of your tests (business requirements)
-2. **ITestImplementation** - The "how" of your tests (concrete operations)
-3. **ITestInterface** - The "glue" between specs and implementation
-4. **Ibdd_in** - Defines the internal test flow shape
-5. **Ibdd_out** - Defines the external test interface
-
-```mermaid
-flowchart LR
-    S[ITestSpecification] -->|defines| O[Ibdd_out]
-    I[ITestImplementation] -->|uses| O
-    I -->|uses| M[Modifier]
-    T[ITestInterface] -->|connects| N[Ibdd_in]
-    S -->|flows through| N
-    I -->|flows through| N
-
-    style S fill:#2aa198,stroke:#073642
-    style I fill:#859900,stroke:#073642
-    style T fill:#b58900,stroke:#073642
-    style O fill:#d33682,stroke:#073642
-    style N fill:#cb4b16,stroke:#073642
-    style M fill:#6c71c4,stroke:#073642
-```
+### Testeranto's 5 essential types
+
+Every testeranto test is built around these 5 types that form a complete testing pipeline.
 
 #### The Specification (ITestSpecification)
 
@@ -130,7 +125,6 @@ The Specification defines the business requirements in plain language, completel
 - Human-readable test descriptions
 - Defines test suites, scenarios (Given/When/Then)
 - Maps directly to BDD concepts
-- Uses Ibdd_out for type safety
 
 ```typescript
 import {
@@ -243,10 +237,9 @@ export const implementation: ITestImplementation<
 
 #### The Interface aka ITestInterface
 
-The test interface is code which is NOT BDD . The interface adapts your test subject so that the BDD hooks can be applied. The interface implements the traditional BDD steps "before all", "after all", "before each", "after each", etc
+The test interface is code which is NOT business logic. The interface adapts your test subject so that the BDD hooks can be applied. The interface implements the traditional BDD steps "before all", "after all", "before each", "after each", etc
 
 ```ts
-
 import {
   Ibdd_in,
   ITestInterface,
@@ -275,7 +268,7 @@ export const testInterface: ITestInterface<
 
 #### type I aka Ibdd_in
 
-this type describes the "inner" shape of your BDD tests.
+This type describes the "inner" shape of your BDD tests. Over the course of the execution of the test, the subject will change shapes- this test describe those changes.
 
 ```ts
 import { Ibdd_in } from "testeranto/src/CoreTypes";
@@ -294,7 +287,7 @@ export type I = Ibdd_in<
 
 #### type O aka Ibdd_out
 
-this type describes the "outer" shape of your BDD tests.
+This type describes the "outer" shape of your BDD tests. This type describes the set of legal BDD clauses.
 
 ```ts
 import { Ibdd_out } from "testeranto/src/CoreTypes";
@@ -335,6 +328,8 @@ export type O = Ibdd_out<
 >;
 ```
 
+### Testeranto's 1 optional type
+
 #### type M (optional)
 
 this type describes the modifications to the shape of the "specification". It can be used to make your BDD tests DRYer but is not necessary
@@ -565,3 +560,20 @@ export default Testeranto<
 
 
 ```
+
+## Trouble shooting
+
+### Double check your runtimes.
+
+Every test has a runtime, which must defined in 2 places. Both must match.
+
+1. The import of the runtime
+2. The runtime defined alongside the test in testeranto.config.ts
+
+By convention, test filenames reveal their runtime. Ex: `__tests__/yourClass.node.test`. This is ONLY a convention. It has no real bearing on the runtime.
+
+## Dos and Don'ts
+
+### Do pass your test subject to the main testeranto function.
+
+### Don't import your test subject elsewhere in your tests.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "testeranto",
   "description": "the AI powered BDD test framework for typescript projects",
-  "version": "0.143.0",
+  "version": "0.146.1",
   "engines": {
     "node": "18.18.0"
   },

package/src/Node.ts

@@ -16,6 +16,8 @@ import {
 
 let ipcfile;
 
+console.log("mark4");
+
 export class NodeTesteranto<
   I extends Ibdd_in_any,
   O extends Ibdd_out_any,
@@ -41,6 +43,7 @@ export class NodeTesteranto<
   }
 
   async receiveTestResourceConfig(partialTestResource: string) {
+    console.log("receiveTestResourceConfig", partialTestResource);
     const t: ITTestResourceConfiguration = JSON.parse(partialTestResource);
     const pm = new PM_Node(t, ipcfile);
     return await this.testJobs[0].receiveTestResourceConfig(pm);
@@ -58,21 +61,22 @@ const testeranto = async <I extends Ibdd_in_any, O extends Ibdd_out, M>(
   testInterface: Partial<INodeTestInterface<I>>,
   testResourceRequirement: ITTestResourceRequest = defaultTestResourceRequirement
 ): Promise<Testeranto<I, O, M>> => {
-  const t = new NodeTesteranto<I, O, M>(
-    input,
-    testSpecification,
-    testImplementation,
-    testResourceRequirement,
-    testInterface
-  );
+  try {
+    const t = new NodeTesteranto<I, O, M>(
+      input,
+      testSpecification,
+      testImplementation,
+      testResourceRequirement,
+      testInterface
+    );
+    console.log("args", process.argv);
 
-  process.on("unhandledRejection", (reason, promise) => {
-    console.error("Unhandled Rejection at:", promise, "reason:", reason);
-    // Optionally, terminate the process or perform cleanup
-    // t.registerUncaughtPromise(reason, promise);
-  });
+    process.on("unhandledRejection", (reason, promise) => {
+      console.error("Unhandled Rejection at:", promise, "reason:", reason);
+      // Optionally, terminate the process or perform cleanup
+      // t.registerUncaughtPromise(reason, promise);
+    });
 
-  try {
     ipcfile = process.argv[3];
     const f = await t.receiveTestResourceConfig(process.argv[2]);
 

package/src/PM/PM_WithEslintAndTsc.ts

@@ -51,7 +51,15 @@ export abstract class PM_WithEslintAndTsc extends PM_Base {
     addableFiles: string[];
   }) => {
     console.log(ansiC.green(ansiC.inverse(`tsc < ${entrypoint}`)));
-    this.typeCheckIsRunning(entrypoint);
+    try {
+      this.typeCheckIsRunning(entrypoint);
+    } catch (e) {
+      console.error("error in tscCheck");
+      console.error(e);
+      console.error(entrypoint);
+      console.error(JSON.stringify(this.summary, null, 2));
+      process.exit(-1);
+    }
 
     const program = tsc.createProgramFromConfig({
       basePath: process.cwd(), // always required, used for relative paths
@@ -94,7 +102,6 @@ export abstract class PM_WithEslintAndTsc extends PM_Base {
     });
 
     fs.writeFileSync(tscPath, results.join("\n"));
-
     this.typeCheckIsNowDone(entrypoint, results.length);
   };
 
@@ -104,7 +111,16 @@ export abstract class PM_WithEslintAndTsc extends PM_Base {
     addableFiles: string[]
   ) => {
     console.log(ansiC.green(ansiC.inverse(`eslint < ${entrypoint}`)));
-    this.lintIsRunning(entrypoint);
+
+    try {
+      this.lintIsRunning(entrypoint);
+    } catch (e) {
+      console.error("error in eslintCheck");
+      console.error(e);
+      console.error(entrypoint);
+      console.error(JSON.stringify(this.summary, null, 2));
+      process.exit(-1);
+    }
 
     const results = (await eslint.lintFiles(addableFiles))
       .filter((r) => r.messages.length)
@@ -155,7 +171,7 @@ export abstract class PM_WithEslintAndTsc extends PM_Base {
       this.name,
       entryPoint.split(".").slice(0, -1).join("."),
       platform,
-      `console_log.txt`
+      `logs.txt`
     );
 
     const lintPath = path.join(
@@ -220,55 +236,86 @@ ${addableFiles
   private ensureSummaryEntry(src: string, isSidecar = false) {
     if (!this.summary[src]) {
       this.summary[src] = {
-        typeErrors: "?",
-        staticErrors: "?",
-        runTimeError: "?",
-        prompt: "?",
-        failingFeatures: {}
+        typeErrors: undefined,
+        staticErrors: undefined,
+        runTimeErrors: undefined,
+        prompt: undefined,
+        failingFeatures: {},
       };
       if (isSidecar) {
         // Sidecars don't need all fields
-        delete this.summary[src].runTimeError;
-        delete this.summary[src].prompt;
+        // delete this.summary[src].runTimeError;
+        // delete this.summary[src].prompt;
       }
     }
     return this.summary[src];
   }
 
   typeCheckIsRunning = (src: string) => {
-    const entry = this.ensureSummaryEntry(src);
-    entry.typeErrors = "?";
+    if (!this.summary[src]) {
+      throw `this.summary[${src}] is undefined`;
+    }
+
+    this.summary[src].typeErrors = "?";
   };
 
   typeCheckIsNowDone = (src: string, failures: number) => {
-    const entry = this.ensureSummaryEntry(src);
-    entry.typeErrors = failures;
+    if (!this.summary[src]) {
+      throw `this.summary[${src}] is undefined`;
+    }
+
+    if (failures === 0) {
+      console.log(ansiC.green(ansiC.inverse(`tsc > ${src}`)));
+    } else {
+      console.log(
+        ansiC.red(ansiC.inverse(`tsc > ${src} failed ${failures} times`))
+      );
+    }
+
+    this.summary[src].typeErrors = failures;
     this.writeBigBoard();
     this.checkForShutdown();
   };
 
   lintIsRunning = (src: string) => {
-    const entry = this.ensureSummaryEntry(src);
-    entry.staticErrors = "?";
+    if (!this.summary[src]) {
+      throw `this.summary[${src}] is undefined`;
+    }
+    this.summary[src].staticErrors = "?";
     this.writeBigBoard();
   };
 
   lintIsNowDone = (src: string, failures: number) => {
-    const entry = this.ensureSummaryEntry(src);
-    entry.staticErrors = failures;
+    if (!this.summary[src]) {
+      throw `this.summary[${src}] is undefined`;
+    }
+
+    if (failures === 0) {
+      console.log(ansiC.green(ansiC.inverse(`eslint > ${src}`)));
+    } else {
+      console.log(
+        ansiC.red(ansiC.inverse(`eslint > ${src} failed ${failures} times`))
+      );
+    }
+
+    this.summary[src].staticErrors = failures;
     this.writeBigBoard();
     this.checkForShutdown();
   };
 
   bddTestIsRunning = (src: string) => {
-    const entry = this.ensureSummaryEntry(src);
-    entry.runTimeError = "?";
+    if (!this.summary[src]) {
+      throw `this.summary[${src}] is undefined`;
+    }
+    this.summary[src].runTimeErrors = "?";
     this.writeBigBoard();
   };
 
   bddTestIsNowDone = (src: string, failures: number) => {
-    const entry = this.ensureSummaryEntry(src);
-    entry.runTimeError = failures;
+    if (!this.summary[src]) {
+      throw `this.summary[${src}] is undefined`;
+    }
+    this.summary[src].runTimeErrors = failures;
     this.writeBigBoard();
     this.checkForShutdown();
   };
@@ -280,50 +327,5 @@ ${addableFiles
     );
   };
 
-  checkForShutdown = () => {
-    console.log(ansiC.inverse(`checkForShutdown`));
-
-    this.writeBigBoard();
-
-    if (this.mode === "dev") return;
-
-    let inflight = false;
-
-    Object.keys(this.summary).forEach((k) => {
-      if (this.summary[k].prompt === "?") {
-        console.log(ansiC.blue(ansiC.inverse(`🕕 prompt ${k}`)));
-        inflight = true;
-      }
-    });
-
-    Object.keys(this.summary).forEach((k) => {
-      if (this.summary[k].runTimeError === "?") {
-        console.log(ansiC.blue(ansiC.inverse(`🕕 runTimeError ${k}`)));
-        inflight = true;
-      }
-    });
-
-    Object.keys(this.summary).forEach((k) => {
-      if (this.summary[k].staticErrors === "?") {
-        console.log(ansiC.blue(ansiC.inverse(`🕕 staticErrors ${k}`)));
-        inflight = true;
-      }
-    });
-
-    Object.keys(this.summary).forEach((k) => {
-      if (this.summary[k].typeErrors === "?") {
-        console.log(ansiC.blue(ansiC.inverse(`🕕 typeErrors ${k}`)));
-        inflight = true;
-      }
-    });
-
-    this.writeBigBoard();
-
-    if (!inflight) {
-      this.browser.disconnect().then(() => {
-        console.log(ansiC.inverse(`${this.name} has been tested. Goodbye.`));
-        process.exit();
-      });
-    }
-  };
+  abstract checkForShutdown();
 }