testeranto 0.134.0 → 0.135.0

package/docs/index.md

@@ -0,0 +1,277 @@
+## Core Concepts
+
+Testeranto's type system provides a rigorous framework for Behavior-Driven Development (BDD) testing. Let's break down the key components using a Rectangle class example.
+
+### The Test Subject
+
+First, define the class you want to test:
+
+```typescript
+class Rectangle {
+  constructor(public width: number, public height: number) {}
+
+  setWidth(w: number) {
+    this.width = w;
+  }
+  setHeight(h: number) {
+    this.height = h;
+  }
+  getArea() {
+    return this.width * this.height;
+  }
+}
+```
+
+### Teseranto's 3 main functions
+
+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.
+
+#### Node
+
+```ts
+import Testeranto from "testeranto/src/Node";
+
+import { RectangleTesterantoBaseTestImplementation } from "./Rectangle.test.implementation";
+import { RectangleTesterantoBaseTestSpecification } from "./Rectangle.test.specification";
+import { RectangleTesterantoBaseInterface } from "./Rectangle.test.interface";
+
+export default Testeranto(
+  null,
+  RectangleTesterantoBaseTestSpecification,
+  RectangleTesterantoBaseTestImplementation,
+  RectangleTesterantoBaseInterface
+);
+```
+
+#### Web
+
+```ts
+import Testeranto from "testeranto/src/Web";
+
+import { RectangleTesterantoBaseTestImplementation } from "./Rectangle.test.implementation";
+import { RectangleTesterantoBaseTestSpecification } from "./Rectangle.test.specification";
+import { RectangleTesterantoBaseInterface } from "./Rectangle.test.interface";
+
+export default Testeranto(
+  null,
+  RectangleTesterantoBaseTestSpecification,
+  RectangleTesterantoBaseTestImplementation,
+  RectangleTesterantoBaseInterface
+);
+```
+
+#### Pure
+
+```ts
+import Testeranto from "testeranto/src/Pure";
+
+import { RectangleTesterantoBaseTestImplementation } from "./Rectangle.test.implementation";
+import { RectangleTesterantoBaseTestSpecification } from "./Rectangle.test.specification";
+import { RectangleTesterantoBaseInterface } from "./Rectangle.test.interface";
+
+export default Testeranto(
+  null,
+  RectangleTesterantoBaseTestSpecification,
+  RectangleTesterantoBaseTestImplementation,
+  RectangleTesterantoBaseInterface
+);
+```
+
+### Testeranto functions and types
+
+Every testeranto test has 4-5 components:
+
+1. ITestSpecification
+2. ITestImplementation
+3. ITestInterface
+4. Ibdd_in
+5. Ibdd_out
+6. the "modifier" type
+
+#### The Specification aka ITestSpecification
+
+The Specification defines the business logic of your tests, divorced from implementation details.
+
+```typescript
+export const RectangleTesterantoBaseTestSpecification: ITestSpecification<
+  I,
+  O
+> = (Suite, Given, When, Then, Check) => {
+  return [
+    Suite.Default(
+      "Testing the Rectangle class",
+      {
+        test0: Given.Default(
+          ["https://api.github.com/repos/adamwong246/testeranto/issues/8"],
+          [],
+          [Then.getWidth(2)]
+        ),
+        test1: Given.Default(
+          [`Rectangles have width and height.`],
+          [When.setWidth(4), When.setHeight(5)],
+          [Then.getWidth(4), Then.getHeight(5), Then.area(20)]
+        ),
+      },
+
+      []
+    ),
+  ];
+};
+```
+
+#### The Implementation aka ITestImplementation
+
+The Implementation defines the hooks that the Specification will call.
+
+```ts
+export const RectangleTesterantoBaseTestImplementation: ITestImplementation<
+  I,
+  O,
+  M
+> = {
+  suites: {
+    Default: "a default suite",
+  },
+
+  givens: {
+    Default: () => new Rectangle(2, 2),
+    WidthAndHeightOf: (width, height) => new Rectangle(width, height),
+  },
+
+  whens: {
+    setWidth: (width: number) => (rectangle) => {
+      rectangle.setWidth(width);
+      return rectangle;
+    },
+    setHeight: (height: number) => (rectangle) => {
+      rectangle.setHeight(height);
+      return rectangle;
+    },
+  },
+
+  thens: {
+    getWidth: (expectedWidth) => (rectangle) => {
+      assert.equal(rectangle.getWidth(), expectedWidth);
+      return rectangle;
+    },
+    getHeight: (expectedHeight) => (rectangle) => {
+      assert.equal(rectangle.getHeight(), expectedHeight);
+      return rectangle;
+    },
+    area: (area) => (rectangle) => {
+      assert.equal(rectangle.area(), area);
+      return rectangle;
+    },
+    circumference: (circumference: number) => (rectangle: Rectangle) => {
+      assert.equal(rectangle.circumference(), circumference);
+      return rectangle;
+    },
+  },
+
+  checks: {
+    Default: () => new Rectangle(2, 2),
+  },
+};
+```
+
+#### 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 "before all", "after all", "before each", and "after each", all of which are optional.
+
+```ts
+export const RectangleTesterantoBaseInterface: ITestInterface<I> = {
+  beforeEach: async (subject, i) => {
+    return i();
+  },
+  andWhen: async function (s, whenCB, tr, utils) {
+    return whenCB(s, utils);
+  },
+  butThen: async (s, t, tr, pm) => {
+    return t(s, pm);
+  },
+  afterEach: (z) => {
+    return z;
+  },
+  afterAll: () => {},
+  assertThis: (x: any, y) => {},
+};
+```
+
+#### type I aka Ibdd_in
+
+this type describes the "inner" shape of your BDD tests.
+
+```ts
+export type I = Ibdd_in<
+  null,
+  null,
+  Rectangle,
+  Rectangle,
+  Rectangle,
+  (...x) => (rectangle: Rectangle, utils: IPM) => Rectangle,
+  (rectangle: Rectangle, utils: IPM) => Rectangle
+>;
+```
+
+#### type O aka Ibdd_out
+
+this type describes the "outer" shape of your BDD tests.
+
+```ts
+export type O = Ibdd_out<
+  // Suite
+  {
+    Default: [string];
+  },
+  // "Given" are initial states
+  {
+    Default;
+    WidthOfOneAndHeightOfOne;
+    WidthAndHeightOf: [number, number];
+  },
+  // "Whens" are steps which change the state of the test subject
+  {
+    HeightIsPubliclySetTo: [number];
+    WidthIsPubliclySetTo: [number];
+    setWidth: [number];
+    setHeight: [number];
+  },
+  // "Thens" are steps which make assertions of the test subject
+  {
+    AreaPlusCircumference: [number];
+    circumference: [number];
+    getWidth: [number];
+    getHeight: [number];
+    area: [number];
+    prototype: [];
+  },
+  // "Checks" are similar to "Givens"
+  {
+    Default;
+    WidthOfOneAndHeightOfOne;
+    WidthAndHeightOf: [number, number];
+  }
+>;
+```
+
+#### 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
+
+```ts
+export type M = {
+  givens: {
+    [K in keyof O["givens"]]: (...Iw: O["givens"][K]) => Rectangle;
+  };
+  whens: {
+    [K in keyof O["whens"]]: (
+      ...Iw: O["whens"][K]
+    ) => (rectangle: Rectangle, utils: PM) => Rectangle;
+  };
+  thens: {
+    [K in keyof O["thens"]]: (
+      ...Iw: O["thens"][K]
+    ) => (rectangle: Rectangle, utils: PM) => Rectangle;
+  };
+};
+```

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "testeranto",
   "description": "the AI powered BDD test framework for typescript projects",
-  "version": "0.134.0",
+  "version": "0.135.0",
   "engines": {
     "node": "18.18.0"
   },
@@ -17,6 +17,10 @@
       "import": "./dist/cjs-shim.js",
       "require": "./dist/cjs-shim.js"
     },
+    "./src/lib": {
+      "import": "./src/lib/index.ts",
+      "require": "./src/lib/index.ts"
+    },
     "./src/lib/abstractBase": {
       "import": "./src/lib/abstractBase.ts",
       "require": "./src/lib/abstractBase.ts"
@@ -177,6 +181,7 @@
     "esbuild-plugin-markdown": "^0.0.3",
     "esbuild-plugin-polyfill-node": "^0.3.0",
     "eslint": "^9.23.0",
+    "eslint-formatter-compact": "^8.40.0",
     "eslint-plugin-import": "^2.31.0",
     "eslint-plugin-react": "^7.31.11",
     "eslint-plugin-react-hooks": "^5.1.0",

package/src/CoreTypes.ts

@@ -0,0 +1,171 @@
+import { ITTestResourceConfiguration } from "./lib";
+
+import { IPM, ITestCheckCallback } from "./lib/types";
+import {
+  GivenSpecification,
+  WhenSpecification,
+  ThenSpecification,
+  TestWhenImplementation,
+  Modify,
+  TestSuiteImplementation,
+  TestGivenImplementation,
+  TestThenImplementation,
+  TestCheckImplementation,
+  TestSuiteShape,
+  TestGivenShape,
+  TestWhenShape,
+  TestThenShape,
+  TestCheckShape,
+  SuiteSpecification,
+} from "./Types";
+
+/////////////////////////////////////////////////////////////////////////////////////////
+
+export type ITestInterface<
+  I extends Ibdd_in<
+    unknown,
+    unknown,
+    unknown,
+    unknown,
+    unknown,
+    unknown,
+    unknown
+  >
+> = {
+  assertThis: (x: I["then"]) => any;
+  andWhen: (
+    store: I["istore"],
+    whenCB: I["when"],
+    testResource: ITTestResourceConfiguration,
+    pm: IPM
+  ) => Promise<I["istore"]>;
+  butThen: (
+    store: I["istore"],
+    thenCB: I["then"],
+    testResource: ITTestResourceConfiguration,
+    pm: IPM
+  ) => Promise<I["iselection"]>;
+  afterAll: (store: I["istore"], pm: IPM) => any;
+  afterEach: (store: I["istore"], key: string, pm: IPM) => Promise<unknown>;
+  beforeAll: (
+    input: I["iinput"],
+    testResource: ITTestResourceConfiguration,
+    pm: IPM
+  ) => Promise<I["isubject"]>;
+  beforeEach: (
+    subject: I["isubject"],
+    initializer: (c?) => I["given"],
+    testResource: ITTestResourceConfiguration,
+    initialValues,
+    pm: IPM
+  ) => Promise<I["istore"]>;
+};
+
+/////////////////////////////////////////////////////////////////////////////////////////
+
+export type ITestSpecification<
+  I extends Ibdd_in<
+    unknown,
+    unknown,
+    unknown,
+    unknown,
+    unknown,
+    unknown,
+    unknown
+  >,
+  O extends Ibdd_out<
+    TestSuiteShape,
+    TestGivenShape,
+    TestWhenShape,
+    TestThenShape,
+    TestCheckShape
+  >
+> = (
+  Suite: SuiteSpecification<I, O>,
+  Given: GivenSpecification<I, O>,
+  When: WhenSpecification<I, O>,
+  Then: ThenSpecification<I, O>,
+  Check: ITestCheckCallback<I, O>
+) => any[];
+
+/////////////////////////////////////////////////////////////////////////////////////////
+
+export type ITestImplementation<
+  I extends Ibdd_in<
+    unknown,
+    unknown,
+    unknown,
+    unknown,
+    unknown,
+    unknown,
+    unknown
+  >,
+  O extends Ibdd_out<
+    TestSuiteShape,
+    TestGivenShape,
+    TestWhenShape,
+    TestThenShape,
+    TestCheckShape
+  >,
+  modifier = {
+    whens: TestWhenImplementation<I, O>;
+  }
+> = Modify<
+  {
+    suites: TestSuiteImplementation<O>;
+    givens: TestGivenImplementation<I, O>;
+    whens: TestWhenImplementation<I, O>;
+    thens: TestThenImplementation<I, O>;
+    checks: TestCheckImplementation<I, O>;
+  },
+  modifier
+>;
+
+/////////////////////////////////////////////////////////////////////////////////////////
+
+export type Ibdd_out<
+  ISuites extends TestSuiteShape = TestSuiteShape,
+  IGivens extends TestGivenShape = TestGivenShape,
+  IWhens extends TestWhenShape = TestWhenShape,
+  IThens extends TestThenShape = TestThenShape,
+  IChecks extends TestCheckShape = TestCheckShape
+> = {
+  suites: ISuites;
+  givens: IGivens;
+  whens: IWhens;
+  thens: IThens;
+  checks: IChecks;
+};
+
+/////////////////////////////////////////////////////////////////////////////////////////
+
+export type Ibdd_in<
+  IInput, // Type of initial test input
+  ISubject, // Type of object being tested
+  IStore, // Type for storing test state between steps
+  ISelection, // Type for selecting state for assertions
+  IGiven, // Type for Given step functions
+  IWhen, // Type for When step functions
+  IThen // Type for Then step functions
+> = {
+  /** Initial input required to start tests */
+  iinput: IInput;
+
+  /** The subject being tested (class, function, etc) */
+  isubject: ISubject;
+
+  /** Complete test state storage */
+  istore: IStore;
+
+  /** Selected portion of state for assertions */
+  iselection: ISelection;
+
+  /** Function type for Given steps */
+  given: IGiven;
+
+  /** Function type for When steps */
+  when: IWhen;
+
+  /** Function type for Then steps */
+  then: IThen;
+};

package/src/Node.ts

@@ -4,23 +4,37 @@ import {
   ITTestResourceConfiguration,
   ITTestResourceRequest,
 } from "./lib/index.js";
-import type {
-  INodeTestInterface,
-  IT,
+import type {} from // INodeTestInterface,
+// IT,
+// ITestImplementation,
+// ITestInterface,
+// ITestSpecification,
+// OT,
+"./Types.js";
+import { PM_Node } from "./PM/node.js";
+import {
+  ITestSpecification,
   ITestImplementation,
   ITestInterface,
-  ITestSpecification,
-  OT,
-} from "./Types.js";
-import { PM_Node } from "./PM/node.js";
+  Ibdd_in,
+  Ibdd_out,
+} from "./CoreTypes.js";
 
 let ipcfile;
 
-export class NodeTesteranto<I extends IT, O extends OT, M> extends Testeranto<
-  I,
-  O,
+export class NodeTesteranto<
+  I extends Ibdd_in<
+    unknown,
+    unknown,
+    unknown,
+    unknown,
+    unknown,
+    unknown,
+    unknown
+  >,
+  O extends Ibdd_out,
   M
-> {
+> extends Testeranto<I, O, M> {
   constructor(
     input: I["iinput"],
     testSpecification: ITestSpecification<I, O>,

package/src/PM/PM_WithEslintAndTsc.ts

@@ -145,8 +145,8 @@ export abstract class PM_WithEslintAndTsc extends PM_Base {
       "testeranto",
       "reports",
       this.name,
-      platform,
       entryPoint.split(".").slice(0, -1).join("."),
+      platform,
       `tests.json`
     );
 
@@ -159,6 +159,42 @@ export abstract class PM_WithEslintAndTsc extends PM_Base {
       `featurePrompt.txt`
     );
 
+    const logPath = path.join(
+      "testeranto",
+      "reports",
+      this.name,
+      entryPoint.split(".").slice(0, -1).join("."),
+      platform,
+      `console_log.txt`
+    );
+
+    const lintPath = path.join(
+      "testeranto",
+      "reports",
+      this.name,
+      entryPoint.split(".").slice(0, -1).join("."),
+      platform,
+      `lint_errors.json`
+    );
+
+    const typePath = path.join(
+      "testeranto",
+      "reports",
+      this.name,
+      entryPoint.split(".").slice(0, -1).join("."),
+      platform,
+      `type_errors.txt`
+    );
+
+    const messagePath = path.join(
+      "testeranto",
+      "reports",
+      this.name,
+      entryPoint.split(".").slice(0, -1).join("."),
+      platform,
+      `message`
+    );
+
     fs.writeFileSync(
       promptPath,
       `
@@ -168,23 +204,18 @@ ${addableFiles
   })
   .join("\n")}
 
-/read ${lintPather(entryPoint, platform, this.name)}
-/read ${tscPather(entryPoint, platform, this.name)}
 /read ${testPaths}
+/read ${logPath}
+/read ${typePath}
+/read ${lintPath}
+`
+    );
 
-/load ${featuresPath}
-
-/code Fix the failing tests described in ${testPaths}. Correct any type signature errors described in the files ${tscPather(
-        entryPoint,
-        platform,
-        this.name
-      )}. Implement any method which throws "Function not implemented. Resolve the lint errors described in ${lintPather(
-        entryPoint,
-        platform,
-        this.name
-      )}"
-          `
+    fs.writeFileSync(
+      messagePath,
+      `Fix the failing tests described in ${testPaths} and ${logPath}. DO NOT refactor beyond what is necessary. Always prefer minimal changes, focusing mostly on keeping the BDD tests passing`
     );
+
     this.summary[
       entryPoint
     ].prompt = `aider --model deepseek/deepseek-chat --load testeranto/${

package/src/PM/index.ts

@@ -37,7 +37,7 @@ export abstract class PM {
   abstract typeInto(selector: string, value: string): any;
   abstract waitForSelector(p, sel: string);
   abstract write(uid: number, contents: string): Promise<boolean>;
-  abstract writeFileSync(f: string, c: string, t: string): Promise<boolean>;
+  abstract writeFileSync(f: string, c: string): Promise<boolean>;
 
   abstract launchSideCar(
     n: number

package/src/PM/main.ts

@@ -238,7 +238,7 @@ export class PM_Main extends PM_WithEslintAndTsc {
         waitForInitialPage: false,
         executablePath,
 
-        headless: false,
+        headless: true,
 
         dumpio: false,
         devtools: false,
@@ -703,9 +703,14 @@ export class PM_Main extends PM_WithEslintAndTsc {
     let haltReturns = false;
 
     const ipcfile = "/tmp/tpipe_" + Math.random();
-    const child = spawn("node", [builtfile, testResources, ipcfile], {
-      stdio: ["pipe", "pipe", "pipe", "ipc"],
-    });
+    const child = spawn(
+      "node",
+      // "node --inspect-brk ",
+      [builtfile, testResources, ipcfile],
+      {
+        stdio: ["pipe", "pipe", "pipe", "ipc"],
+      }
+    );
 
     let buffer: Buffer<ArrayBufferLike> = new Buffer("");
 
@@ -770,7 +775,6 @@ export class PM_Main extends PM_WithEslintAndTsc {
         oStream.write(`stdout > ${data}`);
       });
       child.on("close", (code) => {
-        console.log("close");
         oStream.close();
         server.close();
 
@@ -790,7 +794,6 @@ export class PM_Main extends PM_WithEslintAndTsc {
         haltReturns = true;
       });
       child.on("exit", (code) => {
-        console.log("exit");
         haltReturns = true;
 
         for (let i = 0; i <= portsToUse.length; i++) {
@@ -798,8 +801,6 @@ export class PM_Main extends PM_WithEslintAndTsc {
             this.ports[portsToUse[i]] = true; //port is open again
           }
         }
-
-        console.log("exitthis.ports", this.ports);
       });
       child.on("error", (e) => {
         console.log("error");
@@ -852,10 +853,10 @@ export class PM_Main extends PM_WithEslintAndTsc {
             }
             // files[t].add(filepath);
 
-            fs.writeFileSync(
-              destFolder + "/manifest.json",
-              JSON.stringify(Array.from(files[src]))
-            );
+            // fs.writeFileSync(
+            //   destFolder + "/manifest.json",
+            //   JSON.stringify(Array.from(files[src]))
+            // );
             delete files[src];
 
             Promise.all(screenshots[src] || []).then(() => {
@@ -1254,10 +1255,10 @@ export class PM_Main extends PM_WithEslintAndTsc {
           }
           // files[t].add(filepath);
 
-          fs.writeFileSync(
-            destFolder + "/manifest.json",
-            JSON.stringify(Array.from(files[src]))
-          );
+          // fs.writeFileSync(
+          //   destFolder + "/manifest.json",
+          //   JSON.stringify(Array.from(files[src]))
+          // );
           delete files[src];
 
           Promise.all(screenshots[src] || []).then(() => {