@japa/runner 3.0.0-1 → 3.0.0-3

package/build/modules/core/types.d.ts

@@ -3,4 +3,3 @@ export type BaseReporterOptions = {
     stackLinesCount?: number;
     framesMaxLimit?: number;
 };
-//# sourceMappingURL=types.d.ts.map

package/build/modules/core/types.js

@@ -1 +1,9 @@
+/*
+ * @japa/runner
+ *
+ * (c) Japa
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 export * from '@japa/core/types';

package/build/src/cli_parser.d.ts

@@ -1,6 +1,14 @@
 import type { CLIArgs } from './types.js';
+/**
+ * CLI Parser is used to parse the commandline argument
+ */
 export declare class CliParser {
+    /**
+     * Parses command-line arguments
+     */
     parse(argv: string[]): CLIArgs;
+    /**
+     * Returns the help string
+     */
     getHelp(): string;
 }
-//# sourceMappingURL=cli_parser.d.ts.map

package/build/src/cli_parser.js

@@ -1,6 +1,19 @@
+/*
+ * @japa/runner
+ *
+ * (c) Japa
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+// @ts-ignore-error
 import getopts from 'getopts';
 import colors from '@poppinss/colors';
 const ansi = colors.ansi();
+/**
+ * Known commandline options. The user can still define additional flags and they
+ * will be parsed aswell, but without any normalization
+ */
 const OPTIONS = {
     string: ['tests', 'groups', 'tags', 'files', 'timeout', 'retries', 'reporter'],
     boolean: ['help', 'matchAll'],
@@ -10,6 +23,9 @@ const OPTIONS = {
         help: 'h',
     },
 };
+/**
+ * Help string to display when the `--help flag is used`
+ */
 const GET_HELP = () => `
 ${ansi.yellow('@japa/runner v2.3.0')}
 
@@ -39,10 +55,19 @@ ${ansi.yellow('Notes:')}
 - The retries defined on test object takes precedence over the ${ansi.green('--retries')} flag.
 - The ${ansi.green('--files')} flag checks for the file names ending with the filter substring.
 `;
+/**
+ * CLI Parser is used to parse the commandline argument
+ */
 export class CliParser {
+    /**
+     * Parses command-line arguments
+     */
     parse(argv) {
         return getopts(argv, OPTIONS);
     }
+    /**
+     * Returns the help string
+     */
     getHelp() {
         return GET_HELP();
     }

package/build/src/config_manager.d.ts

@@ -1,7 +1,17 @@
 import type { CLIArgs, Config } from './types.js';
+/**
+ * Config manager is used to hydrate the configuration by merging
+ * the defaults, user defined config and the command line
+ * flags.
+ *
+ * The command line flags have the upmost priority
+ */
 export declare class ConfigManager {
     #private;
     constructor(config: Config, cliArgs: CLIArgs);
+    /**
+     * Hydrates the config with user defined options and the
+     * command-line flags.
+     */
     hydrate(): Required<Config>;
 }
-//# sourceMappingURL=config_manager.d.ts.map

package/build/src/config_manager.js

@@ -1,6 +1,17 @@
+/*
+ * @japa/runner
+ *
+ * (c) Japa
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import debug from './debug.js';
 import { spec } from './reporters/main.js';
 import { Refiner } from '../modules/core/main.js';
+/**
+ * Defaults to use for configuration
+ */
 const DEFAULTS = {
     files: [],
     timeout: 2000,
@@ -14,6 +25,13 @@ const DEFAULTS = {
     importer: (filePath) => import(filePath.href),
     configureSuite: () => { },
 };
+/**
+ * Config manager is used to hydrate the configuration by merging
+ * the defaults, user defined config and the command line
+ * flags.
+ *
+ * The command line flags have the upmost priority
+ */
 export class ConfigManager {
     #config;
     #cliArgs;
@@ -21,9 +39,17 @@ export class ConfigManager {
         this.#config = config;
         this.#cliArgs = cliArgs;
     }
+    /**
+     * Processes a CLI argument and converts it to an
+     * array of strings
+     */
     #processAsArray(value) {
         return Array.isArray(value) ? value : value.split(',').map((item) => item.trim());
     }
+    /**
+     * Returns a copy of filters based upon the CLI
+     * arguments.
+     */
     #getCLIFilters() {
         const filters = {};
         if (this.#cliArgs.tags) {
@@ -43,6 +69,9 @@ export class ConfigManager {
         }
         return filters;
     }
+    /**
+     * Returns the timeout from the CLI args
+     */
     #getCLITimeout() {
         if (this.#cliArgs.timeout) {
             const value = Number(this.#cliArgs.timeout);
@@ -51,6 +80,9 @@ export class ConfigManager {
             }
         }
     }
+    /**
+     * Returns the retries from the CLI args
+     */
     #getCLIRetries() {
         if (this.#cliArgs.retries) {
             const value = Number(this.#cliArgs.retries);
@@ -59,16 +91,27 @@ export class ConfigManager {
             }
         }
     }
+    /**
+     * Returns the forceExit property from the CLI args
+     */
     #getCLIForceExit() {
         if (this.#cliArgs.forceExit) {
             return true;
         }
     }
+    /**
+     * Returns reporters selected using the commandline
+     * --reporter flag
+     */
     #getCLIReporters() {
         if (this.#cliArgs.reporter) {
             return this.#processAsArray(this.#cliArgs.reporter);
         }
     }
+    /**
+     * Hydrates the config with user defined options and the
+     * command-line flags.
+     */
     hydrate() {
         const cliFilters = this.#getCLIFilters();
         const cliRetries = this.#getCLIRetries();
@@ -90,6 +133,10 @@ export class ConfigManager {
             setup: this.#config.setup || [],
             teardown: this.#config.teardown || [],
         };
+        /**
+         * Overwrite activated reporters when defined using CLI
+         * flag
+         */
         if (cliReporters) {
             baseConfig.reporters.activated = cliReporters;
         }

package/build/src/create_test.d.ts

@@ -1,4 +1,7 @@
 import { Emitter, Group, Refiner, Suite, Test } from '../modules/core/main.js';
+/**
+ * Create a new instance of the Test
+ */
 export declare function createTest(title: string, emitter: Emitter, refiner: Refiner, options: {
     group?: Group;
     suite?: Suite;
@@ -6,6 +9,9 @@ export declare function createTest(title: string, emitter: Emitter, refiner: Ref
     timeout?: number;
     retries?: number;
 }): Test<undefined>;
+/**
+ * Create a new instance of the Group
+ */
 export declare function createTestGroup(title: string, emitter: Emitter, refiner: Refiner, options: {
     group?: Group;
     suite?: Suite;
@@ -13,4 +19,3 @@ export declare function createTestGroup(title: string, emitter: Emitter, refiner
     timeout?: number;
     retries?: number;
 }): Group;
-//# sourceMappingURL=create_test.d.ts.map

package/build/src/create_test.js

@@ -1,5 +1,19 @@
+/*
+ * @japa/runner
+ *
+ * (c) Japa
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { Group, Test, TestContext } from '../modules/core/main.js';
+/**
+ * Function to create the test context for the test
+ */
 const contextBuilder = (testInstance) => new TestContext(testInstance);
+/**
+ * Create a new instance of the Test
+ */
 export function createTest(title, emitter, refiner, options) {
     const testInstance = new Test(title, contextBuilder, emitter, refiner, options.group);
     testInstance.options.meta.suite = options.suite;
@@ -11,6 +25,9 @@ export function createTest(title, emitter, refiner, options) {
     if (options.retries !== undefined) {
         testInstance.retry(options.retries);
     }
+    /**
+     * Register test as a child either with the group or the suite
+     */
     if (options.group) {
         options.group.add(testInstance);
     }
@@ -19,6 +36,9 @@ export function createTest(title, emitter, refiner, options) {
     }
     return testInstance;
 }
+/**
+ * Create a new instance of the Group
+ */
 export function createTestGroup(title, emitter, refiner, options) {
     if (options.group) {
         throw new Error('Nested groups are not supported by Japa');

package/build/src/debug.d.ts

@@ -1,4 +1,3 @@
 /// <reference types="@types/node" resolution-mode="require"/>
 declare const _default: import("util").DebugLogger;
 export default _default;
-//# sourceMappingURL=debug.d.ts.map

package/build/src/debug.js

@@ -1,2 +1,10 @@
+/*
+ * @japa/runner
+ *
+ * (c) Japa
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { debuglog } from 'node:util';
 export default debuglog('japa:runner');

package/build/src/exceptions_manager.d.ts

@@ -1,7 +1,19 @@
+/**
+ * Handles uncaught exceptions and prints them to the
+ * console
+ */
 export declare class ExceptionsManager {
     #private;
     hasErrors: boolean;
+    /**
+     * Monitors unhandled exceptions and rejections. The exceptions
+     * are stacked in a buffer, so that we do not clutter the
+     * tests output and once the tests are over, we will
+     * print them to the console.
+     *
+     * In case the tests are completed, we will print errors as they
+     * happen.
+     */
     monitor(): void;
     flow(): Promise<void>;
 }
-//# sourceMappingURL=exceptions_manager.d.ts.map

package/build/src/exceptions_manager.js

@@ -1,10 +1,31 @@
+/*
+ * @japa/runner
+ *
+ * (c) Japa
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { ErrorsPrinter } from '@japa/errors-printer';
+/**
+ * Handles uncaught exceptions and prints them to the
+ * console
+ */
 export class ExceptionsManager {
     #exceptionsBuffer = [];
     #rejectionsBuffer = [];
     #state = 'watching';
     #errorsPrinter = new ErrorsPrinter({ stackLinesCount: 2, framesMaxLimit: 4 });
     hasErrors = false;
+    /**
+     * Monitors unhandled exceptions and rejections. The exceptions
+     * are stacked in a buffer, so that we do not clutter the
+     * tests output and once the tests are over, we will
+     * print them to the console.
+     *
+     * In case the tests are completed, we will print errors as they
+     * happen.
+     */
     monitor() {
         process.on('uncaughtException', async (error) => {
             this.hasErrors = true;
@@ -34,6 +55,9 @@ export class ExceptionsManager {
             return;
         }
         this.#state = 'flowing';
+        /**
+         * Print exceptions
+         */
         if (this.#exceptionsBuffer.length) {
             let exceptionsCount = this.#exceptionsBuffer.length;
             let exceptionsIndex = this.#exceptionsBuffer.length;
@@ -44,6 +68,9 @@ export class ExceptionsManager {
             }
             this.#exceptionsBuffer = [];
         }
+        /**
+         * Print rejections
+         */
         if (this.#rejectionsBuffer.length) {
             let rejectionsCount = this.#exceptionsBuffer.length;
             let rejectionsIndex = this.#exceptionsBuffer.length;

package/build/src/files_manager.d.ts

@@ -1,7 +1,18 @@
 /// <reference types="@types/node" resolution-mode="require"/>
 import type { TestFiles } from './types.js';
+/**
+ * Files manager exposes the API to collect, filter and import test
+ * files based upon the config
+ */
 export declare class FilesManager {
+    /**
+     * Returns a collection of files from the user defined
+     * glob or the implementation function
+     */
     getFiles(cwd: string, files: TestFiles): Promise<URL[]>;
+    /**
+     * Applies file name filter on a collection of file
+     * URLs
+     */
     grep(files: URL[], filters: string[]): URL[];
 }
-//# sourceMappingURL=files_manager.d.ts.map

package/build/src/files_manager.js

@@ -1,8 +1,28 @@
-import { sep } from 'node:path';
+/*
+ * @japa/runner
+ *
+ * (c) Japa
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import slash from 'slash';
 import fastGlob from 'fast-glob';
 import { pathToFileURL } from 'node:url';
+/**
+ * The expression to remove file extension and optionally
+ * .spec|.test from the test file name
+ */
 const FILE_SUFFIX_EXPRESSION = /(\.spec|\.test)?\.[js|ts|jsx|tsx|mjs|mts|cjs|cts]+$/;
+/**
+ * Files manager exposes the API to collect, filter and import test
+ * files based upon the config
+ */
 export class FilesManager {
+    /**
+     * Returns a collection of files from the user defined
+     * glob or the implementation function
+     */
     async getFiles(cwd, files) {
         if (Array.isArray(files) || typeof files === 'string') {
             const testFiles = await fastGlob(files, {
@@ -14,11 +34,20 @@ export class FilesManager {
         }
         return await files();
     }
+    /**
+     * Applies file name filter on a collection of file
+     * URLs
+     */
     grep(files, filters) {
         return files.filter((file) => {
+            const filename = slash(file.pathname);
+            const filenameWithoutTestSuffix = filename.replace(FILE_SUFFIX_EXPRESSION, '');
             return !!filters.find((filter) => {
+                if (filename.endsWith(filter)) {
+                    return true;
+                }
                 const filterSegments = filter.split('/').reverse();
-                const fileSegments = file.pathname.replace(FILE_SUFFIX_EXPRESSION, '').split(sep).reverse();
+                const fileSegments = filenameWithoutTestSuffix.split('/').reverse();
                 return filterSegments.every((segment, index) => {
                     return fileSegments[index] && (segment === '*' || fileSegments[index].endsWith(segment));
                 });

package/build/src/helpers.d.ts

@@ -20,4 +20,3 @@ declare const _default: {
     useColors(colorsToUse: import("@poppinss/colors/types").Colors): void;
 };
 export default _default;
-//# sourceMappingURL=helpers.d.ts.map

package/build/src/helpers.js

@@ -1,2 +1,10 @@
+/*
+ * @japa/runner
+ *
+ * (c) Japa
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { cliui } from '@poppinss/cliui';
 export default cliui();

package/build/src/hooks.d.ts

@@ -1,9 +1,20 @@
 import { Runner } from '../modules/core/main.js';
 import type { Config } from './types.js';
+/**
+ * Exposes API for working with global hooks
+ */
 export declare class GlobalHooks {
     #private;
+    /**
+     * Apply hooks from the config
+     */
     apply(config: Required<Config>): void;
+    /**
+     * Perform setup
+     */
     setup(runner: Runner): Promise<void>;
+    /**
+     * Perform cleanup
+     */
     teardown(error: Error | null, runner: Runner): Promise<void>;
 }
-//# sourceMappingURL=hooks.d.ts.map

package/build/src/hooks.js

@@ -1,17 +1,37 @@
+/*
+ * @japa/runner
+ *
+ * (c) Japa
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import Hooks from '@poppinss/hooks';
+/**
+ * Exposes API for working with global hooks
+ */
 export class GlobalHooks {
     #hooks = new Hooks();
     #setupRunner;
     #teardownRunner;
+    /**
+     * Apply hooks from the config
+     */
     apply(config) {
         config.setup.forEach((hook) => this.#hooks.add('setup', hook));
         config.teardown.forEach((hook) => this.#hooks.add('teardown', hook));
     }
+    /**
+     * Perform setup
+     */
     async setup(runner) {
         this.#setupRunner = this.#hooks.runner('setup');
         this.#teardownRunner = this.#hooks.runner('teardown');
         await this.#setupRunner.run(runner);
     }
+    /**
+     * Perform cleanup
+     */
     async teardown(error, runner) {
         if (this.#setupRunner) {
             await this.#setupRunner.cleanup(error, runner);

package/build/src/planner.d.ts

@@ -1,8 +1,16 @@
 /// <reference types="@types/node" resolution-mode="require"/>
 import type { Config, TestSuite } from './types.js';
+/**
+ * The tests planner is used to plan the tests by doing all
+ * the heavy lifting of executing plugins, registering
+ * reporters, filtering tests and so on.
+ */
 export declare class Planner {
     #private;
     constructor(config: Required<Config>);
+    /**
+     * Creates a plan for running the tests
+     */
     plan(): Promise<{
         reporters: import("@japa/core/types").NamedReporterContract[];
         suites: (TestSuite & {
@@ -15,4 +23,3 @@ export declare class Planner {
         config: Required<Config>;
     }>;
 }
-//# sourceMappingURL=planner.d.ts.map

package/build/src/planner.js

@@ -1,5 +1,18 @@
+/*
+ * @japa/runner
+ *
+ * (c) Japa
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import validator from './validator.js';
 import { FilesManager } from './files_manager.js';
+/**
+ * The tests planner is used to plan the tests by doing all
+ * the heavy lifting of executing plugins, registering
+ * reporters, filtering tests and so on.
+ */
 export class Planner {
     #config;
     #fileManager = new FilesManager();
@@ -9,11 +22,19 @@ export class Planner {
         validator.validateSuitesForUniqueness(config);
         this.#config = config;
     }
+    /**
+     * Returns a list of reporters based upon the activated
+     * reporters list.
+     */
     #getActivatedReporters() {
         return this.#config.reporters.activated.map((activated) => {
             return this.#config.reporters.list.find(({ name }) => activated === name);
         });
     }
+    /**
+     * A generic method to collect files from the user defined
+     * files glob and apply the files filter
+     */
     async #collectFiles(files) {
         let filesURLs = await this.#fileManager.getFiles(this.#config.cwd, files);
         if (this.#config.filters.files && this.#config.filters.files.length) {
@@ -21,6 +42,10 @@ export class Planner {
         }
         return filesURLs;
     }
+    /**
+     * Returns a collection of suites and their associated
+     * test files by applying all the filters
+     */
     async #getSuites() {
         let suites = [];
         let suitesFilters = this.#config.filters.suites || [];
@@ -45,6 +70,9 @@ export class Planner {
         }
         return suites;
     }
+    /**
+     * Returns a list of filters to the passed to the refiner
+     */
     #getRefinerFilters() {
         return Object.keys(this.#config.filters).reduce((result, layer) => {
             if (layer === 'tests' || layer === 'tags' || layer === 'groups') {
@@ -53,6 +81,9 @@ export class Planner {
             return result;
         }, []);
     }
+    /**
+     * Creates a plan for running the tests
+     */
     async plan() {
         const suites = await this.#getSuites();
         const reporters = this.#getActivatedReporters();

package/build/src/plugins/retry.d.ts

@@ -1,8 +1,20 @@
 import type { PluginFn } from '../types.js';
+/**
+ * Returns an object with the title of the tests failed during
+ * the last run.
+ */
 export declare function getFailedTests(): Promise<{
     tests?: string[];
 }>;
+/**
+ * Writes failing tests to the cache directory
+ */
 export declare function cacheFailedTests(tests: string[]): Promise<void>;
+/**
+ * Clears the cache dir
+ */
 export declare function clearCache(): Promise<void>;
+/**
+ * Exposes the API to run failing tests using the "retry" CLI flag.
+ */
 export declare const retryPlugin: PluginFn;
-//# sourceMappingURL=retry.d.ts.map

package/build/src/plugins/retry.js

@@ -1,9 +1,24 @@
+/*
+ * @japa/runner
+ *
+ * (c) Japa
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { join } from 'node:path';
 import findCacheDirectory from 'find-cache-dir';
 import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
 import cliui from '../helpers.js';
+/**
+ * Paths to the cache directory and the summary file
+ */
 const CACHE_DIR = findCacheDirectory({ name: '@japa/runner' });
 const SUMMARY_FILE = CACHE_DIR ? join(CACHE_DIR, 'summary.json') : undefined;
+/**
+ * Returns an object with the title of the tests failed during
+ * the last run.
+ */
 export async function getFailedTests() {
     try {
         const summary = await readFile(SUMMARY_FILE, 'utf-8');
@@ -16,13 +31,22 @@ export async function getFailedTests() {
         throw new Error('Unable to read failed tests cache file', { cause: error });
     }
 }
+/**
+ * Writes failing tests to the cache directory
+ */
 export async function cacheFailedTests(tests) {
     await mkdir(CACHE_DIR, { recursive: true });
     await writeFile(SUMMARY_FILE, JSON.stringify({ tests: tests }));
 }
+/**
+ * Clears the cache dir
+ */
 export async function clearCache() {
     await unlink(SUMMARY_FILE);
 }
+/**
+ * Exposes the API to run failing tests using the "retry" CLI flag.
+ */
 export const retryPlugin = async function retry({ config, cliArgs }) {
     if (!SUMMARY_FILE) {
         return;