puty 0.0.1 → 0.0.3-rc1

package/README.md

@@ -26,6 +26,8 @@ It should run all the tests in the file.
 
 ## Usage
 
+### Testing Functions
+
 ```yaml
 file: './math.js'
 group: math
@@ -61,3 +63,60 @@ in:
   - 2
 out: 3
 ```
+
+### Testing Classes
+
+Puty also supports testing classes with method calls and state assertions:
+
+```yaml
+file: './calculator.js'
+group: Calculator
+suites: [basic-operations]
+---
+suite: basic-operations
+mode: 'class'
+exportName: default
+constructorArgs: [10]  # Initial value
+---
+case: add and multiply operations
+executions:
+  - method: add
+    in: [5]
+    out: 15
+    asserts:
+      - property: value
+        op: eq
+        value: 15
+  - method: multiply
+    in: [2]
+    out: 30
+    asserts:
+      - property: value
+        op: eq
+        value: 30
+      - method: getValue
+        in: []
+        out: 30
+```
+
+#### Class Test Structure
+
+- `mode: 'class'` - Indicates this suite tests a class
+- `constructorArgs` - Arguments passed to the class constructor
+- `executions` - Array of method calls to execute in sequence
+  - `method` - Name of the method to call
+  - `in` - Arguments to pass to the method
+  - `out` - Expected return value (optional)
+  - `asserts` - Assertions to run after the method call
+    - Property assertions: Check instance properties
+    - Method assertions: Call methods and check their return values
+
+### Error Testing
+
+You can test that functions or methods throw expected errors:
+
+```yaml
+case: divide by zero
+in: [10, 0]
+throws: "Division by zero"
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "puty",
-  "version": "0.0.1",
+  "version": "0.0.3-rc1",
   "description": "A tooling function to test javascript functions and classes.",
   "main": "src/index.js",
   "type": "module",
@@ -19,5 +19,8 @@
     "lint": "bunx prettier src tests -c",
     "lint:fix": "bunx prettier src tests -w",
     "build": "bun run esbuild.js"
+  },
+  "devDependencies": {
+    "vitest": "^3.2.1"
   }
 }

package/src/puty.js

@@ -1,9 +1,11 @@
 import path from "node:path";
-import fs from "node:fs";
 import yaml from "js-yaml";
 import { expect, test, describe } from "vitest";
 
-import { traverseAllFiles } from "./utils.js";
+import {
+  traverseAllFiles,
+  parseYamlDocumentsWithIncludes as parseWithIncludes,
+} from "./utils.js";
 
 const extensions = [".test.yaml", ".test.yml", ".spec.yaml", ".spec.yml"];
 
@@ -36,12 +38,27 @@ export const parseYamlDocuments = (yamlContent) => {
         exportName: doc.exportName || doc.suite,
         cases: [],
       };
+      // Only add mode and constructorArgs if mode is explicitly 'class'
+      if (doc.mode === "class") {
+        currentSuite.mode = "class";
+        currentSuite.constructorArgs = doc.constructorArgs || [];
+      }
     } else if (doc.case && currentSuite) {
-      currentSuite.cases.push({
+      const testCase = {
         name: doc.case,
-        in: doc.in || [],
-        out: doc.out,
-      });
+      };
+
+      if (currentSuite.mode === "class") {
+        testCase.executions = doc.executions || [];
+      } else {
+        testCase.in = doc.in || [];
+        testCase.out = doc.out;
+        if (doc.throws) {
+          testCase.throws = doc.throws;
+        }
+      }
+
+      currentSuite.cases.push(testCase);
     }
   }
 
@@ -64,28 +81,111 @@ const setupTestSuite = (testConfig) => {
   describe(group, () => {
     for (const suite of suites) {
       describe(suite.name, () => {
-        const { cases } = suite;
-        for (const testCase of cases) {
-          const {
-            name,
-            in: inArg,
-            out: expectedOut,
-            functionUnderTest,
-          } = testCase;
-          test(name, () => {
-            const out = functionUnderTest(...(inArg || []));
-            if (out instanceof Error) {
-              expect(out.message).toEqual(out.message);
-            } else {
-              expect(out).toEqual(expectedOut);
-            }
-          });
+        const { cases, mode } = suite;
+
+        if (mode === "class") {
+          setupClassTests(suite);
+        } else {
+          setupFunctionTests(suite);
         }
       });
     }
   });
 };
 
+const setupFunctionTests = (suite) => {
+  const { cases } = suite;
+  for (const testCase of cases) {
+    const {
+      name,
+      in: inArg,
+      out: expectedOut,
+      functionUnderTest,
+      throws,
+    } = testCase;
+    test(name, () => {
+      if (!functionUnderTest) {
+        throw new Error(`Function not found for test case: ${name}`);
+      }
+
+      if (throws) {
+        // Test expects an error to be thrown
+        expect(() => functionUnderTest(...(inArg || []))).toThrow(throws);
+      } else {
+        const out = functionUnderTest(...(inArg || []));
+        expect(out).toEqual(expectedOut);
+      }
+    });
+  }
+};
+
+const setupClassTests = (suite) => {
+  const { cases, ClassUnderTest, constructorArgs } = suite;
+  for (const testCase of cases) {
+    const { name, executions } = testCase;
+    test(name, () => {
+      if (!ClassUnderTest) {
+        throw new Error(`Class not found for test suite: ${suite.name}`);
+      }
+
+      const instance = new ClassUnderTest(...constructorArgs);
+
+      for (const execution of executions) {
+        const {
+          method,
+          in: inArg,
+          out: expectedOut,
+          throws,
+          asserts,
+        } = execution;
+
+        // Validate method exists
+        if (!instance[method] || typeof instance[method] !== "function") {
+          throw new Error(`Method '${method}' not found on class instance`);
+        }
+
+        // Execute the method and check its return value
+        if (throws) {
+          expect(() => instance[method](...(inArg || []))).toThrow(throws);
+        } else {
+          const result = instance[method](...(inArg || []));
+          if (expectedOut !== undefined) {
+            expect(result).toEqual(expectedOut);
+          }
+        }
+
+        // Run assertions
+        if (asserts) {
+          for (const assertion of asserts) {
+            if (assertion.property) {
+              // Property assertion
+              const actualValue = instance[assertion.property];
+              if (assertion.op === "eq") {
+                expect(actualValue).toEqual(assertion.value);
+              }
+              // Add more operators as needed
+            } else if (assertion.method) {
+              // Method assertion
+              if (
+                !instance[assertion.method] ||
+                typeof instance[assertion.method] !== "function"
+              ) {
+                throw new Error(
+                  `Method '${assertion.method}' not found on class instance for assertion`,
+                );
+              }
+              const result = instance[assertion.method](
+                ...(assertion.in || []),
+              );
+              expect(result).toEqual(assertion.out);
+            }
+          }
+        }
+      }
+    });
+  }
+};
+
 /**
  *
  * @param {*} module
@@ -97,11 +197,27 @@ export const injectFunctions = (module, originalTestConfig) => {
   let functionUnderTest = module[testConfig.exportName || "default"];
 
   for (const suite of testConfig.suites) {
-    if (suite.exportName) {
-      functionUnderTest = module[suite.exportName];
-    }
-    for (const testCase of suite.cases) {
-      testCase.functionUnderTest = functionUnderTest;
+    if (suite.mode === "class") {
+      const exportName = suite.exportName || "default";
+      const exported = module[exportName];
+      if (!exported) {
+        throw new Error(
+          `Export '${exportName}' not found in module for class suite '${suite.name}'`,
+        );
+      }
+      suite.ClassUnderTest = exported;
+    } else {
+      if (suite.exportName) {
+        functionUnderTest = module[suite.exportName];
+        if (!functionUnderTest) {
+          throw new Error(
+            `Export '${suite.exportName}' not found in module for suite '${suite.name}'`,
+          );
+        }
+      }
+      for (const testCase of suite.cases) {
+        testCase.functionUnderTest = functionUnderTest;
+      }
     }
   }
   return testConfig;
@@ -113,8 +229,7 @@ export const injectFunctions = (module, originalTestConfig) => {
 export const setupTestSuiteFromYaml = async (dirname) => {
   const testYamlFiles = traverseAllFiles(dirname, extensions);
   for (const file of testYamlFiles) {
-    const yamlContent = fs.readFileSync(file, "utf8");
-    const testConfig = parseYamlDocuments(yamlContent);
+    const testConfig = parseWithIncludes(file);
     const filepathRelativeToSpecFile = path.join(
       path.dirname(file),
       testConfig.file,

package/src/utils.js

@@ -3,16 +3,56 @@ import path, { join } from "node:path";
 
 import yaml from "js-yaml";
 
-export const loadYamlWithPath = (path) => {
+export const loadYamlWithPath = (filePath, visitedFiles = new Set()) => {
+  const absolutePath = path.resolve(filePath);
+
+  // Check for circular dependencies
+  if (visitedFiles.has(absolutePath)) {
+    throw new Error(
+      `Circular dependency detected: ${absolutePath} is already being processed`,
+    );
+  }
+
+  // Add current file to visited set
+  visitedFiles.add(absolutePath);
+
   const includeType = new yaml.Type("!include", {
     kind: "scalar",
-    construct: function (filePath) {
-      const content = fs.readFileSync(join(path, "..", filePath), "utf8");
-      return yaml.load(content); // you could recurse here
+    construct: function (includePath) {
+      // Resolve include path relative to the current file's directory
+      const currentDir = path.dirname(absolutePath);
+      const resolvedIncludePath = path.resolve(currentDir, includePath);
+
+      // Check if included file exists
+      if (!fs.existsSync(resolvedIncludePath)) {
+        throw new Error(
+          `Include file not found: ${resolvedIncludePath} (included from ${absolutePath})`,
+        );
+      }
+
+      // Recursively load the included file with the same visited files set
+      return loadYamlWithPath(resolvedIncludePath, new Set(visitedFiles));
     },
   });
+
   const schema = yaml.DEFAULT_SCHEMA.extend([includeType]);
-  return yaml.load(fs.readFileSync(path, "utf8"), { schema });
+
+  try {
+    const content = fs.readFileSync(absolutePath, "utf8");
+    // Check if content contains document separators
+    if (content.includes("---")) {
+      return yaml.loadAll(content, { schema });
+    } else {
+      return yaml.load(content, { schema });
+    }
+  } catch (error) {
+    throw new Error(
+      `Error loading YAML file ${absolutePath}: ${error.message}`,
+    );
+  } finally {
+    // Remove current file from visited set when done processing
+    visitedFiles.delete(absolutePath);
+  }
 };
 
 /**
@@ -33,3 +73,93 @@ export const traverseAllFiles = (startPath, extensions) => {
   }
   return results;
 };
+
+/**
+ * Recursively flatten nested arrays of documents
+ */
+const flattenDocuments = (data) => {
+  if (!Array.isArray(data)) {
+    return [data];
+  }
+
+  const result = [];
+  for (const item of data) {
+    if (Array.isArray(item)) {
+      result.push(...flattenDocuments(item));
+    } else {
+      result.push(item);
+    }
+  }
+  return result;
+};
+
+/**
+ * Process an array of YAML documents into structured test config
+ */
+const processDocuments = (docs) => {
+  const config = {
+    file: null,
+    group: null,
+    suites: [],
+  };
+
+  let currentSuite = null;
+
+  for (const doc of docs) {
+    if (doc.file) {
+      config.file = doc.file;
+      config.group = doc.group || doc.name;
+      if (doc.suites) {
+        config.suiteNames = doc.suites;
+      }
+    } else if (doc.suite) {
+      if (currentSuite) {
+        config.suites.push(currentSuite);
+      }
+      currentSuite = {
+        name: doc.suite,
+        exportName: doc.exportName || doc.suite,
+        cases: [],
+      };
+      // Only add mode and constructorArgs if mode is explicitly 'class'
+      if (doc.mode === "class") {
+        currentSuite.mode = "class";
+        currentSuite.constructorArgs = doc.constructorArgs || [];
+      }
+    } else if (doc.case && currentSuite) {
+      const testCase = {
+        name: doc.case,
+      };
+
+      if (currentSuite.mode === "class") {
+        testCase.executions = doc.executions || [];
+      } else {
+        testCase.in = doc.in || [];
+        testCase.out = doc.out;
+        if (doc.throws) {
+          testCase.throws = doc.throws;
+        }
+      }
+
+      currentSuite.cases.push(testCase);
+    }
+  }
+
+  if (currentSuite) {
+    config.suites.push(currentSuite);
+  }
+
+  return config;
+};
+
+/**
+ * Parse YAML file with !include support into structured test config
+ */
+export const parseYamlDocumentsWithIncludes = (filePath) => {
+  const yamlData = loadYamlWithPath(filePath);
+
+  // Flatten any nested arrays that come from multi-document includes
+  const flattenedDocs = flattenDocuments(yamlData);
+
+  return processDocuments(flattenedDocs);
+};