fail-on-console 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 1.0.0 (2026-07-06)
+
+
+### Features
+
+* add initial fail-on-console implementation ([a414cbf](https://github.com/benquarmby/fail-on-console/commit/a414cbfb129443a2fd1d369d4f37c6b54fe90aa5))

package/README.md

@@ -0,0 +1,120 @@
+# Fail on Console
+
+Prevent console noise from obscuring test results.
+
+This utility fails tests whenever unexpected `console` logs, warnings, or errors are triggered. It is compatible with Vitest and Jest.
+
+## Features
+
+- **Framework Agnostic**: Integrates with Vitest, Jest, or any framework exposing standard lifecycle hooks and `expect.getState()`.
+- **Zero Dependencies**: Pure, lightweight JavaScript with a minimal footprint.
+- **Browser Ready**: Contains no Node.js API dependencies, allowing it to run inside Vitest Browser Mode.
+- **Configurable Targets**: Allows explicit selection of which console methods to monitor.
+- **Flexible Allowlist**: Suppresses known or expected console outputs globally, per suite, or per individual test. Exceptions can be matched against strings, regular expressions, or custom predicate functions.
+
+## Installation
+
+```sh
+# pnpm
+pnpm add --save-dev fail-on-console
+
+# npm
+npm install --save-dev fail-on-console
+
+# yarn
+yarn add --dev fail-on-console
+```
+
+## Setup
+
+`setup` should be called once in a global setup file, accepting the lifecycle hooks and `expect` utility from the testing framework.
+
+### With Vitest
+
+```ts
+import {beforeEach, afterEach, expect} from "vitest";
+import {setup} from "fail-on-console";
+
+setup({beforeEach, afterEach, expect});
+```
+
+### With Jest
+
+```ts
+import {beforeEach, afterEach, expect} from "@jest/globals";
+import {setup} from "fail-on-console";
+
+setup({beforeEach, afterEach, expect});
+```
+
+### Customizing Monitored Methods
+
+By default, `debug` is not monitored but `error`, `warn`, `info`, and `log` are. This can be customized by passing a `methods` array:
+
+```ts
+setup({
+    beforeEach,
+    afterEach,
+    expect,
+    // Fail on console.error, console.warn and console.debug.
+    methods: ["error", "warn", "debug"]
+});
+```
+
+## Suppressing Expected Logs
+
+If a specific test or third-party dependency intentionally logs to the console, `allowConsole` can be used to allow the test to pass.
+
+`allowConsole` can be invoked globally, inside a `describe` block, or inside a specific `test`/`it` block.
+
+```javascript
+import {allowConsole} from "fail-on-console";
+
+// Allow a substring.
+allowConsole("warn", "third-party library warning");
+
+// Allow a Regular Expression.
+allowConsole("error", /^Warning: Each child in a list/);
+
+// Allow with a custom predicate function
+allowConsole("log", (message) => message.startsWith("[analytics]"));
+
+// An array of mixed matchers
+allowConsole("error", ["known warning", /deprecated/, (msg) => msg.includes("third-party")]);
+```
+
+## API Reference
+
+### `setup(options)`
+
+Initializes console spies that monitor active tests.
+
+- `options.beforeEach`: The framework's `beforeEach` hook.
+- `options.afterEach`: The framework's `afterEach` hook.
+- `options.expect`: The framework's `expect` object (must expose `getState()`).
+- `options.methods`: _(Optional)_ Array of `console` methods to track. Defaults to `["error", "warn", "info", "log"]`.
+
+### `allowConsole(method, rules)`
+
+Registers a temporary or global allowlist rule for a monitored console method.
+
+- `method`: `"error" | "warn" | "info" | "log" | "debug"`
+- `rules`: A single rule or an array of rules. A rule can be:
+    - `string`: Allowed if the console message contains this substring.
+    - `RegExp`: Allowed if the regex tests true against the message.
+    - `Function`: A predicate `(message: string) => boolean` returning `true` to allow the message.
+
+## Limitations
+
+`fail-on-console` is not compatible with concurrent asynchronous tests (e.g., `test.concurrent`). Because concurrent tests execute simultaneously within the same environment context, console logs cannot be isolated reliably per individual test. For suites requiring specific log suppression, tests must be run sequentially.
+
+## Credits & Prior Art
+
+This package is inspired by and builds on the excellent foundation laid by:
+
+- [jest-fail-on-console](https://github.com/ValentinH/jest-fail-on-console) by Valentin Hervieu
+- [vitest-fail-on-console](https://github.com/thomasbrodusch/vitest-fail-on-console) by Thomas Brodusch
+
+## License
+
+MIT

package/index.d.ts

@@ -0,0 +1,79 @@
+export type ConsoleMethod = "error" | "warn" | "info" | "log" | "debug";
+
+export interface ExpectStateLike {
+    currentTestName?: string;
+}
+
+export interface ExpectLike {
+    getState(): ExpectStateLike;
+}
+
+export interface LifecycleHookLike {
+    (fn: () => void): void;
+}
+
+export interface TestApi {
+    beforeEach: LifecycleHookLike;
+    afterEach: LifecycleHookLike;
+    expect: ExpectLike;
+}
+
+export interface SetupOptions extends TestApi {
+    methods?: ConsoleMethod[];
+}
+
+export interface AllowPredicate {
+    (message: string): boolean;
+}
+
+export type AllowRule = string | RegExp | AllowPredicate;
+
+/**
+ * Installs console spies that fail the current test if any monitored console
+ * method is called. Call once at the top of the test setup file, passing the
+ * lifecycle hooks and expect function from the test framework. Compatible with
+ * any Jest-compatible API (Jest, Vitest, etc.).
+ * @param {Object} options
+ * @param {Function} options.beforeEach The beforeEach hook from the test framework.
+ * @param {Function} options.afterEach The afterEach hook from the test framework.
+ * @param {Object} options.expect The expect object from the test framework. Must expose getState().
+ * @param {string[]} [options.methods=["error","warn","info","log"]] - Console methods to monitor.
+ * @example
+ * // Jest
+ * import {beforeEach, afterEach, expect} from "@jest/globals";
+ * import {setup} from "fail-on-console";
+ *
+ * setup({beforeEach, afterEach, expect});
+ * @example
+ * // Vitest
+ * import {beforeEach, afterEach, expect} from "vitest";
+ * import {setup} from "fail-on-console";
+ *
+ * setup({beforeEach, afterEach, expect});
+ */
+export function setup(options: SetupOptions): void;
+
+/**
+ * Allows specific console calls to pass. Console exceptions can be configured
+ * globally, within a describe block or inside a single test.
+ * @param {string} method The console method to allow: "error", "warn", "info",
+ * "log", "debug", or "assert".
+ * @param {string|RegExp|Function|Array<string|RegExp|Function>} rules One or
+ * more matchers. A message is allowed if any matcher matches it. A string
+ * matches when the message contains it. A RegExp matches when it tests true
+ * against the message. A function receives the message and returns true to
+ * allow it.
+ * @example
+ * // Single string - allow any warn containing this substring
+ * allowConsole("warn", "third-party library warning");
+ * @example
+ * // RegExp - allow errors matching a pattern
+ * allowConsole("error", /^Warning: Each child in a list/);
+ * @example
+ * // Predicate - allow logs from a specific source
+ * allowConsole("log", (message) => message.startsWith("[analytics]"));
+ * @example
+ * // Mixed array - allow multiple matchers at once
+ * allowConsole("error", ["known warning", /deprecated/, (m) => m.includes("third-party")]);
+ */
+export function allowConsole(method: ConsoleMethod, rules: AllowRule | AllowRule[]): void;

package/index.js

@@ -0,0 +1,117 @@
+let testApi;
+const defaultMethods = ["error", "warn", "info", "log"];
+const allowed = new Map();
+// %s string, %d/%i integer, %o object, %f float
+const printfPattern = /%[sdiof]/g;
+
+/**
+ * Basic implementation of node:util/format for console message formatting.
+ * Covers only the most common uses. Does not handle all specifiers (such as
+ * object expansion) or other edge cases.
+ * @param {...*} args The list of arguments passed to the console method.
+ * @returns {string} The formatted message string.
+ */
+function format(...args) {
+    const [format, ...values] = args;
+
+    if (typeof format !== "string") {
+        return args.map(String).join(" ");
+    }
+
+    let valueIndex = 0;
+    const result = format.replace(printfPattern, function (match) {
+        const value = values[valueIndex];
+        const formatted = valueIndex < values.length ? String(value) : match;
+        valueIndex += 1;
+
+        return formatted;
+    });
+
+    if (valueIndex < values.length) {
+        return result + " " + values.slice(valueIndex).map(String).join(" ");
+    }
+
+    return result;
+}
+
+function isAllowed(message, rule) {
+    if (typeof rule === "string") {
+        return message.includes(rule);
+    }
+
+    if (typeof rule === "function") {
+        return rule(message);
+    }
+
+    return rule.test(message);
+}
+
+function setup({beforeEach, afterEach, expect, methods = defaultMethods}) {
+    if (testApi) {
+        throw new Error("fail-on-console: Call setup() only once.");
+    }
+
+    testApi = {beforeEach, afterEach, expect};
+
+    beforeEach(() => allowed.clear());
+
+    methods.forEach(function (method) {
+        const original = console[method];
+        const calls = [];
+
+        beforeEach(function () {
+            calls.length = 0;
+
+            console[method] = function consoleOverride(...args) {
+                const message = format(...args);
+                const rules = allowed.get(method);
+
+                if (rules?.some((rule) => isAllowed(message, rule))) {
+                    return;
+                }
+
+                const call = {message, stack: ""};
+                Error.captureStackTrace?.(call, consoleOverride);
+
+                calls.push(call);
+            };
+        });
+
+        afterEach(function () {
+            console[method] = original;
+
+            if (!calls.length) {
+                return;
+            }
+
+            const detail = calls.map(({message, stack}) => `${message}\n${stack}`).join("\n\n");
+
+            throw new Error(
+                `Expected test not to call console.${method}().\n\n${detail}\n\nIf expected, use allowConsole("${method}", ...) to add an exception.`
+            );
+        });
+    });
+}
+
+function allowConsole(method, rules) {
+    if (!testApi) {
+        throw new Error("fail-on-console: Call setup() before using allowConsole().");
+    }
+
+    const normalized = Array.isArray(rules) ? rules : [rules];
+    const isInsideTest = !!testApi.expect.getState().currentTestName;
+
+    function addRules() {
+        const existing = allowed.get(method) ?? [];
+        allowed.set(method, [...existing, ...normalized]);
+    }
+
+    if (isInsideTest) {
+        addRules();
+    } else {
+        testApi.beforeEach(addRules);
+    }
+}
+
+exports.setup = setup;
+exports.allowConsole = allowConsole;

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "fail-on-console",
+  "version": "1.0.0",
+  "description": "Prevent console noise from obscuring test results.",
+  "license": "MIT",
+  "main": "./index.js",
+  "files": [
+    "./CHANGELOG.md",
+    "./index.d.ts"
+  ],
+  "devDependencies": {
+    "@commitlint/config-conventional": "^21.2.0",
+    "@vitest/coverage-v8": "4.1.9",
+    "commitlint": "^21.2.0",
+    "jest": "^30.4.2",
+    "prettier": "^3.8.4",
+    "prettier-plugin-packagejson": "^3.0.2",
+    "vitest": "^4.1.9"
+  },
+  "scripts": {
+    "commit:check": "commitlint --from-last-tag",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:compat": "jest",
+    "test:cover": "vitest run --coverage"
+  }
+}