@globisnv/cypress-core 0.0.2 → 0.0.4

package/dist/websocketDetector.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @file websocketDetector.ts
+ *
+ * WebSocket spy and loading-state detector for Cypress E2E tests against a Servoy application.
+ *
+ * ## Problem
+ * Servoy's frontend communicates with its backend exclusively over a single persistent WebSocket.
+ * Standard cy.intercept() cannot observe WebSocket frames, so fragile cy.wait(N) calls were used
+ * to pause tests until the server responded. This module replaces that pattern with a
+ * semantics-aware idle check.
+ *
+ * ## How it works
+ * `attachWebSocketSpy` patches window.WebSocket at page-load time so that every outgoing and
+ * incoming frame is mirrored into `win.wsMessages`. `WS_loadingCheck` then polls that
+ * log and maintains a state machine to determine when the server has fully responded.
+ *
+ * ## Resolution signals — all three must be idle simultaneously
+ *  1. **Pending requests** — each outgoing formService command gets a message-id (cmsgid /
+ *     requestId / msgid). The matching incoming response removes it from `state.pendingRequests`.
+ *  2. **Loading indicator** — `$sabloLoadingIndicator` showLoading/hideLoading signals are
+ *     tracked in `state.loadingIndicator`.
+ *  3. **Data sync (svyPush)** — when the test changes a field, a svyPush frame is sent. The
+ *     loader waits for the server to echo the updated form back before resolving.
+ *  4. ** DOM loading indicator** - when the DOM loading indicator appears.
+ *     The (websocket)loader waits for it to disappear before resolving.
+ *
+ * Once all four are idle for QUIET_PERIOD_MS/resolved, the command resolves.
+ *
+ * ## Dialog handling
+ * The server may open a message dialog mid-flight as part of a response. Plain "Info" dialogs
+ * with the literal title "Info" are auto-dismissed when enabled. All other dialogs immediately unblock the
+ * loader so the test can handle them. Popup window forms ($windowService windows) have their
+ * own tracking path.
+ */
+declare global {
+    namespace Cypress {
+        interface Chainable {
+            /**
+             * Visits the given URL and installs a WebSocket spy on the page.
+             * Waits for the WS connection to open and the initial load to settle before returning.
+             *
+             * @param url - The URL to visit.
+             */
+            WS_visitWithSpy(url: string): Cypress.Chainable<void>;
+            /**
+             * Enables or disables automatic handling of Info dialogs in the WebSocket loader.
+             * When disabled the test must dismiss the dialog itself.
+             *
+             * @param mode - 'enable' to auto-handle, 'disable' to let the test handle it.
+             */
+            WS_toggleDialogHandler(mode: 'enable' | 'disable'): void;
+            /**
+             * Waits for all pending WebSocket activity to resolve before the test continues.
+             * Tracks outgoing requests, incoming responses, loading-indicator state, data-push
+             * syncs, and dialog state.
+             *
+             * Call this after every action that triggers server communication instead of cy.wait(N).
+             *
+             * @param options - Optional timeout and dialog-handling overrides.
+             */
+            WS_loadingCheck(options?: WebSocketLoaderOptions): Cypress.Chainable<void>;
+        }
+    }
+}
+/**
+ * Patches window.WebSocket to mirror every outgoing and incoming frame into `win.wsMessages`.
+ * Must be called from onBeforeLoad so it runs before the application code connects.
+ *
+ * @param window - The AUT window object.
+ */
+export declare function attachWebSocketSpy(window: Window): void;