@j-o-r/sh 1.1.28 → 1.1.29

package/types/Test.d.ts

@@ -1,68 +1,104 @@
 export default Test;
-export type AsyncFunction = (() => Promise<any>);
-export type testDefinition = {
+export type AsyncFunction = () => Promise<any>;
+export type TestDefinition = {
+    /**
+     * - Test name/description.
+     */
     description: string;
     /**
-     * - syc/ async function
+     * - Sync/async test function.
      */
     callback: Function | AsyncFunction;
 };
-export type testReport = {
+export type TestReport = {
+    /**
+     * - Test description.
+     */
     description: string;
     /**
-     * - start time in MS
+     * - Execution duration (ms).
      */
     duration: number;
     /**
-     * - Has it been called?
+     * - Whether the test ran.
      */
     executed: boolean;
 };
-export type Report = {
+export type TestReportSummary = {
+    /**
+     * - Total tests defined.
+     */
     tests: number;
     /**
-     * - start time in MS
+     * - Total execution time (ms).
      */
     duration: number;
     /**
-     * - number of errors
+     * - Number of failures.
      */
     errors: number;
     /**
-     * - number of tests executed
+     * - Number of tests run.
      */
     executed: number;
 };
 declare class Test {
     /**
-    * @param {boolean} [quiet] - does not output a report when true, default `false`
-    */
+     * Creates a test runner instance.
+     *
+     * Tracks tests, errors, unresolved promises via {@link AsyncTracker}.
+     * Supports sync/async callbacks; detects global errors.
+     *
+     * @param {boolean} [quiet=false] - Suppress console reports.
+     * @example
+     * const t = new Test();
+     * t.add('basic', () => { throw new Error('fail'); });
+     * const report = await t.run();
+     */
     constructor(quiet?: boolean);
     /**
-    * Set the timeout when a synced function is called.
-    * This settles async code used in a sync function
-    * and give some time to catch errors (#HACK)
-    * @param {number} timeout - in MS, default 50
-    */
+     * Sets timeout for settling async in sync tests (hack for late errors).
+     *
+     * @param {number} timeout - Timeout (ms); default 50.
+     * @example
+     * t.syncTimeout(100);
+     */
     syncTimeout(timeout: number): void;
     /**
-    *
-    * @param {string} description
-    * @param {Function|AsyncFunction} callback - sync / async function
-    * @throws Error when conditions are not met
-    * @returns {Test}
-    */
+     * Adds a test case.
+     *
+     * @param {string} description - Test name.
+     * @param {Function | AsyncFunction} callback - Test function.
+     * @returns {Test} Self for chaining.
+     * @throws {Error} Invalid description (non-string) or callback (not function).
+     * @example
+     * t.add('check 1+1', () => expect(1+1).toBe(2));
+     */
     add(description: string, callback: Function | AsyncFunction): Test;
     /**
-    * Execute tests
-    * @param {number[]} [execute] - limit the execution tests
-    * @returns {Promise<Report>}
-    */
-    run(execute?: number[]): Promise<Report>;
+     * Runs tests (all or selected); returns summary.
+     *
+     * Prints progress/errors; checks unresolved promises post-run.
+     *
+     * @param {number[]} [execute] - Indices of tests to run (default: all).
+     * @returns {Promise<TestReportSummary>} Summary stats.
+     * @example
+     * await t.run([0, 2]); // Run tests 0 and 2
+     */
+    run(execute?: number[]): Promise<TestReportSummary>;
+    /**
+     * Prints unresolved promises report (if any).
+     *
+     * @example
+     * t.unresolved();
+     */
     unresolved(): void;
     /**
-    * Empty tests
-    */
+     * Resets all tests, reports, errors, tracker.
+     *
+     * @example
+     * t.reset();
+     */
     reset(): void;
     #private;
 }