vitest-browser-angular 0.2.0 → 0.4.0

package/README.md

@@ -1,38 +1,188 @@
 # vitest-browser-angular
 
-Render Angular components in VItest Browser Mode.
+This community package renders Angular components in [Vitest Browser Mode](https://vitest.dev/guide/browser).
 
-## Installation
+```ts
+import { Component, input } from '@angular/core';
+import { expect, test } from 'vitest';
+import { render } from 'vitest-browser-angular';
+
+@Component({
+  selector: 'app-hello-world',
+  template: '<h1>Hello, {{ name() }}!</h1>',
+})
+export class HelloWorld {
+  name = input.required<string>();
+}
+
+test('renders name', async () => {
+  const { locator } = await render(HelloWorld, {
+    inputs: {
+      name: 'World',
+    },
+  });
+
+  await expect.element(locator).toHaveTextContent('Hello, World!');
+});
+```
+
+## Setup
+
+There are currently two ways to set up Vitest for Angular:
+
+- Analog's [`vitest-angular` plugin](https://analogjs.org/docs/features/testing/vitest) _(community)_.
+- Angular CLI's [`unit-test` builder](https://angular.dev/guide/testing#configuration) _(official)_.
+
+While Angular CLI's `unit-test` builder is the official way to set up Vitest for Angular, it has some [limitations](https://analogjs.org/docs/features/testing/overview#angular-support-for-vitest). Analog's `vitest-angular` plugin provides more Vitest features and greater flexibility.
+
+### Setup with Analog Plugin
+
+1. Set up Vitest
+
+```sh
+npm add -D @analogjs/platform vitest-browser-angular
+
+ng g @analogjs/platform:setup-vitest
+```
+
+2. Activate browser mode in the generated Vitest configuration by following the [browser mode configuration instructions](https://vitest.dev/guide/browser/#configuration).
+
+### Setup with Angular CLI
+
+1. Configure your Angular project to use the `@angular/build:unit-test` builder, and add the browsers of your choice.
+
+```json
+{
+  ...,
+  "projects": {
+    "my-app": {
+      ...,
+      "architect": {
+        "test": {
+          "builder": "@angular/build:unit-test",
+          "options": {
+            "browsers": ["Chromium", "Firefox", "Webkit"]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+_Since Angular v21, Vitest is the default runner so you don't need to set the `runner` option._
+
+2. Install the browser provider of your choice using `ng add`
 
 ```sh
-pnpm add -D vitest-browser-angular
+# With Playwright
+ng add @vitest/browser-playwright
+
+# or with WebdriverIO
+ng add @vitest/browser-webdriverio
 ```
 
-## Setup Test Environment
+3. Add the `vitest-browser-angular` package to your project.
 
-To set up your test environment (with Zone.js or Zoneless), use `@analogjs/vitest-angular`'s `setupTestBed()` function.
+```sh
+npm add -D vitest-browser-angular
+```
 
-**Important:** Make sure to use `{ browserMode: true }` when calling `setupTestBed()` to enable Vitest browser mode's visual test preview functionality.
+## Zone.js VS Zoneless Setup
+
+Angular CLI will automatically set up the test environment for you depending on the presence of `zone.js` in your project's polyfills.
+
+When using the Analog plugin, you can control the behavior using the `zoneless` option of `setupTestBed()` in `test-setup.ts`:
+
+```ts
+import { setupTestBed } from '@analogjs/vitest-angular/setup-testbed';
+
+setupTestBed({
+  zoneless: true,
+});
+```
 
 For detailed setup instructions for both Zone.js and Zoneless configurations, please refer to the [Analog Vitest documentation](https://analogjs.org/docs/features/testing/vitest).
 
+## Component Preview
+
+To preview, debug and interact with a component in the browser after the test, you can prevent Angular from destroying it.
+
+In Angular CLI, enable this using the `--debug` option.
+
+With the Analog plugin, enable this using the `browserMode` option of `setupTestBed()` in `test-setup.ts`:
+
+```ts
+import { setupTestBed } from '@analogjs/vitest-angular/setup-testbed';
+
+setupTestBed({
+  browserMode: true,
+});
+```
+
 ## Usage
 
+### Basic Example
+
+The `render` function supports two query patterns:
+
 ```ts
 import { test, expect } from 'vitest';
 import { render } from 'vitest-browser-angular';
 
 @Component({
-  template: '<h1>{{ title }}</h1>',
+  template: ` <h1>Welcome</h1> `,
 })
-export class HelloWorldComponent {
-  title = 'Hello World';
-}
+export class MyComponent {}
+
+test('query elements', async () => {
+  // Pattern 1: Use locator to query within the component element
+  const { locator } = await render(MyComponent);
+  await expect.element(locator.getByText('Welcome')).toBeVisible();
+
+  // Pattern 2: Use screen to query from document.body (useful for portals/overlays)
+  const screen = await render(MyComponent);
+  await expect.element(screen.getByText('Welcome')).toBeVisible();
+  await expect.element(screen.getByText('Some Popover Content')).toBeVisible();
+});
+```
+
+### Query Methods
+
+Both `locator` and `screen` provide the following query methods:
+
+- `getByRole` - Locate by ARIA role and accessible name
+- `getByText` - Locate by text content
+- `getByLabelText` - Locate by associated label text
+- `getByPlaceholder` - Locate by placeholder text
+- `getByAltText` - Locate by alt text (images)
+- `getByTitle` - Locate by title attribute
+- `getByTestId` - Locate by data-testid attribute
+
+**When to use which pattern:**
+
+- **`locator`**: (full name: "Component Locator") - queries are scoped to the component's host element. Best for most component tests.
+- **`screen`**: Queries start from `baseElement` (defaults to `document.body`). Use when testing components that render content outside their host element (modals, tooltips, portals).
 
-test('render', async () => {
-  const { component } = await render(HelloWorldComponent);
-  await expect.element(component).toHaveTextContent('Hello World');
+### Container Element
+
+Access the component's host element directly via `container` (shortcut for `fixture.nativeElement`):
+
+```ts
+const { container, locator } = await render(MyComponent);
+expect(container).toBe(locator.element());
+```
+
+### Base Element
+
+Customize the root element for screen queries (useful for portal/overlay testing):
+
+```ts
+const customContainer = document.querySelector('#modal-root');
+const screen = await render(ModalComponent, {
+  baseElement: customContainer,
 });
+// screen queries now start from customContainer instead of document.body
 ```
 
 ## Inputs
@@ -52,15 +202,15 @@ export class ProductComponent {
 }
 
 test('render with inputs', async () => {
-  const { component } = await render(ProductComponent, {
+  const screen = await render(ProductComponent, {
     inputs: {
       name: 'Laptop',
       price: 1299.99,
     },
   });
 
-  await expect.element(component).toHaveTextContent('Laptop');
-  await expect.element(component).toHaveTextContent('$1299.99');
+  await expect.element(screen.getByText('Laptop')).toBeVisible();
+  await expect.element(screen.getByText(/Price: \$1299\.99/)).toBeVisible();
 });
 ```
 
@@ -91,12 +241,12 @@ import { RouterLink, RouterOutlet } from '@angular/router';
 export class RoutedComponent {}
 
 test('render with simple routing', async () => {
-  const { component } = await render(RoutedComponent, {
+  const screen = await render(RoutedComponent, {
     withRouting: true,
   });
 
-  await expect.element(component).toHaveTextContent('Home');
-  await expect.element(component).toHaveTextContent('About');
+  await expect.element(screen.getByText('Home')).toBeVisible();
+  await expect.element(screen.getByText('About')).toBeVisible();
 });
 ```
 
@@ -143,18 +293,128 @@ const routes: Routes = [
 ];
 
 test('render with route configuration', async () => {
-  const { component, router } = await render(AppComponent, {
+  const { locator, routerHarness, router } = await render(AppComponent, {
     withRouting: {
       routes,
       initialRoute: '/home',
     },
   });
 
-  await expect.element(component).toHaveTextContent('Home Page');
+  await expect.element(locator).toHaveTextContent('Home Page');
+
+  // Navigate programmatically (prefer routerHarness over router)
+  await routerHarness.navigateByUrl('/about');
+  await expect.element(locator).toHaveTextContent('About Page');
+
+  // Use router to inspect state
+  expect(router.url).toBe('/about');
+});
+```
+
+### Route Params
+
+When rendering a routed component, `componentClassInstance` provides access to the actual component instance with full routing context:
+
+```ts
+import { Component, inject } from '@angular/core';
+import { ActivatedRoute, Routes } from '@angular/router';
+
+@Component({
+  template: '<h1>User: {{ userId }}</h1>',
+})
+export class UserComponent {
+  private route = inject(ActivatedRoute);
+  userId = this.route.snapshot.params['id'];
+}
+
+test('access route params', async () => {
+  const routes: Routes = [{ path: 'user/:id', component: UserComponent }];
+
+  const { componentClassInstance } = await render(UserComponent, {
+    withRouting: {
+      routes,
+      initialRoute: '/user/42',
+    },
+  });
 
-  // Navigate programmatically
-  await router.navigate(['/about']);
-  await expect.element(component).toHaveTextContent('About Page');
+  expect(componentClassInstance.userId).toBe('42');
+});
+```
+
+### Passing Inputs via Route Data
+
+By default, `withComponentInputBinding()` is enabled, which automatically binds route `data`, route params, and query params to matching component inputs. This works with both signal inputs (`input()`) and `@Input()` decorators:
+
+```ts
+import { Component, input } from '@angular/core';
+import { Routes } from '@angular/router';
+
+@Component({
+  template: `
+    <h2>{{ name() }}</h2>
+    <p>Age: {{ age() }}</p>
+    <p>Role: {{ role() }}</p>
+  `,
+})
+export class ProfileComponent {
+  name = input('Guest');
+  age = input(0);
+  role = input('user');
+}
+
+test('pass inputs via route data', async () => {
+  const routes: Routes = [
+    {
+      path: 'profile',
+      component: ProfileComponent,
+      data: {
+        name: 'Jane Doe',
+        age: 30,
+        role: 'admin',
+      },
+    },
+  ];
+
+  const { locator, componentClassInstance } = await render(ProfileComponent, {
+    withRouting: {
+      routes,
+      initialRoute: '/profile',
+    },
+  });
+
+  // Inputs are automatically bound from route data
+  expect(componentClassInstance.name()).toBe('Jane Doe');
+  expect(componentClassInstance.age()).toBe(30);
+  expect(componentClassInstance.role()).toBe('admin');
+
+  await expect.element(locator.getByText('Jane Doe')).toBeVisible();
+});
+```
+
+### Disabling Input Binding
+
+If you need to manually handle route data via `ActivatedRoute` instead of automatic input binding, use `disableInputBinding`:
+
+```ts
+test('disable automatic input binding', async () => {
+  const routes: Routes = [
+    {
+      path: 'profile',
+      component: ProfileComponent,
+      data: { name: 'Jane Doe' },
+    },
+  ];
+
+  const { componentClassInstance } = await render(ProfileComponent, {
+    withRouting: {
+      routes,
+      initialRoute: '/profile',
+      disableInputBinding: true, // Inputs will NOT be bound from route data
+    },
+  });
+
+  // Inputs retain their default values
+  expect(componentClassInstance.name()).toBe('Guest');
 });
 ```
 
@@ -172,11 +432,13 @@ export class HelloWorldComponent {
 }
 
 test('renders component with service provider', async () => {
-  const { component } = await render(ServiceConsumerComponent, {
+  const screen = await render(ServiceConsumerComponent, {
     componentProviders: [
       { provide: GreetingService, useClass: FakeGreetingService },
     ],
   });
+
+  await expect.element(screen.getByText('Fake Greeting')).toBeVisible();
 });
 ```
 

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { i as RenderResult, n as RenderConfig, o as cleanup, r as RenderFn, s as render, t as Inputs } from "./pure-WnJuXVlP.mjs";
+import { a as RenderResult, c as render, i as RenderFn, n as Inputs, r as RenderConfig, s as cleanup } from "./pure-iXV3gO_T.mjs";
 
 //#region src/index.d.ts
 declare module "vitest/browser" {

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { n as render, t as cleanup } from "./pure-B-Ur9eBk.mjs";
+import { n as render, t as cleanup } from "./pure-dwpG9XN0.mjs";
 import { beforeEach } from "vitest";
 import { page } from "vitest/browser";
 

package/dist/pure-dwpG9XN0.mjs

@@ -0,0 +1,93 @@
+import { page, utils } from "vitest/browser";
+import { inputBinding } from "@angular/core";
+import { TestBed, ɵgetCleanupHook } from "@angular/core/testing";
+import { Router, provideRouter, withComponentInputBinding } from "@angular/router";
+import { RouterTestingHarness } from "@angular/router/testing";
+
+//#region src/pure.ts
+const { debug, getElementLocatorSelectors } = utils;
+/**
+* Renders an Angular component for testing with Vitest Browser Mode.
+*
+* @param componentClass - The component class to render
+* @param options - Configuration options for rendering
+* @returns A promise that resolves to the render result with locators and component access
+*
+* @example
+* ```typescript
+* // Basic render
+* const { locator } = await render(MyComponent);
+* await expect.element(locator.getByText('Hello')).toBeVisible();
+*
+* // With inputs
+* const { componentClassInstance } = await render(UserComponent, {
+*   inputs: { name: 'John', age: 30 },
+* });
+*
+* // With routing and route data as inputs
+* const { router } = await render(ProfileComponent, {
+*   withRouting: {
+*     routes: [{ path: 'profile', component: ProfileComponent, data: { userId: '42' } }],
+*     initialRoute: '/profile',
+*   },
+* });
+* ```
+*/
+async function render(componentClass, options) {
+	const imports = [componentClass, ...options?.imports || []];
+	const providers = [...options?.providers || []];
+	const baseElement = options?.baseElement || document.body;
+	if (options?.withRouting && options?.inputs) console.warn("[vitest-browser-angular] Using `inputs` with `withRouting` is not supported. Inputs cannot be passed directly to routed components. Consider passing data via route params, query params, or route data instead.");
+	const routingConfig = options?.withRouting ? typeof options.withRouting === "boolean" ? {
+		routes: [{
+			path: "**",
+			component: componentClass
+		}],
+		initialRoute: "/"
+	} : options.withRouting : void 0;
+	if (routingConfig) if (routingConfig.disableInputBinding) providers.push(provideRouter(routingConfig.routes));
+	else providers.push(provideRouter(routingConfig.routes, withComponentInputBinding()));
+	TestBed.configureTestingModule({
+		imports,
+		providers
+	});
+	if (options?.componentProviders) TestBed.overrideComponent(componentClass, { add: { providers: options.componentProviders } });
+	let fixture;
+	let container;
+	let componentClassInstance;
+	let routerHarness;
+	let router;
+	if (routingConfig) {
+		routerHarness = await RouterTestingHarness.create(routingConfig.initialRoute);
+		router = TestBed.inject(Router);
+		fixture = routerHarness.fixture;
+		container = routerHarness.routeNativeElement;
+		componentClassInstance = routerHarness.routeDebugElement?.componentInstance;
+	} else {
+		const bindings = Object.entries(options?.inputs ?? {}).map(([key, value]) => inputBinding(key, () => value));
+		fixture = TestBed.createComponent(componentClass, { bindings });
+		container = fixture.nativeElement;
+		componentClassInstance = fixture.componentInstance;
+	}
+	fixture.autoDetectChanges();
+	await fixture.whenStable();
+	const locator = page.elementLocator(container);
+	return {
+		baseElement,
+		container,
+		fixture,
+		debug: (el = baseElement, maxLength, opts) => debug(el, maxLength, opts),
+		componentClassInstance,
+		component: locator,
+		locator,
+		routerHarness,
+		router,
+		...getElementLocatorSelectors(baseElement)
+	};
+}
+function cleanup(shouldTeardown = false) {
+	return ɵgetCleanupHook(shouldTeardown)();
+}
+
+//#endregion
+export { render as n, cleanup as t };

package/dist/pure-iXV3gO_T.d.mts

@@ -0,0 +1,190 @@
+import { Locator, LocatorSelectors, PrettyDOMOptions } from "vitest/browser";
+import { EnvironmentProviders, InputSignal, Provider, Type } from "@angular/core";
+import { ComponentFixture } from "@angular/core/testing";
+import { Router, Routes } from "@angular/router";
+import { RouterTestingHarness } from "@angular/router/testing";
+
+//#region src/pure.d.ts
+
+/**
+ * Configuration options for rendering components with Angular Router support.
+ *
+ * @example
+ * ```typescript
+ * // Basic routing with route params
+ * await render(UserComponent, {
+ *   withRouting: {
+ *     routes: [{ path: 'user/:id', component: UserComponent }],
+ *     initialRoute: '/user/42',
+ *   },
+ * });
+ *
+ * // Passing inputs via route data (uses withComponentInputBinding)
+ * await render(ProfileComponent, {
+ *   withRouting: {
+ *     routes: [{
+ *       path: 'profile',
+ *       component: ProfileComponent,
+ *       data: { name: 'John', age: 30 },
+ *     }],
+ *     initialRoute: '/profile',
+ *   },
+ * });
+ * ```
+ */
+interface RoutingConfig {
+  /**
+   * The route configuration to use. These routes are passed to `provideRouter()`.
+   */
+  routes: Routes;
+  /**
+   * The initial route to navigate to after setting up the router.
+   * This triggers navigation and activates the matching route's component.
+   *
+   * @example '/user/42' or '/profile?tab=settings'
+   */
+  initialRoute?: string;
+  /**
+   * When `true`, disables Angular's `withComponentInputBinding()` feature.
+   *
+   * By default, `withComponentInputBinding()` is enabled, which automatically
+   * binds route params, query params, and route data to matching component inputs.
+   *
+   * Set this to `true` if you want to manually handle route data via `ActivatedRoute`.
+   *
+   * @default false
+   */
+  disableInputBinding?: boolean;
+}
+type Inputs<CMP_TYPE extends Type<unknown>> = Partial<{ [PROP in keyof InstanceType<CMP_TYPE> as InstanceType<CMP_TYPE>[PROP] extends InputSignal<unknown> ? PROP : never]: InstanceType<CMP_TYPE>[PROP] extends InputSignal<infer VALUE> ? VALUE : never }>;
+/**
+ * Options for rendering a component with `render()`.
+ */
+interface ComponentRenderOptions<CMP_TYPE extends Type<unknown> = Type<unknown>> {
+  /** The base element to render into. Defaults to `document.body`. */
+  baseElement?: HTMLElement;
+  /**
+   * Input values to pass to the component.
+   *
+   * Note: When using `withRouting`, inputs cannot be passed directly.
+   * Use route `data` instead.
+   */
+  inputs?: Inputs<CMP_TYPE>;
+  /**
+   * Enable Angular Router support for the component.
+   *
+   * - When `true`: Creates a wildcard route for the component and navigates to `/`.
+   * - When `RoutingConfig`: Uses the provided routes and initial route.
+   *
+   * By default, `withComponentInputBinding()` is enabled, allowing you to pass
+   * inputs via route `data`, route params, or query params.
+   *
+   * @example
+   * ```typescript
+   * // Simple routing (component matches any route)
+   * await render(MyComponent, { withRouting: true });
+   *
+   * // Full routing configuration
+   * await render(UserComponent, {
+   *   withRouting: {
+   *     routes: [
+   *       { path: 'user/:id', component: UserComponent, data: { role: 'admin' } }
+   *     ],
+   *     initialRoute: '/user/42',
+   *   },
+   * });
+   * ```
+   */
+  withRouting?: RoutingConfig | boolean;
+  /** Additional providers to configure in the testing module. */
+  providers?: Array<Provider | EnvironmentProviders>;
+  /** Providers to add specifically to the component being rendered. */
+  componentProviders?: Array<Provider>;
+  /** Additional imports for the testing module. */
+  imports?: unknown[];
+}
+/**
+ * @deprecated Use ComponentRenderOptions instead
+ */
+type RenderConfig<CMP_TYPE extends Type<unknown> = Type<unknown>> = ComponentRenderOptions<CMP_TYPE>;
+interface RenderResult<T> extends LocatorSelectors {
+  baseElement: HTMLElement;
+  container: HTMLElement;
+  /**
+   * The ComponentFixture for the rendered component.
+   * When using `withRouting`, this is the RouterTestingHarness's internal fixture
+   * not a fixture of `T` directly.
+   */
+  fixture: ComponentFixture<T> | InstanceType<typeof RouterTestingHarness>["fixture"];
+  debug(el?: HTMLElement | HTMLElement[] | Locator | Locator[], maxLength?: number, options?: PrettyDOMOptions): void;
+  /**
+   * @deprecated Use locator instead
+   */
+  component: Locator;
+  /** Vitest browser locator scoped to the rendered component's container. */
+  locator: Locator;
+  /** The instance of the rendered component's class. */
+  componentClassInstance: T;
+  /**
+   * The RouterTestingHarness instance. Only available when `withRouting` is used.
+   *
+   * **Preferred for navigation in tests.** Use `navigateByUrl()` which:
+   * - Waits for all redirects to complete
+   * - Automatically runs change detection
+   * - Returns the activated component instance
+   * - Handles guard rejections gracefully
+   *
+   * @example
+   * ```typescript
+   * // Navigate and get the activated component
+   * const userComponent = await routerHarness.navigateByUrl('/user/42', UserComponent);
+   *
+   * // Simple navigation
+   * await routerHarness.navigateByUrl('/about');
+   * ```
+   */
+  routerHarness?: RouterTestingHarness;
+  /**
+   * The Angular Router instance. Only available when `withRouting` is used.
+   *
+   * Useful for inspecting router state. For navigation, prefer `routerHarness.navigateByUrl()`.
+   *
+   * @example
+   * ```typescript
+   * expect(router.url).toBe('/user/42');
+   * ```
+   */
+  router?: Router;
+}
+type RenderFn = <T>(component: Type<T>, options?: ComponentRenderOptions<Type<T>>) => Promise<RenderResult<T>>;
+/**
+ * Renders an Angular component for testing with Vitest Browser Mode.
+ *
+ * @param componentClass - The component class to render
+ * @param options - Configuration options for rendering
+ * @returns A promise that resolves to the render result with locators and component access
+ *
+ * @example
+ * ```typescript
+ * // Basic render
+ * const { locator } = await render(MyComponent);
+ * await expect.element(locator.getByText('Hello')).toBeVisible();
+ *
+ * // With inputs
+ * const { componentClassInstance } = await render(UserComponent, {
+ *   inputs: { name: 'John', age: 30 },
+ * });
+ *
+ * // With routing and route data as inputs
+ * const { router } = await render(ProfileComponent, {
+ *   withRouting: {
+ *     routes: [{ path: 'profile', component: ProfileComponent, data: { userId: '42' } }],
+ *     initialRoute: '/profile',
+ *   },
+ * });
+ * ```
+ */
+declare function render<T>(componentClass: Type<T>, options?: ComponentRenderOptions<Type<T>>): Promise<RenderResult<T>>;
+declare function cleanup(shouldTeardown?: boolean): void;
+//#endregion
+export { RenderResult as a, render as c, RenderFn as i, Inputs as n, RoutingConfig as o, RenderConfig as r, cleanup as s, ComponentRenderOptions as t };

package/dist/pure.d.mts

@@ -1,2 +1,2 @@
-import { a as RoutingConfig, i as RenderResult, n as RenderConfig, o as cleanup, r as RenderFn, s as render, t as Inputs } from "./pure-WnJuXVlP.mjs";
-export { Inputs, RenderConfig, RenderFn, RenderResult, RoutingConfig, cleanup, render };
+import { a as RenderResult, c as render, i as RenderFn, n as Inputs, o as RoutingConfig, r as RenderConfig, s as cleanup, t as ComponentRenderOptions } from "./pure-iXV3gO_T.mjs";
+export { ComponentRenderOptions, Inputs, RenderConfig, RenderFn, RenderResult, RoutingConfig, cleanup, render };

package/dist/pure.mjs

@@ -1,3 +1,3 @@
-import { n as render, t as cleanup } from "./pure-B-Ur9eBk.mjs";
+import { n as render, t as cleanup } from "./pure-dwpG9XN0.mjs";
 
 export { cleanup, render };