@cappa/core 0.13.2 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1,8 +1,32 @@
1
1
  import { ChangeRegion, InterpretResult, InterpretResult as InterpretResult$1 } from "@blazediff/interpret-native";
2
2
  import "@blazediff/gmsd";
3
- import { Browser, BrowserContext, Locator, Page } from "playwright-core";
3
+ import { Browser, BrowserContext, ConsoleMessage, Locator, Page } from "playwright-core";
4
4
  import { Logger } from "@cappa/logger";
5
5
  import "@blazediff/core-native";
6
+ //#region src/consoleEvents.d.ts
7
+ /**
8
+ * Minimum severity of browser console output to forward, ordered from most
9
+ * to least severe. Browser `console.warn` is reported by Playwright as
10
+ * `warning`; it maps to `"warn"` here.
11
+ */
12
+ type ConsoleLogLevel = "error" | "warn" | "info" | "log" | "debug";
13
+ /**
14
+ * `true` forwards every console message at the logger's debug level (the
15
+ * historical behaviour), `false` forwards none, and a {@link ConsoleLogLevel}
16
+ * forwards messages at or above that severity at their matching logger level.
17
+ */
18
+ type LogConsoleEvents = boolean | ConsoleLogLevel;
19
+ export declare const CONSOLE_LOG_LEVELS: readonly ConsoleLogLevel[];
20
+ type ConsoleEventLogger = Record<ConsoleLogLevel, (message: any, ...args: any[]) => void>;
21
+ /** Maps a Playwright `ConsoleMessage.type()` onto a {@link ConsoleLogLevel}. */
22
+ export declare const toConsoleLogLevel: (type: ReturnType<ConsoleMessage["type"]> | string) => ConsoleLogLevel;
23
+ /**
24
+ * Wires a page's `console` and `pageerror` events to `logger` according to
25
+ * `setting`. Uncaught page errors are always forwarded — at error level when
26
+ * a severity threshold is set, at debug level otherwise.
27
+ */
28
+ export declare const attachConsoleLogging: (page: Pick<Page, "on">, setting: LogConsoleEvents | undefined, logger: ConsoleEventLogger) => void;
29
+ //#endregion
6
30
  //#region src/compare/pixel.d.ts
7
31
  interface CompareResult$1 {
8
32
  numDiffPixels: number;
@@ -469,7 +493,7 @@ declare class ScreenshotTool {
469
493
  logger: ScreenshotLogger;
470
494
  retries: number;
471
495
  filesystem: ScreenshotFileSystem;
472
- logConsoleEvents: boolean;
496
+ logConsoleEvents: LogConsoleEvents;
473
497
  connectionTimeout: number;
474
498
  private defaultUserAgent;
475
499
  /** The real logger, kept so `setLogSink(null)` restores the same instance. */
@@ -488,7 +512,7 @@ declare class ScreenshotTool {
488
512
  diff?: DiffOptions;
489
513
  retries?: number;
490
514
  concurrency?: number;
491
- logConsoleEvents?: boolean;
515
+ logConsoleEvents?: LogConsoleEvents;
492
516
  connectionTimeout?: number;
493
517
  });
494
518
  /**
@@ -813,12 +837,17 @@ type UserConfig = {
813
837
  */
814
838
  concurrency?: number;
815
839
  /**
816
- * Whether to log Playwright console events while executing capture tasks.
840
+ * Which browser console events to log while executing capture tasks.
841
+ *
842
+ * - `true` (default): every console message, at the logger's debug level
843
+ * - `false`: none
844
+ * - `"error" | "warn" | "info" | "log" | "debug"`: only messages at or above
845
+ * that severity, logged at their matching level (so `"error"` surfaces
846
+ * browser errors without `--log-level` tweaks)
817
847
  *
818
- * Enabled by default to aid in debugging. Disable to reduce noise in the
819
- * console output when you do not need the additional details.
848
+ * Uncaught page errors are always logged.
820
849
  */
821
- logConsoleEvents?: boolean;
850
+ logConsoleEvents?: LogConsoleEvents;
822
851
  /**
823
852
  * Timeout in milliseconds for network connections (e.g. fetching stories,
824
853
  * navigating to pages). If a connection does not respond within this time,
@@ -1525,7 +1554,7 @@ type LocalEngineOptions = {
1525
1554
  diff?: DiffOptions;
1526
1555
  retries?: number;
1527
1556
  concurrency?: number;
1528
- logConsoleEvents?: boolean;
1557
+ logConsoleEvents?: LogConsoleEvents;
1529
1558
  fullPage?: boolean;
1530
1559
  viewport?: Viewport;
1531
1560
  connectionTimeout?: number;
@@ -1879,5 +1908,5 @@ export declare class FsScreenshotStore implements ScreenshotStore {
1879
1908
  writeMeta(key: string, meta: DiffMetadata): Promise<void>;
1880
1909
  }
1881
1910
  //#endregion
1882
- export { type ApproveResult, type CaptureEngine, type CaptureManifest, type CaptureRunnerOptions, type ChangeRegion, type ChangedScreenshot, type ConfigEnv, type CreateFileWatcher, type DeletedScreenshot, type DiffConfig, type DiffConfigGMSD, type DiffMetadata, type DiffOptions, type DiffOptionsGMSD, type DiffOptionsPixel, type EmittableWatchEvent, type FailedScreenshot, type FileWatcher, type InterpretResult, type ListTargetsOptions, type LocalEngineOptions, type NewScreenshot, type PassedScreenshot, type Plugin, type PluginCaptureResult, type PluginDef, type PluginFunction, type PluginInfo, type PluginTask, type PluginWatch, type PluginWatchResolve, type RunDetail, type RunEvent, type RunEventListener, type RunEventType, type RunLogLevel, type RunState, type RunStoreOptions, type RunSummary, type RunTrigger, type RunnablePlugin, type Screenshot, type ScreenshotBucket, type ScreenshotCaptureDetails, type ScreenshotCaptureExtras, type ScreenshotCaptureResult, type ScreenshotCaptureSink, type ScreenshotOptions, type ScreenshotOrigin, type ScreenshotQuery, type ScreenshotSettings, type ScreenshotStore, ScreenshotTool, type ScreenshotVariant, type ScreenshotVariantCaptureDetails, type ScreenshotVariantWithUrl, type SerializedError, type StartRunRequest, type StartWatchRequest, type SubscribeOptions, type Target, type TaskFailure, type TaskRecord, type TaskStatus, type UserConfig, type Viewport, type WarmBrowserOptions, type WatchChange, type WatchEvent, type WatchEventType, type WatchScope, type WatchSessionOptions, type WatchStatus };
1911
+ export { type ApproveResult, type CaptureEngine, type CaptureManifest, type CaptureRunnerOptions, type ChangeRegion, type ChangedScreenshot, type ConfigEnv, type ConsoleLogLevel, type CreateFileWatcher, type DeletedScreenshot, type DiffConfig, type DiffConfigGMSD, type DiffMetadata, type DiffOptions, type DiffOptionsGMSD, type DiffOptionsPixel, type EmittableWatchEvent, type FailedScreenshot, type FileWatcher, type InterpretResult, type ListTargetsOptions, type LocalEngineOptions, type LogConsoleEvents, type NewScreenshot, type PassedScreenshot, type Plugin, type PluginCaptureResult, type PluginDef, type PluginFunction, type PluginInfo, type PluginTask, type PluginWatch, type PluginWatchResolve, type RunDetail, type RunEvent, type RunEventListener, type RunEventType, type RunLogLevel, type RunState, type RunStoreOptions, type RunSummary, type RunTrigger, type RunnablePlugin, type Screenshot, type ScreenshotBucket, type ScreenshotCaptureDetails, type ScreenshotCaptureExtras, type ScreenshotCaptureResult, type ScreenshotCaptureSink, type ScreenshotOptions, type ScreenshotOrigin, type ScreenshotQuery, type ScreenshotSettings, type ScreenshotStore, ScreenshotTool, type ScreenshotVariant, type ScreenshotVariantCaptureDetails, type ScreenshotVariantWithUrl, type SerializedError, type StartRunRequest, type StartWatchRequest, type SubscribeOptions, type Target, type TaskFailure, type TaskRecord, type TaskStatus, type UserConfig, type Viewport, type WarmBrowserOptions, type WatchChange, type WatchEvent, type WatchEventType, type WatchScope, type WatchSessionOptions, type WatchStatus };
1883
1912
  //# sourceMappingURL=index.d.cts.map
package/dist/index.d.mts CHANGED
@@ -2,7 +2,31 @@ import "@blazediff/gmsd";
2
2
  import { Logger } from "@cappa/logger";
3
3
  import "@blazediff/core-native";
4
4
  import { ChangeRegion, InterpretResult, InterpretResult as InterpretResult$1 } from "@blazediff/interpret-native";
5
- import { Browser, BrowserContext, Locator, Page } from "playwright-core";
5
+ import { Browser, BrowserContext, ConsoleMessage, Locator, Page } from "playwright-core";
6
+ //#region src/consoleEvents.d.ts
7
+ /**
8
+ * Minimum severity of browser console output to forward, ordered from most
9
+ * to least severe. Browser `console.warn` is reported by Playwright as
10
+ * `warning`; it maps to `"warn"` here.
11
+ */
12
+ type ConsoleLogLevel = "error" | "warn" | "info" | "log" | "debug";
13
+ /**
14
+ * `true` forwards every console message at the logger's debug level (the
15
+ * historical behaviour), `false` forwards none, and a {@link ConsoleLogLevel}
16
+ * forwards messages at or above that severity at their matching logger level.
17
+ */
18
+ type LogConsoleEvents = boolean | ConsoleLogLevel;
19
+ export declare const CONSOLE_LOG_LEVELS: readonly ConsoleLogLevel[];
20
+ type ConsoleEventLogger = Record<ConsoleLogLevel, (message: any, ...args: any[]) => void>;
21
+ /** Maps a Playwright `ConsoleMessage.type()` onto a {@link ConsoleLogLevel}. */
22
+ export declare const toConsoleLogLevel: (type: ReturnType<ConsoleMessage["type"]> | string) => ConsoleLogLevel;
23
+ /**
24
+ * Wires a page's `console` and `pageerror` events to `logger` according to
25
+ * `setting`. Uncaught page errors are always forwarded — at error level when
26
+ * a severity threshold is set, at debug level otherwise.
27
+ */
28
+ export declare const attachConsoleLogging: (page: Pick<Page, "on">, setting: LogConsoleEvents | undefined, logger: ConsoleEventLogger) => void;
29
+ //#endregion
6
30
  //#region src/compare/pixel.d.ts
7
31
  interface CompareResult$1 {
8
32
  numDiffPixels: number;
@@ -469,7 +493,7 @@ declare class ScreenshotTool {
469
493
  logger: ScreenshotLogger;
470
494
  retries: number;
471
495
  filesystem: ScreenshotFileSystem;
472
- logConsoleEvents: boolean;
496
+ logConsoleEvents: LogConsoleEvents;
473
497
  connectionTimeout: number;
474
498
  private defaultUserAgent;
475
499
  /** The real logger, kept so `setLogSink(null)` restores the same instance. */
@@ -488,7 +512,7 @@ declare class ScreenshotTool {
488
512
  diff?: DiffOptions;
489
513
  retries?: number;
490
514
  concurrency?: number;
491
- logConsoleEvents?: boolean;
515
+ logConsoleEvents?: LogConsoleEvents;
492
516
  connectionTimeout?: number;
493
517
  });
494
518
  /**
@@ -813,12 +837,17 @@ type UserConfig = {
813
837
  */
814
838
  concurrency?: number;
815
839
  /**
816
- * Whether to log Playwright console events while executing capture tasks.
840
+ * Which browser console events to log while executing capture tasks.
841
+ *
842
+ * - `true` (default): every console message, at the logger's debug level
843
+ * - `false`: none
844
+ * - `"error" | "warn" | "info" | "log" | "debug"`: only messages at or above
845
+ * that severity, logged at their matching level (so `"error"` surfaces
846
+ * browser errors without `--log-level` tweaks)
817
847
  *
818
- * Enabled by default to aid in debugging. Disable to reduce noise in the
819
- * console output when you do not need the additional details.
848
+ * Uncaught page errors are always logged.
820
849
  */
821
- logConsoleEvents?: boolean;
850
+ logConsoleEvents?: LogConsoleEvents;
822
851
  /**
823
852
  * Timeout in milliseconds for network connections (e.g. fetching stories,
824
853
  * navigating to pages). If a connection does not respond within this time,
@@ -1525,7 +1554,7 @@ type LocalEngineOptions = {
1525
1554
  diff?: DiffOptions;
1526
1555
  retries?: number;
1527
1556
  concurrency?: number;
1528
- logConsoleEvents?: boolean;
1557
+ logConsoleEvents?: LogConsoleEvents;
1529
1558
  fullPage?: boolean;
1530
1559
  viewport?: Viewport;
1531
1560
  connectionTimeout?: number;
@@ -1879,5 +1908,5 @@ export declare class FsScreenshotStore implements ScreenshotStore {
1879
1908
  writeMeta(key: string, meta: DiffMetadata): Promise<void>;
1880
1909
  }
1881
1910
  //#endregion
1882
- export { type ApproveResult, type CaptureEngine, type CaptureManifest, type CaptureRunnerOptions, type ChangeRegion, type ChangedScreenshot, type ConfigEnv, type CreateFileWatcher, type DeletedScreenshot, type DiffConfig, type DiffConfigGMSD, type DiffMetadata, type DiffOptions, type DiffOptionsGMSD, type DiffOptionsPixel, type EmittableWatchEvent, type FailedScreenshot, type FileWatcher, type InterpretResult, type ListTargetsOptions, type LocalEngineOptions, type NewScreenshot, type PassedScreenshot, type Plugin, type PluginCaptureResult, type PluginDef, type PluginFunction, type PluginInfo, type PluginTask, type PluginWatch, type PluginWatchResolve, type RunDetail, type RunEvent, type RunEventListener, type RunEventType, type RunLogLevel, type RunState, type RunStoreOptions, type RunSummary, type RunTrigger, type RunnablePlugin, type Screenshot, type ScreenshotBucket, type ScreenshotCaptureDetails, type ScreenshotCaptureExtras, type ScreenshotCaptureResult, type ScreenshotCaptureSink, type ScreenshotOptions, type ScreenshotOrigin, type ScreenshotQuery, type ScreenshotSettings, type ScreenshotStore, ScreenshotTool, type ScreenshotVariant, type ScreenshotVariantCaptureDetails, type ScreenshotVariantWithUrl, type SerializedError, type StartRunRequest, type StartWatchRequest, type SubscribeOptions, type Target, type TaskFailure, type TaskRecord, type TaskStatus, type UserConfig, type Viewport, type WarmBrowserOptions, type WatchChange, type WatchEvent, type WatchEventType, type WatchScope, type WatchSessionOptions, type WatchStatus };
1911
+ export { type ApproveResult, type CaptureEngine, type CaptureManifest, type CaptureRunnerOptions, type ChangeRegion, type ChangedScreenshot, type ConfigEnv, type ConsoleLogLevel, type CreateFileWatcher, type DeletedScreenshot, type DiffConfig, type DiffConfigGMSD, type DiffMetadata, type DiffOptions, type DiffOptionsGMSD, type DiffOptionsPixel, type EmittableWatchEvent, type FailedScreenshot, type FileWatcher, type InterpretResult, type ListTargetsOptions, type LocalEngineOptions, type LogConsoleEvents, type NewScreenshot, type PassedScreenshot, type Plugin, type PluginCaptureResult, type PluginDef, type PluginFunction, type PluginInfo, type PluginTask, type PluginWatch, type PluginWatchResolve, type RunDetail, type RunEvent, type RunEventListener, type RunEventType, type RunLogLevel, type RunState, type RunStoreOptions, type RunSummary, type RunTrigger, type RunnablePlugin, type Screenshot, type ScreenshotBucket, type ScreenshotCaptureDetails, type ScreenshotCaptureExtras, type ScreenshotCaptureResult, type ScreenshotCaptureSink, type ScreenshotOptions, type ScreenshotOrigin, type ScreenshotQuery, type ScreenshotSettings, type ScreenshotStore, ScreenshotTool, type ScreenshotVariant, type ScreenshotVariantCaptureDetails, type ScreenshotVariantWithUrl, type SerializedError, type StartRunRequest, type StartWatchRequest, type SubscribeOptions, type Target, type TaskFailure, type TaskRecord, type TaskStatus, type UserConfig, type Viewport, type WarmBrowserOptions, type WatchChange, type WatchEvent, type WatchEventType, type WatchScope, type WatchSessionOptions, type WatchStatus };
1883
1912
  //# sourceMappingURL=index.d.mts.map
package/dist/index.mjs CHANGED
@@ -456,6 +456,48 @@ function defineConfig(options) {
456
456
  return options;
457
457
  }
458
458
  //#endregion
459
+ //#region src/consoleEvents.ts
460
+ const CONSOLE_LOG_LEVELS = [
461
+ "error",
462
+ "warn",
463
+ "info",
464
+ "log",
465
+ "debug"
466
+ ];
467
+ /** Maps a Playwright `ConsoleMessage.type()` onto a {@link ConsoleLogLevel}. */
468
+ const toConsoleLogLevel = (type) => {
469
+ switch (type) {
470
+ case "error":
471
+ case "assert": return "error";
472
+ case "warning": return "warn";
473
+ case "info": return "info";
474
+ case "debug":
475
+ case "trace": return "debug";
476
+ default: return "log";
477
+ }
478
+ };
479
+ const severity = (level) => CONSOLE_LOG_LEVELS.indexOf(level);
480
+ /**
481
+ * Wires a page's `console` and `pageerror` events to `logger` according to
482
+ * `setting`. Uncaught page errors are always forwarded — at error level when
483
+ * a severity threshold is set, at debug level otherwise.
484
+ */
485
+ const attachConsoleLogging = (page, setting, logger) => {
486
+ const threshold = setting ?? true;
487
+ if (threshold === true) page.on("console", (message) => {
488
+ logger.debug("console", message.text());
489
+ });
490
+ else if (threshold !== false) page.on("console", (message) => {
491
+ const level = toConsoleLogLevel(message.type());
492
+ if (severity(level) > severity(threshold)) return;
493
+ logger[level](`[browser ${level}]`, message.text());
494
+ });
495
+ page.on("pageerror", (error) => {
496
+ if (typeof threshold === "string") logger.error("[browser pageerror]", error);
497
+ else logger.debug("pageerror", error);
498
+ });
499
+ };
500
+ //#endregion
459
501
  //#region src/mapWithConcurrency.ts
460
502
  /**
461
503
  * Run async work over `items` with at most `concurrency` tasks in flight.
@@ -3114,6 +3156,6 @@ var FsScreenshotStore = class {
3114
3156
  }
3115
3157
  };
3116
3158
  //#endregion
3117
- export { CaptureRunner, DEFAULT_DEBOUNCE_MS, DEFAULT_IGNORED_DIRS, DEFAULT_MAX_TASKS, ENGINE_ERROR_CODES, FsScreenshotStore, LocalEngine, MANIFEST_FILENAME, MANIFEST_VERSION, RunInProgressError, RunStore, ScreenshotFileSystem, ScreenshotTool, UnknownTargetsError, WarmBrowser, WatchInProgressError, WatchSession, collectScreenshots, compareImages, compareImagesGMSD, defineConfig, didScreenshotFail, filterTasks, getDeletedScreenshots, groupScreenshots, imagesMatch, imagesMatchGMSD, isRunInProgressError, isUnknownTargetsError, isWatchInProgressError, mapWithConcurrency, mergeCaptureManifest, readCaptureManifest, readDiffMeta, recordCaptureOrigins, sanitizeScreenshotFilename, selectTasks, toDiffMetaPath, toManifestKey, toSerializedError, toTaskStatus };
3159
+ export { CONSOLE_LOG_LEVELS, CaptureRunner, DEFAULT_DEBOUNCE_MS, DEFAULT_IGNORED_DIRS, DEFAULT_MAX_TASKS, ENGINE_ERROR_CODES, FsScreenshotStore, LocalEngine, MANIFEST_FILENAME, MANIFEST_VERSION, RunInProgressError, RunStore, ScreenshotFileSystem, ScreenshotTool, UnknownTargetsError, WarmBrowser, WatchInProgressError, WatchSession, attachConsoleLogging, collectScreenshots, compareImages, compareImagesGMSD, defineConfig, didScreenshotFail, filterTasks, getDeletedScreenshots, groupScreenshots, imagesMatch, imagesMatchGMSD, isRunInProgressError, isUnknownTargetsError, isWatchInProgressError, mapWithConcurrency, mergeCaptureManifest, readCaptureManifest, readDiffMeta, recordCaptureOrigins, sanitizeScreenshotFilename, selectTasks, toConsoleLogLevel, toDiffMetaPath, toManifestKey, toSerializedError, toTaskStatus };
3118
3160
 
3119
3161
  //# sourceMappingURL=index.mjs.map