feat: Update vitest docs (#1589)

* feat: 4.43

* chore:

* chore: tidy

* chore: update vitest docs (add mocking and spying)

* chore:

Author: johnjenkins

docs/testing/01-overview.md

@@ -21,6 +21,6 @@ Stencil supports the following for testing components:
 
 The integrated Stencil Test Runner is deprecated as of Stencil v4.43 and will be removed in Stencil v5. We recommend migrating to the new testing tools:
 
-- **For `--spec` style tests**: Migrate to [@stencil/vitest](./vitest/01-overview.md). It has a similar API to the current Jest integration but gives you far greater control. You can test against different bundles/outputs, test in a real browser (for accessibility tests, visual regressions, etc.), or pick your node-dom of choice (jsdom, happy-dom, or mock-doc). See the [migration guide](./vitest/06-migration.md) for detailed instructions.
+- **For `--spec` style tests**: Migrate to [@stencil/vitest](./vitest/01-overview.md). It has a similar API to the current Jest integration but gives you far greater control. You can test against different bundles/outputs, test in a real browser (for accessibility tests, visual regressions, etc.), or pick your node-dom of choice (jsdom, happy-dom, or mock-doc). See the [migration guide](./vitest/07-migration.md) for detailed instructions.
 
 - **For `--e2e` style tests**: Many library authors actually want "component" tests—isolated testing of components that run in a browser. For this, use [@stencil/vitest](./vitest/01-overview.md) with browser mode. For true end-to-end tests (routing, full applications, proper onload initialization), use [@stencil/playwright](./playwright/01-overview.md).

docs/testing/stencil-testrunner/01-overview.md

@@ -9,7 +9,7 @@ sidebar_label: Overview
 
 **The Stencil Test Runner is deprecated as of Stencil v4.43 and will be removed in Stencil v5.**
 
-We recommend migrating to [@stencil/vitest](../vitest/01-overview.md) for all new and existing projects. See the [migration guide](../vitest/06-migration.md) for detailed instructions on updating your tests.
+We recommend migrating to [@stencil/vitest](../vitest/01-overview.md) for all new and existing projects. See the [migration guide](../vitest/07-migration.md) for detailed instructions on updating your tests.
 
 **Why is this being removed?**
 

docs/testing/vitest/01-overview.md

@@ -132,4 +132,4 @@ Add the following scripts to your `package.json`:
 
 ## Migration from Stencil Test Runner
 
-If you're migrating from the Stencil Test Runner, see the [Migration Guide](./06-migration.md) for detailed instructions on updating your tests.
+If you're migrating from the Stencil Test Runner, see the [Migration Guide](./07-migration.md) for detailed instructions on updating your tests.

docs/testing/vitest/02-configuration.md

@@ -100,6 +100,7 @@ For spec tests, you can choose between different DOM implementations using `envi
     environmentOptions: {
       stencil: {
         // Options: 'mock-doc' (default), 'jsdom', 'happy-dom'
+        // *note: jsdom and happy-dom require additional dependencies*
         domEnvironment: 'jsdom'
       },
     },
@@ -165,8 +166,8 @@ export {};
 Depending on your Stencil configuration, you may need to adjust how components are loaded:
 
 - **Default (lazy-load)**: Works with the standard dev build
-- **Production build**: Use `--prod` flag or set `buildDist: true` in your stencil.config to generate production bundles
-- **Custom elements**: If using the `dist-custom-elements` output target, adjust the import path accordingly
+- **Production build**: Use `--prod` flag to generate production bundles
+- **Custom elements**: If using the `dist-custom-elements` output target, adjust the setup file accordingly. If you wish to test this output in `--watch` mode, set `buildDist: true` in your stencil.config
 
 ## TypeScript Configuration
 

docs/testing/vitest/03-writing-tests.md

@@ -11,61 +11,25 @@ slug: /testing-vitest-writing-tests
 
 ## Rendering Components
 
-### Basic Rendering
-
 Use the `render` function to render a component for testing:
 
 ```tsx
 import { render, h, describe, it, expect } from '@stencil/vitest';
 
 describe('my-component', () => {
   it('renders', async () => {
-    const { root } = await render(<my-component name="World" />);
+    const { root, waitForChanges } = await render(<my-component name="World" />);
     expect(root.textContent).toContain('World');
+
+    // Update props and wait for re-render
+    root.name = 'Stencil';
+    await waitForChanges();
+    expect(root.textContent).toContain('Stencil');
   });
 });
 ```
 
-### Render Return Values
-
-The `render` function returns an object with utilities for interacting with the rendered component:
-
-```tsx
-const { root, waitForChanges, setProps, unmount, spyOnEvent } = await render(<my-component />);
-```
-
-| Property | Description |
-| -------- | ----------- |
-| `root` | The rendered component element |
-| `waitForChanges` | Wait for component re-renders after state/prop changes |
-| `setProps` | Update component props and wait for changes |
-| `unmount` | Remove the component from the DOM |
-| `spyOnEvent` | Create a spy for custom events |
-
-### Updating Props
-
-There are two ways to update component props:
-
-```tsx
-const { root, waitForChanges, setProps } = await render(<my-component name="World" />);
-
-// Option 1: Direct property assignment
-root.name = 'Stencil';
-await waitForChanges();
-
-// Option 2: Using setProps
-await setProps({ name: 'Stencil' });
-```
-
-### Unmounting
-
-Clean up by unmounting the component:
-
-```tsx
-const { unmount } = await render(<my-component />);
-// ... run tests
-unmount();
-```
+For the complete render function API including all return values and options, see the [API Reference](./04-api.md#render-function).
 
 ## Event Testing
 

docs/testing/vitest/04-api.md

@@ -11,7 +11,7 @@ Complete reference for the `@stencil/vitest` testing utilities.
 
 ## Render Function
 
-### `render(VNode)`
+### `render(VNode, options?)`
 
 Renders a Stencil component for testing.
 
@@ -21,7 +21,42 @@ import { render, h } from '@stencil/vitest';
 const result = await render(<my-component name="World" />);
 ```
 
-**Returns:**
+### Options
+
+| Option | Type | Default | Description |
+| ------ | ---- | ------- | ----------- |
+| `waitForReady` | `boolean` | `true` | Wait for component hydration before returning |
+| `spyOn` | `SpyOnOptions` | - | Configure spies for methods, props, and lifecycle hooks |
+
+#### `waitForReady`
+
+By default, `render()` waits for components to be fully hydrated before returning. It detects when Stencil applies the hydrated flag (class or attribute) to your component, respecting your `stencil.config` settings.
+
+```tsx
+// Default behavior - waits for hydration
+const { root } = await render(<my-component />);
+
+// Skip hydration wait (useful for pre-ready states)
+const { root } = await render(<my-component />, { waitForReady: false });
+```
+
+#### `spyOn`
+
+Configure spies for component methods, props, and lifecycle hooks. See the [Mocking & Spying](./05-mocking.md) guide for comprehensive documentation.
+
+```tsx
+const { root, spies } = await render(<my-component />, {
+  spyOn: {
+    methods: ['handleClick'],
+    props: ['variant'],
+    lifecycle: ['componentDidLoad'],
+  },
+});
+
+expect(spies?.methods.handleClick).toHaveBeenCalled();
+```
+
+### Return Values
 
 | Property | Type | Description |
 | -------- | ---- | ----------- |
@@ -30,6 +65,35 @@ const result = await render(<my-component name="World" />);
 | `setProps` | `(props: object) => Promise<void>` | Update props and wait for changes |
 | `unmount` | `() => void` | Remove the component from the DOM |
 | `spyOnEvent` | `(eventName: string) => EventSpy` | Create a spy for custom events |
+| `spies` | `ComponentSpies \| undefined` | Spy objects when using `spyOn` option |
+
+### Example
+
+```tsx
+import { render, h } from '@stencil/vitest';
+
+const { root, waitForChanges, setProps, unmount, spyOnEvent } = await render(
+  <my-component name="World" />
+);
+
+// Access the element
+expect(root.textContent).toContain('World');
+
+// Update props directly
+root.name = 'Stencil';
+await waitForChanges();
+
+// Or update props via setProps
+await setProps({ name: 'Vitest' });
+
+// Spy on events
+const eventSpy = spyOnEvent('myEvent');
+root.click();
+expect(eventSpy).toHaveReceivedEvent();
+
+// Unmount component
+unmount();
+```
 
 ## Custom Matchers