@react-three-dom/cypress 0.2.0 → 0.3.0

package/src/index.d.ts

@@ -6,47 +6,91 @@
 //   import '@react-three-dom/cypress';
 // ---------------------------------------------------------------------------
 
-import type { ObjectMetadata, ObjectInspection, SceneSnapshot } from './types';
+import type { ObjectMetadata, ObjectInspection, SceneSnapshot, BridgeDiagnostics, CameraState } from './types';
+import type { SceneDiff } from './diffSnapshots';
 
 declare global {
   namespace Cypress {
     interface Chainable {
-      // ---- Debug ----
+      // ---- Multi-canvas ----
+      /**
+       * Switch all subsequent r3f commands to target a specific canvas instance.
+       * Pass `null` to switch back to the default canvas.
+       * @example cy.r3fUseCanvas('minimap'); cy.r3fClick('marker');
+       */
+      r3fUseCanvas(canvasId: string | null): Chainable<void>;
+      /** List all active canvas IDs registered on the page. */
+      r3fGetCanvasIds(): Chainable<string[]>;
+
+      // ---- Debug / Reporter ----
       /** Enable debug logging. Mirrors [r3f-dom:*] browser logs to Cypress command log. */
       r3fEnableDebug(): Chainable<void>;
+      /**
+       * Enable the R3F reporter for rich terminal output (bridge status, object lookup,
+       * interaction timing, diagnostics). Requires `registerR3FTasks(on)` in cypress.config.ts.
+       */
+      r3fEnableReporter(enabled?: boolean): Chainable<void>;
       /** Log the full scene tree to the Cypress command log and browser console. */
       r3fLogScene(): Chainable<void>;
 
+      // ---- Diagnostics ----
+      /** Get bridge diagnostics (object counts, DOM state, GPU info). */
+      r3fGetDiagnostics(): Chainable<BridgeDiagnostics | null>;
+      /** Log bridge diagnostics to the Cypress command log and browser console. */
+      r3fLogDiagnostics(): Chainable<void>;
+      /** Fuzzy search for objects by partial testId, name, or uuid. */
+      r3fFuzzyFind(query: string, limit?: number): Chainable<ObjectMetadata[]>;
+
       // ---- Interactions ----
-      /** Click a 3D object by testId or uuid. */
+      /** Click a 3D object by testId or uuid. Auto-waits for bridge + object. */
       r3fClick(idOrUuid: string): Chainable<void>;
-      /** Double-click a 3D object by testId or uuid. */
+      /** Double-click a 3D object by testId or uuid. Auto-waits for bridge + object. */
       r3fDoubleClick(idOrUuid: string): Chainable<void>;
-      /** Right-click / context-menu a 3D object by testId or uuid. */
+      /** Right-click / context-menu a 3D object by testId or uuid. Auto-waits for bridge + object. */
       r3fContextMenu(idOrUuid: string): Chainable<void>;
-      /** Hover over a 3D object by testId or uuid. */
+      /** Hover over a 3D object by testId or uuid. Auto-waits for bridge + object. */
       r3fHover(idOrUuid: string): Chainable<void>;
-      /** Drag a 3D object with a world-space delta vector. */
+      /** Unhover / pointer-leave — resets hover state. Auto-waits for bridge. */
+      r3fUnhover(): Chainable<void>;
+      /** Drag a 3D object with a world-space delta vector. Auto-waits for bridge + object. */
       r3fDrag(idOrUuid: string, delta: { x: number; y: number; z: number }): Chainable<void>;
-      /** Dispatch a wheel/scroll event on a 3D object. */
+      /** Dispatch a wheel/scroll event on a 3D object. Auto-waits for bridge + object. */
       r3fWheel(idOrUuid: string, options?: { deltaY?: number; deltaX?: number }): Chainable<void>;
-      /** Click empty space to trigger onPointerMissed handlers. */
+      /** Click empty space to trigger onPointerMissed handlers. Auto-waits for bridge. */
       r3fPointerMiss(): Chainable<void>;
-      /** Draw a freeform path on the canvas (for drawing/annotation apps). */
+      /** Draw a freeform path on the canvas (for drawing/annotation apps). Auto-waits for bridge. */
       r3fDrawPath(
         points: Array<{ x: number; y: number; pressure?: number }>,
         options?: { stepDelayMs?: number; pointerType?: 'mouse' | 'pen' | 'touch'; clickAtEnd?: boolean },
       ): Chainable<{ eventCount: number; pointCount: number }>;
 
       // ---- Selection ----
-      /** Select a 3D object (highlights in scene). */
+      /** Select a 3D object (highlights in scene). Auto-waits for bridge + object. */
       r3fSelect(idOrUuid: string): Chainable<void>;
-      /** Clear the current selection. */
+      /** Clear the current selection. Auto-waits for bridge. */
       r3fClearSelection(): Chainable<void>;
 
       // ---- Queries ----
       /** Get object metadata by testId or uuid. */
       r3fGetObject(idOrUuid: string): Chainable<ObjectMetadata | null>;
+      /** Get object metadata by testId. */
+      r3fGetByTestId(testId: string): Chainable<ObjectMetadata | null>;
+      /** Get all objects with the given name (object.name). */
+      r3fGetByName(name: string): Chainable<ObjectMetadata[]>;
+      /** Get object metadata by uuid only. */
+      r3fGetByUuid(uuid: string): Chainable<ObjectMetadata | null>;
+      /** Get direct children of an object by testId or uuid. */
+      r3fGetChildren(idOrUuid: string): Chainable<ObjectMetadata[]>;
+      /** Get parent of an object by testId or uuid. */
+      r3fGetParent(idOrUuid: string): Chainable<ObjectMetadata | null>;
+      /** Get the R3F canvas element (data-r3f-canvas). */
+      r3fGetCanvas(): Chainable<JQuery<HTMLCanvasElement>>;
+      /** Get world-space position [x, y, z] of an object. */
+      r3fGetWorldPosition(idOrUuid: string): Chainable<[number, number, number] | null>;
+      /** Compare two scene snapshots (added, removed, changed). */
+      r3fDiffSnapshots(before: SceneSnapshot, after: SceneSnapshot): Chainable<SceneDiff>;
+      /** Run an action and return { added, removed } object count change. */
+      r3fTrackObjectCount(action: () => Cypress.Chainable<unknown>): Chainable<{ added: number; removed: number }>;
       /** Get heavy inspection data (Tier 2) by testId or uuid. */
       r3fInspect(idOrUuid: string): Chainable<ObjectInspection | null>;
       /** Take a full scene snapshot. */
@@ -57,6 +101,10 @@ declare global {
       // ---- BIM/CAD queries ----
       /** Get all objects of a given Three.js type (e.g. "Mesh", "Group", "Line"). */
       r3fGetByType(type: string): Chainable<ObjectMetadata[]>;
+      /** Get all objects with a given geometry type (e.g. "BoxGeometry"). */
+      r3fGetByGeometryType(type: string): Chainable<ObjectMetadata[]>;
+      /** Get all objects with a given material type (e.g. "MeshStandardMaterial"). */
+      r3fGetByMaterialType(type: string): Chainable<ObjectMetadata[]>;
       /** Get objects that have a specific userData key (and optionally matching value). */
       r3fGetByUserData(key: string, value?: unknown): Chainable<ObjectMetadata[]>;
       /** Count objects of a given Three.js type. */
@@ -64,6 +112,10 @@ declare global {
       /** Batch lookup: get metadata for multiple objects by testId or uuid. */
       r3fGetObjects(ids: string[]): Chainable<Record<string, ObjectMetadata | null>>;
 
+      // ---- Camera ----
+      /** Get current camera state (position, rotation, fov, near, far, zoom, target). */
+      r3fGetCameraState(): Chainable<CameraState>;
+
       // ---- Waiters ----
       /** Wait until the scene is ready (bridge available, object count stable). */
       r3fWaitForSceneReady(options?: {
@@ -93,6 +145,11 @@ declare global {
         pollIntervalMs?: number;
         timeout?: number;
       }): Chainable<{ newObjects: ObjectMetadata[]; newUuids: string[]; count: number }>;
+      /** Wait until an object (by testId or uuid) is no longer in the scene. */
+      r3fWaitForObjectRemoved(
+        idOrUuid: string,
+        options?: { bridgeTimeout?: number; pollIntervalMs?: number; timeout?: number },
+      ): Chainable<void>;
     }
 
     interface Assertion {
@@ -101,8 +158,10 @@ declare global {
       r3fExist(idOrUuid: string): Assertion;
       /** Assert that a 3D object is visible. */
       r3fVisible(idOrUuid: string): Assertion;
-      /** Assert object position within tolerance. */
+      /** Assert object local position within tolerance. */
       r3fPosition(idOrUuid: string, expected: [number, number, number], tolerance?: number): Assertion;
+      /** Assert object world position within tolerance. */
+      r3fWorldPosition(idOrUuid: string, expected: [number, number, number], tolerance?: number): Assertion;
       /** Assert object rotation (Euler radians) within tolerance. */
       r3fRotation(idOrUuid: string, expected: [number, number, number], tolerance?: number): Assertion;
       /** Assert object scale within tolerance. */
@@ -157,6 +216,26 @@ declare global {
       r3fTotalTriangleCount(expected: number): Assertion;
       /** Assert total triangle count is less than a maximum (performance budget). */
       r3fTotalTriangleCountLessThan(max: number): Assertion;
+
+      // ---- Camera assertions ----
+      /** Assert camera position within tolerance. */
+      r3fCameraPosition(expected: [number, number, number], tolerance?: number): Assertion;
+      /** Assert camera field of view (PerspectiveCamera). */
+      r3fCameraFov(expected: number, tolerance?: number): Assertion;
+      /** Assert camera near clipping plane. */
+      r3fCameraNear(expected: number, tolerance?: number): Assertion;
+      /** Assert camera far clipping plane. */
+      r3fCameraFar(expected: number, tolerance?: number): Assertion;
+      /** Assert camera zoom level. */
+      r3fCameraZoom(expected: number, tolerance?: number): Assertion;
+
+      // ---- Batch assertions ----
+      /** Assert ALL given objects exist. Accepts array of ids or glob pattern (e.g. "wall-*"). */
+      r3fAllExist(idsOrPattern: string[] | string): Assertion;
+      /** Assert ALL given objects are visible. Accepts array of ids or glob pattern. */
+      r3fAllVisible(idsOrPattern: string[] | string): Assertion;
+      /** Assert NONE of the given objects exist. Accepts array of ids or glob pattern. */
+      r3fNoneExist(idsOrPattern: string[] | string): Assertion;
     }
   }
 }