@logtape/testing 2.3.0-dev.826 → 2.3.0-dev.840

package/README.md

@@ -95,6 +95,9 @@ test("case", reporter.wrap(async () => {
 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.
+Use `getFailureLogReporterOptionsFromEnv()` when an integration needs to parse
+`LOGTAPE_TEST_MODE` and `LOGTAPE_TEST_LOWEST_LEVEL` from a runtime-supplied
+environment variable getter.
 
 
 Docs

package/dist/mod.cjs

@@ -2,4 +2,5 @@ const require_recorder = require('./recorder.cjs');
 const require_reporter = require('./reporter.cjs');
 
 exports.createFailureLogReporter = require_reporter.createFailureLogReporter;
-exports.createLogRecorder = require_recorder.createLogRecorder;
+exports.createLogRecorder = require_recorder.createLogRecorder;
+exports.getFailureLogReporterOptionsFromEnv = require_reporter.getFailureLogReporterOptionsFromEnv;

package/dist/mod.d.cts

@@ -1,3 +1,3 @@
 import { LogRecordMatch, LogRecorder, PropertyMatcher, createLogRecorder } from "./recorder.cjs";
-import { FailureLogReportMode, FailureLogReporter, FailureLogReporterOptions, createFailureLogReporter } from "./reporter.cjs";
-export { FailureLogReportMode, FailureLogReporter, FailureLogReporterOptions, LogRecordMatch, LogRecorder, PropertyMatcher, createFailureLogReporter, createLogRecorder };
+import { FailureLogReportMode, FailureLogReporter, FailureLogReporterEnvOptions, FailureLogReporterOptions, createFailureLogReporter, getFailureLogReporterOptionsFromEnv } from "./reporter.cjs";
+export { FailureLogReportMode, FailureLogReporter, FailureLogReporterEnvOptions, FailureLogReporterOptions, LogRecordMatch, LogRecorder, PropertyMatcher, createFailureLogReporter, createLogRecorder, getFailureLogReporterOptionsFromEnv };

package/dist/mod.d.ts

@@ -1,3 +1,3 @@
 import { LogRecordMatch, LogRecorder, PropertyMatcher, createLogRecorder } from "./recorder.js";
-import { FailureLogReportMode, FailureLogReporter, FailureLogReporterOptions, createFailureLogReporter } from "./reporter.js";
-export { FailureLogReportMode, FailureLogReporter, FailureLogReporterOptions, LogRecordMatch, LogRecorder, PropertyMatcher, createFailureLogReporter, createLogRecorder };
+import { FailureLogReportMode, FailureLogReporter, FailureLogReporterEnvOptions, FailureLogReporterOptions, createFailureLogReporter, getFailureLogReporterOptionsFromEnv } from "./reporter.js";
+export { FailureLogReportMode, FailureLogReporter, FailureLogReporterEnvOptions, FailureLogReporterOptions, LogRecordMatch, LogRecorder, PropertyMatcher, createFailureLogReporter, createLogRecorder, getFailureLogReporterOptionsFromEnv };

package/dist/mod.js

@@ -1,4 +1,4 @@
 import { createLogRecorder } from "./recorder.js";
-import { createFailureLogReporter } from "./reporter.js";
+import { createFailureLogReporter, getFailureLogReporterOptionsFromEnv } from "./reporter.js";
 
-export { createFailureLogReporter, createLogRecorder };
+export { createFailureLogReporter, createLogRecorder, getFailureLogReporterOptionsFromEnv };

package/dist/reporter.cjs

@@ -65,9 +65,39 @@ function createFailureLogReporter(options = {}) {
 		wrap
 	};
 }
+/**
+* Reads failure log reporter options from environment variables.
+*
+* This helper parses `LOGTAPE_TEST_MODE` and `LOGTAPE_TEST_LOWEST_LEVEL` by
+* default.  It does not access the environment directly; pass a runtime
+* specific `getEnv` callback such as `(name) => process.env[name]`.
+*
+* @param options Environment parsing options.
+* @returns Reporter options parsed from the environment.
+* @throws {TypeError} If an environment variable has an invalid value.
+* @since 2.3.0
+*/
+function getFailureLogReporterOptionsFromEnv(options) {
+	const prefix = options.prefix ?? "LOGTAPE_TEST_";
+	const reporterOptions = {};
+	const mode = options.getEnv(`${prefix}MODE`);
+	if (mode != null) reporterOptions.mode = parseFailureLogReportMode(mode);
+	const lowestLevel = options.getEnv(`${prefix}LOWEST_LEVEL`);
+	if (lowestLevel != null) reporterOptions.lowestLevel = (0, __logtape_logtape.parseLogLevel)(lowestLevel.trim());
+	return reporterOptions;
+}
 function flushRecords(records, sink) {
 	for (const record of records) sink(record);
 }
+function parseFailureLogReportMode(mode) {
+	switch (mode.trim().toLowerCase()) {
+		case "on-failure":
+		case "always":
+		case "never": return mode.trim().toLowerCase();
+		default: throw new TypeError(`Invalid failure log report mode: ${mode}.`);
+	}
+}
 
 //#endregion
-exports.createFailureLogReporter = createFailureLogReporter;
+exports.createFailureLogReporter = createFailureLogReporter;
+exports.getFailureLogReporterOptionsFromEnv = getFailureLogReporterOptionsFromEnv;

package/dist/reporter.d.cts

@@ -34,6 +34,24 @@ interface FailureLogReporterOptions {
    */
   readonly formatter?: TextFormatter;
 }
+/**
+ * Options for {@link getFailureLogReporterOptionsFromEnv}.
+ *
+ * @since 2.3.0
+ */
+interface FailureLogReporterEnvOptions {
+  /**
+   * Reads an environment variable by name.
+   *
+   * The caller supplies this function so the shared parser can stay
+   * runtime-agnostic.
+   */
+  readonly getEnv: (name: string) => string | undefined;
+  /**
+   * The environment variable prefix.  Defaults to `"LOGTAPE_TEST_"`.
+   */
+  readonly prefix?: string;
+}
 /**
  * A reporter that buffers LogTape records while a test callback runs and
  * reports them depending on the configured mode.
@@ -82,7 +100,20 @@ interface FailureLogReporter {
  * @since 2.3.0
  */
 declare function createFailureLogReporter(options?: FailureLogReporterOptions): FailureLogReporter;
+/**
+ * Reads failure log reporter options from environment variables.
+ *
+ * This helper parses `LOGTAPE_TEST_MODE` and `LOGTAPE_TEST_LOWEST_LEVEL` by
+ * default.  It does not access the environment directly; pass a runtime
+ * specific `getEnv` callback such as `(name) => process.env[name]`.
+ *
+ * @param options Environment parsing options.
+ * @returns Reporter options parsed from the environment.
+ * @throws {TypeError} If an environment variable has an invalid value.
+ * @since 2.3.0
+ */
+declare function getFailureLogReporterOptionsFromEnv(options: FailureLogReporterEnvOptions): FailureLogReporterOptions;
 //# sourceMappingURL=reporter.d.ts.map
 //#endregion
-export { FailureLogReportMode, FailureLogReporter, FailureLogReporterOptions, createFailureLogReporter };
+export { FailureLogReportMode, FailureLogReporter, FailureLogReporterEnvOptions, FailureLogReporterOptions, createFailureLogReporter, getFailureLogReporterOptionsFromEnv };
 //# sourceMappingURL=reporter.d.cts.map

package/dist/reporter.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"reporter.d.cts","names":[],"sources":["../src/reporter.ts"],"sourcesContent":[],"mappings":";;;;;;AAiBA;AAOA;;;AAUyB,KAjBb,oBAAA,GAiBa,YAAA,GAAA,QAAA,GAAA,OAAA;;;AAWW;AASpC;;AASqB,UAvCJ,yBAAA,CAuCI;EAAK;;;EACT,SAAW,IAAA,CAAA,EApCV,oBAoCU;EAAK;;;;EASK,SAAmB,WAAA,CAAA,EAvChC,QAuCgC;EAAO;;AAAhB;AA0BhD;EAAwC,SAAA,IAAA,CAAA,EA3DtB,IA2DsB;EAAA;;AAEnB;uBAxDE;;;;;;;;UASN,kBAAA;;;;;;;;0EASI,gBAAgB,UAAU,iBACnC,gBAAgB,UAAU,QAAQ,QAAQ;;;;;;;;+BASvB,UAAU,QAAQ,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;iBA0BzC,wBAAA,WACL,4BACR"}
+{"version":3,"file":"reporter.d.cts","names":[],"sources":["../src/reporter.ts"],"sourcesContent":[],"mappings":";;;;;;AAkBA;AAOA;;;AAUyB,KAjBb,oBAAA,GAiBa,YAAA,GAAA,QAAA,GAAA,OAAA;;;AAWW;AAQpC;AAqBA;AAAmC,UAlDlB,yBAAA,CAkDkB;EAAA;;;EASmB,SAC1C,IAAA,CAAA,EAxDM,oBAwDN;EAAK;;;;EAA4B,SASd,WAAA,CAAA,EA3DN,QA2DM;EAAO;;;AAAU;EA0BhC,SAAA,IAAA,CAAA,EA/EE,IA+EF;EAAwB;;;EAEnB,SAAA,SAAA,CAAA,EA5EE,aA4EF;AAsErB;;;;AAE4B;;UA5IX,4BAAA;;;;;;;;;;;;;;;;;;;UAqBA,kBAAA;;;;;;;;0EASI,gBAAgB,UAAU,iBACnC,gBAAgB,UAAU,QAAQ,QAAQ;;;;;;;;+BASvB,UAAU,QAAQ,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;iBA0BzC,wBAAA,WACL,4BACR;;;;;;;;;;;;;iBAsEa,mCAAA,UACL,+BACR"}

package/dist/reporter.d.ts

@@ -34,6 +34,24 @@ interface FailureLogReporterOptions {
    */
   readonly formatter?: TextFormatter;
 }
+/**
+ * Options for {@link getFailureLogReporterOptionsFromEnv}.
+ *
+ * @since 2.3.0
+ */
+interface FailureLogReporterEnvOptions {
+  /**
+   * Reads an environment variable by name.
+   *
+   * The caller supplies this function so the shared parser can stay
+   * runtime-agnostic.
+   */
+  readonly getEnv: (name: string) => string | undefined;
+  /**
+   * The environment variable prefix.  Defaults to `"LOGTAPE_TEST_"`.
+   */
+  readonly prefix?: string;
+}
 /**
  * A reporter that buffers LogTape records while a test callback runs and
  * reports them depending on the configured mode.
@@ -82,7 +100,20 @@ interface FailureLogReporter {
  * @since 2.3.0
  */
 declare function createFailureLogReporter(options?: FailureLogReporterOptions): FailureLogReporter;
+/**
+ * Reads failure log reporter options from environment variables.
+ *
+ * This helper parses `LOGTAPE_TEST_MODE` and `LOGTAPE_TEST_LOWEST_LEVEL` by
+ * default.  It does not access the environment directly; pass a runtime
+ * specific `getEnv` callback such as `(name) => process.env[name]`.
+ *
+ * @param options Environment parsing options.
+ * @returns Reporter options parsed from the environment.
+ * @throws {TypeError} If an environment variable has an invalid value.
+ * @since 2.3.0
+ */
+declare function getFailureLogReporterOptionsFromEnv(options: FailureLogReporterEnvOptions): FailureLogReporterOptions;
 //# sourceMappingURL=reporter.d.ts.map
 //#endregion
-export { FailureLogReportMode, FailureLogReporter, FailureLogReporterOptions, createFailureLogReporter };
+export { FailureLogReportMode, FailureLogReporter, FailureLogReporterEnvOptions, FailureLogReporterOptions, createFailureLogReporter, getFailureLogReporterOptionsFromEnv };
 //# sourceMappingURL=reporter.d.ts.map

package/dist/reporter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reporter.d.ts","names":[],"sources":["../src/reporter.ts"],"sourcesContent":[],"mappings":";;;;;;AAiBA;AAOA;;;AAUyB,KAjBb,oBAAA,GAiBa,YAAA,GAAA,QAAA,GAAA,OAAA;;;AAWW;AASpC;;AASqB,UAvCJ,yBAAA,CAuCI;EAAK;;;EACT,SAAW,IAAA,CAAA,EApCV,oBAoCU;EAAK;;;;EASK,SAAmB,WAAA,CAAA,EAvChC,QAuCgC;EAAO;;AAAhB;AA0BhD;EAAwC,SAAA,IAAA,CAAA,EA3DtB,IA2DsB;EAAA;;AAEnB;uBAxDE;;;;;;;;UASN,kBAAA;;;;;;;;0EASI,gBAAgB,UAAU,iBACnC,gBAAgB,UAAU,QAAQ,QAAQ;;;;;;;;+BASvB,UAAU,QAAQ,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;iBA0BzC,wBAAA,WACL,4BACR"}
+{"version":3,"file":"reporter.d.ts","names":[],"sources":["../src/reporter.ts"],"sourcesContent":[],"mappings":";;;;;;AAkBA;AAOA;;;AAUyB,KAjBb,oBAAA,GAiBa,YAAA,GAAA,QAAA,GAAA,OAAA;;;AAWW;AAQpC;AAqBA;AAAmC,UAlDlB,yBAAA,CAkDkB;EAAA;;;EASmB,SAC1C,IAAA,CAAA,EAxDM,oBAwDN;EAAK;;;;EAA4B,SASd,WAAA,CAAA,EA3DN,QA2DM;EAAO;;;AAAU;EA0BhC,SAAA,IAAA,CAAA,EA/EE,IA+EF;EAAwB;;;EAEnB,SAAA,SAAA,CAAA,EA5EE,aA4EF;AAsErB;;;;AAE4B;;UA5IX,4BAAA;;;;;;;;;;;;;;;;;;;UAqBA,kBAAA;;;;;;;;0EASI,gBAAgB,UAAU,iBACnC,gBAAgB,UAAU,QAAQ,QAAQ;;;;;;;;+BASvB,UAAU,QAAQ,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;iBA0BzC,wBAAA,WACL,4BACR;;;;;;;;;;;;;iBAsEa,mCAAA,UACL,+BACR"}

package/dist/reporter.js

@@ -1,5 +1,5 @@
 import { materializeLogRecord } from "./snapshot.js";
-import { getConsoleSink, withConfig } from "@logtape/logtape";
+import { getConsoleSink, parseLogLevel, withConfig } from "@logtape/logtape";
 
 //#region src/reporter.ts
 /**
@@ -64,10 +64,39 @@ function createFailureLogReporter(options = {}) {
 		wrap
 	};
 }
+/**
+* Reads failure log reporter options from environment variables.
+*
+* This helper parses `LOGTAPE_TEST_MODE` and `LOGTAPE_TEST_LOWEST_LEVEL` by
+* default.  It does not access the environment directly; pass a runtime
+* specific `getEnv` callback such as `(name) => process.env[name]`.
+*
+* @param options Environment parsing options.
+* @returns Reporter options parsed from the environment.
+* @throws {TypeError} If an environment variable has an invalid value.
+* @since 2.3.0
+*/
+function getFailureLogReporterOptionsFromEnv(options) {
+	const prefix = options.prefix ?? "LOGTAPE_TEST_";
+	const reporterOptions = {};
+	const mode = options.getEnv(`${prefix}MODE`);
+	if (mode != null) reporterOptions.mode = parseFailureLogReportMode(mode);
+	const lowestLevel = options.getEnv(`${prefix}LOWEST_LEVEL`);
+	if (lowestLevel != null) reporterOptions.lowestLevel = parseLogLevel(lowestLevel.trim());
+	return reporterOptions;
+}
 function flushRecords(records, sink) {
 	for (const record of records) sink(record);
 }
+function parseFailureLogReportMode(mode) {
+	switch (mode.trim().toLowerCase()) {
+		case "on-failure":
+		case "always":
+		case "never": return mode.trim().toLowerCase();
+		default: throw new TypeError(`Invalid failure log report mode: ${mode}.`);
+	}
+}
 
 //#endregion
-export { createFailureLogReporter };
+export { createFailureLogReporter, getFailureLogReporterOptionsFromEnv };
 //# sourceMappingURL=reporter.js.map

package/dist/reporter.js.map

@@ -1 +1 @@
-{"version":3,"file":"reporter.js","names":["options: FailureLogReporterOptions","callback: () => TResult","records: LogRecord[]","bufferSink: Sink","record: LogRecord","result: Awaited<TResult>","callback: (this: TThis, ...args: TArgs) => TResult","records: readonly LogRecord[]","sink: Sink"],"sources":["../src/reporter.ts"],"sourcesContent":["import {\n  getConsoleSink,\n  type LogLevel,\n  type LogRecord,\n  type Sink,\n  type TextFormatter,\n  withConfig,\n} from \"@logtape/logtape\";\n\nimport { materializeLogRecord } from \"./snapshot.ts\";\n\n/**\n * Controls when buffered records are reported by a\n * {@link FailureLogReporter}.\n *\n * @since 2.3.0\n */\nexport type FailureLogReportMode = \"on-failure\" | \"always\" | \"never\";\n\n/**\n * Options for {@link createFailureLogReporter}.\n *\n * @since 2.3.0\n */\nexport interface FailureLogReporterOptions {\n  /**\n   * When to report buffered records.  Defaults to `\"on-failure\"`.\n   */\n  readonly mode?: FailureLogReportMode;\n\n  /**\n   * The lowest severity level collected by the reporter's scoped\n   * configuration.  Defaults to `\"info\"`.\n   */\n  readonly lowestLevel?: LogLevel;\n\n  /**\n   * The sink that receives buffered records when the reporter flushes.\n   * Defaults to a console sink.\n   */\n  readonly sink?: Sink;\n\n  /**\n   * The text formatter used by the default console sink.\n   */\n  readonly formatter?: TextFormatter;\n}\n\n/**\n * A reporter that buffers LogTape records while a test callback runs and\n * reports them depending on the configured mode.\n *\n * @since 2.3.0\n */\nexport interface FailureLogReporter {\n  /**\n   * Wraps a callback so matching LogTape records are reported according to the\n   * configured mode.\n   *\n   * @param callback The test callback to wrap.\n   * @returns An async callback with the same parameters.\n   */\n  wrap<TThis, TArgs extends readonly unknown[], TResult>(\n    callback: (this: TThis, ...args: TArgs) => TResult,\n  ): (this: TThis, ...args: TArgs) => Promise<Awaited<TResult>>;\n\n  /**\n   * Runs a callback and reports matching LogTape records according to the\n   * configured mode.\n   *\n   * @param callback The callback to run.\n   * @returns The callback result.\n   */\n  run<TResult>(callback: () => TResult): Promise<Awaited<TResult>>;\n}\n\n/**\n * Creates a failure log reporter for tests.\n *\n * The reporter uses LogTape's scoped configuration support.  The process-wide\n * configuration must already include `Config.contextLocalStorage`, but the\n * reporter does not mutate global logger routing while a wrapped callback\n * runs.\n *\n * @example\n * ```ts\n * import { createFailureLogReporter } from \"@logtape/testing/reporter\";\n *\n * const reporter = createFailureLogReporter({ lowestLevel: \"debug\" });\n *\n * test(\"case\", reporter.wrap(async () => {\n *   // Logs emitted here are reported only if this callback throws.\n * }));\n * ```\n *\n * @param options Reporter options.\n * @returns A failure log reporter.\n * @since 2.3.0\n */\nexport function createFailureLogReporter(\n  options: FailureLogReporterOptions = {},\n): FailureLogReporter {\n  const mode = options.mode ?? \"on-failure\";\n  const lowestLevel = options.lowestLevel ?? \"info\";\n  const outputSink = options.sink ?? getConsoleSink({\n    formatter: options.formatter,\n  });\n\n  async function run<TResult>(\n    callback: () => TResult,\n  ): Promise<Awaited<TResult>> {\n    const records: LogRecord[] = [];\n    const bufferSink: Sink = (record: LogRecord): void => {\n      records.push(materializeLogRecord(record));\n    };\n\n    let result: Awaited<TResult>;\n    try {\n      result = await withConfig({\n        sinks: { failureLogReporter: bufferSink },\n        loggers: [{\n          category: [],\n          lowestLevel,\n          parentSinks: \"override\",\n          sinks: [\"failureLogReporter\"],\n        }],\n      }, callback);\n    } catch (error) {\n      if (mode !== \"never\") {\n        try {\n          flushRecords(records, outputSink);\n        } catch {\n          // Keep the test runner focused on the original assertion error.\n        }\n      }\n      throw error;\n    }\n\n    if (mode === \"always\") flushRecords(records, outputSink);\n    return result;\n  }\n\n  function wrap<TThis, TArgs extends readonly unknown[], TResult>(\n    callback: (this: TThis, ...args: TArgs) => TResult,\n  ): (this: TThis, ...args: TArgs) => Promise<Awaited<TResult>> {\n    return function (\n      this: TThis,\n      ...args: TArgs\n    ): Promise<Awaited<TResult>> {\n      return run(() => Reflect.apply(callback, this, args) as TResult);\n    };\n  }\n\n  return {\n    run,\n    wrap,\n  };\n}\n\nfunction flushRecords(\n  records: readonly LogRecord[],\n  sink: Sink,\n): void {\n  for (const record of records) sink(record);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAmGA,SAAgB,yBACdA,UAAqC,CAAE,GACnB;CACpB,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,cAAc,QAAQ,eAAe;CAC3C,MAAM,aAAa,QAAQ,QAAQ,eAAe,EAChD,WAAW,QAAQ,UACpB,EAAC;CAEF,eAAe,IACbC,UAC2B;EAC3B,MAAMC,UAAuB,CAAE;EAC/B,MAAMC,aAAmB,CAACC,WAA4B;AACpD,WAAQ,KAAK,qBAAqB,OAAO,CAAC;EAC3C;EAED,IAAIC;AACJ,MAAI;AACF,YAAS,MAAM,WAAW;IACxB,OAAO,EAAE,oBAAoB,WAAY;IACzC,SAAS,CAAC;KACR,UAAU,CAAE;KACZ;KACA,aAAa;KACb,OAAO,CAAC,oBAAqB;IAC9B,CAAC;GACH,GAAE,SAAS;EACb,SAAQ,OAAO;AACd,OAAI,SAAS,QACX,KAAI;AACF,iBAAa,SAAS,WAAW;GAClC,QAAO,CAEP;AAEH,SAAM;EACP;AAED,MAAI,SAAS,SAAU,cAAa,SAAS,WAAW;AACxD,SAAO;CACR;CAED,SAAS,KACPC,UAC4D;AAC5D,SAAO,SAEL,GAAG,MACwB;AAC3B,UAAO,IAAI,MAAM,QAAQ,MAAM,UAAU,MAAM,KAAK,CAAY;EACjE;CACF;AAED,QAAO;EACL;EACA;CACD;AACF;AAED,SAAS,aACPC,SACAC,MACM;AACN,MAAK,MAAM,UAAU,QAAS,MAAK,OAAO;AAC3C"}
+{"version":3,"file":"reporter.js","names":["options: FailureLogReporterOptions","callback: () => TResult","records: LogRecord[]","bufferSink: Sink","record: LogRecord","result: Awaited<TResult>","callback: (this: TThis, ...args: TArgs) => TResult","options: FailureLogReporterEnvOptions","reporterOptions: {\n    mode?: FailureLogReportMode;\n    lowestLevel?: LogLevel;\n  }","records: readonly LogRecord[]","sink: Sink","mode: string"],"sources":["../src/reporter.ts"],"sourcesContent":["import {\n  getConsoleSink,\n  type LogLevel,\n  type LogRecord,\n  parseLogLevel,\n  type Sink,\n  type TextFormatter,\n  withConfig,\n} from \"@logtape/logtape\";\n\nimport { materializeLogRecord } from \"./snapshot.ts\";\n\n/**\n * Controls when buffered records are reported by a\n * {@link FailureLogReporter}.\n *\n * @since 2.3.0\n */\nexport type FailureLogReportMode = \"on-failure\" | \"always\" | \"never\";\n\n/**\n * Options for {@link createFailureLogReporter}.\n *\n * @since 2.3.0\n */\nexport interface FailureLogReporterOptions {\n  /**\n   * When to report buffered records.  Defaults to `\"on-failure\"`.\n   */\n  readonly mode?: FailureLogReportMode;\n\n  /**\n   * The lowest severity level collected by the reporter's scoped\n   * configuration.  Defaults to `\"info\"`.\n   */\n  readonly lowestLevel?: LogLevel;\n\n  /**\n   * The sink that receives buffered records when the reporter flushes.\n   * Defaults to a console sink.\n   */\n  readonly sink?: Sink;\n\n  /**\n   * The text formatter used by the default console sink.\n   */\n  readonly formatter?: TextFormatter;\n}\n\n/**\n * Options for {@link getFailureLogReporterOptionsFromEnv}.\n *\n * @since 2.3.0\n */\nexport interface FailureLogReporterEnvOptions {\n  /**\n   * Reads an environment variable by name.\n   *\n   * The caller supplies this function so the shared parser can stay\n   * runtime-agnostic.\n   */\n  readonly getEnv: (name: string) => string | undefined;\n\n  /**\n   * The environment variable prefix.  Defaults to `\"LOGTAPE_TEST_\"`.\n   */\n  readonly prefix?: string;\n}\n\n/**\n * A reporter that buffers LogTape records while a test callback runs and\n * reports them depending on the configured mode.\n *\n * @since 2.3.0\n */\nexport interface FailureLogReporter {\n  /**\n   * Wraps a callback so matching LogTape records are reported according to the\n   * configured mode.\n   *\n   * @param callback The test callback to wrap.\n   * @returns An async callback with the same parameters.\n   */\n  wrap<TThis, TArgs extends readonly unknown[], TResult>(\n    callback: (this: TThis, ...args: TArgs) => TResult,\n  ): (this: TThis, ...args: TArgs) => Promise<Awaited<TResult>>;\n\n  /**\n   * Runs a callback and reports matching LogTape records according to the\n   * configured mode.\n   *\n   * @param callback The callback to run.\n   * @returns The callback result.\n   */\n  run<TResult>(callback: () => TResult): Promise<Awaited<TResult>>;\n}\n\n/**\n * Creates a failure log reporter for tests.\n *\n * The reporter uses LogTape's scoped configuration support.  The process-wide\n * configuration must already include `Config.contextLocalStorage`, but the\n * reporter does not mutate global logger routing while a wrapped callback\n * runs.\n *\n * @example\n * ```ts\n * import { createFailureLogReporter } from \"@logtape/testing/reporter\";\n *\n * const reporter = createFailureLogReporter({ lowestLevel: \"debug\" });\n *\n * test(\"case\", reporter.wrap(async () => {\n *   // Logs emitted here are reported only if this callback throws.\n * }));\n * ```\n *\n * @param options Reporter options.\n * @returns A failure log reporter.\n * @since 2.3.0\n */\nexport function createFailureLogReporter(\n  options: FailureLogReporterOptions = {},\n): FailureLogReporter {\n  const mode = options.mode ?? \"on-failure\";\n  const lowestLevel = options.lowestLevel ?? \"info\";\n  const outputSink = options.sink ?? getConsoleSink({\n    formatter: options.formatter,\n  });\n\n  async function run<TResult>(\n    callback: () => TResult,\n  ): Promise<Awaited<TResult>> {\n    const records: LogRecord[] = [];\n    const bufferSink: Sink = (record: LogRecord): void => {\n      records.push(materializeLogRecord(record));\n    };\n\n    let result: Awaited<TResult>;\n    try {\n      result = await withConfig({\n        sinks: { failureLogReporter: bufferSink },\n        loggers: [{\n          category: [],\n          lowestLevel,\n          parentSinks: \"override\",\n          sinks: [\"failureLogReporter\"],\n        }],\n      }, callback);\n    } catch (error) {\n      if (mode !== \"never\") {\n        try {\n          flushRecords(records, outputSink);\n        } catch {\n          // Keep the test runner focused on the original assertion error.\n        }\n      }\n      throw error;\n    }\n\n    if (mode === \"always\") flushRecords(records, outputSink);\n    return result;\n  }\n\n  function wrap<TThis, TArgs extends readonly unknown[], TResult>(\n    callback: (this: TThis, ...args: TArgs) => TResult,\n  ): (this: TThis, ...args: TArgs) => Promise<Awaited<TResult>> {\n    return function (\n      this: TThis,\n      ...args: TArgs\n    ): Promise<Awaited<TResult>> {\n      return run(() => Reflect.apply(callback, this, args) as TResult);\n    };\n  }\n\n  return {\n    run,\n    wrap,\n  };\n}\n\n/**\n * Reads failure log reporter options from environment variables.\n *\n * This helper parses `LOGTAPE_TEST_MODE` and `LOGTAPE_TEST_LOWEST_LEVEL` by\n * default.  It does not access the environment directly; pass a runtime\n * specific `getEnv` callback such as `(name) => process.env[name]`.\n *\n * @param options Environment parsing options.\n * @returns Reporter options parsed from the environment.\n * @throws {TypeError} If an environment variable has an invalid value.\n * @since 2.3.0\n */\nexport function getFailureLogReporterOptionsFromEnv(\n  options: FailureLogReporterEnvOptions,\n): FailureLogReporterOptions {\n  const prefix = options.prefix ?? \"LOGTAPE_TEST_\";\n  const reporterOptions: {\n    mode?: FailureLogReportMode;\n    lowestLevel?: LogLevel;\n  } = {};\n  const mode = options.getEnv(`${prefix}MODE`);\n  if (mode != null) {\n    reporterOptions.mode = parseFailureLogReportMode(mode);\n  }\n  const lowestLevel = options.getEnv(`${prefix}LOWEST_LEVEL`);\n  if (lowestLevel != null) {\n    reporterOptions.lowestLevel = parseLogLevel(lowestLevel.trim());\n  }\n  return reporterOptions;\n}\n\nfunction flushRecords(\n  records: readonly LogRecord[],\n  sink: Sink,\n): void {\n  for (const record of records) sink(record);\n}\n\nfunction parseFailureLogReportMode(mode: string): FailureLogReportMode {\n  switch (mode.trim().toLowerCase()) {\n    case \"on-failure\":\n    case \"always\":\n    case \"never\":\n      return mode.trim().toLowerCase() as FailureLogReportMode;\n    default:\n      throw new TypeError(`Invalid failure log report mode: ${mode}.`);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAwHA,SAAgB,yBACdA,UAAqC,CAAE,GACnB;CACpB,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,cAAc,QAAQ,eAAe;CAC3C,MAAM,aAAa,QAAQ,QAAQ,eAAe,EAChD,WAAW,QAAQ,UACpB,EAAC;CAEF,eAAe,IACbC,UAC2B;EAC3B,MAAMC,UAAuB,CAAE;EAC/B,MAAMC,aAAmB,CAACC,WAA4B;AACpD,WAAQ,KAAK,qBAAqB,OAAO,CAAC;EAC3C;EAED,IAAIC;AACJ,MAAI;AACF,YAAS,MAAM,WAAW;IACxB,OAAO,EAAE,oBAAoB,WAAY;IACzC,SAAS,CAAC;KACR,UAAU,CAAE;KACZ;KACA,aAAa;KACb,OAAO,CAAC,oBAAqB;IAC9B,CAAC;GACH,GAAE,SAAS;EACb,SAAQ,OAAO;AACd,OAAI,SAAS,QACX,KAAI;AACF,iBAAa,SAAS,WAAW;GAClC,QAAO,CAEP;AAEH,SAAM;EACP;AAED,MAAI,SAAS,SAAU,cAAa,SAAS,WAAW;AACxD,SAAO;CACR;CAED,SAAS,KACPC,UAC4D;AAC5D,SAAO,SAEL,GAAG,MACwB;AAC3B,UAAO,IAAI,MAAM,QAAQ,MAAM,UAAU,MAAM,KAAK,CAAY;EACjE;CACF;AAED,QAAO;EACL;EACA;CACD;AACF;;;;;;;;;;;;;AAcD,SAAgB,oCACdC,SAC2B;CAC3B,MAAM,SAAS,QAAQ,UAAU;CACjC,MAAMC,kBAGF,CAAE;CACN,MAAM,OAAO,QAAQ,QAAQ,EAAE,OAAO,MAAM;AAC5C,KAAI,QAAQ,KACV,iBAAgB,OAAO,0BAA0B,KAAK;CAExD,MAAM,cAAc,QAAQ,QAAQ,EAAE,OAAO,cAAc;AAC3D,KAAI,eAAe,KACjB,iBAAgB,cAAc,cAAc,YAAY,MAAM,CAAC;AAEjE,QAAO;AACR;AAED,SAAS,aACPC,SACAC,MACM;AACN,MAAK,MAAM,UAAU,QAAS,MAAK,OAAO;AAC3C;AAED,SAAS,0BAA0BC,MAAoC;AACrE,SAAQ,KAAK,MAAM,CAAC,aAAa,EAAjC;EACE,KAAK;EACL,KAAK;EACL,KAAK,QACH,QAAO,KAAK,MAAM,CAAC,aAAa;EAClC,QACE,OAAM,IAAI,WAAW,mCAAmC,KAAK;CAChE;AACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logtape/testing",
-  "version": "2.3.0-dev.826+d87464f0",
+  "version": "2.3.0-dev.840+34e837bf",
   "description": "Testing utilities for collecting and asserting LogTape records",
   "keywords": [
     "logging",
@@ -64,12 +64,12 @@
     "dist/"
   ],
   "peerDependencies": {
-    "@logtape/logtape": "^2.3.0-dev.826+d87464f0"
+    "@logtape/logtape": "^2.3.0-dev.840+34e837bf"
   },
   "devDependencies": {
     "tsdown": "^0.12.7",
     "typescript": "^5.8.3",
-    "@logtape/redaction": "^2.3.0-dev.826+d87464f0"
+    "@logtape/redaction": "^2.3.0-dev.840+34e837bf"
   },
   "scripts": {
     "build": "tsdown",