vitest-browser-angular 0.1.0 → 0.3.0

package/README.md

@@ -18,23 +18,69 @@ For detailed setup instructions for both Zone.js and Zoneless configurations, pl
 
 ## Usage
 
+### Basic Example
+
+The `render` function supports two query patterns:
+
 ```ts
-import { test, expect } from 'vitest-browser-angular';
+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();
 
-test('render', async () => {
-  const { component } = await render(HelloWorldComponent);
-  await expect.element(component).toHaveTextContent('Hello World');
+  // 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).
+
+### 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
 
 Pass input values to components using the `inputs` option:
@@ -52,15 +98,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 +137,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 +189,42 @@ const routes: Routes = [
 ];
 
 test('render with route configuration', async () => {
-  const { component, router } = await render(AppComponent, {
+  const { locator, router } = await render(AppComponent, {
     withRouting: {
       routes,
       initialRoute: '/home',
     },
   });
 
-  await expect.element(component).toHaveTextContent('Home Page');
+  await expect.element(locator).toHaveTextContent('Home Page');
 
   // Navigate programmatically
   await router.navigate(['/about']);
-  await expect.element(component).toHaveTextContent('About Page');
+  await expect.element(locator).toHaveTextContent('About Page');
+});
+```
+
+## Component Providers
+
+If you need to add or override [component providers](https://angular.dev/guide/di/defining-dependency-providers#component-or-directive-providers), you can use the `componentProviders` option.
+
+```ts
+@Component({
+  template: '<h1>{{ title }}</h1>',
+  providers: [GreetingService],
+})
+export class HelloWorldComponent {
+  title = 'Hello World';
+}
+
+test('renders component with service provider', async () => {
+  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-HXi6YW9E.mjs";
+import { a as RenderResult, c as render, i as RenderFn, n as Inputs, r as RenderConfig, s as cleanup } from "./pure-DIxLzF0p.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-C8IyvQ5e.mjs";
+import { n as render, t as cleanup } from "./pure-CSDeMQ9B.mjs";
 import { beforeEach } from "vitest";
 import { page } from "vitest/browser";
 

package/dist/pure-CSDeMQ9B.mjs

@@ -0,0 +1,50 @@
+import { page, utils } from "vitest/browser";
+import { inputBinding } from "@angular/core";
+import { TestBed, ɵgetCleanupHook } from "@angular/core/testing";
+import { Router, provideRouter } from "@angular/router";
+import { RouterTestingHarness } from "@angular/router/testing";
+
+//#region src/pure.ts
+const { debug, getElementLocatorSelectors } = utils;
+async function render(componentClass, options) {
+	const imports = [componentClass, ...options?.imports || []];
+	const providers = [...options?.providers || []];
+	const renderResult = {};
+	const baseElement = options?.baseElement || document.body;
+	if (options?.withRouting) {
+		const routes = typeof options.withRouting === "boolean" ? [] : options.withRouting.routes;
+		providers.push(provideRouter(routes));
+	}
+	TestBed.configureTestingModule({
+		imports,
+		providers
+	});
+	if (options?.componentProviders) TestBed.overrideComponent(componentClass, { add: { providers: options.componentProviders } });
+	if (options?.withRouting) {
+		renderResult.routerHarness = await RouterTestingHarness.create(typeof options.withRouting === "boolean" ? void 0 : options.withRouting.initialRoute);
+		renderResult.router = TestBed.inject(Router);
+	}
+	const bindings = Object.entries(options?.inputs ?? {}).map(([key, value]) => inputBinding(key, () => value));
+	const fixture = TestBed.createComponent(componentClass, { bindings });
+	fixture.autoDetectChanges();
+	await fixture.whenStable();
+	const container = fixture.nativeElement;
+	const locator = page.elementLocator(container);
+	return {
+		...renderResult,
+		baseElement,
+		container,
+		fixture,
+		debug: (el = baseElement, maxLength, options$1) => debug(el, maxLength, options$1),
+		componentClassInstance: fixture.componentInstance,
+		component: locator,
+		locator,
+		...getElementLocatorSelectors(baseElement)
+	};
+}
+function cleanup(shouldTeardown = false) {
+	return ɵgetCleanupHook(shouldTeardown)();
+}
+
+//#endregion
+export { render as n, cleanup as t };

package/dist/pure-DIxLzF0p.d.mts

@@ -0,0 +1,43 @@
+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
+interface RoutingConfig {
+  routes: Routes;
+  initialRoute?: string;
+}
+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 }>;
+interface ComponentRenderOptions<CMP_TYPE extends Type<unknown> = Type<unknown>> {
+  baseElement?: HTMLElement;
+  inputs?: Inputs<CMP_TYPE>;
+  withRouting?: RoutingConfig | boolean;
+  providers?: Array<Provider | EnvironmentProviders>;
+  componentProviders?: Array<Provider>;
+  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;
+  fixture: ComponentFixture<T>;
+  debug(el?: HTMLElement | HTMLElement[] | Locator | Locator[], maxLength?: number, options?: PrettyDOMOptions): void;
+  /**
+   * @deprecated Use locator instead
+   */
+  component: Locator;
+  locator: Locator;
+  componentClassInstance: T;
+  routerHarness?: RouterTestingHarness;
+  router?: Router;
+}
+type RenderFn = <T>(component: Type<T>, options?: ComponentRenderOptions<Type<T>>) => Promise<RenderResult<T>>;
+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-HXi6YW9E.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-DIxLzF0p.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-C8IyvQ5e.mjs";
+import { n as render, t as cleanup } from "./pure-CSDeMQ9B.mjs";
 
 export { cleanup, render };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitest-browser-angular",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Render Angular components in VItest Browser Mode",
   "author": "Shai Reznik (HiRez.io)",
   "license": "MIT",

package/dist/pure-C8IyvQ5e.mjs

@@ -1,41 +0,0 @@
-import { page } from "vitest/browser";
-import { inputBinding } from "@angular/core";
-import { TestBed, ɵgetCleanupHook } from "@angular/core/testing";
-import { Router, provideRouter } from "@angular/router";
-import { RouterTestingHarness } from "@angular/router/testing";
-
-//#region src/pure.ts
-async function render(componentClass, config) {
-	const imports = [componentClass, ...config?.imports || []];
-	const providers = [...config?.providers || []];
-	const renderResult = {};
-	if (config?.withRouting) {
-		const routes = typeof config.withRouting === "boolean" ? [] : config.withRouting.routes;
-		providers.push(provideRouter(routes));
-	}
-	TestBed.configureTestingModule({
-		imports,
-		providers
-	});
-	if (config?.withRouting) {
-		renderResult.routerHarness = await RouterTestingHarness.create(typeof config.withRouting === "boolean" ? void 0 : config.withRouting.initialRoute);
-		renderResult.router = TestBed.inject(Router);
-	}
-	const bindings = Object.entries(config?.inputs ?? {}).map(([key, value]) => inputBinding(key, () => value));
-	const fixture = TestBed.createComponent(componentClass, { bindings });
-	fixture.autoDetectChanges();
-	await fixture.whenStable();
-	const component = page.elementLocator(fixture.nativeElement);
-	return {
-		...renderResult,
-		fixture,
-		componentClassInstance: fixture.componentInstance,
-		component
-	};
-}
-function cleanup(shouldTeardown = false) {
-	return ɵgetCleanupHook(shouldTeardown)();
-}
-
-//#endregion
-export { render as n, cleanup as t };

package/dist/pure-HXi6YW9E.d.mts

@@ -1,30 +0,0 @@
-import { Locator } 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
-interface RoutingConfig {
-  routes: Routes;
-  initialRoute?: string;
-}
-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 }>;
-interface RenderConfig<CMP_TYPE extends Type<unknown> = Type<unknown>> {
-  inputs?: Inputs<CMP_TYPE>;
-  withRouting?: RoutingConfig | boolean;
-  providers?: Array<Provider | EnvironmentProviders>;
-  imports?: unknown[];
-}
-interface RenderResult<T> {
-  fixture: ComponentFixture<T>;
-  component: Locator;
-  componentClassInstance: T;
-  routerHarness?: RouterTestingHarness;
-  router?: Router;
-}
-type RenderFn = <T>(component: Type<T>, config?: RenderConfig<Type<T>>) => Promise<RenderResult<T>>;
-declare function render<T>(componentClass: Type<T>, config?: RenderConfig<Type<T>>): Promise<RenderResult<T>>;
-declare function cleanup(shouldTeardown?: boolean): void;
-//#endregion
-export { RoutingConfig as a, RenderResult as i, RenderConfig as n, cleanup as o, RenderFn as r, render as s, Inputs as t };