@japa/runner 3.0.0-8 → 3.0.0-9

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

@@ -0,0 +1,41 @@
+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;
+    protected onGroupEnd(_: GroupEndNode): void;
+    protected onSuiteStart(_: SuiteStartNode): void;
+    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;
+}

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

@@ -0,0 +1,183 @@
+/*
+ * @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`));
+        }
+        if (summary.aggregates.failed) {
+            tests.push(ansi.red(`${summary.aggregates.failed} failed`));
+        }
+        if (summary.aggregates.todo) {
+            tests.push(ansi.cyan(`${summary.aggregates.todo} todo`));
+        }
+        if (summary.aggregates.skipped) {
+            tests.push(ansi.yellow(`${summary.aggregates.skipped} skipped`));
+        }
+        if (summary.aggregates.regression) {
+            tests.push(ansi.magenta(`${summary.aggregates.regression} regression`));
+        }
+        this.runner.summaryBuilder.use(() => {
+            return [
+                {
+                    key: ansi.dim('Tests'),
+                    value: `${tests.join(', ')} ${ansi.dim(`(${summary.aggregates.total})`)}`,
+                },
+                {
+                    key: ansi.dim('Time'),
+                    value: ansi.dim(ms(summary.duration)),
+                },
+            ];
+        });
+        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 });
+                });
+                testOrGroup.children.forEach((test) => {
+                    test.errors.forEach((error) => {
+                        errorsList.push({ title: `${testOrGroup.name} / ${test.title}`, ...error });
+                    });
+                });
+            });
+        });
+        return errorsList;
+    }
+    /**
+     * Pretty print errors
+     */
+    async #printErrors(summary) {
+        if (!summary.failureTree.length) {
+            return;
+        }
+        const errorPrinter = new ErrorsPrinter({
+            stackLinesCount: this.#options.stackLinesCount,
+            framesMaxLimit: this.#options.framesMaxLimit,
+        });
+        errorPrinter.printSectionHeader('ERRORS');
+        await errorPrinter.printErrors(this.#aggregateErrors(summary));
+    }
+    /**
+     * Handlers to capture events
+     */
+    onTestStart(_) { }
+    onTestEnd(_) { }
+    onGroupStart(_) { }
+    onGroupEnd(_) { }
+    onSuiteStart(_) { }
+    onSuiteEnd(_) { }
+    async start(_) { }
+    async end(_) { }
+    /**
+     * Print tests summary
+     */
+    async printSummary(summary) {
+        await this.#printErrors(summary);
+        console.log('');
+        if (summary.aggregates.total === 0 && !summary.hasError) {
+            console.log(ansi.bgYellow().black(' NO TESTS EXECUTED '));
+            return;
+        }
+        if (summary.hasError) {
+            console.log(ansi.bgRed().black(' FAILED '));
+        }
+        else {
+            console.log(ansi.bgGreen().black(' PASSED '));
+        }
+        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) => {
+            this.currentFileName = payload.meta.fileName;
+            this.onTestStart(payload);
+        });
+        emitter.on('test:end', (payload) => {
+            this.onTestEnd(payload);
+        });
+        emitter.on('group:start', (payload) => {
+            this.currentGroupName = payload.title;
+            this.currentFileName = payload.meta.fileName;
+            this.onGroupStart(payload);
+        });
+        emitter.on('group:end', (payload) => {
+            this.currentGroupName = undefined;
+            this.onGroupEnd(payload);
+        });
+        emitter.on('suite:start', (payload) => {
+            this.currentSuiteName = payload.name;
+            this.onSuiteStart(payload);
+        });
+        emitter.on('suite:end', (payload) => {
+            this.currentSuiteName = undefined;
+            this.onSuiteEnd(payload);
+        });
+        emitter.on('runner:start', async (payload) => {
+            await this.start(payload);
+        });
+        emitter.on('runner:end', async (payload) => {
+            await this.end(payload);
+        });
+    }
+}

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

@@ -0,0 +1,5 @@
+export * from '@japa/core/types';
+export type BaseReporterOptions = {
+    stackLinesCount?: number;
+    framesMaxLimit?: number;
+};

package/build/modules/core/types.js

@@ -0,0 +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

@@ -0,0 +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;
+}

package/build/src/cli_parser.js

@@ -0,0 +1,75 @@
+/*
+ * @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', 'failed'],
+    boolean: ['help', 'matchAll', 'failed'],
+    alias: {
+        forceExit: 'force-exit',
+        matchAll: 'match-all',
+        help: 'h',
+    },
+};
+/**
+ * Help string to display when the `--help flag is used`
+ */
+const GET_HELP = () => `
+${ansi.yellow('@japa/runner v2.3.0')}
+
+${ansi.green('--tests')}                     ${ansi.dim('Filter tests by the test title')}
+${ansi.green('--groups')}                    ${ansi.dim('Filter tests by the group title')}
+${ansi.green('--tags')}                      ${ansi.dim('Filter tests by tags')}
+${ansi.green('--files')}                     ${ansi.dim('Filter tests by the file name')}
+${ansi.green('--force-exit')}                ${ansi.dim('Forcefully exit the process')}
+${ansi.green('--timeout')}                   ${ansi.dim('Define default timeout for all tests')}
+${ansi.green('--retries')}                   ${ansi.dim('Define default retries for all tests')}
+${ansi.green('--reporter')}                  ${ansi.dim('Activate one or more test reporters')}
+${ansi.green('--failed')}                    ${ansi.dim('Run tests failed during the last run')}
+${ansi.green('-h, --help')}                  ${ansi.dim('View help')}
+
+${ansi.yellow('Examples:')}
+${ansi.dim('node bin/test.js --tags="@github"')}
+${ansi.dim('node bin/test.js --tags="~@github"')}
+${ansi.dim('node bin/test.js --tags="@github,@slow,@integration" --match-all')}
+${ansi.dim('node bin/test.js --force-exit')}
+${ansi.dim('node bin/test.js --files="user"')}
+${ansi.dim('node bin/test.js --files="functional/user"')}
+${ansi.dim('node bin/test.js --files="unit/user"')}
+
+${ansi.yellow('Notes:')}
+- When groups and tests filters are applied together. We will first filter the
+  tests by group title and then apply the tests title filter.
+- The timeout defined on test object takes precedence over the ${ansi.green('--timeout')} flag.
+- 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

@@ -0,0 +1,18 @@
+import type { CLIArgs, Config, NormalizedConfig } from './types.js';
+export declare const NOOP: () => void;
+/**
+ * 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(): NormalizedConfig;
+}

package/build/src/config_manager.js

@@ -0,0 +1,168 @@
+/*
+ * @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 { Refiner } from '../modules/core/main.js';
+import { dot, ndjson, spec } from './reporters/main.js';
+export const NOOP = () => { };
+/**
+ * Defaults to use for configuration
+ */
+const DEFAULTS = {
+    files: [],
+    timeout: 2000,
+    retries: 0,
+    forceExit: false,
+    plugins: [],
+    reporters: {
+        activated: ['spec'],
+        list: [spec(), ndjson(), dot()],
+    },
+    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;
+    constructor(config, cliArgs) {
+        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) {
+            filters.tags = this.#processAsArray(this.#cliArgs.tags);
+        }
+        if (this.#cliArgs.tests) {
+            filters.tests = this.#processAsArray(this.#cliArgs.tests);
+        }
+        if (this.#cliArgs.files) {
+            filters.files = this.#processAsArray(this.#cliArgs.files);
+        }
+        if (this.#cliArgs.groups) {
+            filters.groups = this.#processAsArray(this.#cliArgs.groups);
+        }
+        if (this.#cliArgs._ && this.#cliArgs._.length) {
+            filters.suites = this.#processAsArray(this.#cliArgs._);
+        }
+        return filters;
+    }
+    /**
+     * Returns the timeout from the CLI args
+     */
+    #getCLITimeout() {
+        if (this.#cliArgs.timeout) {
+            const value = Number(this.#cliArgs.timeout);
+            if (!Number.isNaN(value)) {
+                return value;
+            }
+        }
+    }
+    /**
+     * Returns the retries from the CLI args
+     */
+    #getCLIRetries() {
+        if (this.#cliArgs.retries) {
+            const value = Number(this.#cliArgs.retries);
+            if (!Number.isNaN(value)) {
+                return value;
+            }
+        }
+    }
+    /**
+     * 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();
+        const cliTimeout = this.#getCLITimeout();
+        const cliReporters = this.#getCLIReporters();
+        const cliForceExit = this.#getCLIForceExit();
+        debug('filters applied using CLI flags %O', cliFilters);
+        const baseConfig = {
+            cwd: this.#config.cwd ?? process.cwd(),
+            filters: Object.assign({}, this.#config.filters ?? {}, cliFilters),
+            importer: this.#config.importer ?? DEFAULTS.importer,
+            refiner: this.#config.refiner ?? new Refiner(),
+            retries: cliRetries ?? this.#config.retries ?? DEFAULTS.retries,
+            timeout: cliTimeout ?? this.#config.timeout ?? DEFAULTS.timeout,
+            plugins: this.#config.plugins ?? DEFAULTS.plugins,
+            forceExit: cliForceExit ?? this.#config.forceExit ?? DEFAULTS.forceExit,
+            reporters: this.#config.reporters
+                ? {
+                    activated: this.#config.reporters.activated,
+                    list: this.#config.reporters.list || DEFAULTS.reporters.list,
+                }
+                : DEFAULTS.reporters,
+            configureSuite: this.#config.configureSuite ?? DEFAULTS.configureSuite,
+            setup: this.#config.setup || [],
+            teardown: this.#config.teardown || [],
+        };
+        /**
+         * Overwrite activated reporters when defined using CLI
+         * flag
+         */
+        if (cliReporters) {
+            baseConfig.reporters.activated = cliReporters;
+        }
+        if ('files' in this.#config) {
+            return {
+                files: this.#config.files,
+                ...baseConfig,
+            };
+        }
+        return {
+            suites: this.#config.suites.map((suite) => {
+                return {
+                    name: suite.name,
+                    files: suite.files,
+                    timeout: cliTimeout ?? suite.timeout ?? baseConfig.timeout,
+                    retries: cliRetries ?? suite.retries ?? baseConfig.retries,
+                    configure: suite.configure || NOOP,
+                };
+            }),
+            ...baseConfig,
+        };
+    }
+}

package/build/src/create_test.d.ts

@@ -0,0 +1,21 @@
+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;
+    file?: string;
+    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;
+    file?: string;
+    timeout?: number;
+    retries?: number;
+}): Group;

package/build/src/create_test.js

@@ -0,0 +1,53 @@
+/*
+ * @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;
+    testInstance.options.meta.group = options.group;
+    testInstance.options.meta.fileName = options.file;
+    if (options.timeout !== undefined) {
+        testInstance.timeout(options.timeout);
+    }
+    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);
+    }
+    else if (options.suite) {
+        options.suite.add(testInstance);
+    }
+    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');
+    }
+    const group = new Group(title, emitter, refiner);
+    group.options.meta.suite = options.suite;
+    group.options.meta.fileName = options.file;
+    if (options.suite) {
+        options.suite.add(group);
+    }
+    return group;
+}

package/build/src/debug.d.ts

@@ -0,0 +1,3 @@
+/// <reference types="node" resolution-mode="require"/>
+declare const _default: import("util").DebugLogger;
+export default _default;

package/build/src/debug.js

@@ -0,0 +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

@@ -0,0 +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>;
+}