puty 0.0.4 → 0.0.6

package/README.md

@@ -12,6 +12,7 @@ Puty is ideal for testing pure functions - functions that always return the same
 - [Usage](#usage)
   - [Testing Functions](#testing-functions)
   - [Testing Classes](#testing-classes)
+  - [Testing Factory Functions](#testing-factory-functions)
   - [Error Testing](#error-testing)
   - [Using Mocks](#using-mocks)
   - [Using !include Directive](#using-include-directive)
@@ -33,43 +34,110 @@ npm install puty
 
 ## Quick Start
 
+Get up and running with Puty in just a few minutes!
 
-1. Create a test runner file `puty.test.js` in your project:
+### Prerequisites
 
-```js
-import { setupTestSuiteFromYaml } from "puty";
+- Node.js with ES modules support
+- Vitest installed in your project
 
-// Search for test files in the current directory
-await setupTestSuiteFromYaml();
+### Step 1: Install Puty
 
-// Or specify a different directory
-// await setupTestSuiteFromYaml("./tests");
+```bash
+npm install puty
 ```
 
-**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.
+### Step 2: Setup Your Project
+
+Ensure your `package.json` has ES modules enabled:
 
+```json
+{
+  "type": "module"
+}
+```
+
+### Step 3: Create a Function to Test
 
-2. Create your first test file `math.test.yaml`:
+Create `utils/validator.js`:
+
+```js
+export function isValidEmail(email) {
+  const regex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return regex.test(email);
+}
+
+export function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+```
+
+### Step 4: Create Your Test File
+
+Create `validator.test.yaml`:
 
 ```yaml
-file: './math.js'
-group: math
-suites: [add]
+file: './utils/validator.js'
+group: validator
+suites: [isValidEmail, capitalize]
 ---
-suite: add
-exportName: add
+suite: isValidEmail
+exportName: isValidEmail
+---
+case: valid email should return true
+in: ['user@example.com']
+out: true
+---
+case: invalid email should return false
+in: ['invalid-email']
+out: false
+---
+case: empty string should return false
+in: ['']
+out: false
 ---
-case: add two numbers
-in: [2, 3]
-out: 5
+suite: capitalize
+exportName: capitalize
+---
+case: capitalize first letter
+in: ['hello']
+out: 'Hello'
+---
+case: single letter
+in: ['a']
+out: 'A'
+```
+
+### Step 5: Create Test Runner
+
+Create `puty.test.js`:
+
+```js
+import path from 'path'
+import { setupTestSuiteFromYaml } from 'puty'
+
+const __dirname = path.dirname(new URL(import.meta.url).pathname)
+
+await setupTestSuiteFromYaml(__dirname);
 ```
 
-3. Run your tests:
+### Step 6: Run Your Tests
 
 ```bash
 npx vitest
 ```
 
+You should see output like:
+```
+✓ validator > isValidEmail > valid email should return true
+✓ validator > isValidEmail > invalid email should return false
+✓ validator > isValidEmail > empty string should return false
+✓ validator > capitalize > capitalize first letter
+✓ validator > capitalize > single letter
+```
+
+🎉 **That's it!** You've just created declarative tests using YAML instead of JavaScript.
+
 ### Recommended Vitest Configuration
 
 To enable automatic test reruns when YAML test files change, create a `vitest.config.js` file in your project root:
@@ -195,6 +263,92 @@ executions:
     - Property assertions: Check instance properties (supports nested: `user.profile.name`)
     - Method assertions: Call methods and check their return values (supports nested: `settings.getTheme`)
 
+### Testing Factory Functions
+
+Puty supports testing factory functions that return objects with methods. When using `executions` in a function test, you can omit the `out` field to skip asserting the factory's return value:
+
+```yaml
+file: './store.js'
+group: store
+---
+suite: createStore
+exportName: createStore
+---
+case: test store methods
+in:
+  - { count: 0 }
+# No 'out' field - skip return value assertion
+executions:
+  - method: getCount
+    in: []
+    out: 0
+  - method: dispatch
+    in: [{ type: 'INCREMENT' }]
+    out: 1
+  - method: getCount
+    in: []
+    out: 1
+```
+
+This pattern is useful for:
+- Factory functions that return objects with methods
+- Builder patterns
+- Module patterns that return APIs
+- Any function that returns an object you want to test methods on
+
+Key behaviors:
+- When `out` field is omitted: The function is called but its return value is not asserted
+- When `out:` is present (even empty): The return value is asserted (empty value in YAML equals `null`)
+- This works for any function test, with or without `executions`
+
+Examples:
+```yaml
+# No assertion on return value
+case: test without return assertion
+in: [1, 2]
+
+# Assert return value is null
+case: test null return
+in: [1, 2]
+out:
+
+# Assert return value is 42
+case: test specific return
+in: [1, 2]
+out: 42
+```
+
+#### Testing Undefined Values
+
+To assert that a function returns `undefined`, use the special keyword `__undefined__`:
+
+```yaml
+# Assert function returns undefined
+case: test undefined return
+in: []
+out: __undefined__
+
+# Also works in executions
+executions:
+  - method: doSomething
+    in: []
+    out: __undefined__
+    
+# And in mock definitions
+mocks:
+  callback:
+    calls:
+      - in: ['data']
+        out: __undefined__
+```
+
+The `__undefined__` keyword works in:
+- Function return value assertions (`out: __undefined__`)
+- Method return value assertions in executions
+- Mock return values
+- Mock input expectations
+- Property assertions (`value: __undefined__`)
+
 ### Error Testing
 
 You can test that functions or methods throw expected errors:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "puty",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "description": "A tooling function to test javascript functions and classes.",
   "main": "src/index.js",
   "type": "module",
@@ -25,4 +25,4 @@
   "devDependencies": {
     "vitest": "^3.2.1"
   }
-}
+}

package/src/mockResolver.js

@@ -5,6 +5,7 @@
  */
 
 import { vi } from "vitest";
+import { processUndefined } from "./utils.js";
 
 /**
  * Deep equality check for mock argument validation
@@ -41,12 +42,16 @@ const deepEqual = (a, b) => {
  * @param {Object} globalMocks - Global-level mock definitions
  * @returns {Object} Resolved mock definitions with hierarchy applied
  */
-export const resolveMocks = (caseMocks = {}, suiteMocks = {}, globalMocks = {}) => {
+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;
 };
 
@@ -57,26 +62,26 @@ export const resolveMocks = (caseMocks = {}, suiteMocks = {}, globalMocks = {})
  * @returns {any} Processed value with $mock: references replaced
  */
 export const processMockReferences = (value, mockFunctions) => {
-  if (typeof value === 'string' && value.startsWith('$mock:')) {
+  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));
+    return value.map((item) => processMockReferences(item, mockFunctions));
   }
-  
-  if (value && typeof value === 'object') {
+
+  if (value && typeof value === "object") {
     const processed = {};
     for (const [key, val] of Object.entries(value)) {
       processed[key] = processMockReferences(val, mockFunctions);
     }
     return processed;
   }
-  
+
   return value;
 };
 
@@ -88,40 +93,62 @@ export const processMockReferences = (value, mockFunctions) => {
  * @returns {Object} Mock function wrapper with validation methods
  */
 export const createMockFunction = (mockName, mockDefinition) => {
+  // Handle simple mock definition (fn: true)
+  if (mockDefinition.fn === true) {
+    const mockFn = vi.fn();
+    return {
+      mockFunction: mockFn,
+      expectedCalls: 0, // No specific call expectations
+      actualCalls: () => mockFn.mock.calls.length,
+      validate: () => {
+        // Simple mocks don't have call expectations
+      },
+      mockName,
+    };
+  }
+
   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`);
+      throw new Error(
+        `Mock '${mockName}' was called ${callIndex + 1} time(s) but expected exactly ${calls.length} calls`,
+      );
     }
-    
+
     const expectedCall = calls[callIndex];
-    
+
+    const processedExpectedIn = processUndefined(expectedCall.in);
+
     // Validate input arguments
-    if (!deepEqual(args, expectedCall.in)) {
-      throw new Error(`Expected ${mockName}(${JSON.stringify(expectedCall.in)}) but got ${mockName}(${JSON.stringify(args)})`);
+    if (!deepEqual(args, processedExpectedIn)) {
+      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 processUndefined(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`);
+        throw new Error(
+          `Mock '${mockName}' was called ${callIndex} time(s) but expected exactly ${calls.length} calls`,
+        );
       }
     },
-    mockName
+    mockName,
   };
 };
 
@@ -143,10 +170,10 @@ export const validateMockCalls = (mockFunctions) => {
  */
 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

@@ -8,8 +8,13 @@ import path from "node:path";
 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";
+import { traverseAllFiles, parseWithIncludes, processUndefined } from "./utils.js";
+import {
+  resolveMocks,
+  processMockReferences,
+  createMockFunctions,
+  validateMockCalls,
+} from "./mockResolver.js";
 
 /**
  * Resolves a nested property path on an object (e.g., "user.profile.name")
@@ -19,19 +24,21 @@ import { resolveMocks, processMockReferences, createMockFunctions, validateMockC
  * @throws {Error} If any part of the path doesn't exist
  */
 const getNestedProperty = (obj, path) => {
-  const parts = path.split('.');
+  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}'`);
+      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;
 };
 
@@ -44,34 +51,38 @@ const getNestedProperty = (obj, path) => {
  * @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 parts = path.split(".");
   const methodName = parts.pop();
-  
+
   let current = obj;
-  const parentPath = parts.join('.');
-  
+  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}'`);
+      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}'`);
+    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') {
+  if (typeof current[methodName] !== "function") {
     throw new Error(`'${methodName}' is not a function in path '${path}'`);
   }
-  
+
   return current[methodName](...args);
 };
 
@@ -86,7 +97,7 @@ const extensions = [".test.yaml", ".test.yml", ".spec.yaml", ".spec.yml"];
  * @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|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
@@ -148,10 +159,17 @@ export const parseYamlDocuments = (yamlContent) => {
         testCase.executions = doc.executions || [];
       } else {
         testCase.in = doc.in || [];
-        testCase.out = doc.out;
+        // Always preserve 'out' field if present (including when it's undefined)
+        if ("out" in doc) {
+          testCase.out = doc.out;
+        }
         if (doc.throws) {
           testCase.throws = doc.throws;
         }
+        // Allow executions for function tests (factory pattern)
+        if (doc.executions) {
+          testCase.executions = doc.executions;
+        }
       }
 
       currentSuite.cases.push(testCase);
@@ -216,10 +234,10 @@ const setupFunctionTests = (suite) => {
     const {
       name,
       in: inArg,
-      out: expectedOut,
       functionUnderTest,
       throws,
       mockFunctions,
+      executions,
     } = testCase;
     test(name, () => {
       if (!functionUnderTest) {
@@ -231,10 +249,69 @@ const setupFunctionTests = (suite) => {
           // Test expects an error to be thrown
           expect(() => functionUnderTest(...(inArg || []))).toThrow(throws);
         } else {
-          const out = functionUnderTest(...(inArg || []));
-          expect(out).toEqual(expectedOut);
+          // Call the function
+          const result = functionUnderTest(...(inArg || []));
+
+          // Assert return value if 'out' field is present in the test case
+          if ("out" in testCase) {
+            const expectedOut = processUndefined(testCase.out);
+            expect(result).toEqual(expectedOut);
+          }
+
+          // If executions are present, execute methods on the returned object
+          if (executions && executions.length > 0) {
+            for (const execution of executions) {
+              const {
+                method,
+                in: execInArg,
+                out: execExpectedOut,
+                throws: execThrows,
+                asserts,
+              } = execution;
+
+              if (execThrows) {
+                expect(() =>
+                  callNestedMethod(result, method, execInArg || []),
+                ).toThrow(execThrows);
+              } else {
+                const methodResult = callNestedMethod(
+                  result,
+                  method,
+                  execInArg || [],
+                );
+                if (execExpectedOut !== undefined) {
+                  const processedExpectedOut = processUndefined(execExpectedOut);
+                  expect(methodResult).toEqual(processedExpectedOut);
+                }
+              }
+
+              // Run assertions
+              if (asserts) {
+                for (const assertion of asserts) {
+                  if (assertion.property) {
+                    const actualValue = getNestedProperty(
+                      result,
+                      assertion.property,
+                    );
+                    if (assertion.op === "eq") {
+                      const processedValue = processUndefined(assertion.value);
+                      expect(actualValue).toEqual(processedValue);
+                    }
+                  } else if (assertion.method) {
+                    const assertResult = callNestedMethod(
+                      result,
+                      assertion.method,
+                      assertion.in || [],
+                    );
+                    const processedOut = processUndefined(assertion.out);
+                    expect(assertResult).toEqual(processedOut);
+                  }
+                }
+              }
+            }
+          }
         }
-        
+
         // Validate mock calls after test execution
         if (mockFunctions && Object.keys(mockFunctions).length > 0) {
           validateMockCalls(mockFunctions);
@@ -242,7 +319,9 @@ const setupFunctionTests = (suite) => {
       } finally {
         // Cleanup mocks after test
         if (mockFunctions) {
-          Object.values(mockFunctions).forEach(mock => mock.mockFunction.mockClear?.());
+          Object.values(mockFunctions).forEach((mock) =>
+            mock.mockFunction.mockClear?.(),
+          );
         }
       }
     });
@@ -253,7 +332,7 @@ 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 {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
@@ -281,11 +360,14 @@ const setupClassTests = (suite) => {
 
           // Execute the method and check its return value - supports nested methods
           if (throws) {
-            expect(() => callNestedMethod(instance, method, inArg || [])).toThrow(throws);
+            expect(() =>
+              callNestedMethod(instance, method, inArg || []),
+            ).toThrow(throws);
           } else {
             const result = callNestedMethod(instance, method, inArg || []);
             if (expectedOut !== undefined) {
-              expect(result).toEqual(expectedOut);
+              const processedExpectedOut = processUndefined(expectedOut);
+              expect(result).toEqual(processedExpectedOut);
             }
           }
 
@@ -294,20 +376,29 @@ const setupClassTests = (suite) => {
             for (const assertion of asserts) {
               if (assertion.property) {
                 // Property assertion - supports nested properties like "user.profile.name"
-                const actualValue = getNestedProperty(instance, assertion.property);
+                const actualValue = getNestedProperty(
+                  instance,
+                  assertion.property,
+                );
                 if (assertion.op === "eq") {
-                  expect(actualValue).toEqual(assertion.value);
+                  const processedValue = processUndefined(assertion.value);
+                  expect(actualValue).toEqual(processedValue);
                 }
                 // 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 = callNestedMethod(
+                  instance,
+                  assertion.method,
+                  assertion.in || [],
+                );
+                const processedOut = processUndefined(assertion.out);
+                expect(result).toEqual(processedOut);
               }
             }
           }
         }
-        
+
         // Validate mock calls after test execution
         if (mockFunctions && Object.keys(mockFunctions).length > 0) {
           validateMockCalls(mockFunctions);
@@ -315,7 +406,9 @@ const setupClassTests = (suite) => {
       } finally {
         // Cleanup mocks after test
         if (mockFunctions) {
-          Object.values(mockFunctions).forEach(mock => mock.mockFunction.mockClear?.());
+          Object.values(mockFunctions).forEach((mock) =>
+            mock.mockFunction.mockClear?.(),
+          );
         }
       }
     });
@@ -331,8 +424,8 @@ const setupClassTests = (suite) => {
  * @example
  * // Import module and inject functions
  * const module = await import('./math.js');
- * const testConfig = { 
- *   suites: [{ name: 'add', exportName: 'add', cases: [...] }] 
+ * const testConfig = {
+ *   suites: [{ name: 'add', exportName: 'add', cases: [...] }]
  * };
  * const ready = injectFunctions(module, testConfig);
  * // ready.suites[0].cases[0].functionUnderTest === module.add
@@ -347,33 +440,45 @@ export const injectFunctions = (module, originalTestConfig) => {
       testCase.resolvedMocks = resolveMocks(
         testCase.mocks,
         suite.mocks,
-        testConfig.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);
+        testCase.in = processMockReferences(
+          testCase.in,
+          testCase.mockFunctions,
+        );
       }
       if (testCase.out) {
-        testCase.out = processMockReferences(testCase.out, testCase.mockFunctions);
+        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);
+            execution.in = processMockReferences(
+              execution.in,
+              testCase.mockFunctions,
+            );
           }
           if (execution.out) {
-            execution.out = processMockReferences(execution.out, testCase.mockFunctions);
+            execution.out = processMockReferences(
+              execution.out,
+              testCase.mockFunctions,
+            );
           }
         }
       }
     }
-    
+
     if (suite.mode === "class") {
       const exportName = suite.exportName || "default";
       const exported = module[exportName];
@@ -408,10 +513,10 @@ export const injectFunctions = (module, originalTestConfig) => {
  * @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) => {
@@ -426,7 +531,10 @@ export const setupTestSuiteFromYaml = async (dirname) => {
 
       // testConfig.file is relative to the spec file
       const module = await import(filepathRelativeToSpecFile);
-      const testConfigWithInjectedFunctions = injectFunctions(module, testConfig);
+      const testConfigWithInjectedFunctions = injectFunctions(
+        module,
+        testConfig,
+      );
       setupTestSuite(testConfigWithInjectedFunctions);
     } catch (error) {
       throw error;

package/src/utils.js

@@ -18,7 +18,7 @@ import yaml from "js-yaml";
  * @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
  */
@@ -80,7 +80,7 @@ export const loadYamlWithPath = (filePath, visitedFiles = new Set()) => {
  * @example
  * // Find all YAML test files
  * const testFiles = traverseAllFiles('./tests', ['.test.yaml', '.spec.yml']);
- * 
+ *
  * // Find all JavaScript files
  * const jsFiles = traverseAllFiles('./src', ['.js', '.ts']);
  */
@@ -189,10 +189,17 @@ const processDocuments = (docs) => {
         testCase.executions = doc.executions || [];
       } else {
         testCase.in = doc.in || [];
-        testCase.out = doc.out;
+        // Only add 'out' if it's present in the doc
+        if ("out" in doc) {
+          testCase.out = doc.out;
+        }
         if (doc.throws) {
           testCase.throws = doc.throws;
         }
+        // Allow executions for function tests (factory pattern)
+        if (doc.executions) {
+          testCase.executions = doc.executions;
+        }
       }
 
       currentSuite.cases.push(testCase);
@@ -215,9 +222,9 @@ const processDocuments = (docs) => {
  * // 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: 
+ * // main.yaml:
  * // file: './lib.js'
  * // ---
  * // !include ./test-cases.yaml
@@ -231,3 +238,25 @@ export const parseWithIncludes = (filePath) => {
 
   return processDocuments(flattenedDocs);
 };
+
+/**
+ * Recursively processes a value to convert "__undefined__" strings to actual undefined values
+ * @param {any} value - The value to process (string, array, object, or primitive)
+ * @returns {any} The processed value with "__undefined__" converted to undefined
+ * @example
+ * processUndefined("__undefined__") // returns undefined
+ * processUndefined({ a: "__undefined__", b: [1, "__undefined__"] }) 
+ * // returns { a: undefined, b: [1, undefined] }
+ */
+export const processUndefined = (value) => {
+  if (value === "__undefined__") return undefined;
+  if (Array.isArray(value)) return value.map(processUndefined);
+  if (value && typeof value === "object") {
+    const processed = {};
+    for (const [key, val] of Object.entries(value)) {
+      processed[key] = processUndefined(val);
+    }
+    return processed;
+  }
+  return value;
+};