@japa/runner 1.0.0

package/LICENSE.md

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

package/README.md

@@ -0,0 +1,19 @@
+# @japa/runner
+> An API first tests runner for Node.js
+
+[![github-actions-image]][github-actions-url] [![npm-image]][npm-url] [![license-image]][license-url] [![typescript-image]][typescript-url]
+
+Japa is an API-first testing framework. It focuses only on testing Node.js (backend) applications, thus resulting in a fast, small, and simple tests runner.
+
+[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
+
+[npm-image]: https://img.shields.io/npm/v/@japa/runner.svg?style=for-the-badge&logo=npm
+[npm-url]: https://npmjs.org/package/@japa/runner "npm"
+
+[license-image]: https://img.shields.io/npm/l/@japa/runner?color=blueviolet&style=for-the-badge
+[license-url]: LICENSE.md "license"
+
+[typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript
+[typescript-url]:  "typescript"

package/build/index.d.ts

@@ -0,0 +1,24 @@
+import { TestExecutor } from '@japa/core';
+import { Test, TestContext, Group } from './src/Core';
+import { ConfigureOptions, Filters } from './src/Contracts';
+export { Test, TestContext, Group } from './src/Core';
+/**
+ * Configure the tests runner
+ */
+export declare function configure(options: ConfigureOptions): void;
+/**
+ * Add a new test
+ */
+declare function test(title: string, callback?: TestExecutor<TestContext, undefined>): Test<TestContext, undefined>;
+declare namespace test {
+    var group: (title: string, callback: (group: Group<TestContext>) => void) => void;
+}
+export default test;
+/**
+ * Run japa tests
+ */
+export declare function run(): Promise<void>;
+/**
+ * Process CLI arguments into filters
+ */
+export declare function processCliArgs(argv: string[]): Filters;

package/build/index.js

@@ -0,0 +1,319 @@
+"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.processCliArgs = exports.run = exports.configure = exports.Group = exports.TestContext = 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 hooks_1 = require("@poppinss/hooks");
+const core_1 = require("@japa/core");
+const Core_1 = require("./src/Core");
+var Core_2 = require("./src/Core");
+Object.defineProperty(exports, "Test", { enumerable: true, get: function () { return Core_2.Test; } });
+Object.defineProperty(exports, "TestContext", { enumerable: true, get: function () { return Core_2.TestContext; } });
+Object.defineProperty(exports, "Group", { enumerable: true, get: function () { return Core_2.Group; } });
+/**
+ * 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;
+/**
+ * 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();
+/**
+ * The default suite for registering tests
+ */
+const suite = new core_1.Suite('default', emitter);
+/**
+ * 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);
+    }
+}
+/**
+ * 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 args to an array of strings
+ */
+function processArg(flag) {
+    return (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) {
+    return !!filters.find((matcher) => {
+        if (filePath.endsWith(matcher)) {
+            return true;
+        }
+        return filePath.replace((0, path_1.extname)(filePath), '').endsWith(matcher);
+    });
+}
+/**
+ * Configure the tests runner
+ */
+function configure(options) {
+    const defaultOptions = {
+        files: [],
+        plugins: [],
+        reporters: [],
+        timeout: 2000,
+        filters: {},
+        setup: [],
+        teardown: [],
+        importer: (filePath) => (0, inclusion_1.default)(filePath),
+        refiner: new core_1.Refiner({}),
+        forceExit: false,
+    };
+    runnerOptions = Object.assign(defaultOptions, options);
+}
+exports.configure = configure;
+/**
+ * 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);
+    /**
+     * Set filename
+     */
+    testInstance.options.meta.fileName = recentlyImportedFile;
+    /**
+     * Define timeout on the test when exists globally
+     */
+    if (runnerOptions.timeout !== undefined) {
+        testInstance.timeout(runnerOptions.timeout);
+    }
+    /**
+     * Define test executor function
+     */
+    if (callback) {
+        testInstance.run(callback);
+    }
+    /**
+     * Add test to the group or suite
+     */
+    if (activeGroup) {
+        activeGroup.add(testInstance);
+    }
+    else {
+        suite.add(testInstance);
+    }
+    return testInstance;
+}
+exports.default = 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;
+    callback(activeGroup);
+    /**
+     * Add group to the default suite
+     */
+    suite.add(activeGroup);
+    activeGroup = undefined;
+};
+/**
+ * Run japa tests
+ */
+async function run() {
+    const runner = new core_1.Runner(emitter);
+    runner.add(suite).manageUnHandledExceptions();
+    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 });
+        }
+        /**
+         * Step 2: Notify runner about reporters
+         */
+        runnerOptions.reporters.forEach((reporter) => runner.registerReporter(reporter));
+        /**
+         * Step 3: Run runner hooks.
+         *
+         * We run hooks before importing test files. It allows hooks
+         * to setup the app environment for the test files
+         */
+        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
+         */
+        await setupRunner.run(runner);
+        /**
+         * Step 4: Collect all test files
+         */
+        let files = [];
+        if (Array.isArray(runnerOptions.files)) {
+            files = await (0, fast_glob_1.default)(runnerOptions.files, { absolute: true, onlyFiles: true });
+        }
+        else if (typeof runnerOptions.files === 'function') {
+            files = await runnerOptions.files();
+        }
+        /**
+         * Step 5: Import 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);
+            }
+        }
+        /**
+         * 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 teardown hooks
+         */
+        await teardownRunner.run(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();
+        await setupRunner.cleanup(runner);
+        await teardownRunner.cleanup(runner);
+    }
+    catch (error) {
+        if (setupRunner && setupRunner.isCleanupPending) {
+            await setupRunner.cleanup(error, runner);
+        }
+        if (teardownRunner && teardownRunner.isCleanupPending) {
+            await teardownRunner.cleanup(error, runner);
+        }
+        process.exitCode = 1;
+        runnerOptions.forceExit && process.exit();
+    }
+}
+exports.run = run;
+/**
+ * Process CLI arguments into filters
+ */
+function processCliArgs(argv) {
+    const parsed = (0, getopts_1.default)(argv, {
+        string: ['tests', 'tags', 'groups', 'ignoreTags', 'files'],
+        alias: {
+            ignoreTags: 'ignore-tags',
+        },
+    });
+    const filters = {};
+    if (parsed.tags) {
+        filters.tags = processArg(parsed.tags);
+    }
+    if (parsed.ignoreTags) {
+        filters.tags = filters.tags || [];
+        processArg(parsed.ignoreTags).forEach((tag) => {
+            filters.tags.push(`!${tag}`);
+        });
+    }
+    if (parsed.groups) {
+        filters.groups = processArg(parsed.groups);
+    }
+    if (parsed.tests) {
+        filters.tests = processArg(parsed.tests);
+    }
+    if (parsed.files) {
+        filters.files = processArg(parsed.files);
+    }
+    return filters;
+}
+exports.processCliArgs = processCliArgs;

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

@@ -0,0 +1,39 @@
+import { Runner, Refiner, FilteringOptions, ReporterContract } from '@japa/core';
+import { Test, Group, TestContext } 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[];
+};
+/**
+ * Shape of the plugin function
+ */
+export declare type PluginFn = (config: Required<ConfigureOptions>, runner: Runner, classes: {
+    Test: typeof Test;
+    TestContext: typeof TestContext;
+    Group: typeof Group;
+}) => void | Promise<void>;
+/**
+ * Configuration options
+ */
+export declare type ConfigureOptions = {
+    files: string[] | (() => string[] | Promise<string[]>);
+    timeout?: number;
+    plugins?: PluginFn[];
+    filters?: Filters;
+    setup?: RunnerHooksHandler[];
+    teardown?: RunnerHooksHandler[];
+    reporters?: ReporterContract[];
+    importer?: (filePath: string) => void | Promise<void>;
+    refiner?: Refiner;
+    forceExit?: boolean;
+};

package/build/src/Contracts/index.js

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

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

@@ -0,0 +1,6 @@
+import { Test, Group, TestContext as BaseTestContext } from '@japa/core';
+export declare class TestContext extends BaseTestContext {
+    test: Test<TestContext, any>;
+    constructor(test: Test<TestContext, any>);
+}
+export { Group, Test };

package/build/src/Core/index.js

@@ -0,0 +1,21 @@
+"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.Test = exports.Group = exports.TestContext = void 0;
+const core_1 = require("@japa/core");
+Object.defineProperty(exports, "Test", { enumerable: true, get: function () { return core_1.Test; } });
+Object.defineProperty(exports, "Group", { enumerable: true, get: function () { return core_1.Group; } });
+class TestContext extends core_1.TestContext {
+    constructor(test) {
+        super();
+        this.test = test;
+    }
+}
+exports.TestContext = TestContext;

package/package.json

@@ -0,0 +1,118 @@
+{
+  "name": "@japa/runner",
+  "version": "1.0.0",
+  "description": "Runner for Japa testing framework",
+  "main": "build/index.js",
+  "files": [
+    "build/src",
+    "build/index.d.ts",
+    "build/index.js"
+  ],
+  "exports": {
+    ".": "./build/index.js"
+  },
+  "scripts": {
+    "mrm": "mrm --preset=@adonisjs/mrm-preset",
+    "pretest": "npm run lint",
+    "test": "node .bin/test.js",
+    "clean": "del build",
+    "compile": "npm run lint && npm run clean && tsc",
+    "build": "npm run compile",
+    "prepublishOnly": "npm run build",
+    "lint": "eslint . --ext=.ts",
+    "format": "prettier --write .",
+    "commit": "git-cz",
+    "release": "np --message=\"chore(release): %s\"",
+    "version": "npm run build",
+    "sync-labels": "github-label-sync --labels ./node_modules/@adonisjs/mrm-preset/gh-labels.json japa/runner"
+  },
+  "keywords": [
+    "japa",
+    "tests",
+    "test-runner"
+  ],
+  "author": "virk,japa",
+  "license": "MIT",
+  "devDependencies": {
+    "@adonisjs/mrm-preset": "^5.0.2",
+    "@adonisjs/require-ts": "^2.0.9",
+    "@types/node": "^17.0.14",
+    "commitizen": "^4.2.4",
+    "cz-conventional-changelog": "^3.3.0",
+    "del-cli": "^4.0.1",
+    "eslint": "^8.8.0",
+    "eslint-config-prettier": "^8.3.0",
+    "eslint-plugin-adonis": "^2.1.0",
+    "eslint-plugin-prettier": "^4.0.0",
+    "github-label-sync": "^2.0.2",
+    "husky": "^7.0.4",
+    "japa": "^4.0.0",
+    "mrm": "^3.0.10",
+    "np": "^7.6.0",
+    "prettier": "^2.5.1",
+    "typescript": "^4.5.5"
+  },
+  "mrmConfig": {
+    "core": false,
+    "license": "MIT",
+    "services": [
+      "github-actions"
+    ],
+    "minNodeVersion": "16.13.1",
+    "probotApps": [
+      "stale",
+      "lock"
+    ],
+    "runGhActionsOnWindows": true
+  },
+  "eslintConfig": {
+    "extends": [
+      "plugin:adonis/typescriptPackage",
+      "prettier"
+    ],
+    "plugins": [
+      "prettier"
+    ],
+    "rules": {
+      "prettier/prettier": [
+        "error",
+        {
+          "endOfLine": "auto"
+        }
+      ]
+    }
+  },
+  "eslintIgnore": [
+    "build"
+  ],
+  "prettier": {
+    "trailingComma": "es5",
+    "semi": false,
+    "singleQuote": true,
+    "useTabs": false,
+    "quoteProps": "consistent",
+    "bracketSpacing": true,
+    "arrowParens": "always",
+    "printWidth": 100
+  },
+  "config": {
+    "commitizen": {
+      "path": "cz-conventional-changelog"
+    }
+  },
+  "np": {
+    "contents": ".",
+    "anyBranch": false
+  },
+  "dependencies": {
+    "@japa/core": "^5.0.17-0",
+    "@poppinss/hooks": "^6.0.1-0",
+    "fast-glob": "^3.2.11",
+    "getopts": "^2.3.0",
+    "inclusion": "^1.0.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  }
+}