@japa/runner 2.5.0 → 3.0.0-0

package/LICENSE.md

@@ -1,6 +1,6 @@
 # The MIT License
 
-Copyright 2022 Harminder Virk, contributors
+Copyright (c) 2023 Harminder Virk
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 

package/build/index.d.ts

@@ -1,33 +1,12 @@
-import { TestExecutor, ReporterContract } from '@japa/core';
-import { Test, TestContext, Group, Suite, Runner } from './src/core/main';
-import { Config, PluginFn, RunnerHooksHandler, RunnerHooksCleanupHandler } from './src/types';
-export { Test, Config, Suite, Runner, Group, PluginFn, TestContext, ReporterContract, RunnerHooksHandler, RunnerHooksCleanupHandler, };
-/**
- * Configure the tests runner
- */
-export declare function configure(options: Config): void;
-/**
- * Process CLI arguments into configuration options. The following
- * command line arguments are processed.
- *
- * * --tests=Specify test titles
- * * --tags=Specify test tags
- * * --groups=Specify group titles
- * * --ignore-tags=Specify negated tags
- * * --files=Specify files to match and run
- * * --force-exit=Enable/disable force exit
- * * --timeout=Define timeout for all the tests
- * * -h, --help=Show help
- */
-export declare function processCliArgs(argv: string[]): Partial<Config>;
-/**
- * Run japa tests
- */
-export declare function run(): Promise<void>;
-/**
- * Add a new test
- */
+import type { TestExecutor } from '@japa/core/types';
+import type { Config } from './src/types.js';
+import { Group, Test, TestContext } from './modules/core/main.js';
 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;
 }
+export declare function getActiveTest(): Test<any> | undefined;
+export declare function processCLIArgs(argv: string[]): void;
+export declare function configure(options: Config): void;
+export declare function run(): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

package/build/index.js

@@ -1,482 +1,119 @@
-"use strict";
-/*
- * @japa/runner
- *
- * (c) Japa.dev
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
+import { fileURLToPath } from 'node:url';
+import { ErrorsPrinter } from '@japa/errors-printer';
+import debug from './src/debug.js';
+import validator from './src/validator.js';
+import { Planner } from './src/planner.js';
+import { GlobalHooks } from './src/hooks.js';
+import { CliParser } from './src/cli_parser.js';
+import { retryPlugin } from './src/plugins/retry.js';
+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';
+const emitter = new Emitter();
+let activeTest;
+let cliArgs = {};
+let runnerConfig;
+const executionPlanState = {
+    phase: 'idle',
 };
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.test = exports.run = exports.processCliArgs = exports.configure = exports.TestContext = exports.Group = exports.Runner = exports.Suite = exports.Test = void 0;
-const getopts_1 = __importDefault(require("getopts"));
-const path_1 = require("path");
-const fast_glob_1 = __importDefault(require("fast-glob"));
-const inclusion_1 = __importDefault(require("inclusion"));
-const url_1 = require("url");
-const hooks_1 = require("@poppinss/hooks");
-const cliui_1 = require("@poppinss/cliui");
-const errors_printer_1 = require("@japa/errors-printer");
-const core_1 = require("@japa/core");
-const main_1 = require("./src/core/main");
-Object.defineProperty(exports, "Test", { enumerable: true, get: function () { return main_1.Test; } });
-Object.defineProperty(exports, "TestContext", { enumerable: true, get: function () { return main_1.TestContext; } });
-Object.defineProperty(exports, "Group", { enumerable: true, get: function () { return main_1.Group; } });
-Object.defineProperty(exports, "Suite", { enumerable: true, get: function () { return main_1.Suite; } });
-Object.defineProperty(exports, "Runner", { enumerable: true, get: function () { return main_1.Runner; } });
-/**
- * Filtering layers allowed by the refiner
- */
-const refinerFilteringLayers = ['tests', 'groups', 'tags'];
-/**
- * Reference to the recently imported file. We pass it to the
- * test and the group both
- */
-let recentlyImportedFile;
-/**
- * Global timeout for tests. Fetched from runner options or suites
- * options
- */
-let globalTimeout;
-/**
- * Function to create the test context for the test
- */
-const getContext = (testInstance) => new main_1.TestContext(testInstance);
-/**
- * The global reference to the tests emitter
- */
-const emitter = new core_1.Emitter();
-/**
- * Active suite for tests
- */
-let activeSuite;
-/**
- * Currently active group
- */
-let activeGroup;
-/**
- * Configuration options
- */
-let runnerOptions;
-/**
- * Ensure the configure method has been called
- */
-function ensureIsConfigured(message) {
-    if (!runnerOptions) {
-        throw new Error(message);
-    }
-}
-/**
- * Validate suites filter to ensure a wrong suite is not
- * mentioned
- */
-function validateSuitesFilter() {
-    if (!('suites' in runnerOptions)) {
-        return;
-    }
-    if (!runnerOptions.filters.suites || !runnerOptions.filters.suites.length) {
-        return;
-    }
-    const suites = runnerOptions.suites.map(({ name }) => name);
-    const invalidSuites = runnerOptions.filters.suites.filter((suite) => !suites.includes(suite));
-    if (invalidSuites.length) {
-        throw new Error(`Unrecognized suite "${invalidSuites[0]}". Make sure to define it in the config first`);
-    }
-}
-/**
- * Process command line argument into a string value
- */
-function processAsString(argv, flagName, onMatch) {
-    const flag = argv[flagName];
-    if (flag) {
-        onMatch((Array.isArray(flag) ? flag : flag.split(',')).map((tag) => tag.trim()));
-    }
-}
-/**
- * Find if the file path matches the files filter array.
- * The ending of the file is matched
- */
-function isFileAllowed(filePath, filters) {
-    if (!filters.files || !filters.files.length) {
-        return true;
-    }
-    return !!filters.files.find((matcher) => {
-        if (filePath.endsWith(matcher)) {
-            return true;
-        }
-        return filePath.replace((0, path_1.extname)(filePath), '').endsWith(matcher);
+export function test(title, callback) {
+    validator.ensureIsInPlanningPhase(executionPlanState.phase);
+    const testInstance = createTest(title, emitter, runnerConfig.refiner, executionPlanState);
+    testInstance.setup((t) => {
+        activeTest = t;
+        return () => {
+            activeTest = undefined;
+        };
     });
-}
-/**
- * Returns "true" when no filters are applied or the name is part
- * of the applied filter.
- */
-function isSuiteAllowed(suite, filters) {
-    if (!filters.suites || !filters.suites.length) {
-        return true;
-    }
-    return filters.suites.includes(suite.name);
-}
-/**
- * Collect files using the files collector function or by processing
- * the glob pattern.
- *
- * The return value is further filtered against the `--files` filter.
- */
-async function collectFiles(files) {
-    if (Array.isArray(files) || typeof files === 'string') {
-        const collectedFiles = await (0, fast_glob_1.default)(files, {
-            absolute: true,
-            onlyFiles: true,
-            cwd: runnerOptions.cwd,
-        });
-        return collectedFiles.filter((file) => isFileAllowed(file, runnerOptions.filters));
-    }
-    else if (typeof files === 'function') {
-        const collectedFiles = await files();
-        return collectedFiles.filter((file) => isFileAllowed(file, runnerOptions.filters));
-    }
-    throw new Error('Invalid value for "files" property. Expected a string, array or a function');
-}
-/**
- * Import test files using the configured importer.
- */
-async function importFiles(files) {
-    for (let file of files) {
-        recentlyImportedFile = file;
-        await runnerOptions.importer(file);
+    if (callback) {
+        testInstance.run(callback);
     }
+    return testInstance;
 }
-/**
- * End tests. We wait for the "beforeExit" event when
- * forceExit is not set to true
- */
-async function endTests(runner) {
-    if (runnerOptions.forceExit) {
-        await runner.end();
-    }
-    else {
-        return new Promise((resolve) => {
-            async function beforeExit() {
-                process.removeListener('beforeExit', beforeExit);
-                await runner.end();
-                resolve();
-            }
-            process.on('beforeExit', beforeExit);
-        });
-    }
+test.group = function (title, callback) {
+    validator.ensureIsInPlanningPhase(executionPlanState.phase);
+    executionPlanState.group = createTestGroup(title, emitter, runnerConfig.refiner, executionPlanState);
+    callback(executionPlanState.group);
+    executionPlanState.group = undefined;
+};
+export function getActiveTest() {
+    return activeTest;
 }
-/**
- * Show help output in stdout.
- */
-function showHelp() {
-    const green = cliui_1.logger.colors.green.bind(cliui_1.logger.colors);
-    const grey = cliui_1.logger.colors.grey.bind(cliui_1.logger.colors);
-    console.log(`@japa/runner v2.3.0
-
-Options:
-  ${green('--tests')}                     ${grey('Specify test titles')}
-  ${green('--tags')}                      ${grey('Specify test tags')}
-  ${green('--groups')}                    ${grey('Specify group titles')}
-  ${green('--ignore-tags')}               ${grey('Specify negated tags')}
-  ${green('--files')}                     ${grey('Specify files to match and run')}
-  ${green('--force-exit')}                ${grey('Enable/disable force exit')}
-  ${green('--timeout')}                   ${grey('Define timeout for all the tests')}
-  ${green('-h, --help')}                  ${grey('Display this message')}
-
-Examples:
-  ${grey('$ node bin/test.js --tags="@github"')}
-  ${grey('$ node bin/test.js --files="example.spec.js" --force-exit')}`);
+export function processCLIArgs(argv) {
+    cliArgs = new CliParser().parse(argv);
 }
-/**
- * Configure the tests runner
- */
-function configure(options) {
-    const defaultOptions = {
-        cliArgs: {},
-        cwd: process.cwd(),
-        files: [],
-        suites: [],
-        plugins: [],
-        reporters: [],
-        timeout: 2000,
-        filters: {},
-        setup: [],
-        teardown: [],
-        importer: (filePath) => (0, inclusion_1.default)((0, url_1.pathToFileURL)(filePath).href),
-        refiner: new core_1.Refiner({}),
-        forceExit: false,
-        configureSuite: () => { },
-    };
-    runnerOptions = Object.assign(defaultOptions, options);
+export function configure(options) {
+    runnerConfig = new ConfigManager(options, cliArgs).hydrate();
 }
-exports.configure = configure;
-/**
- * Process CLI arguments into configuration options. The following
- * command line arguments are processed.
- *
- * * --tests=Specify test titles
- * * --tags=Specify test tags
- * * --groups=Specify group titles
- * * --ignore-tags=Specify negated tags
- * * --files=Specify files to match and run
- * * --force-exit=Enable/disable force exit
- * * --timeout=Define timeout for all the tests
- * * -h, --help=Show help
- */
-function processCliArgs(argv) {
-    const parsed = (0, getopts_1.default)(argv, {
-        string: ['tests', 'tags', 'groups', 'ignoreTags', 'files', 'timeout'],
-        boolean: ['forceExit', 'help'],
-        alias: {
-            ignoreTags: 'ignore-tags',
-            forceExit: 'force-exit',
-            help: 'h',
-        },
-    });
-    const config = {
-        filters: {},
-        cliArgs: parsed,
-    };
-    processAsString(parsed, 'tags', (tags) => (config.filters.tags = tags));
-    processAsString(parsed, 'ignoreTags', (tags) => {
-        config.filters.tags = config.filters.tags || [];
-        tags.forEach((tag) => config.filters.tags.push(`!${tag}`));
-    });
-    processAsString(parsed, 'groups', (groups) => (config.filters.groups = groups));
-    processAsString(parsed, 'tests', (tests) => (config.filters.tests = tests));
-    processAsString(parsed, 'files', (files) => (config.filters.files = files));
-    /**
-     * Show help
-     */
-    if (parsed.help) {
-        showHelp();
-        process.exit(0);
-    }
-    /**
-     * Get suites
-     */
-    if (parsed._.length) {
-        processAsString({ suites: parsed._ }, 'suites', (suites) => (config.filters.suites = suites));
-    }
-    /**
-     * Get timeout
-     */
-    if (parsed.timeout) {
-        const value = Number(parsed.timeout);
-        if (!isNaN(value)) {
-            config.timeout = value;
-        }
-    }
-    /**
-     * Get forceExit
-     */
-    if (parsed.forceExit) {
-        config.forceExit = true;
+export async function run() {
+    if (cliArgs.help) {
+        console.log(new CliParser().getHelp());
+        return;
     }
-    return config;
-}
-exports.processCliArgs = processCliArgs;
-/**
- * Run japa tests
- */
-async function run() {
-    const runner = new main_1.Runner(emitter);
-    runner.manageUnHandledExceptions();
-    runner.onSuite(runnerOptions.configureSuite);
-    const hooks = new hooks_1.Hooks();
-    let setupRunner;
-    let teardownRunner;
+    validator.ensureIsConfigured(runnerConfig);
+    executionPlanState.phase = 'planning';
+    const runner = new Runner(emitter);
+    const globalHooks = new GlobalHooks();
+    const exceptionsManager = new ExceptionsManager();
     try {
-        ensureIsConfigured('Cannot run tests without configuring the tests runner');
-        /**
-         * Step 1: Run all plugins
-         *
-         * Plugins can also mutate config. So we process the config after
-         * running plugins only
-         */
-        for (let plugin of runnerOptions.plugins) {
-            await plugin(runnerOptions, runner, { Test: main_1.Test, TestContext: main_1.TestContext, Group: main_1.Group });
+        await retryPlugin({ config: runnerConfig, runner, emitter, cliArgs });
+        for (let plugin of runnerConfig.plugins) {
+            debug('executing "%s" plugin', plugin.name || 'anonymous');
+            await plugin({ runner, emitter, cliArgs, config: runnerConfig });
         }
-        validateSuitesFilter();
-        /**
-         * Step 2: Notify runner about reporters
-         */
-        runnerOptions.reporters.forEach((reporter) => runner.registerReporter(reporter));
-        /**
-         * Step 3: Configure runner hooks.
-         */
-        runnerOptions.setup.forEach((hook) => hooks.add('setup', hook));
-        runnerOptions.teardown.forEach((hook) => hooks.add('teardown', hook));
-        setupRunner = hooks.runner('setup');
-        teardownRunner = hooks.runner('teardown');
-        /**
-         * Step 3.1: Run setup hooks
-         *
-         * We run the setup hooks before importing test files. It
-         * allows hooks to setup the app environment for the
-         * test files.
-         */
-        await setupRunner.run(runner);
-        /**
-         * Step 4: Entertain files property and import test files
-         * as part of the default suite
-         */
-        if ('files' in runnerOptions && runnerOptions.files.length) {
-            /**
-             * Create a default suite for files with no suite
-             */
-            globalTimeout = runnerOptions.timeout;
-            const files = await collectFiles(runnerOptions.files);
-            /**
-             * Create and register suite when files are collected.
-             */
-            if (files.length) {
-                activeSuite = new main_1.Suite('default', emitter, runnerOptions.refiner);
-                runner.add(activeSuite);
-                await importFiles(files);
+        const { config, reporters, suites, refinerFilters } = await new Planner(runnerConfig).plan();
+        reporters.forEach((reporter) => {
+            debug('registering "%s" reporter', reporter.name);
+            runner.registerReporter(reporter);
+        });
+        refinerFilters.forEach((filter) => {
+            debug('apply %s filters "%O" ', filter.layer, filter.filters);
+            config.refiner.add(filter.layer, filter.filters);
+        });
+        config.refiner.matchAllTags(cliArgs.matchAll ?? false);
+        runner.onSuite(config.configureSuite);
+        debug('executing global hooks');
+        globalHooks.apply(config);
+        await globalHooks.setup(runner);
+        for (let suite of suites) {
+            executionPlanState.suite = new Suite(suite.name, emitter, config.refiner);
+            executionPlanState.retries = suite.retries;
+            executionPlanState.timeout = suite.timeout;
+            if (typeof suite.configure === 'function') {
+                suite.configure(executionPlanState.suite);
             }
-        }
-        /**
-         * Step 5: Entertain suites property and import test files
-         * for the filtered suites.
-         */
-        if ('suites' in runnerOptions) {
-            for (let suite of runnerOptions.suites) {
-                if (isSuiteAllowed(suite, runnerOptions.filters)) {
-                    if (suite.timeout !== undefined) {
-                        globalTimeout = suite.timeout;
-                    }
-                    else {
-                        globalTimeout = runnerOptions.timeout;
-                    }
-                    const files = await collectFiles(suite.files);
-                    /**
-                     * Only register the suite and import files when the suite
-                     * files glob + filter has returned one or more files.
-                     */
-                    if (files.length) {
-                        activeSuite = new main_1.Suite(suite.name, emitter, runnerOptions.refiner);
-                        if (typeof suite.configure === 'function') {
-                            suite.configure(activeSuite);
-                        }
-                        runner.add(activeSuite);
-                        await importFiles(files);
-                    }
-                }
+            runner.add(executionPlanState.suite);
+            for (let fileURL of suite.filesURLs) {
+                executionPlanState.file = fileURLToPath(fileURL);
+                debug('importing test file %s', executionPlanState.file);
+                await config.importer(fileURL);
             }
+            executionPlanState.suite = undefined;
         }
-        /**
-         * Step 6: Add filters to the refiner
-         */
-        Object.keys(runnerOptions.filters).forEach((layer) => {
-            if (refinerFilteringLayers.includes(layer)) {
-                const values = runnerOptions.filters[layer];
-                if (values) {
-                    runnerOptions.refiner.add(layer, values);
-                }
-            }
-        });
-        /**
-         * Step 7.1: Start the tests runner
-         */
+        executionPlanState.phase = 'executing';
+        exceptionsManager.monitor();
         await runner.start();
-        /**
-         * Step 7.2: Execute all the tests
-         */
         await runner.exec();
-        /**
-         * Step 7.3: Run cleanup and teardown hooks
-         */
-        await setupRunner.cleanup(runner);
-        await teardownRunner.run(runner);
-        await teardownRunner.cleanup(runner);
-        /**
-         * Step 7.4: End or wait for process to exit
-         */
-        await endTests(runner);
-        /**
-         * Step 8: Update the process exit code
-         */
+        await globalHooks.teardown(null, runner);
+        await runner.end();
+        await exceptionsManager.flow();
         const summary = runner.getSummary();
-        if (summary.hasError) {
+        if (summary.hasError || exceptionsManager.hasErrors) {
             process.exitCode = 1;
         }
-        runnerOptions.forceExit && process.exit();
+        if (config.forceExit) {
+            process.exit();
+        }
     }
     catch (error) {
-        if (setupRunner && setupRunner.isCleanupPending) {
-            await setupRunner.cleanup(error, runner);
-        }
-        if (teardownRunner && teardownRunner.isCleanupPending) {
-            await teardownRunner.cleanup(error, runner);
-        }
-        const printer = new errors_printer_1.ErrorsPrinter();
+        await globalHooks.teardown(error, runner);
+        const printer = new ErrorsPrinter();
         await printer.printError(error);
+        await exceptionsManager.flow();
         process.exitCode = 1;
-        runnerOptions.forceExit && process.exit();
-    }
-}
-exports.run = run;
-/**
- * Add a new test
- */
-function test(title, callback) {
-    ensureIsConfigured('Cannot add test without configuring the test runner');
-    const testInstance = new main_1.Test(title, getContext, emitter, runnerOptions.refiner, activeGroup);
-    /**
-     * Set filename and suite
-     */
-    testInstance.options.meta.suite = activeSuite;
-    testInstance.options.meta.fileName = recentlyImportedFile;
-    /**
-     * Define timeout on the test when exists globally
-     */
-    if (globalTimeout !== undefined) {
-        testInstance.timeout(globalTimeout);
-    }
-    /**
-     * Define test executor function
-     */
-    if (callback) {
-        testInstance.run(callback);
-    }
-    /**
-     * Add test to the group or suite
-     */
-    if (activeGroup) {
-        activeGroup.add(testInstance);
-    }
-    else {
-        activeSuite.add(testInstance);
+        if (runnerConfig.forceExit) {
+            process.exit();
+        }
     }
-    return testInstance;
 }
-exports.test = test;
-/**
- * Define test group
- */
-test.group = function (title, callback) {
-    ensureIsConfigured('Cannot add test group without configuring the test runner');
-    /**
-     * Disallow nested groups
-     */
-    if (activeGroup) {
-        throw new Error('Cannot create nested test groups');
-    }
-    activeGroup = new main_1.Group(title, emitter, runnerOptions.refiner);
-    /**
-     * Set filename and suite
-     */
-    activeGroup.options.meta.suite = activeSuite;
-    activeGroup.options.meta.fileName = recentlyImportedFile;
-    /**
-     * Add group to the default suite
-     */
-    activeSuite.add(activeGroup);
-    callback(activeGroup);
-    activeGroup = undefined;
-};

package/build/src/cli_parser.d.ts

@@ -0,0 +1,6 @@
+import type { CLIArgs } from './types.js';
+export declare class CliParser {
+    parse(argv: string[]): CLIArgs;
+    getHelp(): string;
+}
+//# sourceMappingURL=cli_parser.d.ts.map

package/build/src/cli_parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli_parser.d.ts","sourceRoot":"","sources":["../../src/cli_parser.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAsDzC,qBAAa,SAAS;IAIpB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO;IAO9B,OAAO;CAGR"}