Merge pull request #190 from dahlia/failure-log-reporter

Scoped failure log reporting for tests

Author: dahlia

CHANGES.md

@@ -23,6 +23,26 @@ To be released.
 [#185]: https://github.com/dahlia/logtape/issues/185
 [#188]: https://github.com/dahlia/logtape/pull/188
 
+### @logtape/testing
+
+ -  Added `createFailureLogReporter()` for buffering LogTape records during a
+    test callback and reporting them only when the callback fails by default.
+    The reporter uses scoped configuration, preserves wrapped callback
+    parameters, and supports `mode: "on-failure"`, `mode: "always"`, and
+    `mode: "never"`.  [[#186], [#189]]
+
+     -  Added `FailureLogReporter` interface with `wrap()` and `run()`
+        methods.
+     -  Added `FailureLogReporterOptions` interface with `mode`,
+        `lowestLevel`, `sink`, and `formatter` options.
+     -  Added `FailureLogReportMode` type.
+     -  Added `@logtape/testing/recorder` and
+        `@logtape/testing/reporter` subpath exports while keeping the root
+        `@logtape/testing` export for compatibility.
+
+[#186]: https://github.com/dahlia/logtape/issues/186
+[#189]: https://github.com/dahlia/logtape/pull/189
+
 ### @logtape/file
 
  -  Added `TimeRotatingFileSinkOptions.parseFilename` option to customize how

docs/.vitepress/config.mts

@@ -296,6 +296,8 @@ export default defineConfig({
         twoslashOptions: {
           compilerOptions: {
             lib: ["dom", "dom.iterable", "esnext"],
+            module: 99, // ts.ModuleKind.ESNext
+            moduleResolution: 100, // ts.ModuleResolutionKind.Bundler
             types: [
               "dom",
               "dom.iterable",

docs/manual/library.md

@@ -129,7 +129,7 @@ bun add @logtape/testing
 ~~~~ typescript twoslash
 // @noErrors: 2307
 import { configure, reset } from "@logtape/logtape";
-import { createLogRecorder } from "@logtape/testing";
+import { createLogRecorder } from "@logtape/testing/recorder";
 import { Database } from "my-awesome-lib";
 
 const recorder = createLogRecorder();

docs/manual/testing.md

@@ -91,12 +91,13 @@ bun add @logtape/testing
 
 ~~~~ typescript twoslash
 // @noErrors: 2307
+import { after, before, test } from "node:test";
 import { configure, getLogger, reset } from "@logtape/logtape";
-import { createLogRecorder } from "@logtape/testing";
+import { createLogRecorder } from "@logtape/testing/recorder";
 
 const recorder = createLogRecorder();
 
-try {
+before(async () => {
   await configure({
     sinks: {
       recorder: recorder.sink,  // [!code highlight]
@@ -110,7 +111,11 @@ try {
       { category: ["logtape", "meta"], sinks: [] },
     ],
   });
+});
+
+after(reset);
 
+test("case", () => {
   getLogger(["my-lib"]).info("User {userId} logged in.", {
     userId: 123,
   });
@@ -121,9 +126,7 @@ try {
     message: "User 123 logged in.",
     properties: { userId: 123 },
   });
-} finally {
-  await reset();
-}
+});
 ~~~~
 
 The recorder stores records in sink call order.  It snapshots lazy callback
@@ -145,6 +148,81 @@ sinks, still call `await dispose()` or `await reset()` as usual.
 [*@logtape/testing*]: https://jsr.io/@logtape/testing
 
 
+Failure log reporter
+--------------------
+
+*This API is available since LogTape 2.3.0.*
+
+When logs are useful only after a test fails, use
+`createFailureLogReporter()` from the [*@logtape/testing*] package.  It
+buffers records while the wrapped callback runs, discards them when the
+callback succeeds, and reports them to a sink when the callback throws or
+rejects:
+
+~~~~ typescript twoslash
+// @noErrors: 2307
+import { AsyncLocalStorage } from "node:async_hooks";
+import { after, before, test } from "node:test";
+import { configure, getLogger, reset } from "@logtape/logtape";
+import { createFailureLogReporter } from "@logtape/testing/reporter";
+
+const reporter = createFailureLogReporter({
+  lowestLevel: "debug",
+});
+
+before(async () => {
+  await configure({
+    contextLocalStorage: new AsyncLocalStorage(),
+    sinks: {},
+    loggers: [
+      { category: ["logtape", "meta"], sinks: [] },
+    ],
+  });
+});
+
+after(reset);
+
+test("case", reporter.wrap(async () => {
+  getLogger(["my-lib"]).debug("Fixture state: {state}", {
+    state: "ready",
+  });
+
+  // Run assertions.  The debug log is printed only if this callback fails.
+}));
+~~~~
+
+The reporter uses scoped configuration, so it does not call `configure()` or
+`reset()` for each wrapped callback and does not mutate process-wide logger
+routing while a test is running.  The process-wide configuration still must
+provide `~Config.contextLocalStorage`, because scoped configuration needs it to
+isolate the callback's logging policy.
+
+Use `~FailureLogReporter.wrap()` when passing a callback to a test runner.  It
+preserves callback parameters such as a test context or fixtures, and it always
+returns an async callback.  Use `~FailureLogReporter.run()` when you want to
+invoke the callback directly:
+
+~~~~ typescript twoslash
+// @noErrors: 2307
+import { createFailureLogReporter } from "@logtape/testing/reporter";
+
+const reporter = createFailureLogReporter({
+  lowestLevel: "debug",
+  mode: "on-failure",
+});
+
+await reporter.run(async () => {
+  // Logs emitted here are reported only if this callback fails.
+});
+~~~~
+
+Set `mode: "always"` to report buffered records even when the callback passes,
+or `mode: "never"` to suppress reporting while keeping the shared wrapper in
+place.  By default the reporter writes formatted records to the console; pass
+`sink` to report records elsewhere, or `formatter` to customize the default
+console output.
+
+
 Buffer sink
 -----------
 

packages/testing/README.md

@@ -9,7 +9,8 @@ Testing utilities for LogTape
 This package provides testing utilities for [LogTape].  It includes a log
 recorder that collects `LogRecord` values in memory and provides matcher-based
 assertions for category, level, rendered message, raw message, and structured
-properties.
+properties.  It also includes a failure log reporter that buffers records while
+a test callback runs and reports them only when the callback fails.
 
 [JSR badge]: https://jsr.io/badges/@logtape/testing
 [JSR]: https://jsr.io/@logtape/testing
@@ -40,7 +41,7 @@ Use `createLogRecorder()` as a sink in tests:
 
 ~~~~ typescript
 import { configure, getLogger, reset } from "@logtape/logtape";
-import { createLogRecorder } from "@logtape/testing";
+import { createLogRecorder } from "@logtape/testing/recorder";
 
 const recorder = createLogRecorder();
 
@@ -77,6 +78,24 @@ that need lower-level access.  Most property values are compared with
 matcher values match string property values.  Rendered message matching uses
 the same value rendering as LogTape's default text formatter.
 
+Use `createFailureLogReporter()` when logs are useful only after a test fails:
+
+~~~~ typescript
+import { createFailureLogReporter } from "@logtape/testing/reporter";
+
+const reporter = createFailureLogReporter({
+  lowestLevel: "debug",
+});
+
+test("case", reporter.wrap(async () => {
+  // Logs emitted here are reported only if this callback throws.
+}));
+~~~~
+
+The root `@logtape/testing` entry point re-exports both utilities for
+compatibility, but new code can import `@logtape/testing/recorder` or
+`@logtape/testing/reporter` to depend on only the relevant API surface.
+
 
 Docs
 ----

packages/testing/deno.json

@@ -2,7 +2,11 @@
   "name": "@logtape/testing",
   "version": "2.3.0",
   "license": "MIT",
-  "exports": "./src/mod.ts",
+  "exports": {
+    ".": "./src/mod.ts",
+    "./recorder": "./src/recorder.ts",
+    "./reporter": "./src/reporter.ts"
+  },
   "tasks": {
     "build": "pnpm build",
     "test": "deno test",

packages/testing/package.json

@@ -41,6 +41,22 @@
       "import": "./dist/mod.js",
       "require": "./dist/mod.cjs"
     },
+    "./recorder": {
+      "types": {
+        "import": "./dist/recorder.d.ts",
+        "require": "./dist/recorder.d.cts"
+      },
+      "import": "./dist/recorder.js",
+      "require": "./dist/recorder.cjs"
+    },
+    "./reporter": {
+      "types": {
+        "import": "./dist/reporter.d.ts",
+        "require": "./dist/reporter.d.cts"
+      },
+      "import": "./dist/reporter.js",
+      "require": "./dist/reporter.cjs"
+    },
     "./package.json": "./package.json"
   },
   "sideEffects": false,