testeranto 0.129.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.129.0",
+  "version": "0.135.0",
   "engines": {
     "node": "18.18.0"
   },
@@ -17,113 +17,29 @@
       "import": "./dist/cjs-shim.js",
       "require": "./dist/cjs-shim.js"
     },
-    "./src/SubPackages/**/*": {
-      "import": "./dist/module/SubPackages/",
-      "require": "./dist/common/SubPackages/"
+    "./src/lib": {
+      "import": "./src/lib/index.ts",
+      "require": "./src/lib/index.ts"
     },
-    "./src/SubPackages/react/jsx/index": {
-      "import": "./src/SubPackages/react/jsx/index.ts",
-      "require": "./src/SubPackages/react/jsx/index.ts"
-    },
-    "./src/SubPackages/react/jsx/web": {
-      "import": "./src/SubPackages/react/jsx/web.ts",
-      "require": "./src/SubPackages/react/jsx/web.ts"
-    },
-    "./src/SubPackages/react/jsx/node": {
-      "import": "./src/SubPackages/react/jsx/node.ts",
-      "require": "./src/SubPackages/react/jsx/node.ts"
-    },
-    "./src/SubPackages/react/jsx/pure": {
-      "import": "./src/SubPackages/react/jsx/pure.ts",
-      "require": "./src/SubPackages/react/jsx/pure.ts"
-    },
-    "./src/SubPackages/react/component/index": {
-      "import": "./dist/module/SubPackages/react/component/index.js",
-      "require": "./dist/common/SubPackages/react/component/index.js"
-    },
-    "./src/SubPackages/react/component/web": {
-      "import": "./dist/module/SubPackages/react/component/web.js",
-      "require": "./dist/common/SubPackages/react/component/web.js"
-    },
-    "./src/SubPackages/react/component/node": {
-      "import": "./dist/module/SubPackages/react/component/node.js",
-      "require": "./dist/common/SubPackages/react/component/node.js"
-    },
-    "./src/SubPackages/react-test-renderer/component/index.ts": {
-      "import": "./SubPackages/react-test-renderer/component/index.ts",
-      "require": "./SubPackages/react-test-renderer/component/index.ts"
-    },
-    "./src/SubPackages/react-test-renderer/component/index": {
-      "import": "./SubPackages/react-test-renderer/component/index.ts",
-      "require": "./SubPackages/react-test-renderer/component/index.ts"
-    },
-    "./src/SubPackages/react-test-renderer/component/web": {
-      "import": "./dist/module/SubPackages/react-test-renderer/component/web.js",
-      "require": "./dist/common/SubPackages/react-test-renderer/component/web.js"
-    },
-    "./src/SubPackages/react-test-renderer/component/node": {
-      "import": "./dist/module/SubPackages/react-test-renderer/component/node.js",
-      "require": "./dist/common/SubPackages/react-test-renderer/component/node.js"
-    },
-    "./src/SubPackages/react-test-renderer/jsx/index.js": {
-      "import": "./dist/module/SubPackages/react-test-renderer/jsx/index.js",
-      "require": "./dist/common/SubPackages/react-test-renderer/jsx/index.js"
-    },
-    "./src/SubPackages/react-test-renderer/jsx/web.js": {
-      "import": "./dist/module/SubPackages/react-test-renderer/jsx/web.js",
-      "require": "./dist/common/SubPackages/react-test-renderer/jsx/web.js"
-    },
-    "./src/SubPackages/react-test-renderer/jsx/node.js": {
-      "import": "./dist/module/SubPackages/react-test-renderer/jsx/node.js",
-      "require": "./dist/common/SubPackages/react-test-renderer/jsx/node.js"
-    },
-    "./src/SubPackages/react-test-renderer/jsx/pure.js": {
-      "import": "./dist/module/SubPackages/react-test-renderer/jsx/pure.js",
-      "require": "./dist/common/SubPackages/react-test-renderer/jsx/pure.js"
-    },
-    "./src/SubPackages/react-test-renderer/jsx-promised/index": {
-      "import": "./dist/module/SubPackages/react-test-renderer/jsx-promised/index.js",
-      "require": "./dist/common/SubPackages/react-test-renderer/jsx-promised/index.js"
-    },
-    "./src/SubPackages/react-test-renderer/jsx-promised/web": {
-      "import": "./dist/module/SubPackages/react-test-renderer/jsx-promised/web.js",
-      "require": "./dist/common/SubPackages/react-test-renderer/jsx-promised/web.js"
-    },
-    "./src/SubPackages/react-test-renderer/jsx-promised/node": {
-      "import": "./dist/module/SubPackages/react-test-renderer/jsx-promised/node.js",
-      "require": "./dist/common/SubPackages/react-test-renderer/jsx-promised/node.js"
-    },
-    "./src/SubPackages/react-test-renderer/fc/node": {
-      "import": "./dist/module/SubPackages/react-test-renderer/fc/node.js",
-      "require": "./dist/common/SubPackages/react-test-renderer/fc/node.js"
-    },
-    "./src/SubPackages/react-test-renderer/MemoExoticComponent/node": {
-      "import": "./dist/module/SubPackages/react-test-renderer/MemoExoticComponent/node.js",
-      "require": "./dist/common/SubPackages/react-test-renderer/MemoExoticComponent/node.js"
-    },
-    "./src/SubPackages/react-dom/jsx/web": {
-      "import": "./dist/module/SubPackages/react-dom/jsx/web.js",
-      "require": "./dist/common/SubPackages/react-dom/jsx/web.js"
-    },
-    "./src/SubPackages/react-dom/jsx/node": {
-      "import": "./dist/module/SubPackages/react-dom/jsx/node.js",
-      "require": "./dist/common/SubPackages/react-dom/jsx/node.js"
+    "./src/lib/abstractBase": {
+      "import": "./src/lib/abstractBase.ts",
+      "require": "./src/lib/abstractBase.ts"
     },
-    "./src/SubPackages/react-dom/jsx/index": {
-      "import": "./dist/module/SubPackages/react-dom/jsx/index.js",
-      "require": "./dist/common/SubPackages/react-dom/jsx/index.js"
+    "./src/lib/Sidecar": {
+      "import": "./src/lib/Sidecar.ts",
+      "require": "./src/lib/Sidecar.ts"
     },
-    "./src/SubPackages/react-dom/component/web": {
-      "import": "./dist/module/SubPackages/react-dom/component/web.js",
-      "require": "./dist/common/SubPackages/react-dom/component/web.js"
+    "./src/PureSidecar": {
+      "import": "./src/PureSidecar.ts",
+      "require": "./src/PureSidecar.ts"
     },
-    "./src/SubPackages/react-dom/component/node": {
-      "import": "./dist/module/SubPackages/react-dom/component/node.js",
-      "require": "./dist/common/SubPackages/react-dom/component/node.js"
+    "./src/NodeSidecar": {
+      "import": "./src/NodeSidecar.ts",
+      "require": "./src/NodeSidecar.ts"
     },
-    "./src/lib/abstractBase": {
-      "import": "./src/lib/abstractBase.ts",
-      "require": "./src/lib/abstractBase.ts"
+    "./src/WebSidecar": {
+      "import": "./src/WebSidecar.ts",
+      "require": "./src/WebSidecar.ts"
     },
     "./src/Types": {
       "import": "./src/Types.ts",
@@ -205,7 +121,7 @@
     "build-hard": "rm -rf dist/** && yarn bundle &&  yarn build && yarn type-check",
     "doit": "rm -rf node_modules && yarn install && yarn build",
     "build": "sh prebuild.sh; cp ./src/cjs-shim.js ./dist/cjs-shim.js; tsc -p tsconfig.module.json; tsc -p tsconfig.common.json; tsc -p tsconfig.types.json; sh postBuild.sh; yarn bundle",
-    "dev": "cp ./src/cjs-shim.js ./dist/cjs-shim.js && tsc -p tsconfig.module.json --watch & tsc -p tsconfig.common.json --watch & tsc -p tsconfig.types.json --watch ",
+    "dev": "sh prebuild.sh;  cp ./src/cjs-shim.js ./dist/cjs-shim.js; sh postBuild.sh; tsc -p tsconfig.module.json --watch & tsc -p tsconfig.common.json --watch  ",
     "bundle": "node bundle.js",
     "build-module": "tsc -p tsconfig.module.json",
     "build-common": "tsc -p tsconfig.common.json",
@@ -249,6 +165,7 @@
   "dependencies": {
     "@bscotch/debounce-watch": "^1.1.0",
     "@humanwhocodes/config-array": "^0.13.0",
+    "@jest/globals": "^30.0.4",
     "@types/eslint": "^9.6.1",
     "@types/node-static": "^0.7.11",
     "@ungap/structured-clone": "^1.3.0",
@@ -262,7 +179,9 @@
     "esbuild-plugin-external-package": "^1.0.0",
     "esbuild-plugin-import-map": "^2.1.0",
     "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/Init.ts

@@ -1,5 +1,5 @@
+/* eslint-disable @typescript-eslint/no-unused-vars */
 import fs from "fs";
-import esbuild from "esbuild";
 
 export default async () => {
   [
@@ -11,6 +11,7 @@ export default async () => {
     `testeranto/reports`,
     `testeranto/reports/`,
     `testeranto/features/`,
+    `testeranto/externalTests/`,
   ].forEach((f) => {
     try {
       fs.mkdirSync(`${process.cwd()}/${f}`);
@@ -34,10 +35,10 @@ export default async () => {
     `testeranto/Project.css`
   );
 
-  fs.copyFileSync(
-    `node_modules/testeranto/dist/prebuild/ReportClient.css`,
-    `testeranto/ReportClient.css`
-  );
+  // fs.copyFileSync(
+  //   `node_modules/testeranto/dist/prebuild/ReportClient.css`,
+  //   `testeranto/ReportClient.css`
+  // );
 
   fs.copyFileSync(
     `node_modules/testeranto/dist/prebuild/TestReport.js`,