@japa/runner 3.0.0-2 → 3.0.0-3

package/build/factories/main.d.ts

@@ -1,3 +1,5 @@
 import { RunnerFactory } from './runner.js';
+/**
+ * Create an instance of the runner factory
+ */
 export declare const runner: () => RunnerFactory;
-//# sourceMappingURL=main.d.ts.map

package/build/factories/main.js

@@ -1,2 +1,13 @@
+/*
+ * @japa/runner
+ *
+ * (c) Japa
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { RunnerFactory } from './runner.js';
+/**
+ * Create an instance of the runner factory
+ */
 export const runner = () => new RunnerFactory();

package/build/factories/runner.d.ts

@@ -1,10 +1,27 @@
 import { Config } from '../src/types.js';
 import { Suite, Emitter } from '../modules/core/main.js';
+/**
+ * Runner factory exposes the API to run dummy suites, groups and tests.
+ * You might want to use the factory for testing reporters and
+ * plugins usage
+ */
 export declare class RunnerFactory {
     #private;
+    /**
+     * Configure runner
+     */
     configure(config: Config, argv?: string[]): this;
+    /**
+     * Register custom suites to execute instead
+     * of the dummy one's
+     */
     withSuites(suites: Suite[]): this;
+    /**
+     * Define a custom emitter instance to use
+     */
     useEmitter(emitter: Emitter): this;
+    /**
+     * Run dummy tests. You might use
+     */
     run(): Promise<import("@japa/core/types").RunnerSummary>;
 }
-//# sourceMappingURL=runner.d.ts.map

package/build/factories/runner.js

@@ -1,3 +1,11 @@
+/*
+ * @japa/runner
+ *
+ * (c) Japa
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import assert from 'node:assert';
 import { fileURLToPath } from 'node:url';
 import { Planner } from '../src/planner.js';
@@ -6,6 +14,11 @@ import { CliParser } from '../src/cli_parser.js';
 import { ConfigManager } from '../src/config_manager.js';
 import { createTest, createTestGroup } from '../src/create_test.js';
 import { Suite, Runner, Emitter } from '../modules/core/main.js';
+/**
+ * Runner factory exposes the API to run dummy suites, groups and tests.
+ * You might want to use the factory for testing reporters and
+ * plugins usage
+ */
 export class RunnerFactory {
     #emitter = new Emitter();
     #config;
@@ -15,12 +28,18 @@ export class RunnerFactory {
     get #refiner() {
         return this.#config.refiner;
     }
+    /**
+     * Creating unit and functional suites
+     */
     #createSuites() {
         return [
             new Suite('unit', this.#emitter, this.#refiner),
             new Suite('functional', this.#emitter, this.#refiner),
         ];
     }
+    /**
+     * Creates a variety of tests for Maths.add method
+     */
     #createAdditionTests(group) {
         createTest('add two numbers', this.#emitter, this.#refiner, { group, file: this.#file }).run(() => {
             assert.equal(2 + 2, 4);
@@ -45,6 +64,10 @@ export class RunnerFactory {
         })
             .fails('Have to add support for floating numbers');
     }
+    /**
+     * Creates a variety of dummy tests for creating
+     * a new user
+     */
     #createUserStoreTests(group) {
         createTest('Validate user data', this.#emitter, this.#refiner, {
             group,
@@ -70,6 +93,9 @@ export class RunnerFactory {
             file: this.#file,
         });
     }
+    /**
+     * Creates tests for the unit tests suite
+     */
     #createUnitTests(suite) {
         const additionGroup = createTestGroup('Maths#add', this.#emitter, this.#refiner, {
             suite,
@@ -81,6 +107,9 @@ export class RunnerFactory {
             file: this.#file,
         }).run(() => { });
     }
+    /**
+     * Creates tests for the functional tests suite
+     */
     #createFunctionalTests(suite) {
         const usersStoreGroup = createTestGroup('Users/store', this.#emitter, this.#refiner, {
             suite,
@@ -100,6 +129,9 @@ export class RunnerFactory {
             file: this.#file,
         }).run(() => { });
     }
+    /**
+     * Registers plugins
+     */
     async #registerPlugins(runner) {
         for (let plugin of this.#config.plugins) {
             await plugin({
@@ -110,19 +142,32 @@ export class RunnerFactory {
             });
         }
     }
+    /**
+     * Configure runner
+     */
     configure(config, argv) {
         this.#cliArgs = new CliParser().parse(argv || []);
         this.#config = new ConfigManager(config, this.#cliArgs).hydrate();
         return this;
     }
+    /**
+     * Register custom suites to execute instead
+     * of the dummy one's
+     */
     withSuites(suites) {
         this.#suites = suites;
         return this;
     }
+    /**
+     * Define a custom emitter instance to use
+     */
     useEmitter(emitter) {
         this.#emitter = emitter;
         return this;
     }
+    /**
+     * Run dummy tests. You might use
+     */
     async run() {
         const runner = new Runner(this.#emitter);
         await this.#registerPlugins(runner);

package/build/index.d.ts

@@ -1,12 +1,33 @@
 import type { TestExecutor } from '@japa/core/types';
 import type { Config } from './src/types.js';
 import { Group, Test, TestContext } from './modules/core/main.js';
+/**
+ * Create a Japa test. Defining a test without the callback
+ * will create a todo test.
+ */
 export declare function test(title: string, callback?: TestExecutor<TestContext, undefined>): Test<undefined>;
 export declare namespace test {
     var group: (title: string, callback: (group: Group) => void) => void;
 }
+/**
+ * Get the test of currently running test
+ */
 export declare function getActiveTest(): Test<any> | undefined;
+/**
+ * Make Japa process command line arguments. Later the parsed output
+ * will be used by Japa to compute the configuration
+ */
 export declare function processCLIArgs(argv: string[]): void;
+/**
+ * Configure the tests runner with inline configuration. You must
+ * call configure method before the run method.
+ *
+ * Do note: The CLI flags will overwrite the options provided
+ * to the configure method.
+ */
 export declare function configure(options: Config): void;
+/**
+ * Execute Japa tests. Calling this function will import the test
+ * files behind the scenes
+ */
 export declare function run(): Promise<void>;
-//# sourceMappingURL=index.d.ts.map

package/build/index.js

@@ -1,3 +1,11 @@
+/*
+ * @japa/runner
+ *
+ * (c) Japa
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import { fileURLToPath } from 'node:url';
 import { ErrorsPrinter } from '@japa/errors-printer';
 import debug from './src/debug.js';
@@ -10,13 +18,34 @@ import { ConfigManager } from './src/config_manager.js';
 import { ExceptionsManager } from './src/exceptions_manager.js';
 import { createTest, createTestGroup } from './src/create_test.js';
 import { Emitter, Runner, Suite } from './modules/core/main.js';
+/**
+ * Global emitter instance used by the test
+ */
 const emitter = new Emitter();
+/**
+ * The current active test
+ */
 let activeTest;
+/**
+ * Parsed commandline arguments
+ */
 let cliArgs = {};
+/**
+ * Hydrated config
+ */
 let runnerConfig;
+/**
+ * The state refers to the phase where we configure suites and import
+ * test files. We stick this metadata to the test instance one can
+ * later reference within the test.
+ */
 const executionPlanState = {
     phase: 'idle',
 };
+/**
+ * Create a Japa test. Defining a test without the callback
+ * will create a todo test.
+ */
 export function test(title, callback) {
     validator.ensureIsInPlanningPhase(executionPlanState.phase);
     const testInstance = createTest(title, emitter, runnerConfig.refiner, executionPlanState);
@@ -31,22 +60,46 @@ export function test(title, callback) {
     }
     return testInstance;
 }
+/**
+ * Create a Japa test group
+ */
 test.group = function (title, callback) {
     validator.ensureIsInPlanningPhase(executionPlanState.phase);
     executionPlanState.group = createTestGroup(title, emitter, runnerConfig.refiner, executionPlanState);
     callback(executionPlanState.group);
     executionPlanState.group = undefined;
 };
+/**
+ * Get the test of currently running test
+ */
 export function getActiveTest() {
     return activeTest;
 }
+/**
+ * Make Japa process command line arguments. Later the parsed output
+ * will be used by Japa to compute the configuration
+ */
 export function processCLIArgs(argv) {
     cliArgs = new CliParser().parse(argv);
 }
+/**
+ * Configure the tests runner with inline configuration. You must
+ * call configure method before the run method.
+ *
+ * Do note: The CLI flags will overwrite the options provided
+ * to the configure method.
+ */
 export function configure(options) {
     runnerConfig = new ConfigManager(options, cliArgs).hydrate();
 }
+/**
+ * Execute Japa tests. Calling this function will import the test
+ * files behind the scenes
+ */
 export async function run() {
+    /**
+     * Display help when help flag is used
+     */
     if (cliArgs.help) {
         console.log(new CliParser().getHelp());
         return;
@@ -57,12 +110,26 @@ export async function run() {
     const globalHooks = new GlobalHooks();
     const exceptionsManager = new ExceptionsManager();
     try {
+        /**
+         * Executing the retry plugin as the first thing
+         */
         await retryPlugin({ config: runnerConfig, runner, emitter, cliArgs });
+        /**
+         * Step 1: Executing plugins before creating a plan, so that it can mutate
+         * the config
+         */
         for (let plugin of runnerConfig.plugins) {
             debug('executing "%s" plugin', plugin.name || 'anonymous');
             await plugin({ runner, emitter, cliArgs, config: runnerConfig });
         }
+        /**
+         * Step 2: Creating an execution plan. The output is the result of
+         * applying all the filters and validations.
+         */
         const { config, reporters, suites, refinerFilters } = await new Planner(runnerConfig).plan();
+        /**
+         * Step 3: Registering reporters and filters with the runner
+         */
         reporters.forEach((reporter) => {
             debug('registering "%s" reporter', reporter.name);
             runner.registerReporter(reporter);
@@ -73,10 +140,19 @@ export async function run() {
         });
         config.refiner.matchAllTags(cliArgs.matchAll ?? false);
         runner.onSuite(config.configureSuite);
+        /**
+         * Step 4: Running the setup hooks
+         */
         debug('executing global hooks');
         globalHooks.apply(config);
         await globalHooks.setup(runner);
+        /**
+         * Step 5: Register suites and import test files
+         */
         for (let suite of suites) {
+            /**
+             * Creating and configuring the suite
+             */
             executionPlanState.suite = new Suite(suite.name, emitter, config.refiner);
             executionPlanState.retries = suite.retries;
             executionPlanState.timeout = suite.timeout;
@@ -84,19 +160,34 @@ export async function run() {
                 suite.configure(executionPlanState.suite);
             }
             runner.add(executionPlanState.suite);
+            /**
+             * Importing suite files
+             */
             for (let fileURL of suite.filesURLs) {
                 executionPlanState.file = fileURLToPath(fileURL);
                 debug('importing test file %s', executionPlanState.file);
                 await config.importer(fileURL);
             }
+            /**
+             * Resetting global state
+             */
             executionPlanState.suite = undefined;
         }
+        /**
+         * Onto execution phase
+         */
         executionPlanState.phase = 'executing';
+        /**
+         * Monitor for unhandled erorrs and rejections
+         */
         exceptionsManager.monitor();
         await runner.start();
         await runner.exec();
         await globalHooks.teardown(null, runner);
         await runner.end();
+        /**
+         * Print unhandled errors
+         */
         await exceptionsManager.flow();
         const summary = runner.getSummary();
         if (summary.hasError || exceptionsManager.hasErrors) {
@@ -110,6 +201,10 @@ export async function run() {
         await globalHooks.teardown(error, runner);
         const printer = new ErrorsPrinter();
         await printer.printError(error);
+        /**
+         * Print unhandled errors in case the code inside
+         * the try block never got triggered
+         */
         await exceptionsManager.flow();
         process.exitCode = 1;
         if (runnerConfig.forceExit) {

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

@@ -10,20 +10,53 @@ declare module '@japa/core' {
     }
 }
 export { Emitter, Refiner, BaseReporter };
+/**
+ * Test context carries context data for a given test.
+ */
 export declare class TestContext extends BaseTestContext {
     test: Test;
+    /**
+     * Register a cleanup function that runs after the test finishes
+     * successfully or with an error.
+     */
     cleanup: (cleanupCallback: TestHooksCleanupHandler<TestContext>) => void;
     constructor(test: Test);
 }
+/**
+ * Test class represents an individual test and exposes API to tweak
+ * its runtime behavior.
+ */
 export declare class Test<TestData extends DataSetNode = undefined> extends BaseTest<TestContext, TestData> {
+    /**
+     * @inheritdoc
+     */
     static executedCallbacks: never[];
+    /**
+     * @inheritdoc
+     */
     static executingCallbacks: never[];
+    /**
+     * Assert the test callback throws an exception when a certain
+     * error message and optionally is an instance of a given
+     * Error class.
+     */
     throws(message: string | RegExp, errorConstructor?: any): this;
 }
+/**
+ * TestGroup is used to bulk configure a collection of tests and
+ * define lifecycle hooks for them
+ */
 export declare class Group extends BaseGroup<TestContext> {
 }
+/**
+ * A suite is a collection of tests created around a given
+ * testing type. For example: A suite for unit tests, a
+ * suite for functional tests and so on.
+ */
 export declare class Suite extends BaseSuite<TestContext> {
 }
+/**
+ * Runner class is used to execute the tests
+ */
 export declare class Runner extends BaseRunner<TestContext> {
 }
-//# sourceMappingURL=main.d.ts.map

package/build/modules/core/main.js

@@ -1,8 +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 { Emitter, Refiner, Test as BaseTest, Suite as BaseSuite, Group as BaseGroup, Runner as BaseRunner, TestContext as BaseTestContext, } from '@japa/core';
 import { inspect } from 'node:util';
 import { AssertionError } from 'node:assert';
 import { BaseReporter } from './reporters/base.js';
 export { Emitter, Refiner, BaseReporter };
+/**
+ * Test context carries context data for a given test.
+ */
 export class TestContext extends BaseTestContext {
     test;
     constructor(test) {
@@ -13,15 +24,33 @@ export class TestContext extends BaseTestContext {
         };
     }
 }
+/**
+ * Test class represents an individual test and exposes API to tweak
+ * its runtime behavior.
+ */
 export class Test extends BaseTest {
+    /**
+     * @inheritdoc
+     */
     static executedCallbacks = [];
+    /**
+     * @inheritdoc
+     */
     static executingCallbacks = [];
+    /**
+     * Assert the test callback throws an exception when a certain
+     * error message and optionally is an instance of a given
+     * Error class.
+     */
     throws(message, errorConstructor) {
         const errorInPoint = new AssertionError({});
         const existingExecutor = this.options.executor;
         if (!existingExecutor) {
             throw new Error('Cannot use "test.throws" method without a test callback');
         }
+        /**
+         * Overwriting existing callback
+         */
         this.options.executor = async (...args) => {
             let raisedException;
             try {
@@ -30,19 +59,31 @@ export class Test extends BaseTest {
             catch (error) {
                 raisedException = error;
             }
+            /**
+             * Notify no exception has been raised
+             */
             if (!raisedException) {
                 errorInPoint.message = 'Expected test to throw an exception';
                 throw errorInPoint;
             }
+            /**
+             * Constructor mis-match
+             */
             if (errorConstructor && !(raisedException instanceof errorConstructor)) {
                 errorInPoint.message = `Expected test to throw "${inspect(errorConstructor)}"`;
                 throw errorInPoint;
             }
+            /**
+             * Error does not have a message property
+             */
             const exceptionMessage = raisedException.message;
             if (!exceptionMessage || typeof exceptionMessage !== 'string') {
                 errorInPoint.message = 'Expected test to throw an exception with message property';
                 throw errorInPoint;
             }
+            /**
+             * Message does not match
+             */
             if (typeof message === 'string') {
                 if (exceptionMessage !== message) {
                     errorInPoint.message = `Expected test to throw "${message}". Instead received "${raisedException.message}"`;
@@ -60,9 +101,21 @@ export class Test extends BaseTest {
         return this;
     }
 }
+/**
+ * TestGroup is used to bulk configure a collection of tests and
+ * define lifecycle hooks for them
+ */
 export class Group extends BaseGroup {
 }
+/**
+ * A suite is a collection of tests created around a given
+ * testing type. For example: A suite for unit tests, a
+ * suite for functional tests and so on.
+ */
 export class Suite extends BaseSuite {
 }
+/**
+ * Runner class is used to execute the tests
+ */
 export class Runner extends BaseRunner {
 }

package/build/modules/core/reporters/base.d.ts

@@ -1,12 +1,27 @@
 import type { TestEndNode, SuiteEndNode, GroupEndNode, TestStartNode, RunnerSummary, RunnerEndNode, GroupStartNode, SuiteStartNode, RunnerStartNode, BaseReporterOptions } from '../types.js';
 import { Emitter, Runner } from '../main.js';
+/**
+ * Base reporter to build custom reporters on top of
+ */
 export declare abstract class BaseReporter {
     #private;
     runner?: Runner;
+    /**
+     * Path to the file for which the tests are getting executed
+     */
     currentFileName?: string;
+    /**
+     * Suite for which the tests are getting executed
+     */
     currentSuiteName?: string;
+    /**
+     * Group for which the tests are getting executed
+     */
     currentGroupName?: string;
     constructor(options?: BaseReporterOptions);
+    /**
+     * Handlers to capture events
+     */
     protected onTestStart(_: TestStartNode): void;
     protected onTestEnd(_: TestEndNode): void;
     protected onGroupStart(_: GroupStartNode): void;
@@ -15,7 +30,12 @@ export declare abstract class BaseReporter {
     protected onSuiteEnd(_: SuiteEndNode): void;
     protected start(_: RunnerStartNode): Promise<void>;
     protected end(_: RunnerEndNode): Promise<void>;
+    /**
+     * Print tests summary
+     */
     protected printSummary(summary: RunnerSummary): Promise<void>;
+    /**
+     * Invoked by the tests runner when tests are about to start
+     */
     boot(runner: Runner, emitter: Emitter): void;
 }
-//# sourceMappingURL=base.d.ts.map

package/build/modules/core/reporters/base.js

@@ -1,18 +1,44 @@
+/*
+ * @japa/runner
+ *
+ * (c) Japa
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
 import ms from 'ms';
 import colors from '@poppinss/colors';
 import { ErrorsPrinter } from '@japa/errors-printer';
 const ansi = colors.ansi();
+/**
+ * Base reporter to build custom reporters on top of
+ */
 export class BaseReporter {
     #options;
     runner;
+    /**
+     * Path to the file for which the tests are getting executed
+     */
     currentFileName;
+    /**
+     * Suite for which the tests are getting executed
+     */
     currentSuiteName;
+    /**
+     * Group for which the tests are getting executed
+     */
     currentGroupName;
     constructor(options = {}) {
         this.#options = Object.assign({ stackLinesCount: 2 }, options);
     }
+    /**
+     * Pretty prints the aggregates
+     */
     #printAggregates(summary) {
         const tests = [];
+        /**
+         * Set value for tests row
+         */
         if (summary.aggregates.passed) {
             tests.push(ansi.green(`${summary.aggregates.passed} passed`));
         }
@@ -42,17 +68,26 @@ export class BaseReporter {
         });
         console.log(this.runner.summaryBuilder.build().join('\n'));
     }
+    /**
+     * Aggregates errors tree to a flat array
+     */
     #aggregateErrors(summary) {
         const errorsList = [];
         summary.failureTree.forEach((suite) => {
             suite.errors.forEach((error) => errorsList.push({ title: suite.name, ...error }));
             suite.children.forEach((testOrGroup) => {
+                /**
+                 * Suite child is a test
+                 */
                 if (testOrGroup.type === 'test') {
                     testOrGroup.errors.forEach((error) => {
                         errorsList.push({ title: `${suite.name} / ${testOrGroup.title}`, ...error });
                     });
                     return;
                 }
+                /**
+                 * Suite child is a group
+                 */
                 testOrGroup.errors.forEach((error) => {
                     errorsList.push({ title: testOrGroup.name, ...error });
                 });
@@ -65,6 +100,9 @@ export class BaseReporter {
         });
         return errorsList;
     }
+    /**
+     * Pretty print errors
+     */
     async #printErrors(summary) {
         if (!summary.failureTree.length) {
             return;
@@ -76,6 +114,9 @@ export class BaseReporter {
         errorPrinter.printSectionHeader('ERRORS');
         await errorPrinter.printErrors(this.#aggregateErrors(summary));
     }
+    /**
+     * Handlers to capture events
+     */
     onTestStart(_) { }
     onTestEnd(_) { }
     onGroupStart(_) { }
@@ -84,6 +125,9 @@ export class BaseReporter {
     onSuiteEnd(_) { }
     async start(_) { }
     async end(_) { }
+    /**
+     * Print tests summary
+     */
     async printSummary(summary) {
         await this.#printErrors(summary);
         console.log('');
@@ -100,6 +144,9 @@ export class BaseReporter {
         console.log('');
         this.#printAggregates(summary);
     }
+    /**
+     * Invoked by the tests runner when tests are about to start
+     */
     boot(runner, emitter) {
         this.runner = runner;
         emitter.on('test:start', (payload) => {