@react-three-dom/playwright 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,279 @@
+import * as _playwright_test from '@playwright/test';
+import { Page } from '@playwright/test';
+
+interface ObjectMetadata {
+    uuid: string;
+    name: string;
+    type: string;
+    visible: boolean;
+    testId?: string;
+    geometryType?: string;
+    materialType?: string;
+    vertexCount?: number;
+    triangleCount?: number;
+    instanceCount?: number;
+    position: [number, number, number];
+    rotation: [number, number, number];
+    scale: [number, number, number];
+    parentUuid: string | null;
+    childrenUuids: string[];
+    boundsDirty: boolean;
+}
+interface ObjectInspection {
+    metadata: ObjectMetadata;
+    worldMatrix: number[];
+    bounds: {
+        min: [number, number, number];
+        max: [number, number, number];
+    };
+    geometry?: {
+        type: string;
+        attributes: Record<string, {
+            itemSize: number;
+            count: number;
+        }>;
+        index?: {
+            count: number;
+        };
+        boundingSphere?: {
+            center: [number, number, number];
+            radius: number;
+        };
+    };
+    material?: {
+        type: string;
+        color?: string;
+        map?: string;
+        uniforms?: Record<string, unknown>;
+        transparent?: boolean;
+        opacity?: number;
+        side?: number;
+    };
+    userData: Record<string, unknown>;
+}
+interface SnapshotNode {
+    uuid: string;
+    name: string;
+    type: string;
+    testId?: string;
+    visible: boolean;
+    position: [number, number, number];
+    rotation: [number, number, number];
+    scale: [number, number, number];
+    children: SnapshotNode[];
+}
+interface SceneSnapshot {
+    timestamp: number;
+    objectCount: number;
+    tree: SnapshotNode;
+}
+
+interface WaitForSceneReadyOptions {
+    /** How many consecutive stable polls are required. Default: 3 */
+    stableChecks?: number;
+    /** Interval between polls in ms. Default: 100 */
+    pollIntervalMs?: number;
+    /** Overall timeout in ms. Default: 10_000 */
+    timeout?: number;
+}
+/**
+ * Wait until `window.__R3F_DOM__` is available and the scene's object count
+ * has stabilised (no additions or removals) over several consecutive checks.
+ */
+declare function waitForSceneReady(page: Page, options?: WaitForSceneReadyOptions): Promise<void>;
+interface WaitForIdleOptions {
+    /** Number of consecutive idle frames required. Default: 10 */
+    idleFrames?: number;
+    /** Overall timeout in ms. Default: 10_000 */
+    timeout?: number;
+}
+/**
+ * Wait until no object properties have changed for a number of consecutive
+ * animation frames. Useful after triggering animations or interactions.
+ *
+ * This works by taking successive snapshots and comparing them. When the
+ * JSON representation is unchanged for `idleFrames` consecutive rAF
+ * callbacks, the scene is considered idle.
+ */
+declare function waitForIdle(page: Page, options?: WaitForIdleOptions): Promise<void>;
+
+declare class R3FFixture {
+    private readonly _page;
+    constructor(_page: Page);
+    /** The underlying Playwright Page. */
+    get page(): Page;
+    /** Get object metadata by testId or uuid. Returns null if not found. */
+    getObject(idOrUuid: string): Promise<ObjectMetadata | null>;
+    /** Get heavy inspection data (Tier 2) by testId or uuid. */
+    inspect(idOrUuid: string): Promise<ObjectInspection | null>;
+    /** Take a full scene snapshot. */
+    snapshot(): Promise<SceneSnapshot | null>;
+    /** Get the total number of tracked objects. */
+    getCount(): Promise<number>;
+    /** Click a 3D object by testId or uuid. */
+    click(idOrUuid: string): Promise<void>;
+    /** Double-click a 3D object by testId or uuid. */
+    doubleClick(idOrUuid: string): Promise<void>;
+    /** Right-click / context-menu a 3D object by testId or uuid. */
+    contextMenu(idOrUuid: string): Promise<void>;
+    /** Hover over a 3D object by testId or uuid. */
+    hover(idOrUuid: string): Promise<void>;
+    /** Drag a 3D object with a world-space delta vector. */
+    drag(idOrUuid: string, delta: {
+        x: number;
+        y: number;
+        z: number;
+    }): Promise<void>;
+    /** Dispatch a wheel/scroll event on a 3D object. */
+    wheel(idOrUuid: string, options?: {
+        deltaY?: number;
+        deltaX?: number;
+    }): Promise<void>;
+    /** Click empty space to trigger onPointerMissed handlers. */
+    pointerMiss(): Promise<void>;
+    /**
+     * Wait until the scene is ready — `window.__R3F_DOM__` is available and
+     * the object count has stabilised across several consecutive checks.
+     */
+    waitForSceneReady(options?: WaitForSceneReadyOptions): Promise<void>;
+    /**
+     * Wait until no object properties have changed for a number of consecutive
+     * animation frames. Useful after triggering interactions or animations.
+     */
+    waitForIdle(options?: WaitForIdleOptions): Promise<void>;
+    /** Select a 3D object by testId or uuid (highlights in scene). */
+    select(idOrUuid: string): Promise<void>;
+    /** Clear the current selection. */
+    clearSelection(): Promise<void>;
+}
+declare const test: _playwright_test.TestType<_playwright_test.PlaywrightTestArgs & _playwright_test.PlaywrightTestOptions & {
+    r3f: R3FFixture;
+}, _playwright_test.PlaywrightWorkerArgs & _playwright_test.PlaywrightWorkerOptions>;
+
+/**
+ * Extend Playwright's `expect` with 3D-native matchers.
+ *
+ * Usage:
+ * ```ts
+ * import { test, expect } from '@react-three-dom/playwright';
+ *
+ * test('chair exists', async ({ page, r3f }) => {
+ *   await r3f.waitForSceneReady();
+ *   await expect(r3f).toExist('chair-primary');
+ * });
+ * ```
+ */
+declare const expect: _playwright_test.Expect<{
+    toExist(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, idOrUuid: string): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: string;
+        actual: ObjectMetadata | null;
+    }>;
+    toBeVisible(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, idOrUuid: string): Promise<{
+        pass: false;
+        message: () => string;
+        name: string;
+        expected?: undefined;
+        actual?: undefined;
+    } | {
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: boolean;
+        actual: boolean;
+    }>;
+    toBeInFrustum(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, idOrUuid: string): Promise<{
+        pass: false;
+        message: () => string;
+        name: string;
+        expected?: undefined;
+        actual?: undefined;
+    } | {
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: string;
+        actual: {
+            min: [number, number, number];
+            max: [number, number, number];
+        };
+    }>;
+    toHavePosition(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, idOrUuid: string, expected: [number, number, number], tolerance?: any): Promise<{
+        pass: false;
+        message: () => string;
+        name: string;
+        expected?: undefined;
+        actual?: undefined;
+    } | {
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: [number, number, number];
+        actual: [number, number, number];
+    }>;
+    toHaveBounds(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, idOrUuid: string, expected: {
+        min: [number, number, number];
+        max: [number, number, number];
+    }, tolerance?: any): Promise<{
+        pass: false;
+        message: () => string;
+        name: string;
+        expected?: undefined;
+        actual?: undefined;
+    } | {
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: {
+            min: [number, number, number];
+            max: [number, number, number];
+        };
+        actual: {
+            min: [number, number, number];
+            max: [number, number, number];
+        };
+    }>;
+    toHaveInstanceCount(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, idOrUuid: string, expectedCount: number): Promise<{
+        pass: false;
+        message: () => string;
+        name: string;
+        expected?: undefined;
+        actual?: undefined;
+    } | {
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: number;
+        actual: number;
+    }>;
+}>;
+interface R3FMatcherReceiver {
+    getObject(idOrUuid: string): Promise<ObjectMetadata | null>;
+    inspect(idOrUuid: string): Promise<ObjectInspection | null>;
+}
+
+/** Click a 3D object by its testId or uuid. */
+declare function click(page: Page, idOrUuid: string): Promise<void>;
+/** Double-click a 3D object by its testId or uuid. */
+declare function doubleClick(page: Page, idOrUuid: string): Promise<void>;
+/** Right-click / context-menu a 3D object by its testId or uuid. */
+declare function contextMenu(page: Page, idOrUuid: string): Promise<void>;
+/** Hover over a 3D object by its testId or uuid. */
+declare function hover(page: Page, idOrUuid: string): Promise<void>;
+/** Drag a 3D object by its testId or uuid with a given world-space delta. */
+declare function drag(page: Page, idOrUuid: string, delta: {
+    x: number;
+    y: number;
+    z: number;
+}): Promise<void>;
+/** Dispatch a wheel/scroll event on a 3D object. */
+declare function wheel(page: Page, idOrUuid: string, options?: {
+    deltaY?: number;
+    deltaX?: number;
+}): Promise<void>;
+/** Click empty space to trigger onPointerMissed handlers. */
+declare function pointerMiss(page: Page): Promise<void>;
+
+export { type ObjectInspection, type ObjectMetadata, R3FFixture, type SceneSnapshot, type SnapshotNode, type WaitForIdleOptions, type WaitForSceneReadyOptions, click, contextMenu, doubleClick, drag, expect, hover, pointerMiss, test, waitForIdle, waitForSceneReady, wheel };

package/dist/index.d.ts

@@ -0,0 +1,279 @@
+import * as _playwright_test from '@playwright/test';
+import { Page } from '@playwright/test';
+
+interface ObjectMetadata {
+    uuid: string;
+    name: string;
+    type: string;
+    visible: boolean;
+    testId?: string;
+    geometryType?: string;
+    materialType?: string;
+    vertexCount?: number;
+    triangleCount?: number;
+    instanceCount?: number;
+    position: [number, number, number];
+    rotation: [number, number, number];
+    scale: [number, number, number];
+    parentUuid: string | null;
+    childrenUuids: string[];
+    boundsDirty: boolean;
+}
+interface ObjectInspection {
+    metadata: ObjectMetadata;
+    worldMatrix: number[];
+    bounds: {
+        min: [number, number, number];
+        max: [number, number, number];
+    };
+    geometry?: {
+        type: string;
+        attributes: Record<string, {
+            itemSize: number;
+            count: number;
+        }>;
+        index?: {
+            count: number;
+        };
+        boundingSphere?: {
+            center: [number, number, number];
+            radius: number;
+        };
+    };
+    material?: {
+        type: string;
+        color?: string;
+        map?: string;
+        uniforms?: Record<string, unknown>;
+        transparent?: boolean;
+        opacity?: number;
+        side?: number;
+    };
+    userData: Record<string, unknown>;
+}
+interface SnapshotNode {
+    uuid: string;
+    name: string;
+    type: string;
+    testId?: string;
+    visible: boolean;
+    position: [number, number, number];
+    rotation: [number, number, number];
+    scale: [number, number, number];
+    children: SnapshotNode[];
+}
+interface SceneSnapshot {
+    timestamp: number;
+    objectCount: number;
+    tree: SnapshotNode;
+}
+
+interface WaitForSceneReadyOptions {
+    /** How many consecutive stable polls are required. Default: 3 */
+    stableChecks?: number;
+    /** Interval between polls in ms. Default: 100 */
+    pollIntervalMs?: number;
+    /** Overall timeout in ms. Default: 10_000 */
+    timeout?: number;
+}
+/**
+ * Wait until `window.__R3F_DOM__` is available and the scene's object count
+ * has stabilised (no additions or removals) over several consecutive checks.
+ */
+declare function waitForSceneReady(page: Page, options?: WaitForSceneReadyOptions): Promise<void>;
+interface WaitForIdleOptions {
+    /** Number of consecutive idle frames required. Default: 10 */
+    idleFrames?: number;
+    /** Overall timeout in ms. Default: 10_000 */
+    timeout?: number;
+}
+/**
+ * Wait until no object properties have changed for a number of consecutive
+ * animation frames. Useful after triggering animations or interactions.
+ *
+ * This works by taking successive snapshots and comparing them. When the
+ * JSON representation is unchanged for `idleFrames` consecutive rAF
+ * callbacks, the scene is considered idle.
+ */
+declare function waitForIdle(page: Page, options?: WaitForIdleOptions): Promise<void>;
+
+declare class R3FFixture {
+    private readonly _page;
+    constructor(_page: Page);
+    /** The underlying Playwright Page. */
+    get page(): Page;
+    /** Get object metadata by testId or uuid. Returns null if not found. */
+    getObject(idOrUuid: string): Promise<ObjectMetadata | null>;
+    /** Get heavy inspection data (Tier 2) by testId or uuid. */
+    inspect(idOrUuid: string): Promise<ObjectInspection | null>;
+    /** Take a full scene snapshot. */
+    snapshot(): Promise<SceneSnapshot | null>;
+    /** Get the total number of tracked objects. */
+    getCount(): Promise<number>;
+    /** Click a 3D object by testId or uuid. */
+    click(idOrUuid: string): Promise<void>;
+    /** Double-click a 3D object by testId or uuid. */
+    doubleClick(idOrUuid: string): Promise<void>;
+    /** Right-click / context-menu a 3D object by testId or uuid. */
+    contextMenu(idOrUuid: string): Promise<void>;
+    /** Hover over a 3D object by testId or uuid. */
+    hover(idOrUuid: string): Promise<void>;
+    /** Drag a 3D object with a world-space delta vector. */
+    drag(idOrUuid: string, delta: {
+        x: number;
+        y: number;
+        z: number;
+    }): Promise<void>;
+    /** Dispatch a wheel/scroll event on a 3D object. */
+    wheel(idOrUuid: string, options?: {
+        deltaY?: number;
+        deltaX?: number;
+    }): Promise<void>;
+    /** Click empty space to trigger onPointerMissed handlers. */
+    pointerMiss(): Promise<void>;
+    /**
+     * Wait until the scene is ready — `window.__R3F_DOM__` is available and
+     * the object count has stabilised across several consecutive checks.
+     */
+    waitForSceneReady(options?: WaitForSceneReadyOptions): Promise<void>;
+    /**
+     * Wait until no object properties have changed for a number of consecutive
+     * animation frames. Useful after triggering interactions or animations.
+     */
+    waitForIdle(options?: WaitForIdleOptions): Promise<void>;
+    /** Select a 3D object by testId or uuid (highlights in scene). */
+    select(idOrUuid: string): Promise<void>;
+    /** Clear the current selection. */
+    clearSelection(): Promise<void>;
+}
+declare const test: _playwright_test.TestType<_playwright_test.PlaywrightTestArgs & _playwright_test.PlaywrightTestOptions & {
+    r3f: R3FFixture;
+}, _playwright_test.PlaywrightWorkerArgs & _playwright_test.PlaywrightWorkerOptions>;
+
+/**
+ * Extend Playwright's `expect` with 3D-native matchers.
+ *
+ * Usage:
+ * ```ts
+ * import { test, expect } from '@react-three-dom/playwright';
+ *
+ * test('chair exists', async ({ page, r3f }) => {
+ *   await r3f.waitForSceneReady();
+ *   await expect(r3f).toExist('chair-primary');
+ * });
+ * ```
+ */
+declare const expect: _playwright_test.Expect<{
+    toExist(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, idOrUuid: string): Promise<{
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: string;
+        actual: ObjectMetadata | null;
+    }>;
+    toBeVisible(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, idOrUuid: string): Promise<{
+        pass: false;
+        message: () => string;
+        name: string;
+        expected?: undefined;
+        actual?: undefined;
+    } | {
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: boolean;
+        actual: boolean;
+    }>;
+    toBeInFrustum(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, idOrUuid: string): Promise<{
+        pass: false;
+        message: () => string;
+        name: string;
+        expected?: undefined;
+        actual?: undefined;
+    } | {
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: string;
+        actual: {
+            min: [number, number, number];
+            max: [number, number, number];
+        };
+    }>;
+    toHavePosition(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, idOrUuid: string, expected: [number, number, number], tolerance?: any): Promise<{
+        pass: false;
+        message: () => string;
+        name: string;
+        expected?: undefined;
+        actual?: undefined;
+    } | {
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: [number, number, number];
+        actual: [number, number, number];
+    }>;
+    toHaveBounds(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, idOrUuid: string, expected: {
+        min: [number, number, number];
+        max: [number, number, number];
+    }, tolerance?: any): Promise<{
+        pass: false;
+        message: () => string;
+        name: string;
+        expected?: undefined;
+        actual?: undefined;
+    } | {
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: {
+            min: [number, number, number];
+            max: [number, number, number];
+        };
+        actual: {
+            min: [number, number, number];
+            max: [number, number, number];
+        };
+    }>;
+    toHaveInstanceCount(this: _playwright_test.ExpectMatcherState, r3f: R3FMatcherReceiver, idOrUuid: string, expectedCount: number): Promise<{
+        pass: false;
+        message: () => string;
+        name: string;
+        expected?: undefined;
+        actual?: undefined;
+    } | {
+        pass: boolean;
+        message: () => string;
+        name: string;
+        expected: number;
+        actual: number;
+    }>;
+}>;
+interface R3FMatcherReceiver {
+    getObject(idOrUuid: string): Promise<ObjectMetadata | null>;
+    inspect(idOrUuid: string): Promise<ObjectInspection | null>;
+}
+
+/** Click a 3D object by its testId or uuid. */
+declare function click(page: Page, idOrUuid: string): Promise<void>;
+/** Double-click a 3D object by its testId or uuid. */
+declare function doubleClick(page: Page, idOrUuid: string): Promise<void>;
+/** Right-click / context-menu a 3D object by its testId or uuid. */
+declare function contextMenu(page: Page, idOrUuid: string): Promise<void>;
+/** Hover over a 3D object by its testId or uuid. */
+declare function hover(page: Page, idOrUuid: string): Promise<void>;
+/** Drag a 3D object by its testId or uuid with a given world-space delta. */
+declare function drag(page: Page, idOrUuid: string, delta: {
+    x: number;
+    y: number;
+    z: number;
+}): Promise<void>;
+/** Dispatch a wheel/scroll event on a 3D object. */
+declare function wheel(page: Page, idOrUuid: string, options?: {
+    deltaY?: number;
+    deltaX?: number;
+}): Promise<void>;
+/** Click empty space to trigger onPointerMissed handlers. */
+declare function pointerMiss(page: Page): Promise<void>;
+
+export { type ObjectInspection, type ObjectMetadata, R3FFixture, type SceneSnapshot, type SnapshotNode, type WaitForIdleOptions, type WaitForSceneReadyOptions, click, contextMenu, doubleClick, drag, expect, hover, pointerMiss, test, waitForIdle, waitForSceneReady, wheel };