testeranto 0.140.2 → 0.146.0

package/docs/aiderTest.sh

@@ -0,0 +1 @@
+aider --load docs/testing.prompt.txt --message-file  docs/testing.message.txt

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/docs/testing.ai.txt

@@ -0,0 +1,98 @@
+# Testeranto Testing Patterns
+
+## Key Learnings From Self-Testing
+
+1. Test Organization Insights:
+- Mock implementations proved essential for testing abstract base classes
+- Type parameters (I/O/M) need careful documentation for test writers
+- Integration tests revealed subtle proxy chain issues
+
+2. Effective Patterns:
+- Builder tests validate both construction and runtime behavior  
+- Proxy tests verify path rewriting and content preservation
+- Error tests check both expected and unexpected cases
+- Lifecycle tests cover full BDD sequence
+
+3. Improvement Opportunities:
+- Need more test utilities for common scenarios
+- Could add test generation from type definitions
+- Should document common test pitfalls
+- Would benefit from more example test suites
+
+## Core Testing Principles
+
+1. Tests follow BDD structure with Given/When/Then
+2. All tests are strongly typed using I/O/M types
+3. Test files are organized in a consistent structure:
+   /src
+     TEST_SUBJECT.ts
+     TEST_SUBJECT.test/
+       implementation.ts - Concrete test operations
+       specification.ts - Test scenarios and assertions  
+       interface.ts - Test lifecycle hooks
+       types.ts - Type definitions
+       index.ts - Main test export
+
+## Key Testing Patterns Observed
+
+1. Builder Testing:
+- TestBaseBuilder provides core test infrastructure
+- TestClassBuilder extends it for class-based testing
+- Both use similar test patterns:
+  * Initialization validation
+  * Spec generation checks
+  * Job creation verification
+  * Artifact tracking
+  * Resource requirement validation
+
+2. Comprehensive Test Cases:
+- Basic functionality tests
+- Custom input scenarios  
+- Resource configuration
+- Dynamic modification
+- Error handling
+- Full test run verification
+
+3. Type Safety:
+- Ibdd_in defines internal test flow
+- Ibdd_out defines external interface
+- M type for specification modifications
+
+## Implementation Notes
+
+1. Test builders follow this pattern:
+- Create concrete test implementation
+- Define test specification with scenarios
+- Implement test interface hooks
+- Export via Testeranto runner
+
+2. Key test assertions:
+- Verify proper initialization
+- Check spec generation
+- Validate job creation
+- Track artifacts
+- Confirm resource setup
+
+3. Error handling:
+- Explicit error type checks
+- Expected error messages
+- Async error propagation
+
+## Best Practices
+
+1. For each test:
+- Document test purpose in specification
+- Keep implementations focused
+- Use descriptive type names
+- Include positive and negative cases
+
+2. Test organization:
+- Group related tests in suites  
+- Separate concerns in different files
+- Reuse common test patterns
+- Keep test files small and focused
+
+3. Maintenance:
+- Update docs when patterns change
+- Review test types when interfaces change
+- Verify all test cases after refactors

package/docs/testing.prompt.txt

@@ -0,0 +1,8 @@
+/read README.md
+
+/read docs/index.md
+/read docs/testing.ai.txt
+
+/add src/CoreTypes.ts
+/add src//lib/types.ts
+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "testeranto",
   "description": "the AI powered BDD test framework for typescript projects",
-  "version": "0.140.2",
+  "version": "0.146.0",
   "engines": {
     "node": "18.18.0"
   },
@@ -128,8 +128,8 @@
     "build-types": "tsc -p tsconfig.types.json",
     "type-check": "yarn tsc --noEmit > tsc.log",
     "type-fix": "aider --model deepseek/deepseek-chat --load type-fix.txt",
-    "t-build": "tsx dist/prebuild/build.mjs",
-    "t-run": "tsx dist/prebuild/run.mjs",
+    "t-build": "tsx src/build.ts",
+    "t-run": "tsx src/run.ts",
     "t-init": "tsx dist/prebuild/init-docs.mjs",
     "t-report": "tsx dist/prebuild/ReportServer.mjs",
     "build-docs": "node scripts/compile-docs.js"

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

@@ -30,23 +30,13 @@ export abstract class PM_WithEslintAndTsc extends PM_Base {
 
     this.name = name;
     this.mode = mode;
+    this.summary = {};
 
+    // Initialize all test entries first
     this.configs.tests.forEach(([t, rt, tr, sidecars]) => {
-      this.summary[t] = {
-        runTimeError: "?",
-        typeErrors: "?",
-        staticErrors: "?",
-        prompt: "?",
-        failingFeatures: {},
-      };
-      sidecars.forEach(([t]) => {
-        this.summary[t] = {
-          // runTimeError: "?",
-          typeErrors: "?",
-          staticErrors: "?",
-          // prompt: "?",
-          // failingFeatures: {},
-        };
+      this.ensureSummaryEntry(t);
+      sidecars.forEach(([sidecarName]) => {
+        this.ensureSummaryEntry(sidecarName, true);
       });
     });
   }
@@ -61,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
@@ -104,7 +102,6 @@ export abstract class PM_WithEslintAndTsc extends PM_Base {
     });
 
     fs.writeFileSync(tscPath, results.join("\n"));
-
     this.typeCheckIsNowDone(entrypoint, results.length);
   };
 
@@ -114,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)
@@ -165,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(
@@ -227,34 +233,89 @@ ${addableFiles
     this.checkForShutdown();
   };
 
+  private ensureSummaryEntry(src: string, isSidecar = false) {
+    if (!this.summary[src]) {
+      this.summary[src] = {
+        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;
+      }
+    }
+    return this.summary[src];
+  }
+
   typeCheckIsRunning = (src: string) => {
+    if (!this.summary[src]) {
+      throw `this.summary[${src}] is undefined`;
+    }
+
     this.summary[src].typeErrors = "?";
   };
 
   typeCheckIsNowDone = (src: string, failures: number) => {
+    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) => {
+    if (!this.summary[src]) {
+      throw `this.summary[${src}] is undefined`;
+    }
     this.summary[src].staticErrors = "?";
     this.writeBigBoard();
   };
 
   lintIsNowDone = (src: string, failures: number) => {
+    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) => {
-    this.summary[src].runTimeError = "?";
+    if (!this.summary[src]) {
+      throw `this.summary[${src}] is undefined`;
+    }
+    this.summary[src].runTimeErrors = "?";
     this.writeBigBoard();
   };
 
   bddTestIsNowDone = (src: string, failures: number) => {
-    this.summary[src].runTimeError = failures;
+    if (!this.summary[src]) {
+      throw `this.summary[${src}] is undefined`;
+    }
+    this.summary[src].runTimeErrors = failures;
     this.writeBigBoard();
     this.checkForShutdown();
   };
@@ -266,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();
 }