@stencil/vitest 1.2.0 → 1.4.0

package/README.md

@@ -270,6 +270,44 @@ const formatted = prettifyHtml('<div><span>Hello</span></div>');
 // </div>
 ```
 
+### `waitForStable(elementOrSelector, timeout?)`
+
+Waits for an element to be rendered and visible in the DOM. Only works in real browser environments (not jsdom/happy-dom).
+
+Accepts either an `Element` or a CSS selector string. When a selector is provided, it polls until the element appears in the DOM.
+
+```tsx
+import { render, waitForStable, h } from '@stencil/vitest';
+
+// Wait for a rendered element to be stable / visible
+const { root } = await render(<my-component />);
+await waitForStable(root);
+
+// Wait for an element using a selector (useful when element isn't in DOM yet)
+await waitForStable('my-component .inner-element');
+
+// Custom timeout (default: 5000ms)
+await waitForStable('my-component', 10000);
+```
+
+> **Note:** In non-browser environments, `waitForStable` logs a warning and returns immediately.
+
+### `waitForExist(selector, timeout?)`
+
+Waits for an element matching the selector to exist in the DOM. Unlike `waitForStable`, this works in both real browsers and mock DOM environments (jsdom/happy-dom).
+
+Returns the element if found, or `null` if timeout is reached.
+
+```tsx
+import { waitForExist } from '@stencil/vitest';
+
+// Wait for an element to appear in the DOM
+const element = await waitForExist('my-component .lazy-loaded');
+
+// Custom timeout (default: 5000ms)
+const element = await waitForExist('#dynamic-content', 10000);
+```
+
 ## CLI
 
 The `stencil-test` CLI wraps both Stencil builds with Vitest testing.

package/dist/core.d.ts

@@ -1,7 +1,7 @@
 import './testing/matchers.js';
 import './testing/snapshot-serializer.js';
 export { h } from '@stencil/core';
-export { render } from './testing/render.js';
+export { render, waitForStable, waitForExist } from './testing/render.js';
 export { serializeHtml, prettifyHtml, SerializeOptions } from './testing/html-serializer.js';
 export type { RenderOptions, RenderResult } from './types.js';
 //# sourceMappingURL=core.d.ts.map

package/dist/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AACA,OAAO,uBAAuB,CAAC;AAC/B,OAAO,kCAAkC,CAAC;AAE1C,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAClC,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAC7F,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":"AACA,OAAO,uBAAuB,CAAC;AAC/B,OAAO,kCAAkC,CAAC;AAE1C,OAAO,EAAE,CAAC,EAAE,MAAM,eAAe,CAAC;AAClC,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAC7F,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/core.js

@@ -2,5 +2,5 @@
 import './testing/matchers.js';
 import './testing/snapshot-serializer.js';
 export { h } from '@stencil/core';
-export { render } from './testing/render.js';
+export { render, waitForStable, waitForExist } from './testing/render.js';
 export { serializeHtml, prettifyHtml } from './testing/html-serializer.js';

package/dist/testing/render.d.ts

@@ -15,6 +15,18 @@ interface RenderOptions {
      */
     waitForReady?: boolean;
 }
+/**
+ * Poll until element has dimensions (is rendered/visible in real browser).
+ * Accepts either an Element or a CSS selector string.
+ * If a selector is provided, waits for the element to appear in the DOM first.
+ */
+export declare function waitForStable(elementOrSelector: Element | string, timeout?: number): Promise<void>;
+/**
+ * Poll until element exists in the DOM.
+ * Accepts a CSS selector string and waits for a matching element to appear.
+ * Works in both real browsers and mock DOM environments.
+ */
+export declare function waitForExist(selector: string, timeout?: number): Promise<Element | null>;
 /**
  * Render using Stencil's render
  */

package/dist/testing/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/testing/render.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAY,MAAM,aAAa,CAAC;AAE1D,UAAU,aAAa;IACrB;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAwCD;;GAEG;AACH,wBAAsB,MAAM,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAAE,CAAC,GAAG,GAAG,EACvE,KAAK,EAAE,GAAG,EACV,OAAO,GAAE,aAGR,GACA,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CA6I7B"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../../src/testing/render.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAY,MAAM,aAAa,CAAC;AAE1D,UAAU,aAAa;IACrB;;OAEG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAyBD;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,iBAAiB,EAAE,OAAO,GAAG,MAAM,EAAE,OAAO,SAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAiCtG;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,SAAO,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAY5F;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,CAAC,SAAS,WAAW,GAAG,WAAW,EAAE,CAAC,GAAG,GAAG,EACvE,KAAK,EAAE,GAAG,EACV,OAAO,GAAE,aAGR,GACA,OAAO,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CA6I7B"}

package/dist/testing/render.js

@@ -22,18 +22,53 @@ function isRealBrowser() {
     return true;
 }
 /**
- * Poll until element has dimensions (is rendered/visible in real browser)
+ * Poll until element has dimensions (is rendered/visible in real browser).
+ * Accepts either an Element or a CSS selector string.
+ * If a selector is provided, waits for the element to appear in the DOM first.
  */
-async function waitForRendered(element, timeout = 5000) {
+export async function waitForStable(elementOrSelector, timeout = 5000) {
+    if (!isRealBrowser()) {
+        console.warn('[waitForStable] Only works in real browser environments');
+        return;
+    }
     const start = Date.now();
+    // Resolve element from selector if needed
+    let element = typeof elementOrSelector === 'string' ? null : elementOrSelector;
+    // If an Element was passed, verify it's in the DOM
+    if (element && !document.contains(element)) {
+        console.warn('[waitForStable] Element is not attached to the DOM');
+    }
     while (Date.now() - start < timeout) {
-        const rect = element.getBoundingClientRect();
-        if (rect.width > 0 && rect.height > 0) {
-            return;
+        // If we have a selector, try to find the element
+        if (typeof elementOrSelector === 'string' && !element) {
+            element = document.querySelector(elementOrSelector);
+        }
+        // If we have an element, check if it has dimensions
+        if (element) {
+            const rect = element.getBoundingClientRect();
+            if (rect.width > 0 && rect.height > 0) {
+                return;
+            }
         }
         await new Promise((r) => requestAnimationFrame(r));
     }
-    // Don't throw on timeout - element might be intentionally zero-sized
+    // Don't throw on timeout - element might be intentionally zero-sized or not found
+}
+/**
+ * Poll until element exists in the DOM.
+ * Accepts a CSS selector string and waits for a matching element to appear.
+ * Works in both real browsers and mock DOM environments.
+ */
+export async function waitForExist(selector, timeout = 5000) {
+    const start = Date.now();
+    while (Date.now() - start < timeout) {
+        const element = document.querySelector(selector);
+        if (element) {
+            return element;
+        }
+        await new Promise((r) => setTimeout(r, 16));
+    }
+    return null;
 }
 /**
  * Render using Stencil's render
@@ -99,7 +134,7 @@ export async function render(vnode, options = {
     if (options.waitForReady !== false) {
         if (isRealBrowser()) {
             // In real browser, poll until element has dimensions
-            await waitForRendered(element);
+            await waitForStable(element);
         }
         // Always wait for Stencil's update cycle to complete
         await waitForChanges();

package/package.json

@@ -4,7 +4,7 @@
     "type": "git",
     "url": "https://github.com/stenciljs/vitest"
   },
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "First-class testing utilities for Stencil design systems with Vitest",
   "license": "MIT",
   "type": "module",
@@ -97,7 +97,7 @@
   "dependencies": {
     "jiti": "^2.6.1",
     "local-pkg": "^1.1.2",
-    "vitest-environment-stencil": "1.2.0"
+    "vitest-environment-stencil": "1.4.0"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",