@nu-art/testalot 0.401.1

package/consts.d.ts

@@ -0,0 +1,47 @@
+import { TestCase_Error, TestModel } from './types.js';
+/**
+ * Default test processor for async test cases.
+ *
+ * Validates that either `expectedResult` or `error` is provided, then:
+ * - If error is expected: Asserts the promise rejects with the expected error
+ * - If result is expected: Awaits the promise and validates the result
+ *   - If expectedResult is a function: Calls it with the actual result
+ *   - Otherwise: Deep equals comparison
+ *
+ * @template Result - Actual result type
+ * @template ExpectedResult - Expected result type
+ */
+export type DefaultTestProcessor<Result = any, ExpectedResult = Result> = (promisedResult: Promise<Result>, expectedResult?: ((() => Promise<any>) | ExpectedResult), error?: TestCase_Error) => Promise<any>;
+/**
+ * Default implementation of test processor.
+ *
+ * Handles both success and error cases, with flexible result validation.
+ */
+export declare const defaultTestProcessor: DefaultTestProcessor;
+/**
+ * Creates a test scenario runner function.
+ *
+ * Returns a function that can be used as a Mocha test. If no test case is provided,
+ * creates a default test case that accepts any result.
+ *
+ * @template Result - Actual result type
+ * @template ExpectedResult - Expected result type
+ * @param test - Async function to test
+ * @param _testCase - Optional test case (creates default if not provided)
+ * @param processor - Test processor function (default: defaultTestProcessor)
+ * @returns Function that can be used as a Mocha test
+ */
+export declare const runScenario: <Result, ExpectedResult = Result>(test: () => Promise<Result>, _testCase?: TestModel<void, ExpectedResult>, processor?: DefaultTestProcessor<any, any>) => () => Promise<any>;
+/**
+ * Runs a single test case with input.
+ *
+ * Resolves the test case, extracts expected result or error, and runs the test.
+ *
+ * @template Input - Input type
+ * @template Result - Actual result type
+ * @template ExpectedResult - Expected result type
+ * @param test - Async function that takes input and returns result
+ * @param _testCase - Test case with input and expectations
+ * @param processor - Test processor function (default: defaultTestProcessor)
+ */
+export declare const runSingleTestCase: <Input, Result, ExpectedResult = Result>(test: (input: Input) => Promise<Result>, _testCase: TestModel<Input, ExpectedResult>, processor?: DefaultTestProcessor<any, any>) => Promise<any>;

package/consts.js

@@ -0,0 +1,81 @@
+/*
+ * @nu-art/testalot - Testing utilities and test framework helpers
+ * Copyright (C) 2024 Adam van der Kruk aka TacB0sS
+ * Licensed under the Apache License, Version 2.0
+ */
+import chai, { expect } from 'chai';
+import chaiAsPromised from 'chai-as-promised';
+chai.use(chaiAsPromised);
+/**
+ * Resolves content that can be either a value or a function.
+ */
+function resolveContent(content, ...param) {
+    return typeof content === 'function' ? content(...param) : content;
+}
+const Void = undefined;
+/**
+ * Default implementation of test processor.
+ *
+ * Handles both success and error cases, with flexible result validation.
+ */
+export const defaultTestProcessor = async (promisedResult, expectedResult, error) => {
+    if (expectedResult == null && error == null)
+        throw new Error('MUST provide expectedResult or error');
+    if (typeof error === 'object')
+        return expect(promisedResult).to.be.rejectedWith(error.expected);
+    let result;
+    try {
+        result = await promisedResult;
+    }
+    catch (e) {
+        if (typeof error === 'function')
+            return await error(e);
+        throw e;
+    }
+    if (typeof expectedResult === 'function')
+        return await expectedResult(result);
+    expect(result).to.deep.equal(expectedResult);
+};
+/**
+ * Creates a test scenario runner function.
+ *
+ * Returns a function that can be used as a Mocha test. If no test case is provided,
+ * creates a default test case that accepts any result.
+ *
+ * @template Result - Actual result type
+ * @template ExpectedResult - Expected result type
+ * @param test - Async function to test
+ * @param _testCase - Optional test case (creates default if not provided)
+ * @param processor - Test processor function (default: defaultTestProcessor)
+ * @returns Function that can be used as a Mocha test
+ */
+export const runScenario = (test, _testCase, processor = defaultTestProcessor) => {
+    let testCase;
+    if (_testCase)
+        testCase = resolveContent(_testCase);
+    else
+        testCase = {
+            input: Void,
+            result: async (r) => {
+            }
+        };
+    return async () => runSingleTestCase(test, testCase, processor);
+};
+/**
+ * Runs a single test case with input.
+ *
+ * Resolves the test case, extracts expected result or error, and runs the test.
+ *
+ * @template Input - Input type
+ * @template Result - Actual result type
+ * @template ExpectedResult - Expected result type
+ * @param test - Async function that takes input and returns result
+ * @param _testCase - Test case with input and expectations
+ * @param processor - Test processor function (default: defaultTestProcessor)
+ */
+export const runSingleTestCase = async (test, _testCase, processor = defaultTestProcessor) => {
+    const testCase = resolveContent(_testCase);
+    const expectedResult = 'result' in testCase ? testCase.result : undefined;
+    const error = 'error' in testCase ? testCase.error : undefined;
+    return processor(test(testCase.input), expectedResult, error);
+};

package/index.d.ts

@@ -0,0 +1,2 @@
+export * from './consts.js';
+export * from './types.js';

package/index.js

@@ -0,0 +1,7 @@
+/*
+ * @nu-art/testalot - Testing utilities and test framework helpers
+ * Copyright (C) 2024 Adam van der Kruk aka TacB0sS
+ * Licensed under the Apache License, Version 2.0
+ */
+export * from './consts.js';
+export * from './types.js';

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@nu-art/testalot",
+  "version": "0.401.1",
+  "description": "Testing utilities and test framework helpers for TypeScript projects",
+  "type": "module",
+  "keywords": [
+    "typescript",
+    "testing",
+    "test-framework",
+    "mocha",
+    "test-utilities",
+    "nu-art",
+    "thunderstorm"
+  ],
+  "homepage": "https://github.com/nu-art-js/thunderstorm",
+  "bugs": {
+    "url": "https://github.com/nu-art-js/thunderstorm/issues?q=is%3Aissue+label%3Atestalot"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com:nu-art-js/thunderstorm.git",
+    "directory": "_thunderstorm/testalot"
+  },
+  "publishConfig": {
+    "directory": "dist"
+  },
+  "license": "Apache-2.0",
+  "author": "TacB0sS",
+  "scripts": {},
+  "dependencies": {},
+  "devDependencies": {
+    "chai": "^4.0.0",
+    "chai-as-promised": "^7.0.0"
+  },
+  "unitConfig": {
+    "type": "typescript-lib"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    }
+  }
+}

package/test-template.test.d.ts

@@ -0,0 +1 @@
+export {};

package/test-template.test.js

@@ -0,0 +1,41 @@
+import { runSingleTestCase } from './consts.js';
+const justAGlobalConst = 'just a global const';
+// the test cases, notice these can be a resolvable content, in order to keep bind consts between the input and the output,
+const test = async (input) => {
+    // the actual test logic that all test cases will pass through and all will yield the Result
+    // this logic is silly but demonstrate the concept
+    if (input.inputB === 2)
+        throw new Error('a part of the error message would be The expected error message - but it\'s not the only part of the message');
+    return iAmJustAHelperFunction();
+};
+// helper function - dedicated for this test suite
+function iAmJustAHelperFunction() {
+    return justAGlobalConst;
+}
+const runTestCase = (testCase, processor) => () => runSingleTestCase(test, testCase, processor);
+// the mocha test launch
+describe('template', () => {
+    it('My very fancy test', () => {
+        const justAConst = 'case 1';
+        return runTestCase({
+            input: {
+                inputA: `input for test ${justAConst}`,
+                inputB: 1,
+                inputC: ''
+            },
+            result: justAGlobalConst
+        });
+    });
+    it('My super fancy test case 2 - expected to fail', () => {
+        return runTestCase({
+            input: {
+                inputA: 'input for test case 2',
+                inputB: 2,
+                inputC: ''
+            },
+            error: {
+                expected: 'The expected error message'
+            }
+        });
+    });
+});

package/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Content that can be either a value or a function that returns a value.
+ */
+export type ResolvableContent<T, K extends any[] = any[]> = T | ((...param: K) => T);
+/**
+ * Test case input/output type.
+ *
+ * @template Input - Input type for the test
+ * @template Result - Expected result type
+ */
+export type Types<Input, Result> = {
+    expected?: Result;
+    input: Input;
+};
+/**
+ * Error expectation for test cases.
+ *
+ * Can be:
+ * - Object with expected error message/pattern and optional constructor
+ * - Function that validates the error
+ */
+export type TestCase_Error = {
+    expected: string | RegExp;
+    message?: string;
+    constructor?: Error | Function;
+} | ((error: Error) => Promise<any>);
+/**
+ * Test case model with input and expected result or error.
+ *
+ * Supports:
+ * - Resolvable content (value or function)
+ * - Optional description (can reference the test case itself)
+ * - Expected result (value or validation function)
+ * - Expected error (object or validation function)
+ *
+ * @template Input - Input type
+ * @template ExpectedResult - Expected result type
+ */
+export type TestModel<Input, ExpectedResult> = ResolvableContent<{
+    description?: ResolvableContent<string, [TestModel<Input, ExpectedResult>]>;
+    input: Input;
+} & ({
+    result: ExpectedResult | ((result: ExpectedResult) => Promise<any>);
+} | {
+    error: TestCase_Error;
+})>;
+/**
+ * Function that processes a test case.
+ *
+ * @template Input - Input type
+ * @template ExpectedResult - Expected result type
+ */
+export type TestProcessor<Input, ExpectedResult> = (input: TestModel<Input, ExpectedResult>) => void | Promise<void>;
+/**
+ * Test suite configuration.
+ *
+ * Defines a collection of test cases with setup/teardown hooks.
+ *
+ * @template Input - Input type for test cases
+ * @template ExpectedResult - Expected result type
+ * @deprecated
+ */
+export type TestSuite<Input, ExpectedResult> = {
+    /** Optional setup function (runs before all tests) */
+    before?: () => (void | Promise<void>);
+    /** Function that processes each test case */
+    processor: TestProcessor<Input, ExpectedResult>;
+    /** Optional teardown function (runs after all tests) */
+    after?: () => (void | Promise<void>);
+    /** Array of test cases */
+    testcases: TestModel<Input, ExpectedResult>[];
+    /** Suite label/name */
+    label: string;
+    /** Optional timeout in milliseconds (default: 5000) */
+    timeout?: number;
+};

package/types.js

@@ -0,0 +1,6 @@
+/*
+ * @nu-art/testalot - Testing utilities and test framework helpers
+ * Copyright (C) 2024 Adam van der Kruk aka TacB0sS
+ * Licensed under the Apache License, Version 2.0
+ */
+export {};