@japa/runner 2.1.3 → 2.2.0

package/LICENSE.md

@@ -1,9 +1,9 @@
-# The MIT License
-
-Copyright 2022 Harminder Virk, contributors
-
-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:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+# The MIT License
+
+Copyright 2022 Harminder Virk, contributors
+
+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:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/build/index.d.ts

@@ -1,33 +1,33 @@
-import { Test, TestContext, Group, Suite, Runner } from './src/Core';
-import { TestExecutor, ReporterContract } from '@japa/core';
-import { Config, PluginFn, RunnerHooksHandler, RunnerHooksCleanupHandler } from './src/Contracts';
-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
- */
-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;
-}
+import { Test, TestContext, Group, Suite, Runner } from './src/Core';
+import { TestExecutor, ReporterContract } from '@japa/core';
+import { Config, PluginFn, RunnerHooksHandler, RunnerHooksCleanupHandler } from './src/Contracts';
+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
+ */
+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;
+}

package/build/index.js

@@ -1,180 +1,180 @@
-"use strict";
-/*
- * @japa/runner
- *
- * (c) Harminder Virk <virk@adonisjs.com>
- *
- * 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 };
-};
-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("./src/Core");
-Object.defineProperty(exports, "Test", { enumerable: true, get: function () { return Core_1.Test; } });
-Object.defineProperty(exports, "TestContext", { enumerable: true, get: function () { return Core_1.TestContext; } });
-Object.defineProperty(exports, "Group", { enumerable: true, get: function () { return Core_1.Group; } });
-Object.defineProperty(exports, "Suite", { enumerable: true, get: function () { return Core_1.Suite; } });
-Object.defineProperty(exports, "Runner", { enumerable: true, get: function () { return Core_1.Runner; } });
-const core_1 = require("@japa/core");
-/**
- * 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 Core_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);
-    });
-}
-/**
- * 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);
-    }
-}
-/**
- * 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);
-        });
-    }
-}
-/**
- * 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);
+"use strict";
+/*
+ * @japa/runner
+ *
+ * (c) Harminder Virk <virk@adonisjs.com>
+ *
+ * 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 };
+};
+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("./src/Core");
+Object.defineProperty(exports, "Test", { enumerable: true, get: function () { return Core_1.Test; } });
+Object.defineProperty(exports, "TestContext", { enumerable: true, get: function () { return Core_1.TestContext; } });
+Object.defineProperty(exports, "Group", { enumerable: true, get: function () { return Core_1.Group; } });
+Object.defineProperty(exports, "Suite", { enumerable: true, get: function () { return Core_1.Suite; } });
+Object.defineProperty(exports, "Runner", { enumerable: true, get: function () { return Core_1.Runner; } });
+const core_1 = require("@japa/core");
+/**
+ * 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 Core_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);
+    });
+}
+/**
+ * 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);
+    }
+}
+/**
+ * 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);
+        });
+    }
+}
+/**
+ * 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.1.1
 
 Options:
@@ -189,290 +189,290 @@ Options:
 
 Examples:
   ${grey('$ node bin/test.js --tags="@github"')}
-  ${grey('$ node bin/test.js --files="example.spec.js" --force-exit')}`);
-}
-/**
- * Configure the tests runner
- */
-function configure(options) {
-    const defaultOptions = {
-        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);
-}
-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: {},
-    };
-    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;
-    }
-    return config;
-}
-exports.processCliArgs = processCliArgs;
-/**
- * Run japa tests
- */
-async function run() {
-    const runner = new Core_1.Runner(emitter);
-    runner.manageUnHandledExceptions();
-    runner.onSuite(runnerOptions.configureSuite);
-    const hooks = new hooks_1.Hooks();
-    let setupRunner;
-    let teardownRunner;
-    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: Core_1.Test, TestContext: Core_1.TestContext, Group: Core_1.Group });
-        }
-        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 Core_1.Suite('default', emitter, runnerOptions.refiner);
-                runner.add(activeSuite);
-                await importFiles(files);
-            }
-        }
-        /**
-         * 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 Core_1.Suite(suite.name, emitter, runnerOptions.refiner);
-                        if (typeof suite.configure === 'function') {
-                            suite.configure(activeSuite);
-                        }
-                        runner.add(activeSuite);
-                        await importFiles(files);
-                    }
-                }
-            }
-        }
-        /**
-         * 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
-         */
-        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
-         */
-        const summary = runner.getSummary();
-        if (summary.hasError) {
-            process.exitCode = 1;
-        }
-        runnerOptions.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 printer.printError(error);
-        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 Core_1.Test(title, getContext, emitter, runnerOptions.refiner, activeGroup);
-    /**
-     * Set filename
-     */
-    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);
-    }
-    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 Core_1.Group(title, emitter, runnerOptions.refiner);
-    /**
-     * Set filename
-     */
-    activeGroup.options.meta.fileName = recentlyImportedFile;
-    /**
-     * Add group to the default suite
-     */
-    activeSuite.add(activeGroup);
-    callback(activeGroup);
-    activeGroup = undefined;
-};
+  ${grey('$ node bin/test.js --files="example.spec.js" --force-exit')}`);
+}
+/**
+ * Configure the tests runner
+ */
+function configure(options) {
+    const defaultOptions = {
+        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);
+}
+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: {},
+    };
+    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;
+    }
+    return config;
+}
+exports.processCliArgs = processCliArgs;
+/**
+ * Run japa tests
+ */
+async function run() {
+    const runner = new Core_1.Runner(emitter);
+    runner.manageUnHandledExceptions();
+    runner.onSuite(runnerOptions.configureSuite);
+    const hooks = new hooks_1.Hooks();
+    let setupRunner;
+    let teardownRunner;
+    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: Core_1.Test, TestContext: Core_1.TestContext, Group: Core_1.Group });
+        }
+        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 Core_1.Suite('default', emitter, runnerOptions.refiner);
+                runner.add(activeSuite);
+                await importFiles(files);
+            }
+        }
+        /**
+         * 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 Core_1.Suite(suite.name, emitter, runnerOptions.refiner);
+                        if (typeof suite.configure === 'function') {
+                            suite.configure(activeSuite);
+                        }
+                        runner.add(activeSuite);
+                        await importFiles(files);
+                    }
+                }
+            }
+        }
+        /**
+         * 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
+         */
+        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
+         */
+        const summary = runner.getSummary();
+        if (summary.hasError) {
+            process.exitCode = 1;
+        }
+        runnerOptions.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 printer.printError(error);
+        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 Core_1.Test(title, getContext, emitter, runnerOptions.refiner, activeGroup);
+    /**
+     * Set filename
+     */
+    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);
+    }
+    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 Core_1.Group(title, emitter, runnerOptions.refiner);
+    /**
+     * Set filename
+     */
+    activeGroup.options.meta.fileName = recentlyImportedFile;
+    /**
+     * Add group to the default suite
+     */
+    activeSuite.add(activeGroup);
+    callback(activeGroup);
+    activeGroup = undefined;
+};

package/build/src/Contracts/index.d.ts

@@ -1,67 +1,67 @@
-import { Refiner, FilteringOptions, ReporterContract } from '@japa/core';
-import { Test, Group, TestContext, Runner, Suite } from '../Core';
-/**
- * The cleanup function for runner hooks
- */
-export declare type RunnerHooksCleanupHandler = (error: null | any, runner: Runner) => Promise<any> | any;
-/**
- * The function that can be registered as a runner hook
- */
-export declare type RunnerHooksHandler = (runner: Runner) => Promise<any> | any | RunnerHooksCleanupHandler | Promise<RunnerHooksCleanupHandler>;
-/**
- * Allowed filters
- */
-export declare type Filters = FilteringOptions & {
-    files?: string[];
-    suites?: string[];
-};
-/**
- * Shape of the plugin function
- */
-export declare type PluginFn = (config: Required<Config>, runner: Runner, classes: {
-    Test: typeof Test;
-    TestContext: typeof TestContext;
-    Group: typeof Group;
-}) => void | Promise<void>;
-/**
- * Runner hooks
- */
-export declare type RunnerHooks = {
-    setup: RunnerHooksHandler[];
-    teardown: RunnerHooksHandler[];
-};
-/**
- * Base configuration options
- */
-export declare type BaseConfig = {
-    cwd?: string;
-    timeout?: number;
-    plugins?: PluginFn[];
-    filters?: Filters;
-    configureSuite?: (suite: Suite) => void;
-    reporters?: ReporterContract[];
-    importer?: (filePath: string) => void | Promise<void>;
-    refiner?: Refiner;
-    forceExit?: boolean;
-} & Partial<RunnerHooks>;
-/**
- * Type for the "config.files" property
- */
-export declare type ConfigFiles = string[] | (() => string[] | Promise<string[]>);
-/**
- * Type for the "config.suite" property
- */
-export declare type ConfigSuite = {
-    name: string;
-    files: string | string[] | (() => string[] | Promise<string[]>);
-    configure?: (suite: Suite) => void;
-    timeout?: number;
-};
-/**
- * Configuration options
- */
-export declare type Config = BaseConfig & ({
-    files: ConfigFiles;
-} | {
-    suites: ConfigSuite[];
-});
+import { Refiner, FilteringOptions, ReporterContract } from '@japa/core';
+import { Test, Group, TestContext, Runner, Suite } from '../Core';
+/**
+ * The cleanup function for runner hooks
+ */
+export declare type RunnerHooksCleanupHandler = (error: null | any, runner: Runner) => Promise<any> | any;
+/**
+ * The function that can be registered as a runner hook
+ */
+export declare type RunnerHooksHandler = (runner: Runner) => Promise<any> | any | RunnerHooksCleanupHandler | Promise<RunnerHooksCleanupHandler>;
+/**
+ * Allowed filters
+ */
+export declare type Filters = FilteringOptions & {
+    files?: string[];
+    suites?: string[];
+};
+/**
+ * Shape of the plugin function
+ */
+export declare type PluginFn = (config: Required<Config>, runner: Runner, classes: {
+    Test: typeof Test;
+    TestContext: typeof TestContext;
+    Group: typeof Group;
+}) => void | Promise<void>;
+/**
+ * Runner hooks
+ */
+export declare type RunnerHooks = {
+    setup: RunnerHooksHandler[];
+    teardown: RunnerHooksHandler[];
+};
+/**
+ * Base configuration options
+ */
+export declare type BaseConfig = {
+    cwd?: string;
+    timeout?: number;
+    plugins?: PluginFn[];
+    filters?: Filters;
+    configureSuite?: (suite: Suite) => void;
+    reporters?: ReporterContract[];
+    importer?: (filePath: string) => void | Promise<void>;
+    refiner?: Refiner;
+    forceExit?: boolean;
+} & Partial<RunnerHooks>;
+/**
+ * Type for the "config.files" property
+ */
+export declare type ConfigFiles = string[] | (() => string[] | Promise<string[]>);
+/**
+ * Type for the "config.suite" property
+ */
+export declare type ConfigSuite = {
+    name: string;
+    files: string | string[] | (() => string[] | Promise<string[]>);
+    configure?: (suite: Suite) => void;
+    timeout?: number;
+};
+/**
+ * Configuration options
+ */
+export declare type Config = BaseConfig & ({
+    files: ConfigFiles;
+} | {
+    suites: ConfigSuite[];
+});

package/build/src/Contracts/index.js

@@ -1,10 +1,10 @@
-"use strict";
-/*
- * @japa/runner
- *
- * (c) Harminder Virk <virk@adonisjs.com>
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
+"use strict";
+/*
+ * @japa/runner
+ *
+ * (c) Harminder Virk <virk@adonisjs.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/build/src/Core/index.d.ts

@@ -1,14 +1,18 @@
-import { DataSetNode, Test as BaseTest, Group as BaseGroup, Suite as BaseSuite, Runner as BaseRunner, TestContext as BaseTestContext } from '@japa/core';
-export declare class TestContext extends BaseTestContext {
-    test: Test;
-    constructor(test: Test);
-}
-export declare class Test<TestData extends DataSetNode = undefined> extends BaseTest<TestContext, TestData> {
-    static disposeCallbacks: never[];
-}
-export declare class Group extends BaseGroup<TestContext> {
-}
-export declare class Suite extends BaseSuite<TestContext> {
-}
-export declare class Runner extends BaseRunner<TestContext> {
-}
+import { DataSetNode, Test as BaseTest, Group as BaseGroup, Suite as BaseSuite, Runner as BaseRunner, TestHooksCleanupHandler, TestContext as BaseTestContext } from '@japa/core';
+export declare class TestContext extends BaseTestContext {
+    test: Test;
+    constructor(test: Test);
+    /**
+     * Define a test cleanup hook
+     */
+    cleanup(handler: TestHooksCleanupHandler<this>): this;
+}
+export declare class Test<TestData extends DataSetNode = undefined> extends BaseTest<TestContext, TestData> {
+    static disposeCallbacks: never[];
+}
+export declare class Group extends BaseGroup<TestContext> {
+}
+export declare class Suite extends BaseSuite<TestContext> {
+}
+export declare class Runner extends BaseRunner<TestContext> {
+}

package/build/src/Core/index.js

@@ -1,32 +1,39 @@
-"use strict";
-/*
- * @japa/runner
- *
- * (c) Harminder Virk <virk@adonisjs.com>
- *
- * For the full copyright and license information, please view the LICENSE
- * file that was distributed with this source code.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Runner = exports.Suite = exports.Group = exports.Test = exports.TestContext = void 0;
-const core_1 = require("@japa/core");
-class TestContext extends core_1.TestContext {
-    constructor(test) {
-        super();
-        this.test = test;
-    }
-}
-exports.TestContext = TestContext;
-class Test extends core_1.Test {
-}
-exports.Test = Test;
-Test.disposeCallbacks = [];
-class Group extends core_1.Group {
-}
-exports.Group = Group;
-class Suite extends core_1.Suite {
-}
-exports.Suite = Suite;
-class Runner extends core_1.Runner {
-}
-exports.Runner = Runner;
+"use strict";
+/*
+ * @japa/runner
+ *
+ * (c) Harminder Virk <virk@adonisjs.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Runner = exports.Suite = exports.Group = exports.Test = exports.TestContext = void 0;
+const core_1 = require("@japa/core");
+class TestContext extends core_1.TestContext {
+    constructor(test) {
+        super();
+        this.test = test;
+    }
+    /**
+     * Define a test cleanup hook
+     */
+    cleanup(handler) {
+        this.test.cleanup(handler);
+        return this;
+    }
+}
+exports.TestContext = TestContext;
+class Test extends core_1.Test {
+}
+exports.Test = Test;
+Test.disposeCallbacks = [];
+class Group extends core_1.Group {
+}
+exports.Group = Group;
+class Suite extends core_1.Suite {
+}
+exports.Suite = Suite;
+class Runner extends core_1.Runner {
+}
+exports.Runner = Runner;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@japa/runner",
-  "version": "2.1.3",
+  "version": "2.2.0",
   "description": "Runner for Japa testing framework",
   "main": "build/index.js",
   "files": [
@@ -36,11 +36,11 @@
   "devDependencies": {
     "@adonisjs/mrm-preset": "^5.0.3",
     "@adonisjs/require-ts": "^2.0.12",
-    "@types/node": "^18.7.15",
+    "@types/node": "^18.7.16",
     "commitizen": "^4.2.5",
     "cz-conventional-changelog": "^3.3.0",
     "del-cli": "^5.0.0",
-    "eslint": "^8.23.0",
+    "eslint": "^8.23.1",
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-adonis": "^2.1.0",
     "eslint-plugin-prettier": "^4.2.1",
@@ -50,7 +50,7 @@
     "mrm": "^4.1.0",
     "np": "^7.6.2",
     "prettier": "^2.7.1",
-    "typescript": "^4.8.2"
+    "typescript": "^4.8.3"
   },
   "mrmConfig": {
     "core": false,
@@ -105,11 +105,11 @@
     "anyBranch": false
   },
   "dependencies": {
-    "@japa/core": "^7.0.1",
+    "@japa/core": "^7.2.0",
     "@japa/errors-printer": "^2.0.1",
     "@poppinss/cliui": "^3.0.2",
     "@poppinss/hooks": "^6.0.2-0",
-    "fast-glob": "^3.2.11",
+    "fast-glob": "^3.2.12",
     "getopts": "^2.3.0",
     "inclusion": "^1.0.1"
   },