@rimori/playwright-testing 0.2.1 → 0.2.3-next.1

package/dist/core/RimoriTestEnvironment.d.ts

@@ -1,9 +1,13 @@
 import { Page, Request } from '@playwright/test';
 import { UserInfo } from '@rimori/client/dist/controller/SettingsController';
 import { MainPanelAction, Plugin } from '@rimori/client/dist/fromRimori/PluginTypes';
+import { PluginSettings } from './SettingsStateManager';
+import { EventPayload } from '@rimori/client/dist/fromRimori/EventBus';
 interface RimoriTestEnvironmentOptions {
     page: Page;
     pluginId: string;
+    pluginUrl: string;
+    settings?: PluginSettings;
     queryParams?: Record<string, string>;
     userInfo?: Record<string, unknown>;
     installedPlugins?: Plugin[];
@@ -26,6 +30,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;
@@ -34,9 +44,16 @@ export declare class RimoriTestEnvironment {
     private backendRoutes;
     private supabaseRoutes;
     private messageChannelSimulator;
+    private settingsManager;
     constructor(options: RimoriTestEnvironmentOptions);
     private interceptRoutes;
     setup(): Promise<void>;
+    private getRimoriInfo;
+    /**
+     * Sets up the plugin_settings routes to use the SettingsStateManager.
+     * GET returns current state, PATCH updates state, POST creates/updates state.
+     */
+    private setupSettingsRoutes;
     /**
      * Formats text as SSE (Server-Sent Events) response.
      * Since Playwright's route.fulfill() requires complete body, we format as SSE without delays.
@@ -50,6 +67,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.
@@ -68,46 +89,108 @@ export declare class RimoriTestEnvironment {
     private addBackendRoute;
     readonly plugin: {
         /**
-         * Mocks PATCH request for updating plugin_settings.
-         * @param response - The response for PATCH. Defaults to empty array (no rows updated).
-         *                   Should return array with updated row(s) like [{ id: '...' }] if update succeeds.
+         * Manually set the settings state (useful for test setup).
+         * This directly modifies the internal settings state.
+         * @param settings - The settings to set, or null to clear settings
+         */
+        setSettings: (settings: PluginSettings | null) => void;
+        /**
+         * Get the current settings state (useful for assertions).
+         * @returns The current settings or null if no settings exist
+         */
+        getSettings: () => PluginSettings | null;
+        /**
+         * Override the GET handler for plugin_settings (rarely needed).
+         * By default, GET returns the current state from SettingsStateManager.
          */
-        mockSetSettings: (response?: unknown, options?: MockOptions) => void;
+        mockGetSettings: (settingsRow: PluginSettings | null, options?: MockOptions) => void;
         /**
-         * Mocks GET request for fetching plugin_settings.
-         * @param settingsRow - The full row object from plugin_settings table, or null if not found.
-         *                      Should include: { id, plugin_id, guild_id, settings, is_guild_setting, user_id }.
-         *                      If null, simulates no settings exist (triggers INSERT flow).
+         * Override the PATCH handler for plugin_settings (rarely needed).
+         * By default, PATCH updates the state in SettingsStateManager.
          */
-        mockGetSettings: (settingsRow: {
-            id?: string;
-            plugin_id?: string;
-            guild_id?: string;
-            settings?: Record<string, unknown>;
-            is_guild_setting?: boolean;
-            user_id?: string | null;
-        } | null, options?: MockOptions) => void;
+        mockSetSettings: (response: unknown, options?: MockOptions) => void;
         /**
-         * Mocks POST request for inserting plugin_settings.
-         * @param response - The response for POST. Defaults to success response with inserted row.
+         * Override the POST handler for plugin_settings (rarely needed).
+         * By default, POST inserts/updates the state in SettingsStateManager.
          */
-        mockInsertSettings: (response?: unknown, options?: MockOptions) => void;
+        mockInsertSettings: (response: unknown, options?: MockOptions) => void;
         mockGetUserInfo: (userInfo: Partial<UserInfo>, options?: MockOptions) => void;
         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: EventPayload, 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 +224,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;
     };