@resistdesign/voltra 3.0.0-alpha.2 → 3.0.0-alpha.21

package/common/Testing/CLI.js

@@ -0,0 +1,432 @@
+#!/usr/bin/env node
+import { promises } from 'fs';
+import Path from 'path';
+import { pathToFileURL } from 'url';
+import fastGlob from 'fast-glob';
+import picocolors from 'picocolors';
+
+var importModule = async (modulePath) => {
+  const moduleUrl = pathToFileURL(modulePath);
+  return import(moduleUrl.href);
+};
+var stringifyOutput = (value) => JSON.stringify(
+  value,
+  function(_key, value2) {
+    return typeof value2 === "function" ? "[Function]" : value2;
+  },
+  2
+);
+var OPERATIONS = {
+  ["===" /* EQUALS */]: (a, b) => a === b,
+  ["!==" /* NOT_EQUALS */]: (a, b) => a !== b,
+  ["IN" /* IN */]: (a, b) => Array.isArray(b) && b.includes(a),
+  ["BETWEEN" /* BETWEEN */]: (a, b) => {
+    if (Array.isArray(b) && b.length === 2 && typeof b[0] === "number" && typeof b[1] === "number") {
+      return typeof a === "number" && a >= b[0] && a <= b[1];
+    }
+    throw new Error("BETWEEN requires an array of two numbers as expectation.");
+  },
+  ["CONTAINS" /* CONTAINS */]: (a, b) => typeof a === "string" && typeof b === "string" && a.includes(b),
+  ["REGEX" /* REGEX */]: (a, b) => {
+    if (typeof b === "object" && b !== null && "pattern" in b) {
+      const { pattern, flags } = b;
+      try {
+        const regex = new RegExp(pattern, flags);
+        return typeof a === "string" && regex.test(a);
+      } catch (err) {
+        throw new Error(`Invalid REGEX: ${err.message}`);
+      }
+    }
+    throw new Error(
+      "REGEX requires an expectation with 'pattern' and optional 'flags'."
+    );
+  },
+  ["EXT_REGEX" /* EXT_REGEX */]: (a, b) => {
+    if (typeof b === "object" && b !== null && "pattern" in b) {
+      const { pattern, flags } = b;
+      const buildRegexFromPattern = (pattern2, flags2 = "") => {
+        if (!Array.isArray(pattern2)) {
+          throw new Error("EXT_REGEX pattern must be an array of objects.");
+        }
+        const regexBody = pattern2.map(({ value, escaped }) => {
+          if (typeof value !== "string") {
+            throw new Error(
+              "Each pattern element must have a string 'value'."
+            );
+          }
+          return escaped ? value.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&") : value;
+        }).join("");
+        return new RegExp(regexBody, flags2);
+      };
+      try {
+        const regex = buildRegexFromPattern(pattern, flags);
+        return typeof a === "string" && regex.test(a);
+      } catch (err) {
+        throw new Error(`Invalid EXT_REGEX: ${err.message}`);
+      }
+    }
+    throw new Error(
+      "EXT_REGEX requires an expectation with 'pattern' as an array of PatternElement and optional 'flags'."
+    );
+  },
+  ["DEEP_EQUALS" /* DEEP_EQUALS */]: (a, b) => {
+    if (typeof a === "object" && typeof b === "object" && a !== null && b !== null) {
+      return JSON.stringify(a) === JSON.stringify(b);
+    }
+    return false;
+  },
+  ["ARRAY_CONTAINS" /* ARRAY_CONTAINS */]: (a, b) => {
+    if (Array.isArray(a)) {
+      return a.includes(b);
+    }
+    throw new Error("ARRAY_CONTAINS requires an array as the first argument.");
+  },
+  ["ARRAY_EQUALS" /* ARRAY_EQUALS */]: (a, b) => {
+    if (Array.isArray(a) && Array.isArray(b)) {
+      return JSON.stringify(a) === JSON.stringify(b);
+    }
+    throw new Error("ARRAY_EQUALS requires two arrays as arguments.");
+  }
+};
+var compare = (result, expectation, operation = "===" /* EQUALS */) => {
+  const op = OPERATIONS[operation];
+  if (!op) {
+    throw new Error(`Unsupported operation: ${operation}`);
+  }
+  return op(result, expectation);
+};
+var getResolvedConditions = async (testFilePath, targetTestIndex, targetTestExport, conditions, isSetup = false) => {
+  if (Array.isArray(conditions)) {
+    return conditions;
+  } else if (typeof conditions === "object" && conditions !== null) {
+    const { file, export: targetConditionExport } = conditions;
+    const modulePath = Path.resolve(Path.dirname(testFilePath), file);
+    const targetModule = await importModule(modulePath);
+    const conditionArray = targetModule[targetConditionExport];
+    if (Array.isArray(conditionArray)) {
+      return conditionArray;
+    }
+  }
+  throw new Error(
+    `Invalid conditions for TEST${isSetup ? " SETUP" : ""} ${targetTestIndex + 1} (${targetTestExport}) in ${testFilePath}`
+  );
+};
+var getSetupInstance = async (testFilePath, targetTestIndex, targetTestExport, test, module) => {
+  const { setup } = test;
+  if (!setup) return module;
+  const { conditions: baseConditions, export: targetSetupExport } = setup;
+  const setupFunction = module[targetSetupExport];
+  const conditions = await getResolvedConditions(
+    testFilePath,
+    targetTestIndex,
+    targetTestExport,
+    baseConditions,
+    true
+  );
+  if (typeof setupFunction !== "function") {
+    throw new Error(`Setup export "${setup.export}" is not a function.`);
+  }
+  return setup.instantiate ? new setupFunction(...conditions) : await setupFunction(...conditions);
+};
+var getTestFunction = async (testFilePath, file, targetTestIndex, test, targetModule) => {
+  const { export: targetExport } = test;
+  if (!targetExport) {
+    throw new Error(
+      `Invalid test export (${targetExport}) for TEST ${targetTestIndex + 1} in ${testFilePath}`
+    );
+  }
+  const instance = await getSetupInstance(
+    testFilePath,
+    targetTestIndex,
+    targetExport,
+    test,
+    targetModule
+  );
+  const testFunction = instance[targetExport];
+  if (typeof testFunction !== "function") {
+    throw new Error(
+      `Export "${targetExport}" from "${file}", declared in TEST ${targetTestIndex + 1}, is not a function.`
+    );
+  }
+  return testFunction;
+};
+var getTestConfig = async (testFilePath) => {
+  const testConfig = JSON.parse(
+    await promises.readFile(testFilePath, "utf8")
+  );
+  return testConfig;
+};
+var getResolvedTestConfig = async (testFilePath) => {
+  const { file, tests } = await getTestConfig(testFilePath);
+  if (!file) {
+    throw new Error(`Invalid test configuration in ${testFilePath}`);
+  }
+  const modulePath = Path.resolve(Path.dirname(testFilePath), file);
+  const targetModule = await importModule(modulePath);
+  return {
+    file,
+    targetModule,
+    tests
+  };
+};
+var mergeTestResults = (...results) => results.reduce(
+  ({
+    messages: accMessages = [],
+    generated: accGenerated = [],
+    passes: accPasses = [],
+    failures: accFailures = [],
+    errors: accErrors = []
+  }, {
+    messages = [],
+    generated = [],
+    passes = [],
+    failures = [],
+    errors = []
+  }) => ({
+    messages: [...accMessages, ...messages],
+    generated: [...accGenerated, ...generated],
+    passes: [...accPasses, ...passes],
+    failures: [...accFailures, ...failures],
+    errors: [...accErrors, ...errors]
+  }),
+  { messages: [], passes: [], failures: [], errors: [] }
+);
+var runTest = async (testFilePath, testFunction, test, index, targetExport, report) => {
+  const {
+    conditions: baseConditions,
+    expectation,
+    operation,
+    expectUndefined
+  } = test;
+  const conditions = await getResolvedConditions(
+    testFilePath,
+    index,
+    targetExport,
+    baseConditions
+  );
+  try {
+    const result = await testFunction(...conditions);
+    const passed = expectUndefined || compare(result, expectation, operation);
+    if (passed) {
+      report({
+        passes: [`Test ${index + 1} (${targetExport})`]
+      });
+    } else {
+      report({
+        failures: [
+          `Test ${index + 1} (${targetExport}):
+
+Result:
+
+${stringifyOutput(result)}`
+        ]
+      });
+    }
+  } catch (err) {
+    report({
+      errors: [
+        `Test ${index + 1} (${targetExport}):
+
+Error:
+
+${err.message}`
+      ]
+    });
+  }
+};
+var generateTestsForFile = async (testFilePath, report) => {
+  try {
+    const { file, targetModule, tests } = await getResolvedTestConfig(testFilePath);
+    report({
+      messages: [`Generating expectations for tests in ${testFilePath}`]
+    });
+    const generatedTests = [];
+    let hasNewExpectations = false;
+    for (let i = 0; i < tests.length; i++) {
+      const test = tests[i];
+      const {
+        export: targetExport,
+        conditions: baseConditions,
+        expectation,
+        operation,
+        expectUndefined
+      } = test;
+      const conditions = await getResolvedConditions(
+        testFilePath,
+        i,
+        targetExport,
+        baseConditions
+      );
+      if (expectation !== void 0 || expectUndefined) {
+        generatedTests.push(test);
+      } else {
+        const testFunction = await getTestFunction(
+          testFilePath,
+          file,
+          i,
+          test,
+          targetModule
+        );
+        const result = await testFunction(...conditions);
+        report({
+          generated: [
+            `Expectation for TEST ${i + 1} (${targetExport}):
+
+${stringifyOutput(result)}`
+          ]
+        });
+        generatedTests.push({
+          ...test,
+          expectation: result,
+          operation: operation || "===" /* EQUALS */
+        });
+        hasNewExpectations = true;
+      }
+    }
+    if (hasNewExpectations) {
+      const updatedTestConfig = { file, tests: generatedTests };
+      await promises.writeFile(
+        testFilePath,
+        JSON.stringify(updatedTestConfig, null, 2)
+      );
+      report({ messages: [`Updated test file saved to ${testFilePath}`] });
+    } else {
+      report({
+        messages: [`No new expectations were generated for ${testFilePath}`]
+      });
+    }
+  } catch (err) {
+    report({
+      errors: [`Error processing test file ${testFilePath}:
+
+${err.message}`]
+    });
+  }
+};
+var runTestsForFile = async (testFilePath, report) => {
+  try {
+    const { file, targetModule, tests } = await getResolvedTestConfig(testFilePath);
+    report({
+      messages: [`Running tests from ${testFilePath}`]
+    });
+    for (const [index, test] of tests.entries()) {
+      const { export: targetExport } = test;
+      const testFunction = await getTestFunction(
+        testFilePath,
+        file,
+        index,
+        test,
+        targetModule
+      );
+      await runTest(
+        testFilePath,
+        testFunction,
+        test,
+        index,
+        targetExport,
+        report
+      );
+    }
+  } catch (err) {
+    report({
+      errors: [`Error processing test file ${testFilePath}: ${err.message}`]
+    });
+  }
+};
+var executeTestingCommand = async (testFiles, generateMode = false, report) => {
+  const completeMessage = generateMode ? "Test generation complete." : "Testing complete.";
+  try {
+    for (const testFile of testFiles) {
+      const resolvedTestFile = Path.resolve(testFile);
+      if (generateMode) {
+        await generateTestsForFile(resolvedTestFile, report);
+      } else {
+        await runTestsForFile(resolvedTestFile, report);
+      }
+    }
+    report({
+      messages: [completeMessage]
+    });
+  } catch (err) {
+    report({ errors: [`Error running tests:
+
+${err.message}`] });
+  }
+};
+var main = async () => {
+  const args = process.argv.slice(2);
+  const generateMode = args.includes("--generate");
+  const testPaths = args.filter((arg) => arg !== "--generate");
+  console.log(`${picocolors.bgMagenta(picocolors.whiteBright(" VEST "))}
+`);
+  if (testPaths.length === 0) {
+    console.error("Usage: vest [--generate] <test-directory-path>");
+    process.exit(1);
+  }
+  const testFiles = await fastGlob(testPaths);
+  if (testFiles.length === 0) {
+    console.warn(`No test files found in ${testPaths.join(", ")}`);
+    process.exit(0);
+  }
+  let results = {
+    messages: [],
+    passes: [],
+    failures: [],
+    errors: []
+  };
+  await executeTestingCommand(
+    testFiles,
+    generateMode,
+    (latestResults) => {
+      const {
+        messages = [],
+        generated: generated2 = [],
+        passes: passes2 = [],
+        failures: failures2 = [],
+        errors: errors2 = []
+      } = latestResults;
+      results = mergeTestResults(results, latestResults);
+      messages.forEach(
+        (message) => console.log(`${picocolors.blueBright("MESSAGE:")} ${message}
+`)
+      );
+      generated2.forEach(
+        (generated3) => console.log(`${picocolors.greenBright("GENERATED:")} ${generated3}
+`)
+      );
+      passes2.forEach(
+        (pass) => console.log(`${picocolors.greenBright("PASSED:")} ${pass}
+`)
+      );
+      failures2.forEach(
+        (failure) => console.error(`${picocolors.redBright("FAILED:")} ${failure}
+`)
+      );
+      errors2.forEach(
+        (error) => console.error(
+          `${picocolors.redBright(picocolors.italic("ERROR:"))} ${error}
+`
+        )
+      );
+    }
+  );
+  const { generated = [], passes = [], failures = [], errors = [] } = results;
+  const exitValue = failures.length + errors.length;
+  if (generateMode) {
+    console.log(`${picocolors.greenBright("GENERATED:")} ${generated.length}
+${picocolors.redBright(picocolors.italic("ERRORS:"))} ${errors.length}
+`);
+  } else {
+    console.log(`${picocolors.greenBright("PASSES:")} ${passes.length}
+${picocolors.redBright("FAILURES:")} ${failures.length}
+${picocolors.redBright(picocolors.italic("ERRORS:"))} ${errors.length}
+`);
+  }
+  process.exit(exitValue);
+};
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+
+export { main };

package/{src/common → common}/Testing/Types.d.ts

@@ -1,23 +1,59 @@
 /**
- * Operations used for comparison of during tests.
- * */
+ * Operations used for comparison during tests.
+ */
 export declare enum TestComparisonOperation {
+    /**
+     * Strict equality comparison.
+     * */
     EQUALS = "===",
+    /**
+     * Strict inequality comparison.
+     * */
     NOT_EQUALS = "!==",
+    /**
+     * Value is contained in expectation array.
+     * */
     IN = "IN",
+    /**
+     * Array contains the expectation value.
+     * */
     ARRAY_CONTAINS = "ARRAY_CONTAINS",
+    /**
+     * Numeric value is between two bounds.
+     * */
     BETWEEN = "BETWEEN",
+    /**
+     * String contains another string.
+     * */
     CONTAINS = "CONTAINS",
+    /**
+     * Regex match against a pattern.
+     * */
     REGEX = "REGEX",
+    /**
+     * Extended regex match with explicit pattern elements.
+     * */
     EXT_REGEX = "EXT_REGEX",
+    /**
+     * Deep equality using JSON stringification.
+     * */
     DEEP_EQUALS = "DEEP_EQUALS",
+    /**
+     * Array equality using JSON stringification.
+     * */
     ARRAY_EQUALS = "ARRAY_EQUALS"
 }
 /**
  * A pattern definition object for use with extended regex expectations.
  * */
 export type PatternElement = {
+    /**
+     * Literal pattern segment value.
+     * */
     value: string;
+    /**
+     * Whether to escape regex characters in the value.
+     * */
     escaped?: boolean;
 };
 /**
@@ -28,7 +64,13 @@ export type PatternElement = {
  * Used when a `TestCondition` `operation` is `TestComparisonOperation.EXT_REGEX`.
  * */
 export type EXTRegexExpectation = {
+    /**
+     * Pattern elements to build the regex.
+     * */
     pattern: PatternElement[];
+    /**
+     * Regex flags to apply.
+     * */
     flags?: string;
 };
 /**
@@ -37,31 +79,64 @@ export type EXTRegexExpectation = {
  * Used when a `TestCondition` `operation` is `TestComparisonOperation.REGEX`.
  * */
 export type RegexExpectation = {
+    /**
+     * Regex pattern string.
+     * */
     pattern: string;
+    /**
+     * Regex flags to apply.
+     * */
     flags?: string;
 };
 /**
  * A configuration used to acquire conditions from code instead of a JSON array.
  * */
 export type ConditionConfig = {
+    /**
+     * Relative file path containing the conditions export.
+     * */
     file: string;
+    /**
+     * Export name that contains the conditions array.
+     * */
     export: string;
 };
 /**
  * Preparation for a test when some setup is required or a class needs to be instantiated.
  * */
 export type TestSetup = {
+    /**
+     * Conditions to use for the setup function or constructor.
+     * */
     conditions: unknown[] | ConditionConfig;
+    /**
+     * Export name to call or instantiate for setup.
+     * */
     export: string;
+    /**
+     * Whether to use `new` with the setup export.
+     * */
     instantiate?: boolean;
 };
 /**
  * The basis for a test.
  * */
 export type BaseTest = {
+    /**
+     * Export name for the test function.
+     * */
     export: string;
+    /**
+     * Optional setup configuration.
+     * */
     setup?: TestSetup;
+    /**
+     * Conditions to pass to the test function.
+     * */
     conditions: unknown[] | ConditionConfig;
+    /**
+     * Allow missing expectation and treat undefined as pass.
+     * */
     expectUndefined?: boolean;
 };
 /**
@@ -93,25 +168,49 @@ export type Test = BaseTest & ({
     expectation: unknown[];
 });
 /**
- * A configuration for a test. Designed to be used in JSON for declarative test files.
- * */
+ * A configuration for a test. Designed to be used in JSON spec files.
+ */
 export type TestConfig = {
+    /**
+     * Relative module path containing test exports.
+     * */
     file: string;
+    /**
+     * Tests to execute for the module.
+     * */
     tests: Test[];
 };
 /**
  * A resolved test configuration with the module and tests.
  * */
 export type ResolvedTestConfig = {
+    /**
+     * Required module with test exports.
+     * */
     targetModule: any;
 } & TestConfig;
 /**
  * The results from running one or more tests.
  * */
 export type TestResults = {
+    /**
+     * Informational messages.
+     * */
     messages?: string[];
+    /**
+     * Generated expectation messages.
+     * */
     generated?: string[];
+    /**
+     * Passed test messages.
+     * */
     passes?: string[];
+    /**
+     * Failed test messages.
+     * */
     failures?: string[];
+    /**
+     * Error messages.
+     * */
     errors?: string[];
 };