@japa/runner 3.0.0-8 → 3.0.0-9

package/build/index.js

@@ -1,249 +1,214 @@
-import {
-  CliParser,
-  ConfigManager,
-  GlobalHooks,
-  Planner,
-  createTest,
-  createTestGroup,
-  debug_default,
-  validator_default
-} from "./chunk-W5IABAQU.js";
-import {
-  colors
-} from "./chunk-7THDHQFT.js";
-import {
-  Emitter,
-  Runner,
-  Suite
-} from "./chunk-MCOW34SG.js";
-import "./chunk-HN4AVHWN.js";
-
-// index.ts
-import { fileURLToPath } from "node:url";
-import { ErrorsPrinter as ErrorsPrinter2 } from "@japa/errors-printer";
-
-// src/plugins/retry.ts
-import { join } from "node:path";
-import findCacheDirectory from "find-cache-dir";
-import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
-var CACHE_DIR = findCacheDirectory({ name: "@japa/runner" });
-var SUMMARY_FILE = CACHE_DIR ? join(CACHE_DIR, "summary.json") : void 0;
-async function getFailedTests() {
-  try {
-    const summary = await readFile(SUMMARY_FILE, "utf-8");
-    return JSON.parse(summary);
-  } catch (error) {
-    if (error.code === "ENOENT") {
-      return {};
-    }
-    throw new Error("Unable to read failed tests cache file", { cause: error });
-  }
-}
-async function cacheFailedTests(tests) {
-  await mkdir(CACHE_DIR, { recursive: true });
-  await writeFile(SUMMARY_FILE, JSON.stringify({ tests }));
-}
-var retryPlugin = async function retry({ config, cliArgs: cliArgs2 }) {
-  if (!SUMMARY_FILE) {
-    return;
-  }
-  config.teardown.push(async (runner) => {
-    const summary = runner.getSummary();
-    await cacheFailedTests(summary.failedTestsTitles);
-  });
-  if (cliArgs2.failed) {
-    const { tests } = await getFailedTests();
-    if (!tests || !tests.length) {
-      console.log(colors.bgYellow().black(" No failing tests found. Running all the tests "));
-      return;
-    }
-    config.filters.tests = tests;
-  }
+/*
+ * @japa/runner
+ *
+ * (c) Japa
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+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';
+/**
+ * Global emitter instance used by the test
+ */
+const emitter = new Emitter();
+/**
+ * The current active test
+ */
+let activeTest;
+/**
+ * Parsed commandline arguments
+ */
+let cliArgs = {};
+/**
+ * Hydrated config
+ */
+let runnerConfig;
+/**
+ * The state refers to the phase where we configure suites and import
+ * test files. We stick this metadata to the test instance one can
+ * later reference within the test.
+ */
+const executionPlanState = {
+    phase: 'idle',
 };
-
-// src/exceptions_manager.ts
-import { ErrorsPrinter } from "@japa/errors-printer";
-var ExceptionsManager = class {
-  #exceptionsBuffer = [];
-  #rejectionsBuffer = [];
-  #state = "watching";
-  #errorsPrinter = new ErrorsPrinter({ stackLinesCount: 2, framesMaxLimit: 4 });
-  hasErrors = false;
-  /**
-   * Monitors unhandled exceptions and rejections. The exceptions
-   * are stacked in a buffer, so that we do not clutter the
-   * tests output and once the tests are over, we will
-   * print them to the console.
-   *
-   * In case the tests are completed, we will print errors as they
-   * happen.
-   */
-  monitor() {
-    process.on("uncaughtException", async (error) => {
-      this.hasErrors = true;
-      if (this.#state === "watching") {
-        this.#exceptionsBuffer.push(error);
-      } else {
-        this.#errorsPrinter.printSectionBorder("[Unhandled Error]");
-        await this.#errorsPrinter.printError(error);
-        process.exitCode = 1;
-      }
+/**
+ * Create a Japa test. Defining a test without the callback
+ * will create a todo test.
+ */
+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;
+        };
     });
-    process.on("unhandledRejection", async (error) => {
-      this.hasErrors = true;
-      if (this.#state === "watching") {
-        this.#rejectionsBuffer.push(error);
-      } else {
-        this.#errorsPrinter.printSectionBorder("[Unhandled Rejection]");
-        await this.#errorsPrinter.printError(error);
-        process.exitCode = 1;
-      }
-    });
-  }
-  async flow() {
-    if (this.#state === "flowing") {
-      return;
-    }
-    this.#state = "flowing";
-    if (this.#exceptionsBuffer.length) {
-      let exceptionsCount = this.#exceptionsBuffer.length;
-      let exceptionsIndex = this.#exceptionsBuffer.length;
-      this.#errorsPrinter.printSectionHeader("Unhandled Errors");
-      for (let exception of this.#exceptionsBuffer) {
-        await this.#errorsPrinter.printError(exception);
-        this.#errorsPrinter.printSectionBorder(`[${++exceptionsIndex}/${exceptionsCount}]`);
-      }
-      this.#exceptionsBuffer = [];
-    }
-    if (this.#rejectionsBuffer.length) {
-      let rejectionsCount = this.#exceptionsBuffer.length;
-      let rejectionsIndex = this.#exceptionsBuffer.length;
-      this.#errorsPrinter.printSectionBorder("Unhandled Rejections");
-      for (let rejection of this.#rejectionsBuffer) {
-        await this.#errorsPrinter.printError(rejection);
-        this.#errorsPrinter.printSectionBorder(`[${++rejectionsIndex}/${rejectionsCount}]`);
-      }
-      this.#rejectionsBuffer = [];
+    if (callback) {
+        testInstance.run(callback);
     }
-  }
-};
-
-// index.ts
-var emitter = new Emitter();
-var activeTest;
-var cliArgs = {};
-var runnerConfig;
-var executionPlanState = {
-  phase: "idle"
-};
-function test(title, callback) {
-  validator_default.ensureIsInPlanningPhase(executionPlanState.phase);
-  const testInstance = createTest(title, emitter, runnerConfig.refiner, executionPlanState);
-  testInstance.setup((t) => {
-    activeTest = t;
-    return () => {
-      activeTest = void 0;
-    };
-  });
-  if (callback) {
-    testInstance.run(callback);
-  }
-  return testInstance;
+    return testInstance;
 }
-test.group = function(title, callback) {
-  validator_default.ensureIsInPlanningPhase(executionPlanState.phase);
-  executionPlanState.group = createTestGroup(
-    title,
-    emitter,
-    runnerConfig.refiner,
-    executionPlanState
-  );
-  callback(executionPlanState.group);
-  executionPlanState.group = void 0;
+/**
+ * Create a Japa test group
+ */
+test.group = function (title, callback) {
+    validator.ensureIsInPlanningPhase(executionPlanState.phase);
+    executionPlanState.group = createTestGroup(title, emitter, runnerConfig.refiner, executionPlanState);
+    callback(executionPlanState.group);
+    executionPlanState.group = undefined;
 };
-function getActiveTest() {
-  return activeTest;
+/**
+ * Get the test of currently running test
+ */
+export function getActiveTest() {
+    return activeTest;
 }
-function processCLIArgs(argv) {
-  cliArgs = new CliParser().parse(argv);
+/**
+ * Make Japa process command line arguments. Later the parsed output
+ * will be used by Japa to compute the configuration
+ */
+export function processCLIArgs(argv) {
+    cliArgs = new CliParser().parse(argv);
 }
-function configure(options) {
-  runnerConfig = new ConfigManager(options, cliArgs).hydrate();
+/**
+ * Configure the tests runner with inline configuration. You must
+ * call configure method before the run method.
+ *
+ * Do note: The CLI flags will overwrite the options provided
+ * to the configure method.
+ */
+export function configure(options) {
+    runnerConfig = new ConfigManager(options, cliArgs).hydrate();
 }
-async function run() {
-  if (cliArgs.help) {
-    console.log(new CliParser().getHelp());
-    return;
-  }
-  validator_default.ensureIsConfigured(runnerConfig);
-  executionPlanState.phase = "planning";
-  const runner = new Runner(emitter);
-  const globalHooks = new GlobalHooks();
-  const exceptionsManager = new ExceptionsManager();
-  try {
-    await retryPlugin({ config: runnerConfig, runner, emitter, cliArgs });
-    for (let plugin of runnerConfig.plugins) {
-      debug_default('executing "%s" plugin', plugin.name || "anonymous");
-      await plugin({ runner, emitter, cliArgs, config: runnerConfig });
-    }
-    const { config, reporters, suites, refinerFilters } = await new Planner(runnerConfig).plan();
-    reporters.forEach((reporter) => {
-      debug_default('registering "%s" reporter', reporter.name);
-      runner.registerReporter(reporter);
-    });
-    refinerFilters.forEach((filter) => {
-      debug_default('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_default("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);
-      }
-      runner.add(executionPlanState.suite);
-      for (let fileURL of suite.filesURLs) {
-        executionPlanState.file = fileURLToPath(fileURL);
-        debug_default("importing test file %s", executionPlanState.file);
-        await config.importer(fileURL);
-      }
-      executionPlanState.suite = void 0;
-    }
-    executionPlanState.phase = "executing";
-    exceptionsManager.monitor();
-    await runner.start();
-    await runner.exec();
-    await globalHooks.teardown(null, runner);
-    await runner.end();
-    await exceptionsManager.flow();
-    const summary = runner.getSummary();
-    if (summary.hasError || exceptionsManager.hasErrors) {
-      process.exitCode = 1;
+/**
+ * Execute Japa tests. Calling this function will import the test
+ * files behind the scenes
+ */
+export async function run() {
+    /**
+     * Display help when help flag is used
+     */
+    if (cliArgs.help) {
+        console.log(new CliParser().getHelp());
+        return;
     }
-    if (config.forceExit) {
-      process.exit();
+    validator.ensureIsConfigured(runnerConfig);
+    executionPlanState.phase = 'planning';
+    const runner = new Runner(emitter);
+    const globalHooks = new GlobalHooks();
+    const exceptionsManager = new ExceptionsManager();
+    try {
+        /**
+         * Executing the retry plugin as the first thing
+         */
+        await retryPlugin({ config: runnerConfig, runner, emitter, cliArgs });
+        /**
+         * Step 1: Executing plugins before creating a plan, so that it can mutate
+         * the config
+         */
+        for (let plugin of runnerConfig.plugins) {
+            debug('executing "%s" plugin', plugin.name || 'anonymous');
+            await plugin({ runner, emitter, cliArgs, config: runnerConfig });
+        }
+        /**
+         * Step 2: Creating an execution plan. The output is the result of
+         * applying all the filters and validations.
+         */
+        const { config, reporters, suites, refinerFilters } = await new Planner(runnerConfig).plan();
+        /**
+         * Step 3: Registering reporters and filters with the runner
+         */
+        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);
+        /**
+         * Step 4: Running the setup hooks
+         */
+        debug('executing global hooks');
+        globalHooks.apply(config);
+        await globalHooks.setup(runner);
+        /**
+         * Step 5: Register suites and import test files
+         */
+        for (let suite of suites) {
+            /**
+             * Creating and configuring the suite
+             */
+            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);
+            }
+            runner.add(executionPlanState.suite);
+            /**
+             * Importing suite files
+             */
+            for (let fileURL of suite.filesURLs) {
+                executionPlanState.file = fileURLToPath(fileURL);
+                debug('importing test file %s', executionPlanState.file);
+                await config.importer(fileURL);
+            }
+            /**
+             * Resetting global state
+             */
+            executionPlanState.suite = undefined;
+        }
+        /**
+         * Onto execution phase
+         */
+        executionPlanState.phase = 'executing';
+        /**
+         * Monitor for unhandled erorrs and rejections
+         */
+        exceptionsManager.monitor();
+        await runner.start();
+        await runner.exec();
+        await globalHooks.teardown(null, runner);
+        await runner.end();
+        /**
+         * Print unhandled errors
+         */
+        await exceptionsManager.flow();
+        const summary = runner.getSummary();
+        if (summary.hasError || exceptionsManager.hasErrors) {
+            process.exitCode = 1;
+        }
+        if (config.forceExit) {
+            process.exit();
+        }
     }
-  } catch (error) {
-    await globalHooks.teardown(error, runner);
-    const printer = new ErrorsPrinter2();
-    await printer.printError(error);
-    await exceptionsManager.flow();
-    process.exitCode = 1;
-    if (runnerConfig.forceExit) {
-      process.exit();
+    catch (error) {
+        await globalHooks.teardown(error, runner);
+        const printer = new ErrorsPrinter();
+        await printer.printError(error);
+        /**
+         * Print unhandled errors in case the code inside
+         * the try block never got triggered
+         */
+        await exceptionsManager.flow();
+        process.exitCode = 1;
+        if (runnerConfig.forceExit) {
+            process.exit();
+        }
     }
-  }
 }
-export {
-  configure,
-  getActiveTest,
-  processCLIArgs,
-  run,
-  test
-};

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

@@ -1,3 +1,63 @@
-export { Emitter, Refiner } from '@japa/core';
-export { b as BaseReporter, G as Group, R as Runner, S as Suite, a as Test, T as TestContext } from '../../main-63126780.js';
-import '@japa/core/types';
+/// <reference types="node" resolution-mode="require"/>
+import { Emitter, Refiner, Test as BaseTest, Suite as BaseSuite, Group as BaseGroup, Runner as BaseRunner, TestContext as BaseTestContext } from '@japa/core';
+import { BaseReporter } from './reporters/base.js';
+import type { DataSetNode, TestHooksCleanupHandler } from './types.js';
+declare module '@japa/core' {
+    interface Test<Context extends Record<any, any>, TestData extends DataSetNode = undefined> {
+        throws(message: string | RegExp, errorConstructor?: any): this;
+    }
+    interface TestContext {
+        cleanup: (cleanupCallback: TestHooksCleanupHandler<TestContext>) => void;
+    }
+}
+export { Emitter, Refiner, BaseReporter };
+/**
+ * Test context carries context data for a given test.
+ */
+export declare class TestContext extends BaseTestContext {
+    test: Test;
+    /**
+     * Register a cleanup function that runs after the test finishes
+     * successfully or with an error.
+     */
+    cleanup: (cleanupCallback: TestHooksCleanupHandler<TestContext>) => void;
+    constructor(test: Test);
+}
+/**
+ * Test class represents an individual test and exposes API to tweak
+ * its runtime behavior.
+ */
+export declare class Test<TestData extends DataSetNode = undefined> extends BaseTest<TestContext, TestData> {
+    /**
+     * @inheritdoc
+     */
+    static executedCallbacks: never[];
+    /**
+     * @inheritdoc
+     */
+    static executingCallbacks: never[];
+    /**
+     * Assert the test callback throws an exception when a certain
+     * error message and optionally is an instance of a given
+     * Error class.
+     */
+    throws(message: string | RegExp, errorConstructor?: any): this;
+}
+/**
+ * TestGroup is used to bulk configure a collection of tests and
+ * define lifecycle hooks for them
+ */
+export declare class Group extends BaseGroup<TestContext> {
+}
+/**
+ * A suite is a collection of tests created around a given
+ * testing type. For example: A suite for unit tests, a
+ * suite for functional tests and so on.
+ */
+export declare class Suite extends BaseSuite<TestContext> {
+}
+/**
+ * Runner class is used to execute the tests
+ */
+export declare class Runner extends BaseRunner<TestContext> {
+}

package/build/modules/core/main.js

@@ -1,21 +1,121 @@
-import {
-  BaseReporter,
-  Emitter,
-  Group,
-  Refiner,
-  Runner,
-  Suite,
-  Test,
-  TestContext
-} from "../../chunk-MCOW34SG.js";
-import "../../chunk-HN4AVHWN.js";
-export {
-  BaseReporter,
-  Emitter,
-  Group,
-  Refiner,
-  Runner,
-  Suite,
-  Test,
-  TestContext
-};
+/*
+ * @japa/runner
+ *
+ * (c) Japa
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+import { Emitter, Refiner, Test as BaseTest, Suite as BaseSuite, Group as BaseGroup, Runner as BaseRunner, TestContext as BaseTestContext, } from '@japa/core';
+import { inspect } from 'node:util';
+import { AssertionError } from 'node:assert';
+import { BaseReporter } from './reporters/base.js';
+export { Emitter, Refiner, BaseReporter };
+/**
+ * Test context carries context data for a given test.
+ */
+export class TestContext extends BaseTestContext {
+    test;
+    constructor(test) {
+        super();
+        this.test = test;
+        this.cleanup = (cleanupCallback) => {
+            test.cleanup(cleanupCallback);
+        };
+    }
+}
+/**
+ * Test class represents an individual test and exposes API to tweak
+ * its runtime behavior.
+ */
+export class Test extends BaseTest {
+    /**
+     * @inheritdoc
+     */
+    static executedCallbacks = [];
+    /**
+     * @inheritdoc
+     */
+    static executingCallbacks = [];
+    /**
+     * Assert the test callback throws an exception when a certain
+     * error message and optionally is an instance of a given
+     * Error class.
+     */
+    throws(message, errorConstructor) {
+        const errorInPoint = new AssertionError({});
+        const existingExecutor = this.options.executor;
+        if (!existingExecutor) {
+            throw new Error('Cannot use "test.throws" method without a test callback');
+        }
+        /**
+         * Overwriting existing callback
+         */
+        this.options.executor = async (...args) => {
+            let raisedException;
+            try {
+                await existingExecutor(...args);
+            }
+            catch (error) {
+                raisedException = error;
+            }
+            /**
+             * Notify no exception has been raised
+             */
+            if (!raisedException) {
+                errorInPoint.message = 'Expected test to throw an exception';
+                throw errorInPoint;
+            }
+            /**
+             * Constructor mis-match
+             */
+            if (errorConstructor && !(raisedException instanceof errorConstructor)) {
+                errorInPoint.message = `Expected test to throw "${inspect(errorConstructor)}"`;
+                throw errorInPoint;
+            }
+            /**
+             * Error does not have a message property
+             */
+            const exceptionMessage = raisedException.message;
+            if (!exceptionMessage || typeof exceptionMessage !== 'string') {
+                errorInPoint.message = 'Expected test to throw an exception with message property';
+                throw errorInPoint;
+            }
+            /**
+             * Message does not match
+             */
+            if (typeof message === 'string') {
+                if (exceptionMessage !== message) {
+                    errorInPoint.message = `Expected test to throw "${message}". Instead received "${raisedException.message}"`;
+                    errorInPoint.actual = raisedException.message;
+                    errorInPoint.expected = message;
+                    throw errorInPoint;
+                }
+                return;
+            }
+            if (!message.test(exceptionMessage)) {
+                errorInPoint.message = `Expected test error to match "${message}" regular expression`;
+                throw errorInPoint;
+            }
+        };
+        return this;
+    }
+}
+/**
+ * TestGroup is used to bulk configure a collection of tests and
+ * define lifecycle hooks for them
+ */
+export class Group extends BaseGroup {
+}
+/**
+ * A suite is a collection of tests created around a given
+ * testing type. For example: A suite for unit tests, a
+ * suite for functional tests and so on.
+ */
+export class Suite extends BaseSuite {
+}
+/**
+ * Runner class is used to execute the tests
+ */
+export class Runner extends BaseRunner {
+}