testeranto 0.134.0 → 0.140.0

package/docs/index.md

@@ -0,0 +1,567 @@
+# 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.
+
+### ⚠️ 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
+
+This is the thing-to-be-tested, for this example, a very simple implementation of a Rectangle
+
+```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;
+  }
+}
+```
+
+### 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 the Node main function
+// below this point, all runtimes are identical!
+
+// 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 the Web 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,
+  O extends Ibdd_out,
+  M
+  >(
+    Rectangle.prototype, // <- the subject of the test.
+    specification,
+    implementation,
+    interface
+);
+```
+
+#### Pure
+
+```ts
+import Testeranto from "testeranto/src/Pure"; // <- import the Pure 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,
+  O extends Ibdd_out,
+  M
+  >(
+    Rectangle.prototype, // <- the subject of the test.
+    specification,
+    implementation,
+    interface
+);
+```
+
+### 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
+```
+
+#### The Specification (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**.
+
+- 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
+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",
+      {
+        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
+      []
+    ),
+  ];
+};
+```
+
+#### The Implementation (ITestImplementation)
+
+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
+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: {
+    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 the traditional BDD steps "before all", "after all", "before each", "after each", etc
+
+```ts
+
+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();
+  },
+  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
+import { Ibdd_in } from "testeranto/src/CoreTypes";
+
+// TODO this is inaccurate
+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
+import { Ibdd_out } from "testeranto/src/CoreTypes";
+
+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;
+  };
+};
+```
+
+## 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