@japa/runner 2.0.7 → 2.1.0

package/README.md

@@ -7,6 +7,11 @@ Japa is an API first testing framework. It focuses only on testing Node.js (back
 
 #### 💁 Please visit https://japa.dev for documentation
 
+<br />
+<hr>
+
+![](https://cdn.jsdelivr.net/gh/thetutlage/static/sponsorkit/sponsors.png)
+
 [github-actions-image]: https://img.shields.io/github/workflow/status/japa/runner/test?style=for-the-badge "github-actions"
 
 [github-actions-url]: https://github.com/japa/runner/actions/workflows/test.yml

package/build/index.d.ts

@@ -1,22 +1,11 @@
-import { TestExecutor, ReporterContract } from '@japa/core';
 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;
-/**
- * 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;
-}
-/**
- * Run japa tests
- */
-export declare function run(): Promise<void>;
 /**
  * Process CLI arguments into configuration options. The following
  * command line arguments are processed.
@@ -28,5 +17,17 @@ export declare function run(): Promise<void>;
  * * --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

@@ -11,21 +11,23 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.processCliArgs = exports.run = exports.test = exports.configure = exports.TestContext = exports.Group = exports.Runner = exports.Suite = exports.Test = void 0;
+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 package_json_1 = require("./package.json");
+const cliui_1 = require("@poppinss/cliui");
 const errors_printer_1 = require("@japa/errors-printer");
-const core_1 = require("@japa/core");
 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
  */
@@ -51,7 +53,7 @@ const emitter = new core_1.Emitter();
 /**
  * Active suite for tests
  */
-let activeSuite = new Core_1.Suite('default', emitter);
+let activeSuite;
 /**
  * Currently active group
  */
@@ -85,25 +87,6 @@ function validateSuitesFilter() {
         throw new Error(`Unrecognized suite "${invalidSuites[0]}". Make sure to define it in the config first`);
     }
 }
-/**
- * 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);
-        });
-    }
-}
 /**
  * Process command line argument into a string value
  */
@@ -118,7 +101,10 @@ function processAsString(argv, flagName, onMatch) {
  * The ending of the file is matched
  */
 function isFileAllowed(filePath, filters) {
-    return !!filters.find((matcher) => {
+    if (!filters.files || !filters.files.length) {
+        return true;
+    }
+    return !!filters.files.find((matcher) => {
         if (filePath.endsWith(matcher)) {
             return true;
         }
@@ -127,13 +113,84 @@ function isFileAllowed(filePath, filters) {
 }
 /**
  * Returns "true" when no filters are applied or the name is part
- * of the applied filter
+ * of the applied filter.
  */
-function isSuiteAllowed(name, filters) {
-    if (!filters || !filters.length) {
+function isSuiteAllowed(suite, filters) {
+    if (!filters.suites || !filters.suites.length) {
         return true;
     }
-    return filters.includes(name);
+    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 v${package_json_1.version}
+
+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')}`);
 }
 /**
  * Configure the tests runner
@@ -158,92 +215,70 @@ function configure(options) {
 }
 exports.configure = configure;
 /**
- * Add a new test
+ * 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 test(title, callback) {
-    ensureIsConfigured('Cannot add test without configuring the test runner');
-    const testInstance = new Core_1.Test(title, getContext, emitter, runnerOptions.refiner);
-    /**
-     * Set filename
-     */
-    testInstance.options.meta.fileName = recentlyImportedFile;
-    /**
-     * Define timeout on the test when exists globally
-     */
-    if (globalTimeout !== undefined) {
-        testInstance.timeout(globalTimeout);
-    }
+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));
     /**
-     * Define test executor function
+     * Show help
      */
-    if (callback) {
-        testInstance.run(callback);
+    if (parsed.help) {
+        showHelp();
+        process.exit(0);
     }
     /**
-     * Add test to the group or suite
+     * Get suites
      */
-    if (activeGroup) {
-        activeGroup.add(testInstance);
-    }
-    else {
-        activeSuite.add(testInstance);
+    if (parsed._.length) {
+        processAsString({ suites: parsed._ }, 'suites', (suites) => (config.filters.suites = suites));
     }
-    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
+     * Get timeout
      */
-    if (activeGroup) {
-        throw new Error('Cannot create nested test groups');
+    if (parsed.timeout) {
+        const value = Number(parsed.timeout);
+        if (!isNaN(value)) {
+            config.timeout = value;
+        }
     }
-    activeGroup = new Core_1.Group(title, emitter, runnerOptions.refiner);
     /**
-     * Set filename
-     */
-    activeGroup.options.meta.fileName = recentlyImportedFile;
-    callback(activeGroup);
-    /**
-     * Add group to the default suite
+     * Get forceExit
      */
-    activeSuite.add(activeGroup);
-    activeGroup = undefined;
-};
-/**
- * Collect files using the files collector function or by processing
- * the glob pattern
- */
-async function collectFiles(files) {
-    if (Array.isArray(files) || typeof files === 'string') {
-        return await (0, fast_glob_1.default)(files, { absolute: true, onlyFiles: true, cwd: runnerOptions.cwd });
-    }
-    else if (typeof files === 'function') {
-        return await files();
-    }
-    throw new Error('Invalid value for "files" property. Expected a string, array or a function');
-}
-/**
- * Import test files using the configured importer. Also
- * filter files using the file filter. (if mentioned).
- */
-async function importFiles(files) {
-    for (let file of files) {
-        recentlyImportedFile = file;
-        if (runnerOptions.filters.files && runnerOptions.filters.files.length) {
-            if (isFileAllowed(file, runnerOptions.filters.files)) {
-                await runnerOptions.importer(file);
-            }
-        }
-        else {
-            await runnerOptions.importer(file);
-        }
+    if (parsed.forceExit) {
+        config.forceExit = true;
     }
+    return config;
 }
+exports.processCliArgs = processCliArgs;
 /**
  * Run japa tests
  */
@@ -290,10 +325,19 @@ async function run() {
          * 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);
-            runner.add(activeSuite);
-            await importFiles(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
@@ -301,20 +345,26 @@ async function run() {
          */
         if ('suites' in runnerOptions) {
             for (let suite of runnerOptions.suites) {
-                if (isSuiteAllowed(suite.name, runnerOptions.filters.suites)) {
+                if (isSuiteAllowed(suite, runnerOptions.filters)) {
                     if (suite.timeout !== undefined) {
                         globalTimeout = suite.timeout;
                     }
                     else {
                         globalTimeout = runnerOptions.timeout;
                     }
-                    activeSuite = new Core_1.Suite(suite.name, emitter);
-                    if (typeof suite.configure === 'function') {
-                        suite.configure(activeSuite);
-                    }
                     const files = await collectFiles(suite.files);
-                    runner.add(activeSuite);
-                    await importFiles(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);
+                    }
                 }
             }
         }
@@ -371,58 +421,59 @@ async function run() {
 }
 exports.run = run;
 /**
- * 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
+ * Add a new test
  */
-function processCliArgs(argv) {
-    const parsed = (0, getopts_1.default)(argv, {
-        string: ['tests', 'tags', 'groups', 'ignoreTags', 'files', 'timeout'],
-        boolean: ['forceExit'],
-        alias: {
-            ignoreTags: 'ignore-tags',
-            forceExit: 'force-exit',
-        },
-    });
-    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));
+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);
     /**
-     * Get suites
+     * Set filename
      */
-    if (parsed._.length) {
-        processAsString({ suites: parsed._ }, 'suites', (suites) => (config.filters.suites = suites));
+    testInstance.options.meta.fileName = recentlyImportedFile;
+    /**
+     * Define timeout on the test when exists globally
+     */
+    if (globalTimeout !== undefined) {
+        testInstance.timeout(globalTimeout);
     }
     /**
-     * Get timeout
+     * Define test executor function
      */
-    if (parsed.timeout) {
-        const value = Number(parsed.timeout);
-        if (!isNaN(value)) {
-            config.timeout = value;
-        }
+    if (callback) {
+        testInstance.run(callback);
     }
     /**
-     * Get forceExit
+     * Add test to the group or suite
      */
-    if (parsed.forceExit) {
-        config.forceExit = true;
+    if (activeGroup) {
+        activeGroup.add(testInstance);
     }
-    return config;
+    else {
+        activeSuite.add(testInstance);
+    }
+    return testInstance;
 }
-exports.processCliArgs = processCliArgs;
+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

@@ -44,16 +44,24 @@ export declare type BaseConfig = {
     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: string[] | (() => string[] | Promise<string[]>);
+    files: ConfigFiles;
 } | {
-    suites: {
-        name: string;
-        files: string | string[] | (() => string[] | Promise<string[]>);
-        configure?: (suite: Suite) => void;
-        timeout?: number;
-    }[];
+    suites: ConfigSuite[];
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@japa/runner",
-  "version": "2.0.7",
+  "version": "2.1.0",
   "description": "Runner for Japa testing framework",
   "main": "build/index.js",
   "files": [
@@ -15,7 +15,7 @@
     "mrm": "mrm --preset=@adonisjs/mrm-preset",
     "pretest": "npm run lint",
     "test": "node .bin/test.js",
-    "clean": "del build",
+    "clean": "del-cli build",
     "compile": "npm run lint && npm run clean && tsc",
     "build": "npm run compile",
     "prepublishOnly": "npm run build",
@@ -35,22 +35,22 @@
   "license": "MIT",
   "devDependencies": {
     "@adonisjs/mrm-preset": "^5.0.3",
-    "@adonisjs/require-ts": "^2.0.11",
-    "@types/node": "^17.0.23",
-    "commitizen": "^4.2.4",
+    "@adonisjs/require-ts": "^2.0.12",
+    "@types/node": "^18.7.14",
+    "commitizen": "^4.2.5",
     "cz-conventional-changelog": "^3.3.0",
-    "del-cli": "^4.0.1",
-    "eslint": "^8.12.0",
+    "del-cli": "^5.0.0",
+    "eslint": "^8.23.0",
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-adonis": "^2.1.0",
-    "eslint-plugin-prettier": "^4.0.0",
+    "eslint-plugin-prettier": "^4.2.1",
     "github-label-sync": "^2.2.0",
-    "husky": "^7.0.4",
+    "husky": "^8.0.1",
     "japa": "^4.0.0",
-    "mrm": "^4.0.0",
-    "np": "^7.6.1",
-    "prettier": "^2.6.2",
-    "typescript": "^4.6.3"
+    "mrm": "^4.1.0",
+    "np": "^7.6.2",
+    "prettier": "^2.7.1",
+    "typescript": "^4.8.2"
   },
   "mrmConfig": {
     "core": false,
@@ -105,8 +105,9 @@
     "anyBranch": false
   },
   "dependencies": {
-    "@japa/core": "^6.0.4",
-    "@japa/errors-printer": "^1.3.7",
+    "@japa/core": "^7.0.0",
+    "@japa/errors-printer": "^1.3.10",
+    "@poppinss/cliui": "^3.0.2",
     "@poppinss/hooks": "^6.0.2-0",
     "fast-glob": "^3.2.11",
     "getopts": "^2.3.0",