From 28520e6ac1079577477a533ff18165276049a573 Mon Sep 17 00:00:00 2001 From: Younes Jaaidi Date: Wed, 4 Feb 2026 16:03:33 +0100 Subject: [PATCH 1/6] docs: embed setup instructions for Angular CLI & Analog --- README.md | 124 +++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 118 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 18c9dc7..8c5ae15 100644 --- a/README.md +++ b/README.md @@ -1,21 +1,133 @@ # 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: '

Hello, {{ name() }}!

', +}) +export class HelloWorld { + name = input.required() +} + +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: +- Angular CLI's [`unit-test` builder](https://angular.dev/guide/testing#configuration) *(official)*. +- Analog's [`vitest-angular` plugin](https://analogjs.org/docs/features/testing/vitest) *(community)*. + + +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 -pnpm add -D vitest-browser-angular +npm add -D @analogjs/platform @nx/devkit vitest-browser-angular + +ng g @analogjs/platform:setup-vitest ``` -## Setup Test Environment +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"] + } + } + } + } + } +} +``` -To set up your test environment (with Zone.js or Zoneless), use `@analogjs/vitest-angular`'s `setupTestBed()` function. +*Since Angular v21, Vitest is the default runner so you don't need to set the `runner` option.* -**Important:** Make sure to use `{ browserMode: true }` when calling `setupTestBed()` to enable Vitest browser mode's visual test preview functionality. +Note: You can override the browsers from the command line using the `--browsers` option. + +```sh +ng test --browsers=ChromiumHeadless +``` + +2. Install the browser provider of your choice using `ng add` + +```sh +# With Playwright +ng add @vitest/browser-playwright + +# or with WebdriverIO +ng add @vitest/browser-webdriverio +``` + +3. Add the `vitest-browser-angular` package to your project. + +```sh +npm add -D vitest-browser-angular +``` + + +## Zone.js and 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, this is done using the `--debug` option. + +With the Analog plugin, this is done 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 From 9c5676c5d2892cfadd5b7f1ff3c0cd703f3e6c51 Mon Sep 17 00:00:00 2001 From: Younes Jaaidi Date: Wed, 4 Feb 2026 16:29:50 +0100 Subject: [PATCH 2/6] docs: rephrase --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 8c5ae15..475ff91 100644 --- a/README.md +++ b/README.md @@ -116,9 +116,9 @@ For detailed setup instructions for both Zone.js and Zoneless configurations, pl To preview, debug and interact with a component in the browser after the test, you can prevent Angular from destroying it. -In Angular CLI, this is done using the `--debug` option. +In Angular CLI, enable this using the `--debug` option. -With the Analog plugin, this is done using the `browserMode` option of `setupTestBed()` in `test-setup.ts`: +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'; From cd2bec4f7afc059272bfd7b549816f961a0d2172 Mon Sep 17 00:00:00 2001 From: Younes Jaaidi Date: Wed, 4 Feb 2026 16:36:59 +0100 Subject: [PATCH 3/6] docs: remove the --browser option mention to unclutter the setup --- README.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/README.md b/README.md index 475ff91..fde8fb3 100644 --- a/README.md +++ b/README.md @@ -72,12 +72,6 @@ ng g @analogjs/platform:setup-vitest *Since Angular v21, Vitest is the default runner so you don't need to set the `runner` option.* -Note: You can override the browsers from the command line using the `--browsers` option. - -```sh -ng test --browsers=ChromiumHeadless -``` - 2. Install the browser provider of your choice using `ng add` ```sh From 0d425a1876c4d17e22d4ce8a4169d1b5cba5161a Mon Sep 17 00:00:00 2001 From: Shai Reznik Date: Sun, 15 Mar 2026 14:36:40 +0200 Subject: [PATCH 4/6] Apply suggestion from @shairez I think because we're recommending the vite plugin because it has more features, we should display it first --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index fde8fb3..ed9f00c 100644 --- a/README.md +++ b/README.md @@ -29,8 +29,8 @@ test('renders name', async () => { ## Setup There are currently two ways to set up Vitest for Angular: -- Angular CLI's [`unit-test` builder](https://angular.dev/guide/testing#configuration) *(official)*. - 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. From 42ddecb24fcffccfa4137c4c9664834c30fcaaba Mon Sep 17 00:00:00 2001 From: Shai Reznik Date: Sun, 15 Mar 2026 14:37:28 +0200 Subject: [PATCH 5/6] Apply suggestion from @shairez I think this removes the need for it right? analogjs/analog#2056 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ed9f00c..56cd8b4 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,7 @@ While Angular CLI's `unit-test` builder is the official way to set up Vitest for 1. Set up Vitest ```sh -npm add -D @analogjs/platform @nx/devkit vitest-browser-angular +npm add -D @analogjs/platform vitest-browser-angular ng g @analogjs/platform:setup-vitest ``` From 7484537cb7cb336194547fa766650edf2be78445 Mon Sep 17 00:00:00 2001 From: Shai Reznik Date: Sun, 15 Mar 2026 14:38:03 +0200 Subject: [PATCH 6/6] Apply suggestion from @shairez --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 56cd8b4..3ada428 100644 --- a/README.md +++ b/README.md @@ -89,7 +89,7 @@ npm add -D vitest-browser-angular ``` -## Zone.js and Zoneless Setup +## 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.