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

package/dist/core/MessageChannelSimulator.d.ts

@@ -1,92 +1,21 @@
 import type { Page } from '@playwright/test';
-type Language = {
-    code: string;
-    name: string;
-    native: string;
-    capitalized: string;
-    uppercase: string;
-};
-type StudyBuddy = {
-    id: string;
-    name: string;
-    description: string;
-    avatarUrl: string;
-    voiceId: string;
-    aiPersonality: string;
-};
-export type UserInfo = {
-    mother_tongue: Language;
-    target_language: Language;
-    skill_level_reading: string;
-    skill_level_writing: string;
-    skill_level_grammar: string;
-    skill_level_speaking: string;
-    skill_level_listening: string;
-    skill_level_understanding: string;
-    goal_longterm: string;
-    goal_weekly: string;
-    study_buddy: StudyBuddy;
-    story_genre: string;
-    study_duration: number;
-    motivation_type: string;
-    onboarding_completed: boolean;
-    context_menu_on_select: boolean;
-    user_name?: string;
-    target_country: string;
-    target_city?: string;
-};
-type RimoriGuild = {
-    id: string;
-    longTermGoalOverride: string;
-    allowUserPluginSettings: boolean;
-};
-type PluginInfo = {
-    id: string;
-    title: string;
-    description: string;
-    logo: string;
-    url: string;
-};
-type RimoriInfo = {
-    url: string;
-    key: string;
-    backendUrl: string;
-    token: string;
-    expiration: Date;
-    tablePrefix: string;
-    pluginId: string;
-    guild: RimoriGuild;
-    installedPlugins: PluginInfo[];
-    profile: UserInfo;
-    mainPanelPlugin?: PluginInfo;
-    sidePanelPlugin?: PluginInfo;
-};
-type EventBusMessage = {
-    timestamp: string;
-    sender: string;
-    topic: string;
-    data: unknown;
-    debug: boolean;
-    eventId?: number;
-};
+import { UserInfo, RimoriInfo, EventBusMessage, EventPayload } from '@rimori/client';
 type MessageChannelSimulatorArgs = {
     page: Page;
     pluginId: string;
+    rimoriInfo: RimoriInfo;
     queryParams?: Record<string, string>;
-    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;
     private readonly queryParams;
-    private readonly baseUserInfo;
-    private readonly providedInfo?;
+    private readonly rimoriInfo;
     private readonly listeners;
     private readonly autoResponders;
     private readonly pendingOutbound;
-    private currentUserInfo;
-    private currentRimoriInfo;
     private isReady;
     private instanceId;
     /**
@@ -106,26 +35,33 @@ export declare class MessageChannelSimulator {
     /**
      * Sends an event into the plugin as though the Rimori parent emitted it.
      */
-    emit(topic: string, data: unknown, sender?: string): Promise<void>;
+    emit(topic: string, data: EventPayload, sender?: string): Promise<void>;
     /**
      * Registers a handler for events emitted from the plugin.
      */
     on(topic: string, handler: EventListener): () => void;
     /**
-     * Overrides the default profile returned by the auto responders.
+     * 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 user info.
      */
-    setUserInfo(overrides: Partial<UserInfo>): void;
-    getRimoriInfo(): RimoriInfo | null;
+    setUserInfo(userInfo: UserInfo): void;
+    getRimoriInfo(): RimoriInfo;
     private setupMessageChannel;
     private sendToPlugin;
     private flushPending;
     private handlePortMessage;
     private dispatchEvent;
     private maybeRespond;
-    private buildRimoriInfo;
-    private serializeRimoriInfo;
     private cloneUserInfo;
-    private mergeUserInfo;
     private registerAutoResponders;
     private cloneRimoriInfo;
 }

package/dist/core/MessageChannelSimulator.js

@@ -2,7 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MessageChannelSimulator = void 0;
 const node_crypto_1 = require("node:crypto");
-const default_user_info_1 = require("../fixtures/default-user-info");
 class MessageChannelSimulator {
     /**
      * Creates a simulator that mimics the Rimori host for plugin tests.
@@ -15,22 +14,19 @@ class MessageChannelSimulator {
         this.listeners = new Map();
         this.autoResponders = new Map();
         this.pendingOutbound = [];
-        this.currentRimoriInfo = null;
         this.isReady = false;
         this.instanceId = (0, node_crypto_1.randomUUID)();
         this.page = page;
         this.pluginId = pluginId;
         this.queryParams = queryParams ?? {};
-        this.baseUserInfo = this.cloneUserInfo(default_user_info_1.DEFAULT_USER_INFO);
-        this.currentUserInfo = this.cloneUserInfo(default_user_info_1.DEFAULT_USER_INFO);
-        this.providedInfo = rimoriInfo ? this.cloneRimoriInfo(rimoriInfo) : undefined;
+        this.rimoriInfo = this.cloneRimoriInfo(rimoriInfo);
         this.registerAutoResponders();
     }
     get defaultUserInfo() {
-        return this.cloneUserInfo(this.baseUserInfo);
+        return this.cloneUserInfo(this.rimoriInfo.profile);
     }
     get userInfo() {
-        return this.cloneUserInfo(this.currentUserInfo);
+        return this.cloneUserInfo(this.rimoriInfo.profile);
     }
     /**
      * Injects the handshake shims so the plugin talks to this simulator.
@@ -112,6 +108,7 @@ class MessageChannelSimulator {
         const message = {
             event: {
                 timestamp: new Date().toISOString(),
+                eventId: Math.floor(Math.random() * 1000000),
                 sender,
                 topic,
                 data,
@@ -143,25 +140,52 @@ class MessageChannelSimulator {
         };
     }
     /**
-     * Overrides the default profile returned by the auto responders.
+     * 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
      */
-    setUserInfo(overrides) {
-        this.currentUserInfo = this.mergeUserInfo(this.currentUserInfo, overrides);
-        if (this.currentRimoriInfo) {
-            this.currentRimoriInfo.profile = this.cloneUserInfo(this.currentUserInfo);
-        }
+    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 user info.
+     */
+    setUserInfo(userInfo) {
+        this.rimoriInfo.profile = userInfo;
     }
     getRimoriInfo() {
-        return this.currentRimoriInfo ? this.cloneRimoriInfo(this.currentRimoriInfo) : null;
+        return this.cloneRimoriInfo(this.rimoriInfo);
     }
     async setupMessageChannel() {
         if (this.isReady) {
             return;
         }
-        const rimoriInfo = this.buildRimoriInfo();
-        this.currentRimoriInfo = rimoriInfo;
-        const serialized = this.serializeRimoriInfo(rimoriInfo);
-        await this.page.evaluate(({ pluginId, queryParams, instanceId, rimoriInfo: info, }) => {
+        await this.page.evaluate(({ pluginId, queryParams, instanceId, rimoriInfo, }) => {
             const channel = new MessageChannel();
             channel.port1.onmessage = (event) => {
                 // @ts-expect-error binding injected via exposeBinding
@@ -176,10 +200,7 @@ class MessageChannelSimulator {
                     pluginId,
                     instanceId,
                     queryParams,
-                    rimoriInfo: {
-                        ...info,
-                        expiration: new Date(info.expiration),
-                    },
+                    rimoriInfo,
                 },
                 ports: [channel.port2],
             });
@@ -188,7 +209,7 @@ class MessageChannelSimulator {
             pluginId: this.pluginId,
             queryParams: this.queryParams,
             instanceId: this.instanceId,
-            rimoriInfo: serialized,
+            rimoriInfo: this.rimoriInfo,
         });
         this.isReady = true;
         await this.flushPending();
@@ -215,21 +236,33 @@ class MessageChannelSimulator {
             return;
         }
         if ('event' in payload && payload.event) {
-            console.log('[MessageChannelSimulator] handlePortMessage - received event:', payload.event.topic, 'from:', payload.event.sender);
+            // console.log(
+            //   '[MessageChannelSimulator] handlePortMessage - received event:',
+            //   payload.event.topic,
+            //   'from:',
+            //   payload.event.sender,
+            // );
             await this.dispatchEvent(payload.event);
             await this.maybeRespond(payload.event);
             return;
         }
     }
     async dispatchEvent(event) {
-        console.log('[MessageChannelSimulator] dispatchEvent - topic:', event.topic, 'sender:', event.sender, 'listeners:', this.listeners.has(event.topic) ? this.listeners.get(event.topic)?.size : 0);
+        // console.log(
+        //   '[MessageChannelSimulator] dispatchEvent - topic:',
+        //   event.topic,
+        //   'sender:',
+        //   event.sender,
+        //   'listeners:',
+        //   this.listeners.has(event.topic) ? this.listeners.get(event.topic)?.size : 0,
+        // );
         const handlers = this.listeners.get(event.topic);
         if (!handlers?.size) {
             console.log('[MessageChannelSimulator] No handlers found for topic:', event.topic);
             console.log('[MessageChannelSimulator] Available topics:', Array.from(this.listeners.keys()));
             return;
         }
-        console.log('[MessageChannelSimulator] Calling', handlers.size, 'handler(s) for topic:', event.topic);
+        // console.log('[MessageChannelSimulator] Calling', handlers.size, 'handler(s) for topic:', event.topic);
         for (const handler of handlers) {
             await handler(event);
         }
@@ -252,90 +285,16 @@ class MessageChannelSimulator {
             },
         });
     }
-    buildRimoriInfo() {
-        if (this.providedInfo) {
-            const clone = this.cloneRimoriInfo(this.providedInfo);
-            clone.profile = this.cloneUserInfo(this.currentUserInfo);
-            clone.pluginId = this.pluginId;
-            clone.tablePrefix = clone.tablePrefix || `${this.pluginId}_`;
-            return clone;
-        }
-        return {
-            url: 'http://localhost:3500',
-            key: 'rimori-sdk-key',
-            backendUrl: 'http://localhost:3501',
-            token: 'rimori-token',
-            expiration: new Date(Date.now() + 60 * 60 * 1000),
-            tablePrefix: `${this.pluginId}_`,
-            pluginId: this.pluginId,
-            guild: {
-                id: 'guild-test',
-                longTermGoalOverride: '',
-                allowUserPluginSettings: true,
-            },
-            installedPlugins: [
-                {
-                    id: this.pluginId,
-                    title: 'Test Plugin',
-                    description: 'Playwright testing plugin',
-                    logo: '',
-                    url: 'https://plugins.rimori.localhost',
-                },
-            ],
-            profile: this.cloneUserInfo(this.currentUserInfo),
-        };
-    }
-    serializeRimoriInfo(info) {
-        return {
-            ...info,
-            expiration: info.expiration.toISOString(),
-        };
-    }
     cloneUserInfo(input) {
         return JSON.parse(JSON.stringify(input));
     }
-    mergeUserInfo(current, overrides) {
-        const clone = this.cloneUserInfo(current);
-        if (overrides.mother_tongue) {
-            clone.mother_tongue = {
-                ...clone.mother_tongue,
-                ...overrides.mother_tongue,
-            };
-        }
-        if (overrides.target_language) {
-            clone.target_language = {
-                ...clone.target_language,
-                ...overrides.target_language,
-            };
-        }
-        if (overrides.study_buddy) {
-            clone.study_buddy = {
-                ...clone.study_buddy,
-                ...overrides.study_buddy,
-            };
-        }
-        const { mother_tongue, target_language, study_buddy, ...rest } = overrides;
-        for (const [key, value] of Object.entries(rest)) {
-            if (value === undefined) {
-                continue;
-            }
-            clone[key] = value;
-        }
-        return clone;
-    }
     registerAutoResponders() {
-        this.autoResponders.set('global.supabase.requestAccess', () => this.buildRimoriInfo());
-        this.autoResponders.set('global.profile.requestUserInfo', () => this.cloneUserInfo(this.currentUserInfo));
-        this.autoResponders.set('global.profile.getUserInfo', () => this.cloneUserInfo(this.currentUserInfo));
+        this.autoResponders.set('global.supabase.requestAccess', () => this.cloneRimoriInfo(this.rimoriInfo));
+        this.autoResponders.set('global.profile.requestUserInfo', () => this.cloneUserInfo(this.rimoriInfo.profile));
+        this.autoResponders.set('global.profile.getUserInfo', () => this.cloneUserInfo(this.rimoriInfo.profile));
     }
     cloneRimoriInfo(info) {
-        return {
-            ...info,
-            expiration: new Date(info.expiration),
-            guild: { ...info.guild },
-            installedPlugins: info.installedPlugins.map((plugin) => ({ ...plugin })),
-            profile: this.cloneUserInfo(info.profile),
-        };
+        return JSON.parse(JSON.stringify(info));
     }
 }
 exports.MessageChannelSimulator = MessageChannelSimulator;

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[];
@@ -40,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.
@@ -78,30 +89,31 @@ 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
          */
-        mockSetSettings: (response?: unknown, options?: MockOptions) => void;
+        getSettings: () => PluginSettings | null;
         /**
-         * 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 GET handler for plugin_settings (rarely needed).
+         * By default, GET returns the current state from 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;
+        mockGetSettings: (settingsRow: PluginSettings | null, 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 PATCH handler for plugin_settings (rarely needed).
+         * By default, PATCH updates the state in SettingsStateManager.
          */
-        mockInsertSettings: (response?: unknown, options?: MockOptions) => void;
+        mockSetSettings: (response: unknown, options?: MockOptions) => void;
+        /**
+         * Override the POST handler for plugin_settings (rarely needed).
+         * By default, POST inserts/updates the state in SettingsStateManager.
+         */
+        mockInsertSettings: (response: unknown, options?: MockOptions) => void;
         mockGetUserInfo: (userInfo: Partial<UserInfo>, options?: MockOptions) => void;
         mockGetPluginInfo: (pluginInfo: Plugin, options?: MockOptions) => void;
     };
@@ -122,17 +134,63 @@ export declare class RimoriTestEnvironment {
          * @param options - Mock options including HTTP method (defaults to 'GET' if not specified)
          */
         mockFrom: (tableName: string, value: unknown, options?: MockOptions) => void;
-        mockTable: () => 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.
@@ -166,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;
     };