@japa/runner 3.1.4 → 4.1.0

package/README.md

@@ -1,9 +1,13 @@
 # @japa/runner
-> An API first tests runner for Node.js
+> A simple yet powerful testing framework 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 a simple tests runner.
+Japa comes with everything you need to test your backend applications. Be it writing JSON API tests using an Open API schema or writing browser tests using Playwright.
+
+Unlike other testing frameworks born out of the frontend ecosystem, Japa focuses only on testing backend applications and libraries. Therefore, Japa is **simpler**, **faster**, and **bloatware free**.
+
+Japa
 
 #### 💁 Please visit https://japa.dev for documentation
 
@@ -12,9 +16,9 @@ Japa is an API first testing framework. It focuses only on testing Node.js (back
 
 ![](https://raw.githubusercontent.com/thetutlage/static/main/sponsorkit/sponsors.png)
 
-[github-actions-image]: https://img.shields.io/github/actions/workflow/status/japa/runner/test.yml?style=for-the-badge "github-actions"
+[github-actions-image]: https://img.shields.io/github/actions/workflow/status/japa/runner/checks.yml?style=for-the-badge "github-actions"
 
-[github-actions-url]: https://github.com/japa/runner/actions/workflows/test.yml
+[github-actions-url]: https://github.com/japa/runner/actions/workflows/checks.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"

package/build/{chunk-OBDV3O36.js → chunk-2KG3PWR4.js}

@@ -15,4 +15,3 @@ var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "defau
 export {
   __reExport
 };
-//# sourceMappingURL=chunk-OBDV3O36.js.map

package/build/{chunk-BFNOUWI5.js → chunk-CYGUHLQ7.js}

@@ -13,6 +13,7 @@ import { AssertionError } from "node:assert";
 
 // modules/core/reporters/base.ts
 import ms from "ms";
+import { ErrorsPrinter } from "@japa/errors-printer";
 
 // src/helpers.ts
 import useColors from "@poppinss/colors";
@@ -26,6 +27,7 @@ var icons = process.platform === "win32" && !process.env.WT_SESSION ? {
   pointer: ">",
   info: "i",
   warning: "\u203C",
+  branch: " -",
   squareSmallFilled: "[\u2588]"
 } : {
   tick: "\u2714",
@@ -35,13 +37,12 @@ var icons = process.platform === "win32" && !process.env.WT_SESSION ? {
   pointer: "\u276F",
   info: "\u2139",
   warning: "\u26A0",
+  branch: "\u2514\u2500\u2500",
   squareSmallFilled: "\u25FC"
 };
 
 // modules/core/reporters/base.ts
-import { ErrorsPrinter } from "@japa/errors-printer";
 var BaseReporter = class {
-  #options;
   runner;
   /**
    * Path to the file for which the tests are getting executed
@@ -55,13 +56,14 @@ var BaseReporter = class {
    * Group for which the tests are getting executed
    */
   currentGroupName;
+  options;
   constructor(options = {}) {
-    this.#options = Object.assign({ stackLinesCount: 2 }, options);
+    this.options = Object.assign({ stackLinesCount: 2 }, options);
   }
   /**
    * Pretty prints the aggregates
    */
-  #printAggregates(summary) {
+  printAggregates(summary) {
     const tests = [];
     if (summary.aggregates.passed) {
       tests.push(colors.green(`${summary.aggregates.passed} passed`));
@@ -95,7 +97,7 @@ var BaseReporter = class {
   /**
    * Aggregates errors tree to a flat array
    */
-  #aggregateErrors(summary) {
+  aggregateErrors(summary) {
     const errorsList = [];
     summary.failureTree.forEach((suite) => {
       suite.errors.forEach((error) => errorsList.push({ title: suite.name, ...error }));
@@ -121,16 +123,15 @@ var BaseReporter = class {
   /**
    * Pretty print errors
    */
-  async #printErrors(summary) {
+  async printErrors(summary) {
     if (!summary.failureTree.length) {
       return;
     }
     const errorPrinter = new ErrorsPrinter({
-      stackLinesCount: this.#options.stackLinesCount,
-      framesMaxLimit: this.#options.framesMaxLimit
+      framesMaxLimit: this.options.framesMaxLimit
     });
     errorPrinter.printSectionHeader("ERRORS");
-    await errorPrinter.printErrors(this.#aggregateErrors(summary));
+    await errorPrinter.printErrors(this.aggregateErrors(summary));
   }
   /**
    * Handlers to capture events
@@ -155,7 +156,7 @@ var BaseReporter = class {
    * Print tests summary
    */
   async printSummary(summary) {
-    await this.#printErrors(summary);
+    await this.printErrors(summary);
     console.log("");
     if (summary.aggregates.total === 0 && !summary.hasError) {
       console.log(colors.bgYellow().black(" NO TESTS EXECUTED "));
@@ -167,7 +168,7 @@ var BaseReporter = class {
       console.log(colors.bgGreen().black(" PASSED "));
     }
     console.log("");
-    this.#printAggregates(summary);
+    this.printAggregates(summary);
   }
   /**
    * Invoked by the tests runner when tests are about to start
@@ -227,9 +228,8 @@ var Test = class extends BaseTest {
    */
   static executingCallbacks = [];
   /**
-   * Assert the test callback throws an exception when a certain
-   * error message and optionally is an instance of a given
-   * Error class.
+   * Assert the test throws an exception with a certain error message
+   * and optionally is an instance of a given Error class.
    */
   throws(message, errorConstructor) {
     const errorInPoint = new AssertionError({});
@@ -293,4 +293,3 @@ export {
   Suite,
   Runner
 };
-//# sourceMappingURL=chunk-BFNOUWI5.js.map

package/build/{chunk-PHC5CJQG.js → chunk-DPWXK7IV.js}

@@ -2,7 +2,7 @@ import {
   BaseReporter,
   colors,
   icons
-} from "./chunk-BFNOUWI5.js";
+} from "./chunk-CYGUHLQ7.js";
 
 // src/reporters/dot.ts
 var DotReporter = class extends BaseReporter {
@@ -13,10 +13,12 @@ var DotReporter = class extends BaseReporter {
     let output = "";
     if (payload.isTodo) {
       output = colors.cyan(icons.info);
-    } else if (payload.hasError || payload.isFailing) {
-      output = payload.hasError ? colors.magenta(icons.squareSmallFilled) : colors.red(icons.cross);
+    } else if (payload.hasError) {
+      output = colors.red(icons.cross);
     } else if (payload.isSkipped) {
       output = colors.yellow(icons.bullet);
+    } else if (payload.isFailing) {
+      output = colors.magenta(icons.squareSmallFilled);
     } else {
       output = colors.green(icons.tick);
     }
@@ -47,15 +49,15 @@ var SpecReporter = class extends BaseReporter {
     if (payload.isTodo) {
       return colors.cyan(icons.info);
     }
-    if (payload.isFailing) {
-      return payload.hasError ? colors.magenta(icons.squareSmallFilled) : colors.red(icons.cross);
-    }
     if (payload.hasError) {
       return colors.red(icons.cross);
     }
     if (payload.isSkipped) {
       return colors.yellow(icons.bullet);
     }
+    if (payload.isFailing) {
+      return colors.magenta(icons.squareSmallFilled);
+    }
     return colors.green(icons.tick);
   }
   /**
@@ -66,15 +68,15 @@ var SpecReporter = class extends BaseReporter {
     if (payload.isTodo) {
       return colors.blue(message);
     }
-    if (payload.isFailing) {
-      return payload.hasError ? colors.magenta(message) : colors.red(message);
-    }
     if (payload.hasError) {
       return colors.red(message);
     }
     if (payload.isSkipped) {
       return colors.yellow(message);
     }
+    if (payload.isFailing) {
+      return colors.magenta(message);
+    }
     return colors.grey(message);
   }
   /**
@@ -82,20 +84,21 @@ var SpecReporter = class extends BaseReporter {
    */
   #getSubText(payload) {
     if (payload.isSkipped && payload.skipReason) {
-      return colors.yellow(payload.skipReason);
+      return colors.dim(`${icons.branch} ${colors.italic(payload.skipReason)}`);
     }
     if (!payload.isFailing) {
       return;
     }
-    if (!payload.hasError) {
-      return colors.magenta(`Test marked with ".fails()" must finish with an error`);
+    if (payload.hasError) {
+      const message = payload.errors.find((error) => error.phase === "test")?.error.message ?? `Test marked with ".fails()" must finish with an error`;
+      return colors.dim(`${icons.branch} ${colors.italic(message)}`);
     }
     if (payload.failReason) {
-      return colors.magenta(payload.failReason);
+      return colors.dim(`${icons.branch} ${colors.italic(payload.failReason)}`);
     }
     const testErrorMessage = payload.errors.find((error) => error.phase === "test");
     if (testErrorMessage && testErrorMessage.error) {
-      return colors.magenta(testErrorMessage.error.message);
+      return colors.dim(`${icons.branch} ${colors.italic(testErrorMessage.error.message)}`);
     }
   }
   /**
@@ -217,7 +220,9 @@ var NdJSONReporter = class extends BaseReporter {
     console.log(
       JSON.stringify({
         event: "suite:end",
-        ...payload
+        name: payload.name,
+        hasError: payload.hasError,
+        errors: this.#serializeErrors(payload.errors)
       })
     );
   }
@@ -234,6 +239,80 @@ var NdJSONReporter = class extends BaseReporter {
   }
 };
 
+// src/reporters/github.ts
+import slash from "slash";
+import { relative as relative3 } from "node:path";
+import { stripVTControlCharacters } from "node:util";
+import { ErrorsPrinter } from "@japa/errors-printer";
+var GithubReporter = class extends BaseReporter {
+  /**
+   * Performs string escape on annotation message as per
+   * https://github.com/actions/toolkit/blob/f1d9b4b985e6f0f728b4b766db73498403fd5ca3/packages/core/src/command.ts#L80-L85
+   */
+  escapeMessage(value) {
+    return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+  }
+  /**
+   * Performs string escape on annotation properties as per
+   * https://github.com/actions/toolkit/blob/f1d9b4b985e6f0f728b4b766db73498403fd5ca3/packages/core/src/command.ts#L80-L85
+   */
+  escapeProperty(value) {
+    return value.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A").replace(/:/g, "%3A").replace(/,/g, "%2C");
+  }
+  /**
+   * Formats the message as per the Github annotations spec.
+   * https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-an-error-message
+   */
+  formatMessage({
+    command,
+    properties,
+    message
+  }) {
+    let result = `::${command}`;
+    Object.entries(properties).forEach(([k, v], i) => {
+      result += i === 0 ? " " : ",";
+      result += `${k}=${this.escapeProperty(v)}`;
+    });
+    result += `::${this.escapeMessage(message)}`;
+    return result;
+  }
+  /**
+   * Prints Github annotation for a given error
+   */
+  async getErrorAnnotation(printer, error) {
+    const parsedError = await printer.parseError(error.error);
+    if (!("frames" in parsedError)) {
+      return;
+    }
+    const mainFrame = parsedError.frames.find((frame) => frame.type === "app");
+    if (!mainFrame) {
+      return;
+    }
+    return this.formatMessage({
+      command: "error",
+      properties: {
+        file: slash(relative3(process.cwd(), mainFrame.fileName)),
+        title: error.title,
+        line: String(mainFrame.lineNumber),
+        column: String(mainFrame.columnNumber)
+      },
+      message: stripVTControlCharacters(parsedError.message)
+    });
+  }
+  async end() {
+    const summary = this.runner.getSummary();
+    const errorsList = this.aggregateErrors(summary);
+    const errorPrinter = new ErrorsPrinter(this.options);
+    for (let error of errorsList) {
+      const formatted = await this.getErrorAnnotation(errorPrinter, error);
+      if (formatted) {
+        console.log(`
+${formatted}`);
+      }
+    }
+  }
+};
+
 // src/reporters/main.ts
 var spec = (options) => {
   return {
@@ -253,10 +332,16 @@ var ndjson = (options) => {
     handler: (...args) => new NdJSONReporter(options).boot(...args)
   };
 };
+var github = (options) => {
+  return {
+    name: "github",
+    handler: (...args) => new GithubReporter(options).boot(...args)
+  };
+};
 
 export {
   spec,
   dot,
-  ndjson
+  ndjson,
+  github
 };
-//# sourceMappingURL=chunk-PHC5CJQG.js.map

package/build/{chunk-NVI2OU43.js → chunk-WEAHCEFK.js}

@@ -1,15 +1,16 @@
 import {
   dot,
+  github,
   ndjson,
   spec
-} from "./chunk-PHC5CJQG.js";
+} from "./chunk-DPWXK7IV.js";
 import {
   Group,
   Refiner,
   Test,
   TestContext,
   colors
-} from "./chunk-BFNOUWI5.js";
+} from "./chunk-CYGUHLQ7.js";
 
 // src/debug.ts
 import { debuglog } from "node:util";
@@ -259,11 +260,12 @@ var GlobalHooks = class {
 // src/cli_parser.ts
 import getopts from "getopts";
 var OPTIONS = {
-  string: ["tests", "groups", "tags", "files", "timeout", "retries", "reporters", "failed"],
-  boolean: ["help", "matchAll", "failed"],
+  string: ["tests", "groups", "tags", "files", "timeout", "retries", "reporters", "bailLayer"],
+  boolean: ["help", "matchAll", "failed", "bail"],
   alias: {
     forceExit: "force-exit",
     matchAll: "match-all",
+    bailLayer: "bail-layer",
     help: "h"
   }
 };
@@ -273,12 +275,15 @@ ${colors.yellow("@japa/runner v2.3.0")}
 ${colors.green("--tests")}                     ${colors.dim("Filter tests by the test title")}
 ${colors.green("--groups")}                    ${colors.dim("Filter tests by the group title")}
 ${colors.green("--tags")}                      ${colors.dim("Filter tests by tags")}
+${colors.green("--match-all")}                 ${colors.dim("Run tests that matches all the supplied tags")}
 ${colors.green("--files")}                     ${colors.dim("Filter tests by the file name")}
 ${colors.green("--force-exit")}                ${colors.dim("Forcefully exit the process")}
 ${colors.green("--timeout")}                   ${colors.dim("Define default timeout for all tests")}
 ${colors.green("--retries")}                   ${colors.dim("Define default retries for all tests")}
 ${colors.green("--reporters")}                 ${colors.dim("Activate one or more test reporters")}
 ${colors.green("--failed")}                    ${colors.dim("Run tests failed during the last run")}
+${colors.green("--bail")}                      ${colors.dim("Exit early when a test fails")}
+${colors.green("--bail-layer")}                ${colors.dim('Specify at which layer to enable the bail mode. Can be "group" or "suite"')}
 ${colors.green("-h, --help")}                  ${colors.dim("View help")}
 
 ${colors.yellow("Examples:")}
@@ -289,13 +294,18 @@ ${colors.dim("node bin/test.js --force-exit")}
 ${colors.dim('node bin/test.js --files="user"')}
 ${colors.dim('node bin/test.js --files="functional/user"')}
 ${colors.dim('node bin/test.js --files="unit/user"')}
+${colors.dim("node bin/test.js --failed")}
+${colors.dim("node bin/test.js --bail")}
+${colors.dim("node bin/test.js --bail=group")}
 
 ${colors.yellow("Notes:")}
 - When groups and tests filters are applied together. We will first filter the
-  tests by group title and then apply the tests title filter.
+  tests by group title and then apply the tests filter.
 - The timeout defined on test object takes precedence over the ${colors.green("--timeout")} flag.
 - The retries defined on test object takes precedence over the ${colors.green("--retries")} flag.
 - The ${colors.green("--files")} flag checks for the file names ending with the filter substring.
+- The ${colors.green("--tags")} filter runs tests that has one or more of the supplied tags.
+- You can use the ${colors.green("--match-all")} flag to run tests that has all the supplied tags.
 `;
 var CliParser = class {
   /**
@@ -322,8 +332,8 @@ var DEFAULTS = {
   forceExit: false,
   plugins: [],
   reporters: {
-    activated: ["spec"],
-    list: [spec(), ndjson(), dot()]
+    activated: ["spec"].concat(process.env.GITHUB_ACTIONS === "true" ? ["github"] : []),
+    list: [spec(), ndjson(), dot(), github()]
   },
   importer: (filePath) => import(filePath.href),
   configureSuite: () => {
@@ -501,4 +511,3 @@ export {
   createTest,
   createTestGroup
 };
-//# sourceMappingURL=chunk-NVI2OU43.js.map

package/build/factories/{create_diverse_tests.d.ts → create_dummy_tests.d.ts}

@@ -3,4 +3,4 @@ import { Suite, Emitter, Refiner } from '../modules/core/main.js';
  * Returns an array of suites with dummy tests reproducting
  * different test behavior
  */
-export declare function createDiverseTests(emitter: Emitter, refiner: Refiner, file?: string): Suite[];
+export declare function createDummyTests(emitter: Emitter, refiner: Refiner, file?: string): Suite[];

package/build/factories/main.d.ts

@@ -4,5 +4,5 @@ import { RunnerFactory } from './runner.js';
  * Create an instance of the runner factory
  */
 export declare const runner: () => RunnerFactory;
-export { createDiverseTests } from './create_diverse_tests.js';
+export { createDummyTests } from './create_dummy_tests.js';
 export declare const syncReporter: ReporterContract;

package/build/factories/main.js

@@ -5,14 +5,14 @@ import {
   Planner,
   createTest,
   createTestGroup
-} from "../chunk-NVI2OU43.js";
-import "../chunk-PHC5CJQG.js";
+} from "../chunk-WEAHCEFK.js";
+import "../chunk-DPWXK7IV.js";
 import {
   Emitter,
   Runner,
   Suite
-} from "../chunk-BFNOUWI5.js";
-import "../chunk-OBDV3O36.js";
+} from "../chunk-CYGUHLQ7.js";
+import "../chunk-2KG3PWR4.js";
 
 // factories/runner.ts
 import { fileURLToPath } from "node:url";
@@ -21,6 +21,7 @@ var RunnerFactory = class {
   #config;
   #cliArgs;
   #file = fileURLToPath(import.meta.url);
+  #bail = false;
   get #refiner() {
     return this.#config.refiner;
   }
@@ -65,11 +66,19 @@ var RunnerFactory = class {
       return [defaultSuite];
     });
   }
+  /**
+   * Enable/disable the bail mode
+   */
+  bail(toggle = true) {
+    this.#bail = toggle;
+    return this;
+  }
   /**
    * Run dummy tests. You might use
    */
   async runSuites(suites) {
     const runner2 = new Runner(this.#emitter);
+    runner2.bail(this.#bail);
     await this.#registerPlugins(runner2);
     const { config, reporters, refinerFilters } = await new Planner(this.#config).plan();
     const globalHooks = new GlobalHooks();
@@ -90,7 +99,7 @@ var RunnerFactory = class {
   }
 };
 
-// factories/create_diverse_tests.ts
+// factories/create_dummy_tests.ts
 import assert from "node:assert";
 function createUnitTestsSuite(emitter, refiner, file) {
   const suite = new Suite("unit", emitter, refiner);
@@ -126,6 +135,9 @@ function createUnitTestsSuite(emitter, refiner, file) {
   createTest("add floating numbers", emitter, refiner, { group, file }).run(() => {
     assert.equal(2 + 2.2 + 2.1, 6);
   }).fails("Have to add support for floating numbers");
+  createTest("regression test that is passing", emitter, refiner, { group, file }).run(() => {
+    assert.equal(2 + 2.2 + 2.1, 2 + 2.2 + 2.1);
+  }).fails("Have to add support for floating numbers");
   createTest("A test with an error that is not an AssertionError", emitter, refiner, {
     group,
     file
@@ -165,6 +177,14 @@ function createFunctionalTestsSuite(emitter, refiner, file) {
     group,
     file
   });
+  createTest("Test that times out", emitter, refiner, {
+    group,
+    file
+  }).run(() => {
+    return new Promise((resolve) => {
+      setTimeout(resolve, 2100);
+    });
+  });
   const usersListGroup = createTestGroup("Users/list", emitter, refiner, {
     suite,
     file
@@ -172,7 +192,7 @@ function createFunctionalTestsSuite(emitter, refiner, file) {
   usersListGroup.setup(() => {
     throw new Error("Unable to cleanup database");
   });
-  createTest("A test that will never because the group hooks fails", emitter, refiner, {
+  createTest("A test that will never run because the group hooks fails", emitter, refiner, {
     group: usersListGroup
   });
   createTest("A top level test inside functional suite", emitter, refiner, {
@@ -182,7 +202,7 @@ function createFunctionalTestsSuite(emitter, refiner, file) {
   });
   return suite;
 }
-function createDiverseTests(emitter, refiner, file) {
+function createDummyTests(emitter, refiner, file) {
   return [
     createUnitTestsSuite(emitter, refiner, file),
     createFunctionalTestsSuite(emitter, refiner, file)
@@ -208,8 +228,7 @@ var syncReporter = {
   }
 };
 export {
-  createDiverseTests,
+  createDummyTests,
   runner,
   syncReporter
 };
-//# sourceMappingURL=main.js.map

package/build/factories/runner.d.ts

@@ -19,6 +19,10 @@ export declare class RunnerFactory {
      * Run a test using the runner
      */
     runTest(title: string, callback: TestExecutor<TestContext, undefined>): Promise<RunnerSummary>;
+    /**
+     * Enable/disable the bail mode
+     */
+    bail(toggle?: boolean): this;
     /**
      * Run dummy tests. You might use
      */

package/build/index.d.ts

@@ -1,6 +1,7 @@
 import type { TestExecutor } from '@japa/core/types';
 import type { Config } from './src/types.js';
 import { Group, Test, TestContext } from './modules/core/main.js';
+type OmitFirstArg<F> = F extends [_: any, ...args: infer R] ? R : never;
 /**
  * Create a Japa test. Defining a test without the callback
  * will create a todo test.
@@ -8,6 +9,7 @@ import { Group, Test, TestContext } from './modules/core/main.js';
 export declare function test(title: string, callback?: TestExecutor<TestContext, undefined>): Test<undefined>;
 export declare namespace test {
     var group: (title: string, callback: (group: Group) => void) => void;
+    var macro: <T extends (test: Test, ...args: any[]) => any>(callback: T) => (...args: OmitFirstArg<Parameters<T>>) => ReturnType<T>;
 }
 /**
  * Get the test of currently running test
@@ -31,3 +33,4 @@ export declare function configure(options: Config): void;
  * files behind the scenes
  */
 export declare function run(): Promise<void>;
+export {};