@mushi-mushi/web 0.3.1 → 0.4.0

package/README.md

@@ -46,7 +46,7 @@ Each trigger respects its config flag — set `rageClick: false` to disable rage
 
 ## Bundle Size
 
-~6 KB brotli (limit: 30 KB). Requires `@mushi-mushi/core` as a dependency (not bundled inline).
+~6 KB brotli, enforced at **15 KB gzipped** via `size-limit` in CI. Requires `@mushi-mushi/core` as a dependency (not bundled inline). The `./test-utils` entry is a separate artifact and is never pulled into production bundles.
 
 ## Quick Start
 
@@ -99,6 +99,28 @@ setupProactiveTriggers({
 });
 ```
 
+## Test utilities (`./test-utils`)
+
+Deterministic Playwright / jsdom helpers, published as a separate
+entry-point so production bundles pay nothing for them:
+
+```ts
+import { triggerBug, openReport, waitForQueueDrain } from '@mushi-mushi/web/test-utils';
+```
+
+| Export              | Purpose                                                                 |
+|---------------------|-------------------------------------------------------------------------|
+| `triggerBug(opts?)` | Submit a report bypassing the widget. Returns the server-assigned id.   |
+| `openReport(cat?)`  | Open the widget programmatically without submitting.                    |
+| `waitForQueueDrain` | Resolve once the offline queue is empty (number remaining at timeout).  |
+
+Every helper no-ops when `Mushi.getInstance()` returns `null`, so
+conditional-wiring tests (e.g. cloud vs local targets) don't need to
+branch. For browser-context use in Playwright's `page.evaluate`, import
+the SDK via the app's own bundle (`window.__mushi__` in dev builds) or
+POST to `/v1/reports` directly — `page.evaluate` has no npm resolver in
+the browser context.
+
 ## License
 
 MIT

package/dist/test-utils.cjs

@@ -0,0 +1,22 @@
+'use strict';
+
+require('@mushi-mushi/core');
+
+// src/mushi.ts
+
+// src/test-utils.ts
+async function triggerBug(opts = {}) {
+  return null;
+}
+function openReport(category) {
+  return;
+}
+async function waitForQueueDrain(options = {}) {
+  return 0;
+}
+
+exports.openReport = openReport;
+exports.triggerBug = triggerBug;
+exports.waitForQueueDrain = waitForQueueDrain;
+//# sourceMappingURL=test-utils.cjs.map
+//# sourceMappingURL=test-utils.cjs.map

package/dist/test-utils.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/test-utils.ts"],"names":[],"mappings":";;;;;;;AAsDA,eAAsB,UAAA,CAAW,IAAA,GAA0B,EAAC,EAA2B;AAErF,EAAU,OAAO,IAAA;AAqBnB;AAOO,SAAS,WAAW,QAAA,EAAsC;AAE/D,EAAU;AAEZ;AAOA,eAAsB,iBAAA,CAAkB,OAAA,GAAkC,EAAC,EAAoB;AAE7F,EAAU,OAAO,CAAA;AAenB","file":"test-utils.cjs","sourcesContent":["/**\n * @mushi-mushi/web/test-utils\n *\n * Playwright / jsdom helpers for deterministic SDK tests. This module is\n * published as a separate entry-point so production bundles never pay the\n * cost — import it via `import { triggerBug, openReport } from\n * '@mushi-mushi/web/test-utils'`.\n *\n * Design goals:\n *   1. Zero production footprint. Nothing here is imported from `./mushi`,\n *      `./widget`, or any runtime module. We reach for the live SDK via\n *      `Mushi.getInstance()` so the test process sees exactly what the app\n *      bootstrapped — no duplicate SDK singletons, no double-init races.\n *   2. Safe in a test harness even when Mushi is disabled. Every helper\n *      no-ops when `Mushi.getInstance()` returns `null`, so Playwright\n *      specs that conditionally wire Mushi (e.g. cloud vs local targets)\n *      don't have to branch.\n *   3. Flat surface. Tests want 3 verbs: \"open the widget\", \"submit a\n *      report programmatically\", \"wait until the SDK confirms the POST\n *      landed\". Anything beyond that belongs in the app under test.\n */\n\nimport { Mushi } from './mushi';\nimport type {\n  MushiReportCategory,\n  MushiSDKInstance,\n} from '@mushi-mushi/core';\n\n/** Options accepted by `triggerBug`. Mirrors the core report contract but\n *  keeps every field optional so a Playwright test can say\n *  `triggerBug({ description: 'button dead' })` without a category. */\nexport interface TriggerBugOptions {\n  /** Short free-text description of the issue. Defaults to a marker\n   *  string so tests that forget to pass a description still produce a\n   *  distinguishable report in the admin console. */\n  description?: string;\n  /** Severity-free category tag. */\n  category?: MushiReportCategory;\n  /** Arbitrary metadata the test wants to round-trip. Merged on top of\n   *  whatever `setMetadata` has already stored. */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Submit a report bypassing the widget UI. Returns the server-assigned\n * `reportId` when the POST lands, or `null` if Mushi isn't initialised in\n * this test context (or the submit failed — the SDK swallows network\n * errors silently by design).\n *\n * Use this from Playwright `page.evaluate(...)` calls to round-trip a\n * report into the backend without needing to drive the widget's DOM. It's\n * the fastest way to assert \"a bug report made it from the browser into\n * reports/ in Supabase\".\n */\nexport async function triggerBug(opts: TriggerBugOptions = {}): Promise<string | null> {\n  const sdk = Mushi.getInstance();\n  if (!sdk) return null;\n\n  const description = opts.description\n    ?? `[test-utils] triggerBug marker ${new Date().toISOString()}`;\n\n  if (opts.metadata) {\n    for (const [k, v] of Object.entries(opts.metadata)) {\n      try { sdk.setMetadata(k, v); } catch { /* ignore */ }\n    }\n  }\n\n  // `captureEvent` is the documented programmatic-submit API since 0.3.0\n  // — it bypasses the widget, resolves with the server-assigned report\n  // id, and participates in the same offline queue / pre-filter pipeline\n  // as a widget submission.\n  return await sdk.captureEvent({\n    description,\n    source: 'test-utils',\n    ...(opts.category ? { category: opts.category } : {}),\n    ...(opts.metadata ? { metadata: opts.metadata } : {}),\n  });\n}\n\n/**\n * Programmatically open the Mushi widget without submitting anything. Use\n * for interaction tests that want to assert \"the widget is mounted and\n * reachable\" or to drive a user-like flow via Playwright selectors.\n */\nexport function openReport(category?: MushiReportCategory): void {\n  const sdk = Mushi.getInstance();\n  if (!sdk) return;\n  sdk.report(category ? { category } : undefined);\n}\n\n/**\n * Wait until the offline queue drains — useful after `triggerBug` in tests\n * that submit while offline then assert the report eventually syncs.\n * Resolves with the number of queued items remaining (0 = fully drained).\n */\nexport async function waitForQueueDrain(options: { timeoutMs?: number } = {}): Promise<number> {\n  const sdk = Mushi.getInstance();\n  if (!sdk) return 0;\n  const timeoutMs = options.timeoutMs ?? 5_000;\n  const started = Date.now();\n  // The SDK instance doesn't publicly expose the queue, but `getQueueSize`\n  // has been in the contract since 0.2.x. We tolerate its absence so\n  // upgrading doesn't break tests that only need triggerBug/openReport.\n  const getQueueSize = (sdk as MushiSDKInstance & { getQueueSize?: () => number }).getQueueSize;\n  if (typeof getQueueSize !== 'function') return 0;\n\n  while (Date.now() - started < timeoutMs) {\n    const remaining = getQueueSize.call(sdk);\n    if (remaining === 0) return 0;\n    await new Promise((r) => setTimeout(r, 100));\n  }\n  return getQueueSize.call(sdk);\n}\n"]}

package/dist/test-utils.d.cts

@@ -0,0 +1,66 @@
+import { MushiReportCategory } from '@mushi-mushi/core';
+
+/**
+ * @mushi-mushi/web/test-utils
+ *
+ * Playwright / jsdom helpers for deterministic SDK tests. This module is
+ * published as a separate entry-point so production bundles never pay the
+ * cost — import it via `import { triggerBug, openReport } from
+ * '@mushi-mushi/web/test-utils'`.
+ *
+ * Design goals:
+ *   1. Zero production footprint. Nothing here is imported from `./mushi`,
+ *      `./widget`, or any runtime module. We reach for the live SDK via
+ *      `Mushi.getInstance()` so the test process sees exactly what the app
+ *      bootstrapped — no duplicate SDK singletons, no double-init races.
+ *   2. Safe in a test harness even when Mushi is disabled. Every helper
+ *      no-ops when `Mushi.getInstance()` returns `null`, so Playwright
+ *      specs that conditionally wire Mushi (e.g. cloud vs local targets)
+ *      don't have to branch.
+ *   3. Flat surface. Tests want 3 verbs: "open the widget", "submit a
+ *      report programmatically", "wait until the SDK confirms the POST
+ *      landed". Anything beyond that belongs in the app under test.
+ */
+
+/** Options accepted by `triggerBug`. Mirrors the core report contract but
+ *  keeps every field optional so a Playwright test can say
+ *  `triggerBug({ description: 'button dead' })` without a category. */
+interface TriggerBugOptions {
+    /** Short free-text description of the issue. Defaults to a marker
+     *  string so tests that forget to pass a description still produce a
+     *  distinguishable report in the admin console. */
+    description?: string;
+    /** Severity-free category tag. */
+    category?: MushiReportCategory;
+    /** Arbitrary metadata the test wants to round-trip. Merged on top of
+     *  whatever `setMetadata` has already stored. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Submit a report bypassing the widget UI. Returns the server-assigned
+ * `reportId` when the POST lands, or `null` if Mushi isn't initialised in
+ * this test context (or the submit failed — the SDK swallows network
+ * errors silently by design).
+ *
+ * Use this from Playwright `page.evaluate(...)` calls to round-trip a
+ * report into the backend without needing to drive the widget's DOM. It's
+ * the fastest way to assert "a bug report made it from the browser into
+ * reports/ in Supabase".
+ */
+declare function triggerBug(opts?: TriggerBugOptions): Promise<string | null>;
+/**
+ * Programmatically open the Mushi widget without submitting anything. Use
+ * for interaction tests that want to assert "the widget is mounted and
+ * reachable" or to drive a user-like flow via Playwright selectors.
+ */
+declare function openReport(category?: MushiReportCategory): void;
+/**
+ * Wait until the offline queue drains — useful after `triggerBug` in tests
+ * that submit while offline then assert the report eventually syncs.
+ * Resolves with the number of queued items remaining (0 = fully drained).
+ */
+declare function waitForQueueDrain(options?: {
+    timeoutMs?: number;
+}): Promise<number>;
+
+export { type TriggerBugOptions, openReport, triggerBug, waitForQueueDrain };

package/dist/test-utils.d.ts

@@ -0,0 +1,66 @@
+import { MushiReportCategory } from '@mushi-mushi/core';
+
+/**
+ * @mushi-mushi/web/test-utils
+ *
+ * Playwright / jsdom helpers for deterministic SDK tests. This module is
+ * published as a separate entry-point so production bundles never pay the
+ * cost — import it via `import { triggerBug, openReport } from
+ * '@mushi-mushi/web/test-utils'`.
+ *
+ * Design goals:
+ *   1. Zero production footprint. Nothing here is imported from `./mushi`,
+ *      `./widget`, or any runtime module. We reach for the live SDK via
+ *      `Mushi.getInstance()` so the test process sees exactly what the app
+ *      bootstrapped — no duplicate SDK singletons, no double-init races.
+ *   2. Safe in a test harness even when Mushi is disabled. Every helper
+ *      no-ops when `Mushi.getInstance()` returns `null`, so Playwright
+ *      specs that conditionally wire Mushi (e.g. cloud vs local targets)
+ *      don't have to branch.
+ *   3. Flat surface. Tests want 3 verbs: "open the widget", "submit a
+ *      report programmatically", "wait until the SDK confirms the POST
+ *      landed". Anything beyond that belongs in the app under test.
+ */
+
+/** Options accepted by `triggerBug`. Mirrors the core report contract but
+ *  keeps every field optional so a Playwright test can say
+ *  `triggerBug({ description: 'button dead' })` without a category. */
+interface TriggerBugOptions {
+    /** Short free-text description of the issue. Defaults to a marker
+     *  string so tests that forget to pass a description still produce a
+     *  distinguishable report in the admin console. */
+    description?: string;
+    /** Severity-free category tag. */
+    category?: MushiReportCategory;
+    /** Arbitrary metadata the test wants to round-trip. Merged on top of
+     *  whatever `setMetadata` has already stored. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Submit a report bypassing the widget UI. Returns the server-assigned
+ * `reportId` when the POST lands, or `null` if Mushi isn't initialised in
+ * this test context (or the submit failed — the SDK swallows network
+ * errors silently by design).
+ *
+ * Use this from Playwright `page.evaluate(...)` calls to round-trip a
+ * report into the backend without needing to drive the widget's DOM. It's
+ * the fastest way to assert "a bug report made it from the browser into
+ * reports/ in Supabase".
+ */
+declare function triggerBug(opts?: TriggerBugOptions): Promise<string | null>;
+/**
+ * Programmatically open the Mushi widget without submitting anything. Use
+ * for interaction tests that want to assert "the widget is mounted and
+ * reachable" or to drive a user-like flow via Playwright selectors.
+ */
+declare function openReport(category?: MushiReportCategory): void;
+/**
+ * Wait until the offline queue drains — useful after `triggerBug` in tests
+ * that submit while offline then assert the report eventually syncs.
+ * Resolves with the number of queued items remaining (0 = fully drained).
+ */
+declare function waitForQueueDrain(options?: {
+    timeoutMs?: number;
+}): Promise<number>;
+
+export { type TriggerBugOptions, openReport, triggerBug, waitForQueueDrain };

package/dist/test-utils.js

@@ -0,0 +1,18 @@
+import '@mushi-mushi/core';
+
+// src/mushi.ts
+
+// src/test-utils.ts
+async function triggerBug(opts = {}) {
+  return null;
+}
+function openReport(category) {
+  return;
+}
+async function waitForQueueDrain(options = {}) {
+  return 0;
+}
+
+export { openReport, triggerBug, waitForQueueDrain };
+//# sourceMappingURL=test-utils.js.map
+//# sourceMappingURL=test-utils.js.map

package/dist/test-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/test-utils.ts"],"names":[],"mappings":";;;;;AAsDA,eAAsB,UAAA,CAAW,IAAA,GAA0B,EAAC,EAA2B;AAErF,EAAU,OAAO,IAAA;AAqBnB;AAOO,SAAS,WAAW,QAAA,EAAsC;AAE/D,EAAU;AAEZ;AAOA,eAAsB,iBAAA,CAAkB,OAAA,GAAkC,EAAC,EAAoB;AAE7F,EAAU,OAAO,CAAA;AAenB","file":"test-utils.js","sourcesContent":["/**\n * @mushi-mushi/web/test-utils\n *\n * Playwright / jsdom helpers for deterministic SDK tests. This module is\n * published as a separate entry-point so production bundles never pay the\n * cost — import it via `import { triggerBug, openReport } from\n * '@mushi-mushi/web/test-utils'`.\n *\n * Design goals:\n *   1. Zero production footprint. Nothing here is imported from `./mushi`,\n *      `./widget`, or any runtime module. We reach for the live SDK via\n *      `Mushi.getInstance()` so the test process sees exactly what the app\n *      bootstrapped — no duplicate SDK singletons, no double-init races.\n *   2. Safe in a test harness even when Mushi is disabled. Every helper\n *      no-ops when `Mushi.getInstance()` returns `null`, so Playwright\n *      specs that conditionally wire Mushi (e.g. cloud vs local targets)\n *      don't have to branch.\n *   3. Flat surface. Tests want 3 verbs: \"open the widget\", \"submit a\n *      report programmatically\", \"wait until the SDK confirms the POST\n *      landed\". Anything beyond that belongs in the app under test.\n */\n\nimport { Mushi } from './mushi';\nimport type {\n  MushiReportCategory,\n  MushiSDKInstance,\n} from '@mushi-mushi/core';\n\n/** Options accepted by `triggerBug`. Mirrors the core report contract but\n *  keeps every field optional so a Playwright test can say\n *  `triggerBug({ description: 'button dead' })` without a category. */\nexport interface TriggerBugOptions {\n  /** Short free-text description of the issue. Defaults to a marker\n   *  string so tests that forget to pass a description still produce a\n   *  distinguishable report in the admin console. */\n  description?: string;\n  /** Severity-free category tag. */\n  category?: MushiReportCategory;\n  /** Arbitrary metadata the test wants to round-trip. Merged on top of\n   *  whatever `setMetadata` has already stored. */\n  metadata?: Record<string, unknown>;\n}\n\n/**\n * Submit a report bypassing the widget UI. Returns the server-assigned\n * `reportId` when the POST lands, or `null` if Mushi isn't initialised in\n * this test context (or the submit failed — the SDK swallows network\n * errors silently by design).\n *\n * Use this from Playwright `page.evaluate(...)` calls to round-trip a\n * report into the backend without needing to drive the widget's DOM. It's\n * the fastest way to assert \"a bug report made it from the browser into\n * reports/ in Supabase\".\n */\nexport async function triggerBug(opts: TriggerBugOptions = {}): Promise<string | null> {\n  const sdk = Mushi.getInstance();\n  if (!sdk) return null;\n\n  const description = opts.description\n    ?? `[test-utils] triggerBug marker ${new Date().toISOString()}`;\n\n  if (opts.metadata) {\n    for (const [k, v] of Object.entries(opts.metadata)) {\n      try { sdk.setMetadata(k, v); } catch { /* ignore */ }\n    }\n  }\n\n  // `captureEvent` is the documented programmatic-submit API since 0.3.0\n  // — it bypasses the widget, resolves with the server-assigned report\n  // id, and participates in the same offline queue / pre-filter pipeline\n  // as a widget submission.\n  return await sdk.captureEvent({\n    description,\n    source: 'test-utils',\n    ...(opts.category ? { category: opts.category } : {}),\n    ...(opts.metadata ? { metadata: opts.metadata } : {}),\n  });\n}\n\n/**\n * Programmatically open the Mushi widget without submitting anything. Use\n * for interaction tests that want to assert \"the widget is mounted and\n * reachable\" or to drive a user-like flow via Playwright selectors.\n */\nexport function openReport(category?: MushiReportCategory): void {\n  const sdk = Mushi.getInstance();\n  if (!sdk) return;\n  sdk.report(category ? { category } : undefined);\n}\n\n/**\n * Wait until the offline queue drains — useful after `triggerBug` in tests\n * that submit while offline then assert the report eventually syncs.\n * Resolves with the number of queued items remaining (0 = fully drained).\n */\nexport async function waitForQueueDrain(options: { timeoutMs?: number } = {}): Promise<number> {\n  const sdk = Mushi.getInstance();\n  if (!sdk) return 0;\n  const timeoutMs = options.timeoutMs ?? 5_000;\n  const started = Date.now();\n  // The SDK instance doesn't publicly expose the queue, but `getQueueSize`\n  // has been in the contract since 0.2.x. We tolerate its absence so\n  // upgrading doesn't break tests that only need triggerBug/openReport.\n  const getQueueSize = (sdk as MushiSDKInstance & { getQueueSize?: () => number }).getQueueSize;\n  if (typeof getQueueSize !== 'function') return 0;\n\n  while (Date.now() - started < timeoutMs) {\n    const remaining = getQueueSize.call(sdk);\n    if (remaining === 0) return 0;\n    await new Promise((r) => setTimeout(r, 100));\n  }\n  return getQueueSize.call(sdk);\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mushi-mushi/web",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Mushi Mushi browser SDK — embeddable bug reporting widget with Shadow DOM isolation",
   "license": "MIT",
   "type": "module",
@@ -17,6 +17,16 @@
         "types": "./dist/index.d.cts",
         "default": "./dist/index.cjs"
       }
+    },
+    "./test-utils": {
+      "import": {
+        "types": "./dist/test-utils.d.ts",
+        "default": "./dist/test-utils.js"
+      },
+      "require": {
+        "types": "./dist/test-utils.d.cts",
+        "default": "./dist/test-utils.cjs"
+      }
     }
   },
   "files": [
@@ -62,12 +72,19 @@
   "sideEffects": false,
   "size-limit": [
     {
+      "name": "Core SDK bundle (minified + gzipped)",
       "path": "dist/index.js",
-      "limit": "30 KB"
+      "limit": "15 KB",
+      "gzip": true
+    },
+    {
+      "name": "Core SDK bundle (uncompressed)",
+      "path": "dist/index.js",
+      "limit": "60 KB"
     }
   ],
   "dependencies": {
-    "@mushi-mushi/core": "^0.3.1"
+    "@mushi-mushi/core": "^0.4.0"
   },
   "devDependencies": {
     "@size-limit/file": "^12.1.0",
@@ -81,6 +98,9 @@
     "@mushi-mushi/tsconfig": "0.0.0"
   },
   "author": "Kenji Sakuramoto",
+  "engines": {
+    "node": ">=20"
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",