@rimori/playwright-testing 0.2.1 → 0.2.3

package/README.md

@@ -17,6 +17,157 @@ The `@rimori/playwright-testing` package enables end-to-end testing of Rimori pl
 npm install --save-dev @rimori/playwright-testing @playwright/test
 # or
 pnpm add -D @rimori/playwright-testing @playwright/test
+# or
+yarn add -D @rimori/playwright-testing @playwright/test
+```
+
+## Setup Steps
+
+To initialize Playwright testing in your Rimori plugin, follow these steps:
+
+### 1. Install Dependencies
+
+Add the required dependencies to your `package.json`:
+
+```json
+{
+  "devDependencies": {
+    "@playwright/test": "^1.40.0",
+    "@rimori/playwright-testing": "^0.2.1"
+  }
+}
+```
+
+Then run:
+
+```bash
+npm install
+# or
+yarn install
+# or
+pnpm install
+```
+
+### 2. Create Playwright Configuration
+
+Create a `playwright.config.ts` file in your plugin root:
+
+```typescript
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './test',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: 'html',
+  use: {
+    trace: 'on-first-retry',
+    headless: false,
+    screenshot: 'only-on-failure',
+  },
+  timeout: 30000,
+  expect: {
+    timeout: 5000,
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+});
+```
+
+### 3. Add Test Scripts
+
+Add test scripts to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "test": "playwright test",
+    "test:headed": "playwright test --headed",
+    "test:debug": "playwright test --debug",
+    "test:ui": "playwright test --ui",
+    "test:headed:debug": "playwright test --headed --debug"
+  }
+}
+```
+
+### 4. Create Test Directory and Files
+
+Create a `test` directory in your plugin root and add your test files:
+
+```typescript
+// test/my-plugin.test.ts
+import { test, expect } from '@playwright/test';
+import { RimoriTestEnvironment } from '@rimori/playwright-testing';
+
+const pluginId = 'pl1234567890'; // Your plugin ID from rimori.config.ts
+const pluginUrl = 'http://localhost:3002'; // Your dev server URL
+
+test.describe('My Plugin', () => {
+  let env: RimoriTestEnvironment;
+
+  test.beforeEach(async ({ page }) => {
+    env = new RimoriTestEnvironment({ page, pluginId });
+
+    // Set up your mocks here
+    // env.ai.mockGetObject(...);
+    // env.plugin.mockGetSettings(...);
+
+    await env.setup();
+    await page.goto(`${pluginUrl}/#/your-page`);
+  });
+
+  test('should work correctly', async ({ page }) => {
+    await expect(page.getByText('Hello')).toBeVisible();
+  });
+});
+```
+
+### 5. Get Your Plugin ID
+
+Find your plugin ID in `rimori/rimori.config.ts`:
+
+```typescript
+const config: RimoriPluginConfig = {
+  id: 'pl1234567890', // <-- This is your plugin ID
+  // ...
+};
+```
+
+### 6. Run Tests
+
+1. **Start your dev server** in one terminal:
+
+   ```bash
+   npm run dev
+   # or
+   yarn dev
+   ```
+
+2. **Run tests** in another terminal:
+   ```bash
+   npm test
+   # or
+   yarn test
+   ```
+
+### Complete Example Setup
+
+Here's a complete example of what your plugin structure should look like:
+
+```
+your-plugin/
+├── package.json          # With @playwright/test and test scripts
+├── playwright.config.ts  # Playwright configuration
+├── rimori/
+│   └── rimori.config.ts  # Contains your plugin ID
+└── test/
+    └── my-plugin.test.ts # Your test files
 ```
 
 ## Quick Start

package/dist/core/MessageChannelSimulator.d.ts

@@ -76,6 +76,7 @@ type MessageChannelSimulatorArgs = {
     rimoriInfo?: RimoriInfo;
 };
 type EventListener = (event: EventBusMessage) => void | Promise<void>;
+type AutoResponder = (event: EventBusMessage) => unknown | Promise<unknown>;
 export declare class MessageChannelSimulator {
     private readonly page;
     private readonly pluginId;
@@ -111,6 +112,16 @@ export declare class MessageChannelSimulator {
      * Registers a handler for events emitted from the plugin.
      */
     on(topic: string, handler: EventListener): () => void;
+    /**
+     * Registers a one-time auto-responder for a request/response topic.
+     * When a request with an eventId comes in for this topic, the responder will
+     * be called once and then automatically removed.
+     *
+     * @param topic - The event topic to respond to
+     * @param responder - A function that returns the response data, or a value to return directly
+     * @returns A function to manually remove the responder before it's used
+     */
+    respondOnce(topic: string, responder: AutoResponder | unknown): () => void;
     /**
      * Overrides the default profile returned by the auto responders.
      */

package/dist/core/MessageChannelSimulator.js

@@ -142,6 +142,39 @@ class MessageChannelSimulator {
             }
         };
     }
+    /**
+     * Registers a one-time auto-responder for a request/response topic.
+     * When a request with an eventId comes in for this topic, the responder will
+     * be called once and then automatically removed.
+     *
+     * @param topic - The event topic to respond to
+     * @param responder - A function that returns the response data, or a value to return directly
+     * @returns A function to manually remove the responder before it's used
+     */
+    respondOnce(topic, responder) {
+        let used = false;
+        const wrappedResponder = (event) => {
+            if (used) {
+                return undefined;
+            }
+            used = true;
+            // Remove from autoResponders after first use
+            this.autoResponders.delete(topic);
+            // If responder is a function, call it with the event, otherwise return the value directly
+            if (typeof responder === 'function') {
+                return responder(event);
+            }
+            return responder;
+        };
+        this.autoResponders.set(topic, wrappedResponder);
+        // Return a function to manually remove the responder
+        return () => {
+            if (!used) {
+                this.autoResponders.delete(topic);
+                used = true;
+            }
+        };
+    }
     /**
      * Overrides the default profile returned by the auto responders.
      */

package/dist/core/RimoriTestEnvironment.d.ts

@@ -26,6 +26,12 @@ interface MockOptions {
      * The HTTP method for the route. If not provided, defaults will be used based on the route type.
      */
     method?: HttpMethod;
+    /**
+     * If true, the mock is removed after first use. Default: false (persistent).
+     * This allows for sequential mock responses where each mock is consumed once.
+     * Useful for testing flows where the same route is called multiple times with different responses.
+     */
+    once?: boolean;
 }
 export declare class RimoriTestEnvironment {
     private readonly page;
@@ -50,6 +56,10 @@ export declare class RimoriTestEnvironment {
      * Creates a route key combining HTTP method and normalized URL.
      */
     private createRouteKey;
+    /**
+     * Removes a one-time mock from the mocks array after it's been used.
+     */
+    private removeOneTimeMock;
     private handleRoute;
     /**
      * Adds a supabase route to the supabase routes object.
@@ -96,18 +106,79 @@ export declare class RimoriTestEnvironment {
         mockGetPluginInfo: (pluginInfo: Plugin, options?: MockOptions) => void;
     };
     readonly db: {
-        mockFrom: () => void;
-        mockTable: () => void;
+        /**
+         * Mocks a Supabase table endpoint (from(tableName)).
+         * The table name will be prefixed with the plugin ID in the actual URL.
+         *
+         * Supabase operations map to HTTP methods as follows:
+         * - .select() → GET
+         * - .insert() → POST
+         * - .update() → PATCH
+         * - .delete() → DELETE (can return data with .delete().select())
+         * - .upsert() → POST
+         *
+         * @param tableName - The table name (e.g., 'decks')
+         * @param value - The response value to return for the request
+         * @param options - Mock options including HTTP method (defaults to 'GET' if not specified)
+         */
+        mockFrom: (tableName: string, value: unknown, options?: MockOptions) => void;
     };
     readonly event: {
-        mockEmit: () => void;
-        mockRequest: () => void;
-        mockOn: () => void;
+        /**
+         * Emit an event into the plugin as if it came from Rimori main or another plugin.
+         *
+         * Note: This does NOT currently reach worker listeners such as those in
+         * `worker/listeners/decks.ts` or `worker/listeners/flascards.ts` – those run in a
+         * separate process. This helper is intended for UI‑side events only.
+         */
+        mockEmit: (topic: string, data: unknown, sender?: string) => Promise<void>;
+        /**
+         * Registers a one-time auto-responder for request/response style events.
+         *
+         * When the plugin calls `plugin.event.request(topic, data)`, this registered responder
+         * will automatically return the provided response value. The responder is automatically
+         * removed after the first request, ensuring it only responds once.
+         *
+         * Example:
+         * ```ts
+         * // Register a responder that will return deck summaries when requested
+         * env.event.mockRequest('deck.requestOpenToday', [
+         *   { id: 'deck-1', name: 'My Deck', total_new: 5, total_learning: 2, total_review: 10 }
+         * ]);
+         *
+         * // Now when the plugin calls: plugin.event.request('deck.requestOpenToday', {})
+         * // It will receive the deck summaries array above
+         * ```
+         *
+         * @param topic - The event topic to respond to (e.g., 'deck.requestOpenToday')
+         * @param response - The response value to return, or a function that receives the event and returns the response
+         * @returns A function to manually remove the responder before it's used
+         */
+        mockRequest: (topic: string, response: unknown | ((event: unknown) => unknown)) => () => void;
+        /**
+         * Listen for events emitted by the plugin.
+         * @param topic - The event topic to listen for (e.g., 'global.accomplishment.triggerMicro')
+         * @param handler - The handler function that receives the event data
+         * @returns A function to unsubscribe from the event
+         */
+        on: (topic: string, handler: (data: unknown) => void) => (() => void);
         mockOnce: () => void;
         mockRespond: () => void;
         mockEmitAccomplishment: () => void;
         mockOnAccomplishment: () => void;
-        mockEmitSidebarAction: () => void;
+        /**
+         * Emits a sidebar action event into the plugin as if Rimori main had triggered it.
+         * This is useful for testing sidebar-driven flows like flashcard creation from selected text.
+         *
+         * It sends a message on the 'global.sidebar.triggerAction' topic, which plugins can listen to via:
+         *   plugin.event.on<{ action: string; text: string }>('global.sidebar.triggerAction', ...)
+         *
+         * @param payload - The payload forwarded to the plugin, typically including an `action` key and optional `text`.
+         */
+        triggerSidebarAction: (payload: {
+            action: string;
+            text?: string;
+        }) => Promise<void>;
         /**
          * Triggers a side panel action event as the parent application would.
          * This simulates how rimori-main's SidebarPluginHandler responds to plugin's 'action.requestSidebar' events.
@@ -141,6 +212,61 @@ export declare class RimoriTestEnvironment {
         mockGetTextFromVoice: (text: string, options?: MockOptions) => void;
         mockGetObject: (value: unknown, options?: MockOptions) => void;
     };
+    /**
+     * Helpers for tracking browser audio playback in tests.
+     *
+     * This is useful for components like the AudioPlayer in @rimori/react-client which:
+     *  1) Fetch audio data from the backend (mocked via `env.ai.mockGetVoice`)
+     *  2) Create `new Audio(url)` and call `.play()`
+     *
+     * With tracking enabled you can assert how many times audio playback was attempted:
+     *
+     * ```ts
+     * await env.audio.enableTracking();
+     * await env.ai.mockGetVoice(Buffer.from('dummy'), { method: 'POST' });
+     * await env.setup();
+     * // ...navigate and trigger audio...
+     * const counts = await env.audio.getPlayCounts();
+     * expect(counts.mediaPlayCalls).toBeGreaterThan(0);
+     * ```
+     *
+     * **Counter Types:**
+     * - `mediaPlayCalls`: Tracks calls to `.play()` on any `HTMLMediaElement` instance
+     *   (including `<audio>`, `<video>` elements, or any element that inherits from `HTMLMediaElement`).
+     *   This counter increments whenever `HTMLMediaElement.prototype.play()` is invoked.
+     * - `audioPlayCalls`: Tracks calls to `.play()` specifically on instances created via the `Audio` constructor
+     *   (e.g., `new Audio(url).play()`). This is a subset of `mediaPlayCalls` but provides more specific
+     *   tracking for programmatically created audio elements.
+     *
+     * **Note**: Since `Audio` instances are also `HTMLMediaElement` instances, calling `.play()` on an
+     * `Audio` object will increment **both** counters. For most use cases, checking `mediaPlayCalls`
+     * is sufficient as it captures all audio playback attempts.
+     */
+    readonly audio: {
+        /**
+         * Injects tracking hooks for HTMLMediaElement.play and the Audio constructor.
+         * Must be called before the plugin code runs (ideally before env.setup()).
+         */
+        enableTracking: () => Promise<void>;
+        /**
+         * Returns current audio play counters from the browser context.
+         *
+         * @returns An object with two counters:
+         *   - `mediaPlayCalls`: Total number of `.play()` calls on any `HTMLMediaElement` (includes all audio/video elements)
+         *   - `audioPlayCalls`: Number of `.play()` calls on instances created via `new Audio()` (subset of `mediaPlayCalls`)
+         *
+         * **Note**: Since `Audio` extends `HTMLMediaElement`, calling `.play()` on an `Audio` instance increments both counters.
+         * For general audio playback tracking, use `mediaPlayCalls` as it captures all playback attempts.
+         */
+        getPlayCounts: () => Promise<{
+            mediaPlayCalls: number;
+            audioPlayCalls: number;
+        }>;
+        /**
+         * Resets the audio play counters to zero.
+         */
+        resetPlayCounts: () => Promise<void>;
+    };
     readonly runtime: {
         mockFetchBackend: () => void;
     };

package/dist/core/RimoriTestEnvironment.js

@@ -43,6 +43,7 @@ class RimoriTestEnvironment {
             mockInsertSettings: (response, options) => {
                 console.log('Mocking insert settings for mockInsertSettings', response, options);
                 console.warn('mockInsertSettings is not tested');
+                // TODO this function should not exist and possibly be combined with the mockSetSettings function
                 // POST request returns the inserted row or success response
                 // Default to an object representing successful insert
                 const defaultResponse = response ?? {
@@ -64,18 +65,103 @@ class RimoriTestEnvironment {
             },
         };
         this.db = {
-            mockFrom: () => { },
-            mockTable: () => { },
+            /**
+             * Mocks a Supabase table endpoint (from(tableName)).
+             * The table name will be prefixed with the plugin ID in the actual URL.
+             *
+             * Supabase operations map to HTTP methods as follows:
+             * - .select() → GET
+             * - .insert() → POST
+             * - .update() → PATCH
+             * - .delete() → DELETE (can return data with .delete().select())
+             * - .upsert() → POST
+             *
+             * @param tableName - The table name (e.g., 'decks')
+             * @param value - The response value to return for the request
+             * @param options - Mock options including HTTP method (defaults to 'GET' if not specified)
+             */
+            mockFrom: (tableName, value, options) => {
+                console.log('Mocking db.from for table:', tableName, 'method:', options?.method ?? 'GET', value, options);
+                const fullTableName = `${this.pluginId}_${tableName}`;
+                this.addSupabaseRoute(fullTableName, value, options);
+            },
         };
         this.event = {
-            mockEmit: () => { },
-            mockRequest: () => { },
-            mockOn: () => { },
+            /**
+             * Emit an event into the plugin as if it came from Rimori main or another plugin.
+             *
+             * Note: This does NOT currently reach worker listeners such as those in
+             * `worker/listeners/decks.ts` or `worker/listeners/flascards.ts` – those run in a
+             * separate process. This helper is intended for UI‑side events only.
+             */
+            mockEmit: async (topic, data, sender = 'test') => {
+                if (!this.messageChannelSimulator) {
+                    throw new Error('MessageChannelSimulator not initialized. Call setup() first.');
+                }
+                await this.messageChannelSimulator.emit(topic, data, sender);
+            },
+            /**
+             * Registers a one-time auto-responder for request/response style events.
+             *
+             * When the plugin calls `plugin.event.request(topic, data)`, this registered responder
+             * will automatically return the provided response value. The responder is automatically
+             * removed after the first request, ensuring it only responds once.
+             *
+             * Example:
+             * ```ts
+             * // Register a responder that will return deck summaries when requested
+             * env.event.mockRequest('deck.requestOpenToday', [
+             *   { id: 'deck-1', name: 'My Deck', total_new: 5, total_learning: 2, total_review: 10 }
+             * ]);
+             *
+             * // Now when the plugin calls: plugin.event.request('deck.requestOpenToday', {})
+             * // It will receive the deck summaries array above
+             * ```
+             *
+             * @param topic - The event topic to respond to (e.g., 'deck.requestOpenToday')
+             * @param response - The response value to return, or a function that receives the event and returns the response
+             * @returns A function to manually remove the responder before it's used
+             */
+            mockRequest: (topic, response) => {
+                if (!this.messageChannelSimulator) {
+                    throw new Error('MessageChannelSimulator not initialized. Call setup() first.');
+                }
+                return this.messageChannelSimulator.respondOnce(topic, response);
+            },
+            /**
+             * Listen for events emitted by the plugin.
+             * @param topic - The event topic to listen for (e.g., 'global.accomplishment.triggerMicro')
+             * @param handler - The handler function that receives the event data
+             * @returns A function to unsubscribe from the event
+             */
+            on: (topic, handler) => {
+                if (!this.messageChannelSimulator) {
+                    throw new Error('MessageChannelSimulator not initialized. Call setup() first.');
+                }
+                return this.messageChannelSimulator.on(topic, (event) => {
+                    handler(event.data);
+                });
+            },
             mockOnce: () => { },
             mockRespond: () => { },
             mockEmitAccomplishment: () => { },
             mockOnAccomplishment: () => { },
-            mockEmitSidebarAction: () => { },
+            /**
+             * Emits a sidebar action event into the plugin as if Rimori main had triggered it.
+             * This is useful for testing sidebar-driven flows like flashcard creation from selected text.
+             *
+             * It sends a message on the 'global.sidebar.triggerAction' topic, which plugins can listen to via:
+             *   plugin.event.on<{ action: string; text: string }>('global.sidebar.triggerAction', ...)
+             *
+             * @param payload - The payload forwarded to the plugin, typically including an `action` key and optional `text`.
+             */
+            triggerSidebarAction: async (payload) => {
+                if (!this.messageChannelSimulator) {
+                    throw new Error('MessageChannelSimulator not initialized. Call setup() first.');
+                }
+                // Simulate Rimori main emitting the sidebar trigger event towards the plugin
+                await this.messageChannelSimulator.emit('global.sidebar.triggerAction', payload, 'sidebar');
+            },
             /**
              * Triggers a side panel action event as the parent application would.
              * This simulates how rimori-main's SidebarPluginHandler responds to plugin's 'action.requestSidebar' events.
@@ -86,15 +172,11 @@ class RimoriTestEnvironment {
                     throw new Error('MessageChannelSimulator not initialized. Call setup() first.');
                 }
                 const topic = `${this.pluginId}.action.requestSidebar`;
-                console.log('[RimoriTestEnvironment] Setting up listener for topic:', topic, 'with payload:', payload);
                 const actionPayload = payload;
                 const off = this.messageChannelSimulator.on(topic, async (event) => {
-                    console.log('[RimoriTestEnvironment] Received action.requestSidebar event:', event);
-                    console.log('[RimoriTestEnvironment] Responding to action.requestSidebar with payload:', actionPayload);
                     await this.messageChannelSimulator.emit(topic, actionPayload, 'sidebar');
                     off();
                 });
-                console.log('[RimoriTestEnvironment] Listener set up for topic:', topic);
             },
             /**
              * Triggers a main panel action event as the parent application would.
@@ -111,20 +193,16 @@ class RimoriTestEnvironment {
                 // Listen for when the plugin emits 'action.requestMain' (which becomes '{pluginId}.action.requestMain')
                 // and respond with the MainPanelAction payload, matching rimori-main's EventBus.respond behavior
                 const topic = `${this.pluginId}.action.requestMain`;
-                console.log('[RimoriTestEnvironment] Setting up listener for topic:', topic, 'with payload:', payload);
                 // Store the payload in a closure so we can respond with it
                 const actionPayload = payload;
                 // Set up a one-time listener that responds when the plugin emits 'action.requestMain'
                 // The handler receives the event object from the plugin
                 const off = this.messageChannelSimulator.on(topic, async (event) => {
-                    console.log('[RimoriTestEnvironment] Received action.requestMain event:', event);
-                    console.log('[RimoriTestEnvironment] Responding to action.requestMain with payload:', actionPayload);
                     // When plugin emits 'action.requestMain', respond with the MainPanelAction data
                     // The sender is 'mainPanel' to match rimori-main's MainPluginHandler behavior
                     await this.messageChannelSimulator.emit(topic, actionPayload, 'mainPanel');
                     off(); // Remove listener after responding once (one-time response like EventBus.respond)
                 });
-                console.log('[RimoriTestEnvironment] Listener set up for topic:', topic);
             },
         };
         this.ai = {
@@ -145,7 +223,6 @@ class RimoriTestEnvironment {
              */
             mockGetSteamedText: (text, options) => {
                 console.log('Mocking get steamed text for mockGetSteamedText', text, options);
-                console.warn('mockGetSteamedText is not tested');
                 this.addBackendRoute('/ai/llm', text, { ...options, isStreaming: true });
             },
             mockGetVoice: (values, options) => {
@@ -160,10 +237,128 @@ class RimoriTestEnvironment {
             },
             mockGetObject: (value, options) => {
                 console.log('Mocking get object for mockGetObject', value, options);
-                console.warn('mockGetObject is not tested');
                 this.addBackendRoute('/ai/llm-object', value, { ...options, method: 'POST' });
             },
         };
+        /**
+         * Helpers for tracking browser audio playback in tests.
+         *
+         * This is useful for components like the AudioPlayer in @rimori/react-client which:
+         *  1) Fetch audio data from the backend (mocked via `env.ai.mockGetVoice`)
+         *  2) Create `new Audio(url)` and call `.play()`
+         *
+         * With tracking enabled you can assert how many times audio playback was attempted:
+         *
+         * ```ts
+         * await env.audio.enableTracking();
+         * await env.ai.mockGetVoice(Buffer.from('dummy'), { method: 'POST' });
+         * await env.setup();
+         * // ...navigate and trigger audio...
+         * const counts = await env.audio.getPlayCounts();
+         * expect(counts.mediaPlayCalls).toBeGreaterThan(0);
+         * ```
+         *
+         * **Counter Types:**
+         * - `mediaPlayCalls`: Tracks calls to `.play()` on any `HTMLMediaElement` instance
+         *   (including `<audio>`, `<video>` elements, or any element that inherits from `HTMLMediaElement`).
+         *   This counter increments whenever `HTMLMediaElement.prototype.play()` is invoked.
+         * - `audioPlayCalls`: Tracks calls to `.play()` specifically on instances created via the `Audio` constructor
+         *   (e.g., `new Audio(url).play()`). This is a subset of `mediaPlayCalls` but provides more specific
+         *   tracking for programmatically created audio elements.
+         *
+         * **Note**: Since `Audio` instances are also `HTMLMediaElement` instances, calling `.play()` on an
+         * `Audio` object will increment **both** counters. For most use cases, checking `mediaPlayCalls`
+         * is sufficient as it captures all audio playback attempts.
+         */
+        this.audio = {
+            /**
+             * Injects tracking hooks for HTMLMediaElement.play and the Audio constructor.
+             * Must be called before the plugin code runs (ideally before env.setup()).
+             */
+            enableTracking: async () => {
+                await this.page.addInitScript(() => {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const w = window;
+                    if (!w.__rimoriAudio) {
+                        w.__rimoriAudio = {
+                            mediaPlayCalls: 0,
+                            audioPlayCalls: 0,
+                        };
+                    }
+                    const proto = (w.HTMLMediaElement && w.HTMLMediaElement.prototype) || undefined;
+                    if (proto && !proto.__rimoriPatched) {
+                        const originalPlay = proto.play;
+                        proto.play = function (...args) {
+                            w.__rimoriAudio.mediaPlayCalls += 1;
+                            return originalPlay.apply(this, args);
+                        };
+                        Object.defineProperty(proto, '__rimoriPatched', {
+                            value: true,
+                            configurable: false,
+                            enumerable: false,
+                            writable: false,
+                        });
+                    }
+                    const OriginalAudio = w.Audio;
+                    if (OriginalAudio && !OriginalAudio.__rimoriPatched) {
+                        const PatchedAudio = function (...args) {
+                            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                            const audio = new OriginalAudio(...args);
+                            const originalPlay = audio.play.bind(audio);
+                            audio.play = () => {
+                                w.__rimoriAudio.audioPlayCalls += 1;
+                                return originalPlay();
+                            };
+                            return audio;
+                        };
+                        PatchedAudio.prototype = OriginalAudio.prototype;
+                        Object.defineProperty(PatchedAudio, '__rimoriPatched', {
+                            value: true,
+                            configurable: false,
+                            enumerable: false,
+                            writable: false,
+                        });
+                        w.Audio = PatchedAudio;
+                    }
+                });
+            },
+            /**
+             * Returns current audio play counters from the browser context.
+             *
+             * @returns An object with two counters:
+             *   - `mediaPlayCalls`: Total number of `.play()` calls on any `HTMLMediaElement` (includes all audio/video elements)
+             *   - `audioPlayCalls`: Number of `.play()` calls on instances created via `new Audio()` (subset of `mediaPlayCalls`)
+             *
+             * **Note**: Since `Audio` extends `HTMLMediaElement`, calling `.play()` on an `Audio` instance increments both counters.
+             * For general audio playback tracking, use `mediaPlayCalls` as it captures all playback attempts.
+             */
+            getPlayCounts: async () => {
+                return this.page.evaluate(() => {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const w = window;
+                    if (!w.__rimoriAudio) {
+                        return { mediaPlayCalls: 0, audioPlayCalls: 0 };
+                    }
+                    return {
+                        mediaPlayCalls: Number(w.__rimoriAudio.mediaPlayCalls || 0),
+                        audioPlayCalls: Number(w.__rimoriAudio.audioPlayCalls || 0),
+                    };
+                });
+            },
+            /**
+             * Resets the audio play counters to zero.
+             */
+            resetPlayCounts: async () => {
+                await this.page.evaluate(() => {
+                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                    const w = window;
+                    if (w.__rimoriAudio) {
+                        w.__rimoriAudio.mediaPlayCalls = 0;
+                        w.__rimoriAudio.audioPlayCalls = 0;
+                    }
+                });
+            },
+        };
         this.runtime = {
             mockFetchBackend: () => { },
         };
@@ -230,6 +425,9 @@ class RimoriTestEnvironment {
     }
     async setup() {
         console.log('Setting up RimoriTestEnvironment');
+        this.page.on('console', (msg) => {
+            console.log(`[browser:${msg.type()}]`, msg.text());
+        });
         // Add default handlers for common routes that plugins typically access
         // These can be overridden by explicit mock calls
         if (!this.supabaseRoutes[this.createRouteKey('GET', `${this.rimoriInfo.url}/rest/v1/plugin_settings`)]) {
@@ -334,8 +532,18 @@ class RimoriTestEnvironment {
         const normalizedUrl = this.normalizeUrl(url);
         return `${method} ${normalizedUrl}`;
     }
+    /**
+     * Removes a one-time mock from the mocks array after it's been used.
+     */
+    removeOneTimeMock(mock, mocks) {
+        if (!mock.options?.once)
+            return;
+        const index = mocks.indexOf(mock);
+        if (index > -1) {
+            mocks.splice(index, 1);
+        }
+    }
     async handleRoute(route, routes) {
-        console.warn('handleRoute is not tested');
         const request = route.request();
         const requestUrl = request.url();
         const method = request.method().toUpperCase();
@@ -378,6 +586,8 @@ class RimoriTestEnvironment {
         // Handle the matched mock
         const options = matchingMock.options;
         await new Promise((resolve) => setTimeout(resolve, options?.delay ?? 0));
+        // Remove one-time mock after handling (before responding)
+        this.removeOneTimeMock(matchingMock, mocks);
         if (options?.error) {
             return await route.abort(options.error);
         }
@@ -392,9 +602,10 @@ class RimoriTestEnvironment {
             });
         }
         // Regular JSON response
+        const responseBody = JSON.stringify(matchingMock.value);
         route.fulfill({
             status: 200,
-            body: JSON.stringify(matchingMock.value),
+            body: responseBody,
         });
     }
     /**
@@ -404,7 +615,6 @@ class RimoriTestEnvironment {
      * @param options - The options for the route. Method defaults to 'GET' if not specified.
      */
     addSupabaseRoute(path, values, options) {
-        console.warn('addSupabaseRoute is not tested');
         const method = options?.method ?? 'GET';
         const fullPath = `${this.rimoriInfo.url}/rest/v1/${path}`;
         const routeKey = this.createRouteKey(method, fullPath);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rimori/playwright-testing",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Playwright testing utilities for Rimori plugins and workers",
   "license": "Apache-2.0",
   "main": "dist/index.js",