fix: readme & tests

Author: Dobrunia

packages/javascript/README.md

@@ -253,7 +253,7 @@ Freeze detectors use two complementary APIs:
 - **Long Tasks API** — browser reports tasks taking longer than 50 ms.
 - **Long Animation Frames (LoAF)** — browser reports frames taking longer than 50 ms with richer script attribution (Chrome 123+, Edge 123+).
 
-Both freeze detectors are enabled by default. If one API is unsupported, the other still works.
+Both freeze detectors are disabled by default. If enabled and one API is unsupported, the other still works.
 Each detected freeze is reported immediately with detailed context (duration, blocking time, scripts involved, etc.).
 `thresholdMs` is an additional Hawk filter on top of browser reporting. Hawk emits an issue when measured duration is equal to or greater than this value. Values below `50ms` are clamped to `50ms`.
 
@@ -308,8 +308,8 @@ const hawk = new HawkCatcher({
 |--------|------|---------|-------------|
 | `errors` | `boolean` | `true` | Enable global errors handling (`window.onerror` and `unhandledrejection`). |
 | `webVitals` | `boolean` | `false` | Collect all Core Web Vitals and send one issue event when at least one metric is rated `poor`. Requires optional `web-vitals` dependency. |
-| `longTasks` | `false` or `{ thresholdMs?: number }` | `{ thresholdMs: 70 }` | Detect long tasks and emit issue events when duration is equal to or greater than the max allowed duration (`thresholdMs`, minimum effective value is `50ms`). |
-| `longAnimationFrames` | `false` or `{ thresholdMs?: number }` | `{ thresholdMs: 200 }` | Detect LoAF events and emit issue events when duration is equal to or greater than the max allowed duration (`thresholdMs`, minimum effective value is `50ms`). Requires Chrome 123+ / Edge 123+. |
+| `longTasks` | `boolean` or `{ thresholdMs?: number }` | `false` | `false` disables. `true` enables with default threshold. Object enables and uses `thresholdMs` when valid; otherwise fallback threshold `70ms` is used (minimum effective value `50ms`). |
+| `longAnimationFrames` | `boolean` or `{ thresholdMs?: number }` | `false` | `false` disables. `true` enables with default threshold. Object enables and uses `thresholdMs` when valid; otherwise fallback threshold `200ms` is used (minimum effective value `50ms`). Requires Chrome 123+ / Edge 123+. |
 
 ## Source maps consuming
 

packages/javascript/src/addons/issues.ts

@@ -12,10 +12,10 @@ import type {
 import { compactJson } from '../utils/compactJson';
 import log from '../utils/log';
 
-const DEFAULT_LONG_TASK_THRESHOLD_MS = 70;
-const DEFAULT_LOAF_THRESHOLD_MS = 200;
-const MIN_ISSUE_THRESHOLD_MS = 50;
-const WEB_VITALS_REPORT_TIMEOUT_MS = 10000;
+export const DEFAULT_LONG_TASK_THRESHOLD_MS = 70;
+export const DEFAULT_LOAF_THRESHOLD_MS = 200;
+export const MIN_ISSUE_THRESHOLD_MS = 50;
+export const WEB_VITALS_REPORT_TIMEOUT_MS = 10000;
 
 const METRIC_THRESHOLDS: Record<string, [good: number, poor: number]> = {
   LCP: [2500, 4000],
@@ -54,16 +54,16 @@ export class IssuesMonitor {
     this.isInitialized = true;
     this.destroyed = false;
 
-    if (options.longTasks !== false) {
+    if (options.longTasks !== undefined && options.longTasks !== false) {
       this.observeLongTasks(
-        resolveThreshold(options.longTasks?.thresholdMs, DEFAULT_LONG_TASK_THRESHOLD_MS),
+        resolveThreshold(resolveThresholdOption(options.longTasks), DEFAULT_LONG_TASK_THRESHOLD_MS),
         onIssue
       );
     }
 
-    if (options.longAnimationFrames !== false) {
+    if (options.longAnimationFrames !== undefined && options.longAnimationFrames !== false) {
       this.observeLoAF(
-        resolveThreshold(options.longAnimationFrames?.thresholdMs, DEFAULT_LOAF_THRESHOLD_MS),
+        resolveThreshold(resolveThresholdOption(options.longAnimationFrames), DEFAULT_LOAF_THRESHOLD_MS),
         onIssue
       );
     }
@@ -355,6 +355,18 @@ function resolveThreshold(value: number | undefined, fallback: number): number {
   return Math.max(MIN_ISSUE_THRESHOLD_MS, Math.round(value));
 }
 
+/**
+ *
+ * @param value
+ */
+function resolveThresholdOption(value: boolean | { thresholdMs?: number }): number | undefined {
+  if (typeof value === 'object' && value !== null) {
+    return value.thresholdMs;
+  }
+
+  return undefined;
+}
+
 /**
  *
  * @param name metric name

packages/javascript/src/catcher.ts

@@ -326,8 +326,8 @@ export default class Catcher {
   private configureIssues(settings: HawkInitialSettings): void {
     const issues = settings.issues ?? {};
     const shouldHandleGlobalErrors = settings.disableGlobalErrorsHandling !== true && issues.errors !== false;
-    const shouldDetectPerformanceIssues = issues.longTasks !== false
-      || issues.longAnimationFrames !== false
+    const shouldDetectPerformanceIssues = (issues.longTasks !== undefined && issues.longTasks !== false)
+      || (issues.longAnimationFrames !== undefined && issues.longAnimationFrames !== false)
       || issues.webVitals === true;
 
     if (shouldHandleGlobalErrors) {

packages/javascript/src/types/issues.ts

@@ -30,18 +30,24 @@ export interface IssuesOptions {
   webVitals?: boolean;
 
   /**
-   * Long Tasks options. Set `false` to disable.
+   * Long Tasks options.
+   * `false` disables the feature.
+   * Any other value enables it with default threshold.
+   * If `thresholdMs` is a valid number greater than or equal to 50, it is used.
    *
    * @default false
    */
-  longTasks?: false | IssueThresholdOptions;
+  longTasks?: boolean | IssueThresholdOptions;
 
   /**
-   * Long Animation Frames options. Set `false` to disable.
+   * Long Animation Frames options.
+   * `false` disables the feature.
+   * Any other value enables it with default threshold.
+   * If `thresholdMs` is a valid number greater than or equal to 50, it is used.
    *
    * @default false
    */
-  longAnimationFrames?: false | IssueThresholdOptions;
+  longAnimationFrames?: boolean | IssueThresholdOptions;
 }
 
 /**

packages/javascript/tests/issues-monitor.test.ts

@@ -1,5 +1,10 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import type { Metric, ReportCallback } from 'web-vitals';
+import {
+  DEFAULT_LONG_TASK_THRESHOLD_MS,
+  MIN_ISSUE_THRESHOLD_MS,
+  WEB_VITALS_REPORT_TIMEOUT_MS,
+} from '../src/addons/issues';
 
 class MockPerformanceObserver {
   public static supportedEntryTypes: string[] = ['longtask', 'long-animation-frame'];
@@ -96,10 +101,10 @@ describe('IssuesMonitor', () => {
 
     expect(observer).toBeDefined();
 
-    observer!.emit([entry('longtask', 49)]);
+    observer!.emit([entry('longtask', MIN_ISSUE_THRESHOLD_MS - 1)]);
     expect(onIssue).not.toHaveBeenCalled();
 
-    observer!.emit([entry('longtask', 50)]);
+    observer!.emit([entry('longtask', MIN_ISSUE_THRESHOLD_MS)]);
     expect(onIssue).toHaveBeenCalledTimes(1);
   });
 
@@ -109,17 +114,37 @@ describe('IssuesMonitor', () => {
     const onIssue = vi.fn();
     const monitor = new IssuesMonitor();
 
-    monitor.init({ longTasks: { thresholdMs: 70 }, longAnimationFrames: false, webVitals: false }, onIssue);
+    const customThresholdMs = 75;
+
+    monitor.init({ longTasks: { thresholdMs: customThresholdMs }, longAnimationFrames: false, webVitals: false }, onIssue);
+    const observer = MockPerformanceObserver.byType('longtask');
+
+    expect(observer).toBeDefined();
+
+    observer!.emit([entry('longtask', customThresholdMs - 1)]);
+    expect(onIssue).not.toHaveBeenCalled();
+
+    observer!.emit([entry('longtask', customThresholdMs)]);
+    expect(onIssue).toHaveBeenCalledTimes(1);
+    expect(onIssue.mock.calls[0][0].title).toContain(`${customThresholdMs} ms`);
+  });
+
+  it('should use default threshold when longTasks is true', async () => {
+    mockWebVitals();
+    const { IssuesMonitor } = await import('../src/addons/issues');
+    const onIssue = vi.fn();
+    const monitor = new IssuesMonitor();
+
+    monitor.init({ longTasks: true, longAnimationFrames: false, webVitals: false }, onIssue);
     const observer = MockPerformanceObserver.byType('longtask');
 
     expect(observer).toBeDefined();
 
-    observer!.emit([entry('longtask', 55)]);
+    observer!.emit([entry('longtask', DEFAULT_LONG_TASK_THRESHOLD_MS - 1)]);
     expect(onIssue).not.toHaveBeenCalled();
 
-    observer!.emit([entry('longtask', 75)]);
+    observer!.emit([entry('longtask', DEFAULT_LONG_TASK_THRESHOLD_MS)]);
     expect(onIssue).toHaveBeenCalledTimes(1);
-    expect(onIssue.mock.calls[0][0].title).toContain('75 ms');
   });
 
   it('should ignore second init call and avoid duplicate observers', async () => {
@@ -177,7 +202,7 @@ describe('IssuesMonitor', () => {
     await vi.dynamicImportSettled();
 
     webVitals.emit({ name: 'LCP', value: 5000, rating: 'poor', delta: 5000 });
-    vi.advanceTimersByTime(10000);
+    vi.advanceTimersByTime(WEB_VITALS_REPORT_TIMEOUT_MS);
 
     expect(onIssue).toHaveBeenCalledTimes(1);
     expect(onIssue.mock.calls[0][0].title).toContain('Poor Web Vitals');