@scenetest/scenes 0.1.0

package/dist/message-bus.js

@@ -0,0 +1,74 @@
+/**
+ * Message bus for inter-actor coordination.
+ *
+ * Key behavior: Messages are "sticky" - they persist on the bus.
+ * If you listen AFTER a message was emitted, you still receive it (once).
+ * This prevents race conditions when declaring causality early in scenes.
+ */
+export class MessageBus {
+    emittedMessages = new Set();
+    listeners = new Map();
+    /**
+     * Emit a message to the bus.
+     * All current and future listeners for this message will be triggered.
+     */
+    emit(message) {
+        this.emittedMessages.add(message);
+        // Trigger any waiting listeners
+        const callbacks = this.listeners.get(message);
+        if (callbacks) {
+            for (const cb of callbacks) {
+                cb();
+            }
+            this.listeners.delete(message);
+        }
+    }
+    /**
+     * Wait for a message to be emitted.
+     * If the message was already emitted, resolves immediately.
+     */
+    waitFor(message, timeout = 30000) {
+        // If already emitted, resolve immediately (sticky behavior)
+        if (this.emittedMessages.has(message)) {
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                // Remove this listener on timeout
+                const callbacks = this.listeners.get(message);
+                if (callbacks) {
+                    const index = callbacks.indexOf(callback);
+                    if (index !== -1) {
+                        callbacks.splice(index, 1);
+                    }
+                    if (callbacks.length === 0) {
+                        this.listeners.delete(message);
+                    }
+                }
+                reject(new Error(`Timeout waiting for message: "${message}"`));
+            }, timeout);
+            const callback = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+            const callbacks = this.listeners.get(message) || [];
+            callbacks.push(callback);
+            this.listeners.set(message, callbacks);
+        });
+    }
+    /**
+     * Check if a message has been emitted.
+     */
+    hasEmitted(message) {
+        return this.emittedMessages.has(message);
+    }
+    /**
+     * Clear all messages and listeners.
+     * Call this between scene runs.
+     */
+    clear() {
+        this.emittedMessages.clear();
+        this.listeners.clear();
+    }
+}
+//# sourceMappingURL=message-bus.js.map

package/dist/message-bus.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-bus.js","sourceRoot":"","sources":["../src/message-bus.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,OAAO,UAAU;IACb,eAAe,GAAG,IAAI,GAAG,EAAU,CAAA;IACnC,SAAS,GAAG,IAAI,GAAG,EAA6B,CAAA;IAExD;;;OAGG;IACH,IAAI,CAAC,OAAe;QAClB,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QAEjC,gCAAgC;QAChC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;QAC7C,IAAI,SAAS,EAAE,CAAC;YACd,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;gBAC3B,EAAE,EAAE,CAAA;YACN,CAAC;YACD,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;QAChC,CAAC;IACH,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,OAAe,EAAE,OAAO,GAAG,KAAK;QACtC,4DAA4D;QAC5D,IAAI,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;YACtC,OAAO,OAAO,CAAC,OAAO,EAAE,CAAA;QAC1B,CAAC;QAED,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,kCAAkC;gBAClC,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;gBAC7C,IAAI,SAAS,EAAE,CAAC;oBACd,MAAM,KAAK,GAAG,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;oBACzC,IAAI,KAAK,KAAK,CAAC,CAAC,EAAE,CAAC;wBACjB,SAAS,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;oBAC5B,CAAC;oBACD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;wBAC3B,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;oBAChC,CAAC;gBACH,CAAC;gBACD,MAAM,CAAC,IAAI,KAAK,CAAC,iCAAiC,OAAO,GAAG,CAAC,CAAC,CAAA;YAChE,CAAC,EAAE,OAAO,CAAC,CAAA;YAEX,MAAM,QAAQ,GAAG,GAAG,EAAE;gBACpB,YAAY,CAAC,KAAK,CAAC,CAAA;gBACnB,OAAO,EAAE,CAAA;YACX,CAAC,CAAA;YAED,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,CAAA;YACnD,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;YACxB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,SAAS,CAAC,CAAA;QACxC,CAAC,CAAC,CAAA;IACJ,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,OAAe;QACxB,OAAO,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IAC1C,CAAC;IAED;;;OAGG;IACH,KAAK;QACH,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,CAAA;QAC5B,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAA;IACxB,CAAC;CACF"}

package/dist/reactive.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Reactive flow execution model.
+ *
+ * In the standard `scene()` model, `await` is the trigger — actions queue
+ * on a chain and execute only when awaited.  The test writer carries a
+ * mental timeline: "has this happened yet?  do I need to wait?"
+ *
+ * In the reactive `flow()` model:
+ *
+ *   1. Actor DSL calls are **declarations** — they push to a persistent
+ *      per-actor queue and return immediately.
+ *   2. After the flow function returns, all actors **drain their queues
+ *      concurrently** — each actor advances through its own queue as fast
+ *      as the DOM allows.
+ *   3. `see()`, `seeText()`, and friends already poll/wait for DOM state,
+ *      so cross-actor synchronization happens *through the application
+ *      under test* rather than through `await` ordering in the script.
+ *
+ * This eliminates the "test-writer conceptualisation race condition" —
+ * you can declare `bob.seeText('Hello')` at any point relative to
+ * `alice.click('send')` and it will work, because bob's queue reaches
+ * that instruction whenever it reaches it.  If the text is already
+ * there, it resolves instantly.  If not, it polls.  No `waitUntil`
+ * API is needed.
+ *
+ * @example
+ * ```ts
+ * import { flow } from '@scenetest/scenes'
+ *
+ * flow('two users chat', ({ actor }) => {
+ *   const alice = actor('alice')
+ *   const bob   = actor('bob')
+ *
+ *   // Declaration phase — nothing executes yet
+ *   alice.openTo('/chat')
+ *   alice.see('message-input').typeInto('message-input', 'Hello!').click('send')
+ *
+ *   bob.openTo('/chat')
+ *   bob.seeText('Hello!')
+ *   // ↑ no race: bob will poll for "Hello!" whenever he gets to that
+ *   //   instruction in his queue.  alice may or may not have sent it yet.
+ *
+ *   // When this function returns, browsers launch in parallel,
+ *   // then both actors drain concurrently.
+ * })
+ * ```
+ */
+import type { Page } from 'playwright';
+import type { ActorConfig, Selector, TimelineEntry, ScriptWarning, FlowFn, ConcurrentActorHandle } from './types.js';
+import { MessageBus } from './message-bus.js';
+/**
+ * Concurrent actor handle implementation (declarative / flow model).
+ *
+ * Unlike `SequentialActorHandleImpl`, every DSL method pushes to a single
+ * persistent queue on the actor itself and returns `this`.  Scope lives on
+ * the actor so it flows naturally through the sequential drain.
+ */
+export declare class ConcurrentActorHandleImpl implements ConcurrentActorHandle {
+    private bus;
+    private timeline;
+    private warnings;
+    private actionTimeout;
+    private warnAfter;
+    readonly role: string;
+    readonly id: string;
+    readonly username?: string;
+    readonly email?: string;
+    readonly password?: string;
+    [key: string]: unknown;
+    private _page;
+    private queue;
+    private currentScope;
+    private scopeStack;
+    private warningTriggers;
+    private conditionalMonitors;
+    private _draining;
+    private _aborted;
+    private _abortReason?;
+    /** Registry of all actors in this scene, for [actor.field] interpolation */
+    private _actorRegistry;
+    /** Team metadata for [team.field] interpolation */
+    private _teamMetadata;
+    constructor(role: string, config: ActorConfig, page: Page | null, bus: MessageBus, timeline: TimelineEntry[], warnings: ScriptWarning[], actionTimeout: number, warnAfter: number);
+    /**
+     * Playwright page for this actor.
+     * Available after page initialization (before drain).
+     */
+    get page(): Page;
+    /**
+     * Set the Playwright page for this actor.
+     * Called by the flow runner after declaration, before drain.
+     */
+    _setPage(page: Page): void;
+    /**
+     * Set the actor registry for [actor.field] interpolation.
+     * Called by the flow runner after all actors are created.
+     */
+    _setActorRegistry(registry: Map<string, ConcurrentActorHandle>): void;
+    /**
+     * Set team metadata for [team.field] interpolation.
+     */
+    _setTeamMetadata(metadata: Record<string, string>): void;
+    private push;
+    /** Number of queued actions */
+    get pending(): number;
+    /** Whether this actor has been aborted by a peer failure */
+    get aborted(): boolean;
+    private get scope();
+    openTo(url: string): this;
+    scrollToBottom(): this;
+    see(selector: Selector): this;
+    seeInView(selector: Selector): this;
+    notSee(selector: Selector): this;
+    seeText(text: string): this;
+    seeToast(selector: Selector): this;
+    click(selector?: Selector): this;
+    typeInto(selector: Selector, value: string): this;
+    check(selector: Selector): this;
+    select(selector: Selector, value: string): this;
+    up(selector?: Selector): this;
+    prev(): this;
+    wait(ms: number): this;
+    emit(message: string): this;
+    /**
+     * Block this actor's queue until a message arrives on the bus.
+     *
+     * Because the bus is sticky, if the message was already emitted this
+     * resolves immediately — no race.
+     */
+    waitFor(message: string): this;
+    do(fn: (page: Page) => Promise<void>): this;
+    /**
+     * Queue actions from a text DSL string.
+     *
+     * Parses the multiline string into individual action lines and pushes
+     * each onto the actor's queue.  Returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * user.dsl(`
+     *   openTo /login
+     *   see login-form
+     *   typeInto email alice@test.com
+     *   click submit
+     * `)
+     * user.see('dashboard')
+     * ```
+     */
+    dsl(text: string): this;
+    /**
+     * Interpolate [namespace.field] references in a string.
+     *
+     * Supported namespaces:
+     * - [self.field] — this actor's own fields
+     * - [role.field] — another actor's fields (requires actor registry)
+     * - [team.field] — team metadata
+     */
+    private _interpolate;
+    /**
+     * Register a persistent warning trigger.
+     * If the selector becomes visible during any action, a warning is recorded.
+     * Unlike the `scene()` model, there are no watchers that clear after
+     * each await — warnings are the right primitive for reactive flows.
+     */
+    warnIf(selector: Selector, message: string): void;
+    /**
+     * Conditional monitor — "if this appears at any point, do these things."
+     *
+     * Registers a persistent monitor that polls during every subsequent
+     * action in the actor's queue.  When `selector` becomes visible, the
+     * sub-actions declared inside `callback` execute inline (the current
+     * action is paused, the sub-actions run, then the action resumes).
+     * One-shot: the monitor stops polling after it fires once.
+     *
+     * The callback receives `this` (the actor), but while it runs the
+     * actor's internal queue is temporarily swapped so that DSL calls
+     * push to the monitor's sub-action list instead of the main queue.
+     *
+     * @example
+     * ```ts
+     * alice.openTo('/app')
+     * alice.if('welcome-modal', a => a.click('dismiss'))
+     * alice.see('dashboard')
+     * // If the welcome modal pops up during any action after the if(),
+     * // click('dismiss') fires inline, then the action resumes.
+     * ```
+     */
+    if(selector: Selector, callback: (actor: this) => void): void;
+    /**
+     * Abort this actor's queue. Called by `drainAll` when a peer actor fails.
+     * The actor will throw at its next action boundary.
+     */
+    abort(reason: string): void;
+    /**
+     * Drain the action queue.
+     *
+     * Executes all queued actions sequentially.  Called automatically by the
+     * flow runner after the declaration phase completes.
+     *
+     * Each action is executed with concurrent warning-trigger polling (same
+     * approach as `ActionChainImpl.executeWithWatchers`).
+     */
+    drain(): Promise<void>;
+    /**
+     * Execute a single action while polling monitors concurrently.
+     *
+     * Handles both warning triggers (record a warning) and conditional
+     * monitors (execute sub-actions inline).
+     */
+    private executeWithMonitors;
+}
+/**
+ * Drain all actors concurrently.
+ *
+ * When any actor fails, all others are aborted so they don't hang waiting
+ * for DOM state that will never arrive.  We use `Promise.allSettled` to
+ * collect all results and throw the first *original* (non-abort) error.
+ */
+export declare function drainAll(actors: ConcurrentActorHandleImpl[]): Promise<void>;
+/**
+ * Define a reactive flow.
+ *
+ * Inside the flow function, actor DSL calls just queue actions — nothing
+ * executes.  After the function returns, all actors drain their queues
+ * concurrently through the application.
+ *
+ * @example
+ * ```ts
+ * import { flow } from '@scenetest/scenes'
+ *
+ * flow('user updates profile', ({ actor }) => {
+ *   const user = actor('user')
+ *
+ *   user.openTo('/login')
+ *   user
+ *     .see('login-form')
+ *     .typeInto('email', user.email!)
+ *     .typeInto('password', user.password!)
+ *     .click('submit')
+ *
+ *   user.see('dashboard')
+ *   user.openTo('/profile')
+ *   user
+ *     .see('profile-form')
+ *     .typeInto('name-input', 'New Name')
+ *     .click('save-button')
+ *
+ *   user.seeText('New Name')
+ * })
+ * ```
+ *
+ * @example Multi-actor
+ * ```ts
+ * flow('two users chat', ({ actor }) => {
+ *   const alice = actor('alice')
+ *   const bob   = actor('bob')
+ *
+ *   alice.openTo('/chat')
+ *   alice.see('message-input').typeInto('message-input', 'Hello!').click('send')
+ *
+ *   bob.openTo('/chat')
+ *   bob.seeText('Hello!')
+ * })
+ * ```
+ */
+export declare function flow(name: string, fn: FlowFn): void;
+//# sourceMappingURL=reactive.d.ts.map

package/dist/reactive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reactive.d.ts","sourceRoot":"","sources":["../src/reactive.ts"],"names":[],"mappings":"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"}