puty 0.0.3 → 0.0.4-rc2

package/README.md

@@ -13,6 +13,7 @@ Puty is ideal for testing pure functions - functions that always return the same
   - [Testing Functions](#testing-functions)
   - [Testing Classes](#testing-classes)
   - [Error Testing](#error-testing)
+  - [Using Mocks](#using-mocks)
   - [Using !include Directive](#using-include-directive)
 - [YAML Structure](#yaml-structure)
 
@@ -21,6 +22,7 @@ Puty is ideal for testing pure functions - functions that always return the same
 - 📝 Write tests in simple YAML format
 - 📦 Modular test organization with `!include` directive
 - 🎯 Clear separation of test data and test logic
+- 🧪 Mock support for testing functions with dependencies
 - ⚡ Powered by Vitest for fast test execution
 
 ## Installation
@@ -186,12 +188,12 @@ executions:
 - `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
+  - `method` - Name of the method to call (supports nested: `user.api.getData`)
   - `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
+    - Property assertions: Check instance properties (supports nested: `user.profile.name`)
+    - Method assertions: Call methods and check their return values (supports nested: `settings.getTheme`)
 
 ### Error Testing
 
@@ -203,6 +205,79 @@ in: [10, 0]
 throws: "Division by zero"
 ```
 
+### Using Mocks
+
+Puty supports mocking dependencies using the `$mock:` syntax. This is useful for testing functions that have external dependencies like loggers, API clients, or callbacks.
+
+#### Basic Mock Example
+
+```yaml
+file: './calculator.js'
+group: calculator
+---
+suite: calculate
+exportName: calculateWithLogger
+---
+case: test with mock logger
+in:
+  - 10
+  - 5
+  - $mock:logger
+out: 15
+mocks:
+  logger:
+    calls:
+      - in: ['Calculating 10 + 5']
+      - in: ['Result: 15']
+```
+
+#### Mock Hierarchy
+
+Mocks can be defined at three levels (case overrides suite, suite overrides global):
+
+```yaml
+file: './service.js'
+group: service
+mocks:
+  globalApi:    # Global mock - available to all suites
+    calls:
+      - in: ['/default']
+        out: { status: 200 }
+---
+suite: userService
+mocks:
+  api:          # Suite mock - available to all cases in this suite
+    calls:
+      - in: ['/users']
+        out: { users: [] }
+---
+case: get user with mock
+in: [123, $mock:api]
+out: { id: 123, name: 'John' }
+mocks:
+  api:          # Case mock - overrides suite mock
+    calls:
+      - in: ['/users/123']
+        out: { id: 123, name: 'John' }
+```
+
+#### Testing Callbacks
+
+Mocks are perfect for testing event-driven code:
+
+```yaml
+case: test event emitter
+executions:
+  - method: on
+    in: ['data', $mock:callback]
+  - method: emit
+    in: ['data', 'hello']
+mocks:
+  callback:
+    calls:
+      - in: ['hello']
+```
+
 ### Using !include Directive
 
 Puty supports the `!include` directive to modularize and reuse YAML test files. This is useful for:
@@ -271,6 +346,11 @@ Puty test files use multi-document YAML format with three types of documents:
 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
+mocks:                     # Optional: Global mocks available to all suites
+  mockName:
+    calls:
+      - in: [args]
+        out: result
 ```
 
 ### 2. Suite Definition Documents
@@ -280,6 +360,11 @@ 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)
+mocks:                     # Optional: Suite-level mocks for all cases in this suite
+  mockName:
+    calls:
+      - in: [args]
+        out: result
 ```
 
 ### 3. Test Case Documents
@@ -287,25 +372,58 @@ constructorArgs: [arg1]    # Optional: Arguments for class constructor (class mo
 For function tests:
 ```yaml
 case: 'test description'   # Required: Test case name
-in: [arg1, arg2]          # Required: Input arguments
+in: [arg1, arg2]          # Required: Input arguments (use $mock:name for mocks)
 out: expectedValue        # Optional: Expected output (omit if testing for errors)
 throws: 'Error message'   # Optional: Expected error message
+mocks:                    # Optional: Case-specific mocks
+  mockName:
+    calls:                # Array of expected calls
+      - in: [args]        # Expected arguments
+        out: result       # Optional: Return value
+        throws: 'error'   # Optional: Throw error instead
 ```
 
 For class tests:
 ```yaml
 case: 'test description'
 executions:
-  - method: 'methodName'
+  - method: 'methodName'        # Supports nested: 'user.api.getData'
     in: [arg1]
-    out: expectedValue    # Optional
-    throws: 'Error msg'   # Optional
+    out: expectedValue          # Optional
+    throws: 'Error msg'         # Optional
     asserts:
-      - property: 'prop'
-        op: 'eq'          # Currently only 'eq' is supported
+      - property: 'prop'        # Supports nested: 'user.profile.name'
+        op: 'eq'                # Currently only 'eq' is supported
         value: expected
-      - method: 'getter'
+      - method: 'getter'        # Supports nested: 'settings.ui.getTheme'
         in: []
         out: expected
+mocks:                          # Optional: Mocks for the entire test case
+  mockName:
+    calls:
+      - in: [args]
+        out: result
+```
+
+#### Nested Properties and Methods
+
+Puty supports accessing nested properties and calling nested methods using dot notation:
+
+```yaml
+case: 'test nested access'
+executions:
+  - method: 'settings.ui.setTheme'    # Call nested method
+    in: ['dark']
+    out: 'dark'
+    asserts:
+      - property: 'user.profile.name'    # Access nested property
+        op: eq
+        value: 'John Doe'
+      - property: 'user.account.balance' # Deep nested property
+        op: eq
+        value: 100.50
+      - method: 'api.client.get'         # Call nested method
+        in: ['/users/123']
+        out: 'GET /users/123'
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "puty",
-  "version": "0.0.3",
+  "version": "0.0.4-rc2",
   "description": "A tooling function to test javascript functions and classes.",
   "main": "src/index.js",
   "type": "module",
@@ -16,6 +16,8 @@
     "js-yaml": "~4.1.0"
   },
   "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest run",
     "lint": "bunx prettier src tests -c",
     "lint:fix": "bunx prettier src tests -w",
     "build": "bun run esbuild.js"

package/src/mockResolver.js

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview Mock resolution and processing utilities
+ * This module provides functions for resolving mock references, creating mock functions,
+ * and validating mock calls in YAML-driven tests.
+ */
+
+import { vi } from "vitest";
+
+/**
+ * Deep equality check for mock argument validation
+ * @param {any} a - First value to compare
+ * @param {any} b - Second value to compare
+ * @returns {boolean} True if values are deeply equal
+ */
+const deepEqual = (a, b) => {
+  if (a === b) return true;
+  if (a == null || b == null) return false;
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+      if (!deepEqual(a[i], b[i])) return false;
+    }
+    return true;
+  }
+  if (typeof a === "object" && typeof b === "object") {
+    const keysA = Object.keys(a);
+    const keysB = Object.keys(b);
+    if (keysA.length !== keysB.length) return false;
+    for (const key of keysA) {
+      if (!keysB.includes(key) || !deepEqual(a[key], b[key])) return false;
+    }
+    return true;
+  }
+  return false;
+};
+
+/**
+ * Resolves mock references following hierarchy: case -> suite -> global
+ * @param {Object} caseMocks - Case-level mock definitions
+ * @param {Object} suiteMocks - Suite-level mock definitions
+ * @param {Object} globalMocks - Global-level mock definitions
+ * @returns {Object} Resolved mock definitions with hierarchy applied
+ */
+export const resolveMocks = (caseMocks = {}, suiteMocks = {}, globalMocks = {}) => {
+  const resolved = {};
+  
+  // Apply hierarchy: global -> suite -> case (case overrides suite, suite overrides global)
+  Object.assign(resolved, globalMocks, suiteMocks, caseMocks);
+  
+  return resolved;
+};
+
+/**
+ * Recursively processes values, replacing $mock: references with mock functions
+ * @param {any} value - Value to process (can be string, array, object, or primitive)
+ * @param {Object} mockFunctions - Map of mock name to mock function wrapper
+ * @returns {any} Processed value with $mock: references replaced
+ */
+export const processMockReferences = (value, mockFunctions) => {
+  if (typeof value === 'string' && value.startsWith('$mock:')) {
+    const mockName = value.substring(6); // Remove '$mock:' prefix
+    if (!mockFunctions[mockName]) {
+      throw new Error(`Mock '${mockName}' is referenced but not defined`);
+    }
+    return mockFunctions[mockName].mockFunction;
+  }
+  
+  if (Array.isArray(value)) {
+    return value.map(item => processMockReferences(item, mockFunctions));
+  }
+  
+  if (value && typeof value === 'object') {
+    const processed = {};
+    for (const [key, val] of Object.entries(value)) {
+      processed[key] = processMockReferences(val, mockFunctions);
+    }
+    return processed;
+  }
+  
+  return value;
+};
+
+/**
+ * Creates a mock function with call tracking and validation
+ * @param {string} mockName - Name of the mock for error reporting
+ * @param {Object} mockDefinition - Mock definition with calls array
+ * @param {Array} mockDefinition.calls - Array of expected calls with in/out/throws
+ * @returns {Object} Mock function wrapper with validation methods
+ */
+export const createMockFunction = (mockName, mockDefinition) => {
+  const { calls } = mockDefinition;
+  let callIndex = 0;
+  
+  const mockFn = vi.fn().mockImplementation((...args) => {
+    if (callIndex >= calls.length) {
+      throw new Error(`Mock '${mockName}' was called ${callIndex + 1} time(s) but expected exactly ${calls.length} calls`);
+    }
+    
+    const expectedCall = calls[callIndex];
+    
+    // Validate input arguments
+    if (!deepEqual(args, expectedCall.in)) {
+      throw new Error(`Expected ${mockName}(${JSON.stringify(expectedCall.in)}) but got ${mockName}(${JSON.stringify(args)})`);
+    }
+    
+    callIndex++;
+    
+    if (expectedCall.throws) {
+      throw new Error(expectedCall.throws);
+    }
+    
+    return expectedCall.out;
+  });
+  
+  return {
+    mockFunction: mockFn,
+    expectedCalls: calls.length,
+    actualCalls: () => callIndex,
+    validate: () => {
+      if (callIndex !== calls.length) {
+        throw new Error(`Mock '${mockName}' was called ${callIndex} time(s) but expected exactly ${calls.length} calls`);
+      }
+    },
+    mockName
+  };
+};
+
+/**
+ * Validates all mocks were called as expected
+ * @param {Object} mockFunctions - Map of mock name to mock function wrapper
+ * @throws {Error} If any mock validation fails
+ */
+export const validateMockCalls = (mockFunctions) => {
+  for (const mockWrapper of Object.values(mockFunctions)) {
+    mockWrapper.validate();
+  }
+};
+
+/**
+ * Creates mock functions from resolved mock definitions
+ * @param {Object} resolvedMocks - Resolved mock definitions
+ * @returns {Object} Map of mock name to mock function wrapper
+ */
+export const createMockFunctions = (resolvedMocks) => {
+  const mockFunctions = {};
+  
+  for (const [mockName, mockDef] of Object.entries(resolvedMocks)) {
+    mockFunctions[mockName] = createMockFunction(mockName, mockDef);
+  }
+  
+  return mockFunctions;
+};

package/src/puty.js

@@ -9,6 +9,71 @@ import yaml from "js-yaml";
 import { expect, test, describe } from "vitest";
 
 import { traverseAllFiles, parseWithIncludes } from "./utils.js";
+import { resolveMocks, processMockReferences, createMockFunctions, validateMockCalls } from "./mockResolver.js";
+
+/**
+ * Resolves a nested property path on an object (e.g., "user.profile.name")
+ * @param {Object} obj - The object to traverse
+ * @param {string} path - The property path (e.g., "user.profile.name")
+ * @returns {any} The value at the path
+ * @throws {Error} If any part of the path doesn't exist
+ */
+const getNestedProperty = (obj, path) => {
+  const parts = path.split('.');
+  let current = obj;
+  
+  for (let i = 0; i < parts.length; i++) {
+    if (current == null) {
+      throw new Error(`Cannot access property '${parts[i]}' of ${current} in path '${path}'`);
+    }
+    if (!(parts[i] in current)) {
+      throw new Error(`Property '${parts[i]}' not found in path '${path}'`);
+    }
+    current = current[parts[i]];
+  }
+  
+  return current;
+};
+
+/**
+ * Resolves a nested method path and calls it (e.g., "user.api.getData")
+ * @param {Object} obj - The object to traverse
+ * @param {string} path - The method path (e.g., "user.api.getData")
+ * @param {Array} args - Arguments to pass to the method
+ * @returns {any} The result of the method call
+ * @throws {Error} If any part of the path doesn't exist or final part is not a function
+ */
+const callNestedMethod = (obj, path, args = []) => {
+  const parts = path.split('.');
+  const methodName = parts.pop();
+  
+  let current = obj;
+  const parentPath = parts.join('.');
+  
+  // Navigate to the parent object
+  for (const part of parts) {
+    if (current == null) {
+      throw new Error(`Cannot access property '${part}' of ${current} in path '${path}'`);
+    }
+    if (!(part in current)) {
+      throw new Error(`Property '${part}' not found in path '${path}'`);
+    }
+    current = current[part];
+  }
+  
+  // Check if the method exists and is a function
+  if (current == null) {
+    throw new Error(`Cannot access method '${methodName}' of ${current} in path '${path}'`);
+  }
+  if (!(methodName in current)) {
+    throw new Error(`Method '${methodName}' not found in path '${path}'`);
+  }
+  if (typeof current[methodName] !== 'function') {
+    throw new Error(`'${methodName}' is not a function in path '${path}'`);
+  }
+  
+  return current[methodName](...args);
+};
 
 /**
  * File extensions that are recognized as YAML test files
@@ -43,6 +108,7 @@ export const parseYamlDocuments = (yamlContent) => {
   const config = {
     file: null,
     group: null,
+    mocks: {},
     suites: [],
   };
 
@@ -52,6 +118,7 @@ export const parseYamlDocuments = (yamlContent) => {
     if (doc.file) {
       config.file = doc.file;
       config.group = doc.group || doc.name;
+      config.mocks = doc.mocks || {};
       if (doc.suites) {
         config.suiteNames = doc.suites;
       }
@@ -62,6 +129,7 @@ export const parseYamlDocuments = (yamlContent) => {
       currentSuite = {
         name: doc.suite,
         exportName: doc.exportName || doc.suite,
+        mocks: doc.mocks || {},
         cases: [],
       };
       // Only add mode and constructorArgs if mode is explicitly 'class'
@@ -72,6 +140,8 @@ export const parseYamlDocuments = (yamlContent) => {
     } else if (doc.case && currentSuite) {
       const testCase = {
         name: doc.case,
+        mocks: doc.mocks || {},
+        resolvedMocks: null,
       };
 
       if (currentSuite.mode === "class") {
@@ -149,18 +219,31 @@ const setupFunctionTests = (suite) => {
       out: expectedOut,
       functionUnderTest,
       throws,
+      mockFunctions,
     } = 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);
+      try {
+        if (throws) {
+          // Test expects an error to be thrown
+          expect(() => functionUnderTest(...(inArg || []))).toThrow(throws);
+        } else {
+          const out = functionUnderTest(...(inArg || []));
+          expect(out).toEqual(expectedOut);
+        }
+        
+        // Validate mock calls after test execution
+        if (mockFunctions && Object.keys(mockFunctions).length > 0) {
+          validateMockCalls(mockFunctions);
+        }
+      } finally {
+        // Cleanup mocks after test
+        if (mockFunctions) {
+          Object.values(mockFunctions).forEach(mock => mock.mockFunction.mockClear?.());
+        }
       }
     });
   }
@@ -178,7 +261,7 @@ const setupFunctionTests = (suite) => {
 const setupClassTests = (suite) => {
   const { cases, ClassUnderTest, constructorArgs } = suite;
   for (const testCase of cases) {
-    const { name, executions } = testCase;
+    const { name, executions, mockFunctions } = testCase;
     test(name, () => {
       if (!ClassUnderTest) {
         throw new Error(`Class not found for test suite: ${suite.name}`);
@@ -186,57 +269,54 @@ const setupClassTests = (suite) => {
 
       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`);
-        }
+      try {
+        for (const execution of executions) {
+          const {
+            method,
+            in: inArg,
+            out: expectedOut,
+            throws,
+            asserts,
+          } = execution;
 
-        // 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);
+          // Execute the method and check its return value - supports nested methods
+          if (throws) {
+            expect(() => callNestedMethod(instance, method, inArg || [])).toThrow(throws);
+          } else {
+            const result = callNestedMethod(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`,
-                );
+          // Run assertions
+          if (asserts) {
+            for (const assertion of asserts) {
+              if (assertion.property) {
+                // Property assertion - supports nested properties like "user.profile.name"
+                const actualValue = getNestedProperty(instance, assertion.property);
+                if (assertion.op === "eq") {
+                  expect(actualValue).toEqual(assertion.value);
+                }
+                // Add more operators as needed
+              } else if (assertion.method) {
+                // Method assertion - supports nested methods like "user.api.getData"
+                const result = callNestedMethod(instance, assertion.method, assertion.in || []);
+                expect(result).toEqual(assertion.out);
               }
-              const result = instance[assertion.method](
-                ...(assertion.in || []),
-              );
-              expect(result).toEqual(assertion.out);
             }
           }
         }
+        
+        // Validate mock calls after test execution
+        if (mockFunctions && Object.keys(mockFunctions).length > 0) {
+          validateMockCalls(mockFunctions);
+        }
+      } finally {
+        // Cleanup mocks after test
+        if (mockFunctions) {
+          Object.values(mockFunctions).forEach(mock => mock.mockFunction.mockClear?.());
+        }
       }
     });
   }
@@ -262,6 +342,38 @@ export const injectFunctions = (module, originalTestConfig) => {
   let functionUnderTest = module[testConfig.exportName || "default"];
 
   for (const suite of testConfig.suites) {
+    for (const testCase of suite.cases) {
+      // Resolve mocks for this test case using hierarchy
+      testCase.resolvedMocks = resolveMocks(
+        testCase.mocks,
+        suite.mocks,
+        testConfig.mocks
+      );
+      
+      // Create mock functions from resolved mock definitions
+      testCase.mockFunctions = createMockFunctions(testCase.resolvedMocks);
+      
+      // Process mock references in test inputs and outputs
+      if (testCase.in) {
+        testCase.in = processMockReferences(testCase.in, testCase.mockFunctions);
+      }
+      if (testCase.out) {
+        testCase.out = processMockReferences(testCase.out, testCase.mockFunctions);
+      }
+      
+      // Process mock references in class test executions
+      if (testCase.executions) {
+        for (const execution of testCase.executions) {
+          if (execution.in) {
+            execution.in = processMockReferences(execution.in, testCase.mockFunctions);
+          }
+          if (execution.out) {
+            execution.out = processMockReferences(execution.out, testCase.mockFunctions);
+          }
+        }
+      }
+    }
+    
     if (suite.mode === "class") {
       const exportName = suite.exportName || "default";
       const exported = module[exportName];
@@ -305,15 +417,19 @@ export const injectFunctions = (module, originalTestConfig) => {
 export const setupTestSuiteFromYaml = async (dirname) => {
   const testYamlFiles = traverseAllFiles(dirname, extensions);
   for (const file of testYamlFiles) {
-    const testConfig = parseWithIncludes(file);
-    const filepathRelativeToSpecFile = path.join(
-      path.dirname(file),
-      testConfig.file,
-    );
+    try {
+      const testConfig = parseWithIncludes(file);
+      const filepathRelativeToSpecFile = path.join(
+        path.dirname(file),
+        testConfig.file,
+      );
 
-    // testConfig.file is relative to the spec file
-    const module = await import(filepathRelativeToSpecFile);
-    const testConfigWithInjectedFunctions = injectFunctions(module, testConfig);
-    setupTestSuite(testConfigWithInjectedFunctions);
+      // testConfig.file is relative to the spec file
+      const module = await import(filepathRelativeToSpecFile);
+      const testConfigWithInjectedFunctions = injectFunctions(module, testConfig);
+      setupTestSuite(testConfigWithInjectedFunctions);
+    } catch (error) {
+      throw error;
+    }
   }
 };

package/src/utils.js

@@ -149,6 +149,7 @@ const processDocuments = (docs) => {
   const config = {
     file: null,
     group: null,
+    mocks: {},
     suites: [],
   };
 
@@ -158,6 +159,7 @@ const processDocuments = (docs) => {
     if (doc.file) {
       config.file = doc.file;
       config.group = doc.group || doc.name;
+      config.mocks = doc.mocks || {};
       if (doc.suites) {
         config.suiteNames = doc.suites;
       }
@@ -168,6 +170,7 @@ const processDocuments = (docs) => {
       currentSuite = {
         name: doc.suite,
         exportName: doc.exportName || doc.suite,
+        mocks: doc.mocks || {},
         cases: [],
       };
       // Only add mode and constructorArgs if mode is explicitly 'class'
@@ -178,6 +181,8 @@ const processDocuments = (docs) => {
     } else if (doc.case && currentSuite) {
       const testCase = {
         name: doc.case,
+        mocks: doc.mocks || {},
+        resolvedMocks: null,
       };
 
       if (currentSuite.mode === "class") {