testeranto 0.135.0 → 0.140.1

package/docs/index.md

@@ -1,10 +1,14 @@
-## Core Concepts
+# Testeranto docs and 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.
+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.
+
+### ⚠️ this doc is a work in progress. It is 99% accurate but needs some attention to be complete. ⚠️
+
+Let's break down the key components using a Rectangle class example.
 
 ### The Test Subject
 
-First, define the class you want to test:
+This is the thing-to-be-tested, for this example, a very simple implementation of a Rectangle
 
 ```typescript
 class Rectangle {
@@ -22,81 +26,130 @@ class Rectangle {
 }
 ```
 
-### Teseranto's 3 main functions
+### Testeranto's 3 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";
+import Testeranto from "testeranto/src/Node"; // <- import the Node main function
+// below this point, all runtimes are identical!
 
-export default Testeranto(
-  null,
-  RectangleTesterantoBaseTestSpecification,
-  RectangleTesterantoBaseTestImplementation,
-  RectangleTesterantoBaseInterface
+// Note the type parameters I, O, and M: these will be important later
+export default Testeranto<
+  I extends Ibdd_in,
+  O extends Ibdd_out,
+  M
+  >(
+    Rectangle.prototype, // <- the subject of the test.
+    specification,
+    implementation,
+    interface
 );
 ```
 
 #### Web
 
 ```ts
-import Testeranto from "testeranto/src/Web";
+import Testeranto from "testeranto/src/Web"; // <- import the Web main function
+// below this point, all runtimes are identical!
 
-import { RectangleTesterantoBaseTestImplementation } from "./Rectangle.test.implementation";
-import { RectangleTesterantoBaseTestSpecification } from "./Rectangle.test.specification";
-import { RectangleTesterantoBaseInterface } from "./Rectangle.test.interface";
+import { implementation } from "./Rectangle.test.implementation";
+import { specification } from "./Rectangle.test.specification";
+import { interface } from "./Rectangle.test.interface";
 
-export default Testeranto(
-  null,
-  RectangleTesterantoBaseTestSpecification,
-  RectangleTesterantoBaseTestImplementation,
-  RectangleTesterantoBaseInterface
+// Note the type parameters I, O, and M: these will be important later
+export default Testeranto<
+  I extends Ibdd_in,
+  O extends Ibdd_out,
+  M
+  >(
+    Rectangle.prototype, // <- the subject of the test.
+    specification,
+    implementation,
+    interface
 );
 ```
 
 #### Pure
 
 ```ts
-import Testeranto from "testeranto/src/Pure";
+import Testeranto from "testeranto/src/Pure"; // <- import the Pure main function
+// below this point, all runtimes are identical!
 
-import { RectangleTesterantoBaseTestImplementation } from "./Rectangle.test.implementation";
-import { RectangleTesterantoBaseTestSpecification } from "./Rectangle.test.specification";
-import { RectangleTesterantoBaseInterface } from "./Rectangle.test.interface";
+import { implementation } from "./Rectangle.test.implementation";
+import { specification } from "./Rectangle.test.specification";
+import { interface } from "./Rectangle.test.interface";
 
-export default Testeranto(
-  null,
-  RectangleTesterantoBaseTestSpecification,
-  RectangleTesterantoBaseTestImplementation,
-  RectangleTesterantoBaseInterface
+// Note the type parameters I, O, and M: these will be important later
+export default Testeranto<
+  I extends Ibdd_in,
+  O extends Ibdd_out,
+  M
+  >(
+    Rectangle.prototype, // <- the subject of the test.
+    specification,
+    implementation,
+    interface
 );
 ```
 
-### Testeranto functions and types
-
-Every testeranto test has 4-5 components:
+### 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
+```
 
-1. ITestSpecification
-2. ITestImplementation
-3. ITestInterface
-4. Ibdd_in
-5. Ibdd_out
-6. the "modifier" type
+#### The Specification (ITestSpecification)
 
-#### The Specification aka ITestSpecification
+The Specification defines the business requirements in plain language, completely separate from implementation details. This is where you describe **what** should be tested without worrying about **how**.
 
-The Specification defines the business logic of your tests, divorced from implementation details.
+- Pure business logic
+- Human-readable test descriptions
+- Defines test suites, scenarios (Given/When/Then)
+- Maps directly to BDD concepts
+- Uses Ibdd_out for type safety
 
 ```typescript
-export const RectangleTesterantoBaseTestSpecification: ITestSpecification<
-  I,
-  O
-> = (Suite, Given, When, Then, Check) => {
+import {
+  Ibdd_in,
+  Ibdd_out,
+  ITestSpecification,
+} from "testeranto/src/CoreTypes";
+
+//  Note the type parameters I and O. These are important!
+export const specification: ITestSpecification<
+  I extends Ibdd_in,
+  O extends Ibdd_out,
+> = (
+  Suite,
+  Given,
+  When,
+  Then,
+  Check
+) => {
   return [
     Suite.Default(
       "Testing the Rectangle class",
@@ -113,20 +166,34 @@ export const RectangleTesterantoBaseTestSpecification: ITestSpecification<
         ),
       },
 
+      // Ignore this for now
       []
     ),
   ];
 };
 ```
 
-#### The Implementation aka ITestImplementation
+#### The Implementation (ITestImplementation)
 
-The Implementation defines the hooks that the Specification will call.
+The Implementation provides the concrete operations that bring specifications to life. This is where you define **how** each test step actually works.
+
+- `suites`: Test grouping and organization
+- `givens`: Initial test states/setup
+- `whens`: Actions that change state
+- `thens`: Assertions and validations
+- `checks`: Additional verification points
 
 ```ts
-export const RectangleTesterantoBaseTestImplementation: ITestImplementation<
-  I,
-  O,
+import {
+  Ibdd_in,
+  Ibdd_out,
+  ITestImplementation,
+} from "testeranto/src/CoreTypes";
+
+//  Note the type parameters I and O. These are important!
+export const implementation: ITestImplementation<
+  I extends Ibdd_in,
+  O extends Ibdd_out,
   M
 > = {
   suites: {
@@ -176,10 +243,19 @@ export const RectangleTesterantoBaseTestImplementation: 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 "before all", "after all", "before each", and "after each", all of which are optional.
+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
 
 ```ts
-export const RectangleTesterantoBaseInterface: ITestInterface<I> = {
+
+import {
+  Ibdd_in,
+  ITestInterface,
+} from "testeranto/src/CoreTypes";
+
+//  Note the type parameter. This is important!
+export const testInterface: ITestInterface<
+  I extends Ibdd_in,
+> = {
   beforeEach: async (subject, i) => {
     return i();
   },
@@ -202,6 +278,9 @@ export const RectangleTesterantoBaseInterface: ITestInterface<I> = {
 this type describes the "inner" shape of your BDD tests.
 
 ```ts
+import { Ibdd_in } from "testeranto/src/CoreTypes";
+
+// TODO this is inaccurate
 export type I = Ibdd_in<
   null,
   null,
@@ -218,6 +297,8 @@ export type I = Ibdd_in<
 this type describes the "outer" shape of your BDD tests.
 
 ```ts
+import { Ibdd_out } from "testeranto/src/CoreTypes";
+
 export type O = Ibdd_out<
   // Suite
   {
@@ -274,4 +355,213 @@ export type M = {
     ) => (rectangle: Rectangle, utils: PM) => Rectangle;
   };
 };
+```
+
+## Putting it all together
+
+```ts
+//  Make sure you import the right runtime
+import Testeranto from "testeranto/src/Pure";
+
+import {
+  Ibdd_in,
+  Ibdd_out,
+  ITestImplementation,
+  ITestSpecification,
+  ITestInterface,
+} from "testeranto/src/CoreTypes";
+
+// The test subject
+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;
+  }
+}
+
+////////////////////////////////////////////////////////
+
+// TODO this is inaccurate
+type I = Ibdd_in<
+  null,
+  null,
+  Rectangle,
+  Rectangle,
+  Rectangle,
+  (...x) => (rectangle: Rectangle, utils: IPM) => Rectangle,
+  (rectangle: Rectangle, utils: IPM) => Rectangle
+>;
+
+type O = Ibdd_out<
+  // Suites
+  {
+    Default: [string];
+  },
+  // Givens
+  {
+    Default;
+    WidthOfOneAndHeightOfOne;
+    WidthAndHeightOf: [number, number];
+  },
+  // Whens
+  {
+    HeightIsPubliclySetTo: [number];
+    WidthIsPubliclySetTo: [number];
+    setWidth: [number];
+    setHeight: [number];
+  },
+  // Thens
+  {
+    AreaPlusCircumference: [number];
+    circumference: [number];
+    getWidth: [number];
+    getHeight: [number];
+    area: [number];
+    prototype: [];
+  },
+  // Checks are broken right now, ignore them
+  {
+    Default;
+    WidthOfOneAndHeightOfOne;
+    WidthAndHeightOf: [number, number];
+  }
+>;
+
+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;
+  };
+};
+
+const testInterface: ITestInterface<
+  I extends Ibdd_in,
+> = {
+  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) => {},
+};
+
+const testImplementation: ITestImplementation<
+  I extends Ibdd_in,
+  O extends Ibdd_out,
+  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),
+  },
+};
+
+const testSpecification: ITestSpecification<
+  I extends Ibdd_in,
+  O extends Ibdd_out,
+> = (
+  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)]
+        ),
+      },
+
+      // Ignore this for now
+      []
+    ),
+  ];
+};
+
+// 1 function will launch the test
+export default Testeranto<
+  I extends Ibdd_in,
+  O extends Ibdd_out,
+  M
+  >(
+    Rectangle.prototype,
+    testSpecification,
+    testSmplementation,
+    testSnterface
+);
+
+
+
 ```

package/docs/style.md

@@ -0,0 +1,116 @@
+# Official Color Palette
+
+<div class="color-sampler">
+  <div class="color-group">
+    <h2>Primary Colors</h2>
+    <div class="color-row">
+      <div class="color-swatch" style="background-color: #ff6b6b; color: white;">
+        <span class="hex">#ff6b6b</span>
+        <span class="name">Coral Blush</span>
+      </div>
+      <div class="color-swatch" style="background-color: #4ecdc4; color: white;">
+        <span class="hex">#4ecdc4</span>
+        <span class="name">Mint Teal</span>
+      </div>
+      <div class="color-swatch" style="background-color: #E6B422; color: #292f36;">
+        <span class="hex">#E6B422</span>
+        <span class="name">Muted Gold</span>
+      </div>
+      <div class="color-swatch" style="background-color: #00B4A0; color: white;">
+        <span class="hex">#00B4A0</span>
+        <span class="name">Deep Teal</span>
+      </div>
+    </div>
+  </div>
+
+  <div class="color-group">
+    <h2>Text & Background</h2>
+    <div class="color-row">
+      <div class="color-swatch" style="background-color: #292f36; color: white;">
+        <span class="hex">#292f36</span>
+        <span class="name">Midnight Ink</span>
+      </div>
+      <div class="color-swatch" style="background-color: #f1faee; color: #292f36;">
+        <span class="hex">#f1faee</span>
+        <span class="name">Pearl Mist</span>
+      </div>
+    </div>
+  </div>
+
+  <div class="color-group">
+    <h2>Gradient Colors</h2>
+    <div class="color-row">
+      <div class="color-swatch" style="background-color: #0a0f1f; color: white;">
+        <span class="hex">#0a0f1f</span>
+        <span class="name">Deep Cosmos</span>
+      </div>
+      <div class="color-swatch" style="background-color: #1a2b50; color: white;">
+        <span class="hex">#1a2b50</span>
+        <span class="name">Twilight Navy</span>
+      </div>
+      <div class="color-swatch" style="background-color: #B07D85; color: white;">
+        <span class="hex">#B07D85</span>
+        <span class="name">Muted Rose</span>
+      </div>
+      <div class="color-swatch" style="background-color: #7fb3d5; color: white;">
+        <span class="hex">#7fb3d5</span>
+        <span class="name">Sky Whisper</span>
+      </div>
+    </div>
+  </div>
+</div>
+
+<style>
+.color-sampler {
+  margin: 2rem 0;
+  max-width: 800px;
+}
+
+.color-group {
+  margin-bottom: 2rem;
+}
+
+.color-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 1rem;
+  margin-top: 1rem;
+}
+
+.color-swatch {
+  flex: 1;
+  min-width: 150px;
+  padding: 1rem;
+  border-radius: 8px;
+  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  height: 100px;
+  transition: transform 0.2s ease;
+}
+
+.color-swatch:hover {
+  transform: translateY(-5px);
+}
+
+.hex {
+  font-family: monospace;
+  font-weight: bold;
+  font-size: 1.1rem;
+}
+
+.name {
+  font-style: italic;
+  margin-top: 0.5rem;
+}
+</style>
+
+## Usage Guidelines
+
+- Use "Coral Blush" for primary actions and important elements
+- "Mint Teal" works well for secondary actions and accents
+- The gradient colors create the sunrise effect from dark to light
+- "Muted Gold" and "Deep Teal" provide sophisticated accents
+- "Midnight Ink" and "Pearl Mist" ensure good text contrast