fail-on-console 1.1.2 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [1.3.0](https://github.com/benquarmby/fail-on-console/compare/v1.2.0...v1.3.0) (2026-08-01)
+
+
+### Features
+
+* support process.stdout and process.stderr monitoring ([a79f82f](https://github.com/benquarmby/fail-on-console/commit/a79f82fa6ea778d44e8a59654f89bdd66464ab76))
+
+## [1.2.0](https://github.com/benquarmby/fail-on-console/compare/v1.1.2...v1.2.0) (2026-07-25)
+
+
+### Features
+
+* do not require expect API in setupConsole ([04c0bad](https://github.com/benquarmby/fail-on-console/commit/04c0bad55f39773e6fb326f6364a5c64d46b3e0f))
+
 ## [1.1.2](https://github.com/benquarmby/fail-on-console/compare/v1.1.1...v1.1.2) (2026-07-22)
 
 

package/README.md

@@ -5,13 +5,14 @@ Fail Vitest or Jest tests when unexpected console logs, warnings or errors occur
 [![npm version](https://img.shields.io/npm/v/fail-on-console.svg)](https://www.npmjs.com/package/fail-on-console)
 [![license](https://img.shields.io/npm/l/fail-on-console.svg)](https://github.com/benquarmby/fail-on-console/blob/main/LICENSE)
 
-The `fail-on-console` utility fails test suites whenever unexpected `console` logs, warnings, or errors are triggered, keeping test results clear and easy to read.
+The `fail-on-console` utility fails test suites whenever unexpected `console` output or `process` writes are triggered, keeping test results clear and easy to read.
 
 ## Features
 
 - **⚡ Vitest and Jest Native**: Seamless integration with Vitest (including Browser Mode) and Jest using standard lifecycle hooks.
+- **📡 Raw Stream Monitoring:** Fails on unexpected writes to `process.stdout` or `process.stderr` on top of standard console calls. Output from libraries that write directly to the stream doesn't slip through.
 - **🪶 Zero Dependencies**: Pure, lightweight JavaScript with a tiny footprint.
-- **🎯 Configurable Targets**: Choose exactly which console methods to monitor (`log`, `warn`, `error`, `info`, `debug`).
+- **🎯 Configurable Targets**: Choose exactly which console methods and / or process streams to monitor.
 - **📋 Flexible Allowlist**: Easily suppress expected console noise globally, per suite, or per test using strings, regular expressions, or custom predicates.
 
 ## Installation
@@ -35,10 +36,10 @@ Initialize `setupConsole` inside a configured [`setupFiles`](https://vitest.dev/
 
 ```js
 // vitest.setup.js
-import {beforeEach, afterEach, expect} from "vitest";
+import {beforeEach, afterEach} from "vitest";
 import {setupConsole} from "fail-on-console";
 
-setupConsole({beforeEach, afterEach, expect});
+setupConsole({beforeEach, afterEach});
 ```
 
 ### With Jest
@@ -47,46 +48,48 @@ Initialize `setupConsole` inside a configured [`setupFilesAfterEnv`](https://jes
 
 ```js
 // jest.setup.js
-import {beforeEach, afterEach, expect} from "@jest/globals";
+import {beforeEach, afterEach} from "@jest/globals";
 import {setupConsole} from "fail-on-console";
 
-setupConsole({beforeEach, afterEach, expect});
+setupConsole({beforeEach, afterEach});
 ```
 
-### Customizing Monitored Methods
+### Customizing Monitored Methods and Streams
 
-By default, `debug` is not monitored but `error`, `warn`, `info`, and `log` are. This can be customized by passing a `methods` array:
+By default, `console.debug` is not monitored but `error`, `warn`, `info`, and `log` are. This can be customized by passing a `methods` array. Similarly, `process.stdout` and `process.stderr` are not monitored by default, but can be configured with a `streams` array:
 
 ```ts
 setupConsole({
     beforeEach,
     afterEach,
-    expect,
     // Fail on console.error, console.warn, and console.debug.
-    methods: ["error", "warn", "debug"]
+    methods: ["error", "warn", "debug"],
+    // Fail when libraries like Bunyan write straight to process.stdout,
+    // bypassing console entirely.
+    streams: ["stdout", "stderr"]
 });
 ```
 
 ## 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.
+If a specific test or third-party dependency intentionally logs to the console, `allowConsole` and `allowStream` 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.
+These functions can be invoked globally, inside a `describe` block, or inside a specific `test`/`it` block.
 
 ```javascript
-import {allowConsole} from "fail-on-console";
+import {allowConsole, allowStream} 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/);
+allowStream("stderr", /^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")]);
+allowStream("stdout", ["known warning", /deprecated/, (msg) => msg.includes("third-party")]);
 ```
 
 ## API Reference
@@ -97,8 +100,8 @@ 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"]`.
+- `options.streams`: _(Optional)_ Array of `process` streams to track. Defaults to `[]` (no streams monitored).
 
 ### `allowConsole(method, rules)`
 
@@ -110,6 +113,16 @@ Registers a temporary or global allowlist rule for a monitored console method.
     - `RegExp`: Allowed if the regex tests true against the message.
     - `Function`: A predicate `(message: string) => boolean` returning `true` to allow the message.
 
+### `allowStream(stream, rules)`
+
+Registers a temporary or global allowlist rule for a monitored process stream.
+
+- `stream`: `"stdout" | "stderr"`
+- `rules`: A single rule or an array of rules. A rule can be:
+    - `string`: Allowed if the written 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
 
 ### Concurrency
@@ -124,6 +137,10 @@ Monitoring `console.assert` is currently unsupported. It has a distinct signatur
 
 Mocha is unsupported due to API incompatibilities related to test context. There are no clean or reliable workarounds for integration.
 
+### Browser Mode
+
+`process.stdout` and `process.stderr` don't exist in a real browser environment, so the `streams` option has no effect under Vitest Browser Mode. `setupConsole` detects this and silently skips stream monitoring rather than throwing. `methods` monitoring is unaffected and works normally.
+
 ## Credits & Prior Art
 
 This package is inspired by and builds on the excellent foundation laid by:

package/index.d.ts

@@ -1,4 +1,5 @@
 export type ConsoleMethod = "error" | "warn" | "info" | "log" | "debug";
+export type ProcessStream = "stderr" | "stdout";
 
 export interface ExpectStateLike {
     currentTestName?: string;
@@ -15,11 +16,15 @@ export interface LifecycleHookLike {
 export interface TestApi {
     beforeEach: LifecycleHookLike;
     afterEach: LifecycleHookLike;
-    expect: ExpectLike;
+    /**
+     * @deprecated No longer needed. This option can be omitted.
+     */
+    expect?: ExpectLike;
 }
 
 export interface SetupOptions extends TestApi {
     methods?: ConsoleMethod[];
+    streams?: ProcessStream[];
 }
 
 export interface AllowPredicate {
@@ -37,25 +42,25 @@ export function setup(options: SetupOptions): void;
 /**
  * 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.).
+ * lifecycle hooks from the test framework. Compatible with any Jest-like API
+ * (Vitest, Jest, 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.
+ * @param {string[]} [options.streams=[]] Process streams to monitor. None by default.
  * @example
- * // Jest
- * import {beforeEach, afterEach, expect} from "@jest/globals";
+ * // Vitest
+ * import {beforeEach, afterEach} from "vitest";
  * import {setup} from "fail-on-console";
  *
- * setup({beforeEach, afterEach, expect});
+ * setup({beforeEach, afterEach});
  * @example
- * // Vitest
- * import {beforeEach, afterEach, expect} from "vitest";
+ * // Jest
+ * import {beforeEach, afterEach} from "@jest/globals";
  * import {setup} from "fail-on-console";
  *
- * setup({beforeEach, afterEach, expect});
+ * setup({beforeEach, afterEach});
  */
 export function setupConsole(options: SetupOptions): void;
 
@@ -63,14 +68,13 @@ export function setupConsole(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".
+ * "log" or "debug".
  * @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.
+ * more rules. A message is allowed if any rule finds a match. 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
+ * // String - allow any warn containing this substring
  * allowConsole("warn", "third-party library warning");
  * @example
  * // RegExp - allow errors matching a pattern
@@ -79,7 +83,26 @@ export function setupConsole(options: SetupOptions): void;
  * // Predicate - allow logs from a specific source
  * allowConsole("log", (message) => message.startsWith("[analytics]"));
  * @example
- * // Mixed array - allow multiple matchers at once
+ * // Mixed array - allow multiple rules at once
  * allowConsole("error", ["known warning", /deprecated/, (m) => m.includes("third-party")]);
  */
 export function allowConsole(method: ConsoleMethod, rules: AllowRule | AllowRule[]): void;
+
+/**
+ * Allows specific writes to `process.stdout` or `process.stderr` to pass.
+ * Stream exceptions can be configured globally, within a describe block or
+ * inside a single test. No-op in environments where `globalThis.process` does
+ * not exist.
+ * @param {string} stream The target process stream to allow: "stdout" or "stderr".
+ * @param {string|RegExp|Function|Array<string|RegExp|Function>} rules One or
+ * more rules. A message is allowed if any rule finds a match. 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
+ * // String - allow standard output containing this substring
+ * allowStream("stdout", "unavoidable log message");]);
+ * @example
+ * // Mixed array - allow standard errors using multiple rules at once
+ * allowStream("stderr", ["known warning", /deprecated/, (m) => m.includes("third-party")]);
+ */
+export function allowStream(stream: ProcessStream, rules: Rule | Rule[]): void;

package/index.js

@@ -1,36 +1,51 @@
-let testApi;
 const supportedMethods = ["error", "warn", "info", "log", "debug"];
+const supportedStreams = ["stderr", "stdout"];
 // Everything but console.debug is monitored by default. Debug logging in tests
 // is usually intentional.
 const defaultMethods = supportedMethods.slice(0, -1);
-const allowed = new Map();
+// No streams are monitored by default.
+const defaultStreams = [];
 // %s string, %d/%i integer, %o object, %f float
 const printfPattern = /%[sdiof]/g;
 
+// Module scoped variables to manage test state. Not safe for concurrent tests.
+// Test frameworks run tests serially by default.
+let testApi;
+let isInsideTest = false;
+const allowedMethods = new Map();
+const allowedStreams = new Map();
+
 function quoteString(value) {
     return `"${value}"`;
 }
 
-function assertSupportedMethods(methods) {
-    if (!Array.isArray(methods)) {
-        throw new Error("fail-on-console: Expected an array of console methods.");
+function assertSupportedValues(pluralName, supportedValues, values) {
+    if (!Array.isArray(values)) {
+        throw new Error(`fail-on-console: Expected an array of ${pluralName}.`);
     }
 
-    const unsupported = methods.filter((method) => !supportedMethods.includes(method));
+    const unsupported = values.filter((value) => !supportedValues.includes(value));
 
     if (!unsupported.length) {
         return;
     }
 
-    const method = unsupported.length === 1 ? "method" : "methods";
     const invalidList = unsupported.map(quoteString).join(", ");
-    const validList = supportedMethods.map(quoteString).join(", ");
+    const validList = supportedValues.map(quoteString).join(", ");
 
     throw new Error(
-        `fail-on-console: Unsupported console ${method} provided: ${invalidList}. Supported methods are: ${validList}.`
+        `fail-on-console: One or more unsupported ${pluralName} provided: ${invalidList}. Supported ${pluralName} are: ${validList}.`
     );
 }
 
+function assertSupportedMethods(methods) {
+    return assertSupportedValues("console methods", supportedMethods, methods);
+}
+
+function assertSupportedStreams(streams) {
+    return assertSupportedValues("process streams", supportedStreams, streams);
+}
+
 /**
  * Basic implementation of node:util/format for console message formatting.
  * Covers only the most common uses. Does not handle all specifiers (such as
@@ -73,16 +88,41 @@ function isAllowed(message, rule) {
     return rule.test(message);
 }
 
-function setupConsole({beforeEach, afterEach, expect, methods = defaultMethods}) {
+function chunkToString(chunk, encoding = "utf8") {
+    if (typeof chunk === "string") {
+        return chunk;
+    }
+
+    if (ArrayBuffer.isView(chunk)) {
+        if (Buffer.isBuffer(chunk)) {
+            return chunk.toString(encoding);
+        }
+
+        return new TextDecoder(encoding).decode(chunk);
+    }
+
+    return Buffer.from(chunk).toString(encoding);
+}
+
+function setupConsole({beforeEach, afterEach, methods = defaultMethods, streams = defaultStreams}) {
     if (testApi) {
         throw new Error("fail-on-console: Call setupConsole() only once.");
     }
 
     assertSupportedMethods(methods);
+    assertSupportedStreams(streams);
 
-    testApi = {beforeEach, afterEach, expect};
+    testApi = {beforeEach, afterEach};
 
-    beforeEach(() => allowed.clear());
+    beforeEach(function () {
+        isInsideTest = true;
+        allowedMethods.clear();
+        allowedStreams.clear();
+    });
+
+    afterEach(function () {
+        isInsideTest = false;
+    });
 
     methods.forEach(function (method) {
         const original = console[method];
@@ -93,7 +133,7 @@ function setupConsole({beforeEach, afterEach, expect, methods = defaultMethods})
 
             console[method] = function consoleOverride(...args) {
                 const message = format(...args);
-                const rules = allowed.get(method);
+                const rules = allowedMethods.get(method);
 
                 if (rules?.some((rule) => isAllowed(message, rule))) {
                     return;
@@ -120,6 +160,56 @@ function setupConsole({beforeEach, afterEach, expect, methods = defaultMethods})
             );
         });
     });
+
+    streams.forEach(function (streamName) {
+        const stream = globalThis.process?.[streamName];
+
+        if (!stream) {
+            return;
+        }
+
+        const originalWrite = stream.write;
+        const calls = [];
+
+        beforeEach(function () {
+            calls.length = 0;
+
+            stream.write = function streamOverride(chunk, encoding, cb) {
+                if (typeof encoding === "function") {
+                    cb = encoding;
+                    encoding = undefined;
+                }
+
+                const message = chunkToString(chunk, encoding);
+                const rules = allowedStreams.get(streamName);
+
+                if (!rules?.some((rule) => isAllowed(message, rule))) {
+                    const call = {message, stack: ""};
+                    Error.captureStackTrace?.(call, streamOverride);
+
+                    calls.push(call);
+                }
+
+                cb?.();
+
+                return true;
+            };
+        });
+
+        afterEach(function () {
+            stream.write = originalWrite;
+
+            if (!calls.length) {
+                return;
+            }
+
+            const detail = calls.map(({message, stack}) => `${message}\n${stack}`).join("\n\n");
+
+            throw new Error(
+                `Expected test not to write to process.${streamName}.\n\n${detail}\n\nIf expected, use allowStream("${streamName}", ...) to add an exception.`
+            );
+        });
+    });
 }
 
 function allowConsole(method, rules) {
@@ -130,11 +220,31 @@ function allowConsole(method, rules) {
     assertSupportedMethods([method]);
 
     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]);
+        const existing = allowedMethods.get(method) ?? [];
+        allowedMethods.set(method, [...existing, ...normalized]);
+    }
+
+    if (isInsideTest) {
+        addRules();
+    } else {
+        testApi.beforeEach(addRules);
+    }
+}
+
+function allowStream(stream, rules) {
+    if (!testApi) {
+        throw new Error("fail-on-console: Call setupConsole() before using allowStream().");
+    }
+
+    assertSupportedStreams([stream]);
+
+    const normalized = Array.isArray(rules) ? rules : [rules];
+
+    function addRules() {
+        const existing = allowedStreams.get(stream) ?? [];
+        allowedStreams.set(stream, [...existing, ...normalized]);
     }
 
     if (isInsideTest) {
@@ -147,3 +257,4 @@ function allowConsole(method, rules) {
 exports.setup = setupConsole;
 exports.setupConsole = setupConsole;
 exports.allowConsole = allowConsole;
+exports.allowStream = allowStream;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fail-on-console",
-  "version": "1.1.2",
+  "version": "1.3.0",
   "description": "Fail Vitest or Jest tests when unexpected console logs, warnings or errors occur.",
   "keywords": [
     "jest",
@@ -20,19 +20,20 @@
   ],
   "devDependencies": {
     "@commitlint/config-conventional": "^21.2.0",
-    "@vitest/coverage-v8": "4.1.9",
-    "commitlint": "^21.2.0",
+    "@vitest/coverage-v8": "4.1.10",
+    "commitlint": "^21.2.1",
     "jest": "^30.4.2",
-    "prettier": "^3.8.4",
+    "npm-run-all2": "^9.0.3",
+    "prettier": "^3.9.6",
     "prettier-plugin-packagejson": "^3.0.2",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.10"
   },
   "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"
+    "test:jest": "jest",
+    "test:vitest": "vitest run --coverage",
+    "verify": "run-s commit:check format:check test:vitest test:jest"
   }
 }