puty 0.0.2 → 0.0.3

package/README.md

@@ -1,6 +1,27 @@
-# Puty: Pure Unit Test in Yaml
+# Puty: Pure Unit Test in YAML
 
-Write unit test specifications using YAML files, powered by vitest as the test runner.
+Puty is a declarative testing framework that allows you to write unit tests using YAML files instead of JavaScript code. It's built on top of [Vitest](https://vitest.dev/) and designed to make testing more accessible and maintainable by separating test data from test logic.
+
+Puty is ideal for testing pure functions - functions that always return the same output for the same input and have no side effects. The declarative YAML format perfectly captures the essence of pure function testing: given these inputs, expect this output.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Usage](#usage)
+  - [Testing Functions](#testing-functions)
+  - [Testing Classes](#testing-classes)
+  - [Error Testing](#error-testing)
+  - [Using !include Directive](#using-include-directive)
+- [YAML Structure](#yaml-structure)
+
+## Features
+
+- 📝 Write tests in simple YAML format
+- 📦 Modular test organization with `!include` directive
+- 🎯 Clear separation of test data and test logic
+- ⚡ Powered by Vitest for fast test execution
 
 ## Installation
 
@@ -8,26 +29,71 @@ Write unit test specifications using YAML files, powered by vitest as the test r
 npm install puty
 ```
 
-create a file in your project `puty.test.js`
+## Quick Start
+
+
+1. Create a test runner file `puty.test.js` in your project:
+
 ```js
-import { setupTestSuiteFromYaml } from "./puty.js";
+import { setupTestSuiteFromYaml } from "puty";
+
+// Search for test files in the current directory
 await setupTestSuiteFromYaml();
+
+// Or specify a different directory
+// await setupTestSuiteFromYaml("./tests");
 ```
 
-This function will read for all `.spec.yaml` and `.test.yaml` files in the current directory and run the tests.
+**Note:** Puty uses ES module imports and requires your project to support ES modules. If you're using Node.js, make sure to add `"type": "module"` to your `package.json` or use `.mjs` file extensions.
 
-run
 
+2. Create your first test file `math.test.yaml`:
+
+```yaml
+file: './math.js'
+group: math
+suites: [add]
+---
+suite: add
+exportName: add
+---
+case: add two numbers
+in: [2, 3]
+out: 5
 ```
-vitest
+
+3. Run your tests:
+
+```bash
+npx vitest
+```
+
+### Recommended Vitest Configuration
+
+To enable automatic test reruns when YAML test files change, create a `vitest.config.js` file in your project root:
+
+```js
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    forceRerunTriggers: [
+      '**/*.js',
+      '**/*.{test,spec}.yaml',
+      '**/*.{test,spec}.yml'
+    ],
+  },
+});
 ```
 
-It should run all the tests in the file.
+This configuration ensures that Vitest will re-run your tests whenever you modify either your JavaScript source files or your YAML test files.
 
 ## Usage
 
 ### Testing Functions
 
+Here's a complete example of testing JavaScript functions with Puty:
+
 ```yaml
 file: './math.js'
 group: math
@@ -64,6 +130,22 @@ in:
 out: 3
 ```
 
+This under the hood creates a test structure in Vitest like:
+```js
+describe('math', () => {
+  describe('add', () => {
+    it('add 1 and 2', () => { ... })
+    it('add 2 and 2', () => { ... })
+  })
+  describe('increment', () => {
+    it('increment 1', () => { ... })
+    it('increment 2', () => { ... })
+  })
+})
+```
+
+See the [YAML Structure](#yaml-structure) section for detailed documentation of all available fields.
+
 ### Testing Classes
 
 Puty also supports testing classes with method calls and state assertions:
@@ -120,3 +202,110 @@ case: divide by zero
 in: [10, 0]
 throws: "Division by zero"
 ```
+
+### Using !include Directive
+
+Puty supports the `!include` directive to modularize and reuse YAML test files. This is useful for:
+- Sharing common test data across multiple test files
+- Organizing large test suites into smaller, manageable files
+- Reusing test cases for different modules
+
+#### Basic Usage
+
+You can include entire YAML documents:
+
+```yaml
+file: "./math.js"
+group: math-tests
+suites: [add]
+---
+!include ./suite-definition.yaml
+---
+!include ./test-cases.yaml
+```
+
+#### Including Values
+
+You can also include specific values within a YAML document:
+
+```yaml
+case: test with shared data
+in: !include ./test-data/input.yaml
+out: !include ./test-data/expected-output.yaml
+```
+
+#### Recursive Includes
+
+The `!include` directive supports recursive includes, allowing included files to include other files:
+
+```yaml
+# main.yaml
+!include ./level1.yaml
+
+# level1.yaml
+suite: test
+---
+!include ./level2.yaml
+
+# level2.yaml
+case: nested test
+in: []
+out: "success"
+```
+
+#### Important Notes
+
+- File paths in `!include` are relative to the YAML file containing the directive
+- Circular dependencies are detected and will cause an error
+- Missing include files will result in a clear error message
+- Both single documents and multi-document YAML files can be included
+
+
+## YAML Structure
+
+Puty test files use multi-document YAML format with three types of documents:
+
+### 1. Configuration Document (First document)
+
+```yaml
+file: './module.js'        # Required: Path to JS file (relative to YAML file)
+group: 'test-group'        # Required: Test group name (or use 'name')
+suites: ['suite1', 'suite2'] # Optional: List of suites to define
+```
+
+### 2. Suite Definition Documents
+
+```yaml
+suite: 'suiteName'         # Required: Suite name
+exportName: 'functionName' # Optional: Export to test (defaults to suite name or 'default')
+mode: 'class'              # Optional: Set to 'class' for class testing
+constructorArgs: [arg1]    # Optional: Arguments for class constructor (class mode only)
+```
+
+### 3. Test Case Documents
+
+For function tests:
+```yaml
+case: 'test description'   # Required: Test case name
+in: [arg1, arg2]          # Required: Input arguments
+out: expectedValue        # Optional: Expected output (omit if testing for errors)
+throws: 'Error message'   # Optional: Expected error message
+```
+
+For class tests:
+```yaml
+case: 'test description'
+executions:
+  - method: 'methodName'
+    in: [arg1]
+    out: expectedValue    # Optional
+    throws: 'Error msg'   # Optional
+    asserts:
+      - property: 'prop'
+        op: 'eq'          # Currently only 'eq' is supported
+        value: expected
+      - method: 'getter'
+        in: []
+        out: expected
+```
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "puty",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "A tooling function to test javascript functions and classes.",
   "main": "src/index.js",
   "type": "module",

package/src/index.js

@@ -1,3 +1,12 @@
+/**
+ * @fileoverview Main entry point for the puty testing framework
+ * Exports the primary function for setting up YAML-driven test suites.
+ */
+
 import { setupTestSuiteFromYaml } from "./puty.js";
 
+/**
+ * Main entry point function for discovering and setting up test suites from YAML files
+ * @see {@link setupTestSuiteFromYaml} for detailed documentation
+ */
 export { setupTestSuiteFromYaml };

package/src/puty.js

@@ -1,14 +1,42 @@
+/**
+ * @fileoverview Main test framework functionality for YAML-driven testing
+ * This module provides functions for setting up test suites from YAML configurations,
+ * injecting functions/classes from modules, and executing tests using vitest.
+ */
+
 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, parseWithIncludes } from "./utils.js";
 
+/**
+ * File extensions that are recognized as YAML test files
+ * @type {string[]}
+ */
 const extensions = [".test.yaml", ".test.yml", ".spec.yaml", ".spec.yml"];
 
 /**
- * Parse YAML content with document separators into structured test config
+ * Parses YAML content containing multiple documents separated by '---' into a structured test configuration
+ * @param {string} yamlContent - Raw YAML content string to parse
+ * @returns {Object} Structured test configuration object
+ * @returns {string|null} returns.file - Path to the JavaScript file being tested
+ * @returns {string|null} returns.group - Test group name  
+ * @returns {string[]} [returns.suiteNames] - Array of suite names defined in config
+ * @returns {Object[]} returns.suites - Array of test suite objects
+ * @example
+ * const yamlContent = `
+ * file: './math.js'
+ * group: math
+ * ---
+ * suite: add
+ * exportName: add
+ * ---
+ * case: add 1 and 2
+ * in: [1, 2]
+ * out: 3
+ * `;
+ * const config = parseYamlDocuments(yamlContent);
  */
 export const parseYamlDocuments = (yamlContent) => {
   const docs = yaml.loadAll(yamlContent);
@@ -68,8 +96,19 @@ export const parseYamlDocuments = (yamlContent) => {
 };
 
 /**
- *
- * @param {*} testConfig
+ * Sets up and registers test suites with the testing framework (vitest)
+ * @param {Object} testConfig - Test configuration object containing suites and cases
+ * @param {string} testConfig.group - Name of the test group (used as describe block name)
+ * @param {Object[]} testConfig.suites - Array of test suite objects
+ * @param {boolean} [testConfig.skip] - Whether to skip this entire test suite
+ * @example
+ * setupTestSuite({
+ *   group: 'math',
+ *   suites: [{
+ *     name: 'add',
+ *     cases: [{ name: 'add 1+2', functionUnderTest: addFn, in: [1,2], out: 3 }]
+ *   }]
+ * });
  */
 const setupTestSuite = (testConfig) => {
   const { group, suites, skip } = testConfig;
@@ -91,6 +130,16 @@ const setupTestSuite = (testConfig) => {
   });
 };
 
+/**
+ * Sets up individual test cases for function-based testing
+ * @param {Object} suite - Test suite configuration
+ * @param {Object[]} suite.cases - Array of test case objects
+ * @param {string} suite.cases[].name - Test case name
+ * @param {any[]} suite.cases[].in - Input arguments for the function
+ * @param {any} suite.cases[].out - Expected output value
+ * @param {Function} suite.cases[].functionUnderTest - The function to test
+ * @param {string|RegExp} [suite.cases[].throws] - Expected error message/pattern if function should throw
+ */
 const setupFunctionTests = (suite) => {
   const { cases } = suite;
   for (const testCase of cases) {
@@ -117,6 +166,15 @@ const setupFunctionTests = (suite) => {
   }
 };
 
+/**
+ * Sets up individual test cases for class-based testing
+ * @param {Object} suite - Test suite configuration for class testing
+ * @param {Object[]} suite.cases - Array of test case objects
+ * @param {string} suite.cases[].name - Test case name  
+ * @param {Object[]} suite.cases[].executions - Array of method executions to perform
+ * @param {Function} suite.ClassUnderTest - The class constructor to test
+ * @param {any[]} suite.constructorArgs - Arguments to pass to class constructor
+ */
 const setupClassTests = (suite) => {
   const { cases, ClassUnderTest, constructorArgs } = suite;
   for (const testCase of cases) {
@@ -185,10 +243,19 @@ const setupClassTests = (suite) => {
 };
 
 /**
- *
- * @param {*} module
- * @param {*} originalTestConfig
- * @returns
+ * Injects functions and classes from an imported module into test configuration objects
+ * @param {Object} module - The imported JavaScript module containing functions/classes to test
+ * @param {Object} originalTestConfig - Original test configuration object
+ * @returns {Object} Test configuration with injected functions/classes ready for testing
+ * @throws {Error} When required exports are not found in the module
+ * @example
+ * // Import module and inject functions
+ * const module = await import('./math.js');
+ * const testConfig = { 
+ *   suites: [{ name: 'add', exportName: 'add', cases: [...] }] 
+ * };
+ * const ready = injectFunctions(module, testConfig);
+ * // ready.suites[0].cases[0].functionUnderTest === module.add
  */
 export const injectFunctions = (module, originalTestConfig) => {
   const testConfig = structuredClone(originalTestConfig);
@@ -222,13 +289,23 @@ export const injectFunctions = (module, originalTestConfig) => {
 };
 
 /**
- * Setup test suites from all yaml files in the current directory and its subdirectories
+ * Discovers and sets up test suites from all YAML test files in a directory and its subdirectories
+ * @param {string} dirname - Directory path to search for YAML test files
+ * @returns {Promise<void>} Promise that resolves when all test suites are set up
+ * @throws {Error} When YAML files cannot be parsed or modules cannot be imported
+ * @example
+ * // Set up all test suites from YAML files in the current directory
+ * await setupTestSuiteFromYaml('.');
+ * 
+ * // Set up tests from a specific directory
+ * await setupTestSuiteFromYaml('./tests');
+ * 
+ * // This will find all files matching: *.test.yaml, *.test.yml, *.spec.yaml, *.spec.yml
  */
 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

@@ -1,23 +1,88 @@
+/**
+ * @fileoverview Utility functions for YAML processing with !include directive support
+ * This module provides functions for loading YAML files with include capabilities,
+ * directory traversal, and parsing YAML test configurations.
+ */
+
 import fs from "node:fs";
 import path, { join } from "node:path";
 
 import yaml from "js-yaml";
 
-export const loadYamlWithPath = (path) => {
+/**
+ * Loads a YAML file with support for !include directives and circular dependency detection
+ * @param {string} filePath - Absolute or relative path to the YAML file to load
+ * @param {Set<string>} [visitedFiles=new Set()] - Set of already visited file paths for circular dependency detection
+ * @returns {any|any[]} The parsed YAML content. Returns single object for single documents, array for multi-document YAML
+ * @throws {Error} When circular dependencies are detected, files are not found, or YAML parsing fails
+ * @example
+ * // Load a simple YAML file
+ * const config = loadYamlWithPath('./config.yaml');
+ * 
+ * // Load YAML with includes
+ * const data = loadYamlWithPath('./main.yaml'); // main.yaml contains: data: !include ./data.yaml
+ */
+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");
+    // Always use loadAll - it handles both single and multi-document YAML
+    const docs = yaml.loadAll(content, { schema });
+    // If only one document, return it directly (not as array)
+    return docs.length === 1 ? docs[0] : docs;
+  } 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);
+  }
 };
 
 /**
- * Traverse all files in the current directory and its subdirectories
- * Return an array of full path of files
+ * Recursively traverses a directory and returns all files matching the specified extensions
+ * @param {string} startPath - The directory path to start traversing from
+ * @param {string[]} extensions - Array of file extensions to match (e.g., ['.yaml', '.yml'])
+ * @returns {string[]} Array of absolute file paths for all matching files found
+ * @example
+ * // Find all YAML test files
+ * const testFiles = traverseAllFiles('./tests', ['.test.yaml', '.spec.yml']);
+ * 
+ * // Find all JavaScript files
+ * const jsFiles = traverseAllFiles('./src', ['.js', '.ts']);
  */
 export const traverseAllFiles = (startPath, extensions) => {
   const results = [];
@@ -33,3 +98,131 @@ export const traverseAllFiles = (startPath, extensions) => {
   }
   return results;
 };
+
+/**
+ * Recursively flattens nested arrays of YAML documents that result from multi-document includes
+ * @param {any|any[]} data - The data to flatten, can be a single document or nested arrays
+ * @returns {any[]} Flattened array of documents
+ * @example
+ * // Flatten nested document arrays
+ * const nested = [doc1, [doc2, doc3], doc4];
+ * const flat = flattenDocuments(nested); // [doc1, doc2, doc3, doc4]
+ */
+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;
+};
+
+/**
+ * Processes an array of YAML documents and converts them into a structured test configuration
+ * @param {any[]} docs - Array of YAML document objects to process
+ * @returns {Object} Structured test configuration object
+ * @returns {string|null} returns.file - Path to the JavaScript file being tested
+ * @returns {string|null} returns.group - Test group name
+ * @returns {string[]} [returns.suiteNames] - Array of suite names defined in config
+ * @returns {Object[]} returns.suites - Array of test suite objects
+ * @returns {string} returns.suites[].name - Suite name
+ * @returns {string} returns.suites[].exportName - Function/class export name to test
+ * @returns {Object[]} returns.suites[].cases - Array of test cases
+ * @returns {string} [returns.suites[].mode] - Test mode ('class' for class testing)
+ * @returns {any[]} [returns.suites[].constructorArgs] - Constructor arguments for class mode
+ * @example
+ * const docs = [
+ *   { file: './math.js', group: 'math', suites: ['add'] },
+ *   { suite: 'add', exportName: 'add' },
+ *   { case: 'add 1+2', in: [1, 2], out: 3 }
+ * ];
+ * const config = processDocuments(docs);
+ */
+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;
+};
+
+/**
+ * Parses a YAML file with !include directive support and converts it into a structured test configuration
+ * @param {string} filePath - Path to the YAML file to parse
+ * @returns {Object} Structured test configuration object ready for test execution
+ * @throws {Error} When file cannot be found, YAML is invalid, or circular dependencies are detected
+ * @example
+ * // Parse a test configuration file with includes
+ * const config = parseWithIncludes('./tests/math.spec.yaml');
+ * // Returns: { file: './math.js', group: 'math', suites: [...] }
+ * 
+ * // Works with files containing !include directives
+ * // main.yaml: 
+ * // file: './lib.js'
+ * // ---
+ * // !include ./test-cases.yaml
+ * const config = parseWithIncludes('./main.yaml');
+ */
+export const parseWithIncludes = (filePath) => {
+  const yamlData = loadYamlWithPath(filePath);
+
+  // Flatten any nested arrays that come from multi-document includes
+  const flattenedDocs = flattenDocuments(yamlData);
+
+  return processDocuments(flattenedDocs);
+};