npm - testeranto - Versions diffs - 0.135.0 → 0.140.0 - Mend

testeranto 0.135.0 → 0.140.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (187) hide show

package/docs.html ADDED Viewed

@@ -0,0 +1,537 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>index.md</title>
+    <!-- Prism.js CSS -->
+    <link href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/themes/prism-tomorrow.min.css" rel="stylesheet" />
+    <link href="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/plugins/line-numbers/prism-line-numbers.min.css" rel="stylesheet" />
+    <!-- load style AFTER prism -->
+    <link rel="stylesheet" href="style.css">
+</head>
+<body>
+    <div class="parallax-background"></div>
+    <div id="container">
+        <h1>Testeranto docs and core concepts</h1>
+<p>Testeranto&#39;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 <strong>3 core functions and 5 essential types</strong>. Follow these patterns, and TypeScript&#39;s type checker will guide you through the rest.</p>
+<h3>⚠️ this doc is a work in progress. It is 99% accurate but needs some attention to be complete. ⚠️</h3>
+<p>Let&#39;s break down the key components using a Rectangle class example.</p>
+<h3>The Test Subject</h3>
+<p>This is the thing-to-be-tested, for this example, a very simple implementation of a Rectangle</p>
+<pre class="language-typescript line-numbers"><code class="language-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;
+  }
+}</code></pre><h3>Testeranto&#39;s 3 functions</h3>
+<p>For each of testeranto&#39;s runtime, there is a specific Testeranto main function. Each is it&#39;s own import but all 3 are called in the same way.</p>
+<h4>Node</h4>
+<pre>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
+);</pre><h4>Web</h4>
+<pre>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
+);</pre><h4>Pure</h4>
+<pre>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
+);</pre><h3>Testeranto&#39;s 5 Essential Types</h3>
+<p>Every testeranto test is built around these 5 types that form a complete testing pipeline:</p>
+<ol>
+<li><strong>ITestSpecification</strong> - The &quot;what&quot; of your tests (business requirements)</li>
+<li><strong>ITestImplementation</strong> - The &quot;how&quot; of your tests (concrete operations)</li>
+<li><strong>ITestInterface</strong> - The &quot;glue&quot; between specs and implementation</li>
+<li><strong>Ibdd_in</strong> - Defines the internal test flow shape</li>
+<li><strong>Ibdd_out</strong> - Defines the external test interface</li>
+</ol>
+<pre class="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</pre><h4>The Specification (ITestSpecification)</h4>
+<p>The Specification defines the business requirements in plain language, completely separate from implementation details. This is where you describe <strong>what</strong> should be tested without worrying about <strong>how</strong>.</p>
+<ul>
+<li>Pure business logic</li>
+<li>Human-readable test descriptions</li>
+<li>Defines test suites, scenarios (Given/When/Then)</li>
+<li>Maps directly to BDD concepts</li>
+<li>Uses Ibdd_out for type safety</li>
+</ul>
+<pre class="language-typescript line-numbers"><code class="language-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
+      []
+    ),
+  ];
+};</code></pre><h4>The Implementation (ITestImplementation)</h4>
+<p>The Implementation provides the concrete operations that bring specifications to life. This is where you define <strong>how</strong> each test step actually works.</p>
+<ul>
+<li><code>suites</code>: Test grouping and organization</li>
+<li><code>givens</code>: Initial test states/setup</li>
+<li><code>whens</code>: Actions that change state</li>
+<li><code>thens</code>: Assertions and validations</li>
+<li><code>checks</code>: Additional verification points</li>
+</ul>
+<pre>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),
+  },
+};</pre><h4>The Interface aka ITestInterface</h4>
+<p>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 &quot;before all&quot;, &quot;after all&quot;, &quot;before each&quot;, &quot;after each&quot;, etc</p>
+<pre>
+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) => {},
+};</pre><h4>type I aka Ibdd_in</h4>
+<p>this type describes the &quot;inner&quot; shape of your BDD tests.</p>
+<pre>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
+>;</pre><h4>type O aka Ibdd_out</h4>
+<p>this type describes the &quot;outer&quot; shape of your BDD tests.</p>
+<pre>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];
+  }
+>;</pre><h4>type M (optional)</h4>
+<p>this type describes the modifications to the shape of the &quot;specification&quot;. It can be used to make your BDD tests DRYer but is not necessary</p>
+<pre>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;
+  };
+};</pre><h2>Putting it all together</h2>
+<pre>//  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
+);
+</pre>
+    </div>
+    <!-- Prism.js JS -->
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/prism.min.js"></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/components/prism-typescript.min.js"></script>
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/prism/1.29.0/plugins/line-numbers/prism-line-numbers.min.js"></script>
+    <script>
+        document.addEventListener('DOMContentLoaded', function() {
+            Prism.highlightAll();
+            // Parallax effect
+            const parallaxBg = document.querySelector('.parallax-background');
+            window.addEventListener('scroll', function() {
+                const scrollPosition = window.pageYOffset;
+                parallaxBg.style.transform = 'translateY(scrollPosition)';
+            });
+        });
+    </script>
+</body>
+</html>