Improve selectors

Author: ascorbic

packages/vitest-browser-astro/README.md

@@ -16,6 +16,8 @@ Using pnpm:
 pnpm add -D vitest-browser-astro @vitest/browser playwright
 ```
 
+**Note:** This package currently requires Vitest 3.x. Vitest 4 is not yet compatible with Astro.
+
 ## Quick Start
 
 Create `vitest.config.ts`:
@@ -225,7 +227,7 @@ test("React counter increments on click", async () => {
 	const screen = await render(Counter);
 
 	// Wait for hydration to complete
-	await waitForHydration(screen.container);
+	await waitForHydration(screen);
 
 	const count = screen.getByTestId("count");
 	const button = screen.getByTestId("increment");
@@ -251,10 +253,14 @@ Astro wraps framework components in `<astro-island>` elements with an `ssr` attr
 
 The `waitForHydration()` function waits for this attribute to be removed before proceeding.
 
-Pass `screen.container` to wait for all islands, or a specific island element to wait for just that one. An optional timeout can be specified (default: 5000ms):
+Pass the `screen` result to wait for all islands, or a specific locator to wait for islands within that element:
 
 ```ts
-await waitForHydration(screen.container, 10000); // Wait up to 10 seconds
+// Wait for all islands in the component
+await waitForHydration(screen);
+
+// Wait for islands within a specific element
+await waitForHydration(screen.getByTestId("header"));
 ```
 
 Skip `waitForHydration()` for components without client directives. You can also manually check for hydration by waiting for the `ssr` attribute to be removed:
@@ -295,10 +301,9 @@ const screen = await render(Component, {
 });
 ```
 
-Returns an object which includes Vitest Browser's [locator selectors](https://vitest.dev/guide/browser/#locators) and the container element.
+Returns an object which includes Vitest Browser's [locator selectors](https://vitest.dev/guide/browser/#locators) and an `.element()` method.
 
-- `container` - DOM element containing the rendered component
-- `unmount()` - Remove the component from the DOM
+- `element()` - Returns the DOM element containing the rendered component
 - `getByRole(role)` - Find element by ARIA role
 - `getByAltText(altText)` - Find element by alt text
 - `getByLabelText(labelText)` - Find element by associated label text
@@ -307,14 +312,16 @@ Returns an object which includes Vitest Browser's [locator selectors](https://vi
 - `getByTitle(title)` - Find element by title attribute
 - `getByTestId(id)` - Find element by `data-testid` attribute
 
-### `waitForHydration(container, timeout?)`
+### `waitForHydration(locator)`
 
-Waits for framework component hydration to complete (default timeout: 5000ms).
+Waits for framework component hydration to complete.
 
 ```ts
-await waitForHydration(screen.container);
-// or a specific island
-await waitForHydration(screen.getByTestId("header"));
+// Wait for all islands
+await waitForHydration(screen);
+
+// Wait for islands within a specific element
+await waitForHydration(screen.getByTestId("footer"));
 ```
 
 ### `cleanup()`
@@ -323,24 +330,6 @@ Removes all rendered components from the DOM. Called automatically between tests
 
 ## Troubleshooting
 
-### TypeScript errors with `.astro` imports
-
-Ensure `tsconfig.json` extends Astro's base configuration:
-
-```json
-{
-	"extends": "astro/tsconfigs/base"
-}
-```
-
-Then restart the TypeScript server.
-
-### Tests hanging or timing out
-
-1. Install Playwright browsers: `npx playwright install`
-2. Verify `browser.enabled: true` in Vitest config
-3. Run with `headless: false` to debug visually
-
 ### Framework components not hydrating
 
 1. Add the framework renderer using `getContainerRenderer()` in plugin options
@@ -353,7 +342,7 @@ For more issues, see [GitHub Issues](https://github.com/ascorbic/vitest-browser-
 ## Requirements
 
 - Astro 5.x or later
-- Vitest 3.x or later
+- Vitest 3.x (Vitest 4 is not yet compatible with Astro)
 - Vite 6.x or later
 
 ## Contributing

packages/vitest-browser-astro/src/pure.ts

@@ -1,4 +1,6 @@
 import { getElementLocatorSelectors } from "@vitest/browser/utils";
+import type { Locator } from "@vitest/browser/context";
+import { expect } from "vitest";
 import type { RenderOptions, RenderResult } from "./types";
 
 const mountedContainers = new Set<HTMLElement>();
@@ -65,26 +67,15 @@ function setupContainer(
 }
 
 /**
- * Creates a render result with cleanup and locators
+ * Creates a render result with locators
  */
 function createRenderResult(
 	container: HTMLElement,
 	baseElement: HTMLElement,
 ): RenderResult {
 	mountedContainers.add(container);
-
-	const unmount = () => {
-		container.innerHTML = "";
-		mountedContainers.delete(container);
-		if (container.parentNode === document.body) {
-			document.body.removeChild(container);
-		}
-	};
-
 	return {
-		container,
-		baseElement,
-		unmount,
+		element: () => container,
 		...getElementLocatorSelectors(baseElement),
 	};
 }
@@ -130,30 +121,25 @@ export async function cleanup(): Promise<void> {
  * Call this before interacting with framework components to ensure event handlers
  * are attached and the component is fully interactive.
  *
- * @param container - The container element to search for islands (usually screen.container)
- * @param timeout - Maximum time to wait in milliseconds (default: 5000)
+ * @param container - Either a Locator or RenderResult to search for astro-island children
  *
  * @example
  * ```ts
+ * // Wait for all islands in the render result
  * const screen = await render(Counter);
- * await waitForHydration(screen.container);
- * await userEvent.click(screen.getByRole('button'));
+ * await waitForHydration(screen);
+ *
+ * // Wait for a specific island
+ * await waitForHydration(screen.getByTestId('my-island'));
  * ```
  */
 export async function waitForHydration(
-	container: HTMLElement,
-	timeout = 5000,
+	container: Locator | RenderResult,
 ): Promise<void> {
-	// Use a simple polling approach since we're in browser context
-	const startTime = Date.now();
-	while (container.querySelectorAll("astro-island[ssr]").length > 0) {
-		if (Date.now() - startTime > timeout) {
-			const remainingCount =
-				container.querySelectorAll("astro-island[ssr]").length;
-			throw new Error(
-				`Hydration timeout: ${remainingCount} island(s) still have 'ssr' attribute after ${timeout}ms`,
-			);
-		}
-		await new Promise((resolve) => setTimeout(resolve, 50));
-	}
+	// Poll until all astro-island children no longer have the ssr attribute
+	await expect
+		.poll(
+			() => container.element().querySelectorAll("astro-island[ssr]").length,
+		)
+		.toBe(0);
 }

packages/vitest-browser-astro/src/types.ts

@@ -20,10 +20,8 @@ export interface RenderOptions {
 }
 
 /**
- * Result returned from render() function with DOM access and locators
+ * Result returned from render() function
  */
 export interface RenderResult extends LocatorSelectors {
-	container: HTMLElement;
-	baseElement: HTMLElement;
-	unmount: () => void;
+	element: () => HTMLElement;
 }

packages/vitest-browser-astro/test/fixtures/astro-site/test/browser.test.ts

@@ -24,8 +24,8 @@ describe("render() in browser", () => {
 				},
 			});
 
-			expect(screen.container).toBeTruthy();
-			expect(screen.container).toBeInstanceOf(HTMLElement);
+			expect(screen.element()).toBeTruthy();
+			expect(screen.element()).toBeInstanceOf(HTMLElement);
 			await expect.element(screen.getByTestId("card")).toBeInTheDocument();
 		});
 
@@ -52,7 +52,7 @@ describe("render() in browser", () => {
 
 			await expect.element(screen.getByText("Only Title")).toBeVisible();
 			// Description should not be rendered
-			expect(screen.container.querySelector("p")).toBeNull();
+			expect(screen.element().querySelector("p")).toBeNull();
 		});
 	});
 
@@ -82,7 +82,7 @@ describe("render() in browser", () => {
 
 			await expect.element(screen.getByTestId("tags")).toBeInTheDocument();
 			expect(
-				screen.container.querySelectorAll('[data-testid="tags"] li'),
+				screen.element().querySelectorAll('[data-testid="tags"] li'),
 			).toHaveLength(3);
 		});
 
@@ -169,29 +169,6 @@ describe("render() in browser", () => {
 		});
 	});
 
-	describe("cleanup", () => {
-		it("should provide unmount function", async () => {
-			const screen = await render(SimpleCard, {
-				props: { title: "Test" },
-			});
-
-			expect(screen.unmount).toBeTypeOf("function");
-		});
-
-		it("should remove component from DOM when unmounted", async () => {
-			const screen = await render(SimpleCard, {
-				props: { title: "Test" },
-			});
-
-			const card = screen.getByTestId("card");
-			await expect.element(card).toBeInTheDocument();
-
-			screen.unmount();
-
-			expect(document.body.contains(screen.container)).toBe(false);
-		});
-	});
-
 	describe("locators API", () => {
 		it("should provide getByText locator", async () => {
 			const screen = await render(SimpleCard, {
@@ -437,7 +414,7 @@ describe("React components", () => {
 		await expect.element(count).toHaveTextContent("0");
 
 		// Wait for hydration to complete before interacting
-		await waitForHydration(screen.container);
+		await waitForHydration(screen);
 		await userEvent.click(incrementBtn);
 		await expect.element(count).toHaveTextContent("1");
 
@@ -447,6 +424,27 @@ describe("React components", () => {
 		await userEvent.click(decrementBtn);
 		await expect.element(count).toHaveTextContent("1");
 	});
+
+	it("should wait for hydration on a specific locator", async () => {
+		const screen = await render(WithReact, {
+			props: {
+				initialCount: 5,
+			},
+		});
+
+		const container = screen.getByTestId("with-react");
+
+		// Wait for hydration on the specific container
+		await waitForHydration(container);
+
+		const count = screen.getByTestId("react-count");
+		const incrementBtn = screen.getByTestId("react-increment");
+
+		await expect.element(count).toHaveTextContent("5");
+
+		await userEvent.click(incrementBtn);
+		await expect.element(count).toHaveTextContent("6");
+	});
 });
 
 describe("Vue components", () => {
@@ -494,7 +492,7 @@ describe("Vue components", () => {
 		await expect.element(count).toHaveTextContent("0");
 
 		// Wait for hydration to complete before interacting
-		await waitForHydration(screen.container);
+		await waitForHydration(screen);
 
 		await userEvent.click(incrementBtn);
 		await expect.element(count).toHaveTextContent("1");
@@ -554,7 +552,7 @@ describe("Svelte components", () => {
 		await expect.element(count).toHaveTextContent("0");
 
 		// Wait for hydration to complete before interacting
-		await waitForHydration(screen.container);
+		await waitForHydration(screen);
 
 		await userEvent.click(incrementBtn);
 		await expect.element(count).toHaveTextContent("1");