docs(browser): add render libraries examples by sheremet-va · Pull Request #9325 · vitest-dev/vitest

sheremet-va · 2025-12-22T18:53:34Z

Description

Resolves #9019

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

It's really useful if your PR references an issue where it is discussed ahead of time. If the feature is substantial or introduces breaking changes without a discussion, PR might be closed.
Ideally, include a test that fails without this PR but passes with it.
Please, don't make changes to pnpm-lock.yaml unless you introduce a new test example.
Please check Allow edits by maintainers to make review process faster. Note that this option is not available for repositories that are owned by Github organizations.

Tests

Run the tests with pnpm test:ci.

Documentation

If you introduce new functionality, document it. You can run documentation with pnpm run docs command.

Changesets

Changes in changelog are generated from PR name. Please, make sure that it explains your changes in an understandable manner. Please, prefix changeset messages with feat:, fix:, perf:, docs:, or chore:.

netlify · 2025-12-22T18:55:33Z

✅ Deploy Preview for vitest-dev ready!

Name	Link
🔨 Latest commit	`b7f7d1e`
🔍 Latest deploy log	https://app.netlify.com/projects/vitest-dev/deploys/698481fd769e0e00080ec65d
😎 Deploy Preview	https://deploy-preview-9325--vitest-dev.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

…der-functions-examples

macarie

I like having these in the main docs, they're easier to discover 😄

Just a couple of small suggestions regarding wording. I believe some of them (the container-related ones) also apply to the Vue page.

docs/api/browser/react.md

mcous

Looks great! Got a few minor corrections for the Svelte usage since its options aren't exactly symmetrical with React testing library

docs/api/browser/svelte.md

docs/api/browser/angular.md

shairez · 2026-01-16T15:27:05Z

docs/api/browser/angular.md

+`vitest-browser-angular` returns APIs that interact well with built-in [locators](/api/browser/locators), [user events](/api/browser/interactivity) and [assertions](/api/browser/assertions): for example, Vitest will automatically retry the element until the assertion is successful, even if it was rerendered between the assertions.
+:::
+
+The package exposes two entry points: `vitest-browser-angular` and `vitest-browser-angular/pure`. They expose identical API, but the `pure` entry point doesn't add a handler to remove the component before the next test has started.


I'm not sure this is accurate, the package.json currently doesn't export the /pure

This is a convention in other packages, do you think it makes sense to expose in angular?

Oh! I didn't know pure was exposed in other packages.
What are the use cases for the pure entry point? Why would users opt-out of cleanup?

Also, there are two Angular specificities:

whether users are using Angular CLI or Analog, cleanup will be registered between tests (either through afterEach or beforeEach depending on an Angular's TestBed flag)

not cleaning up between tests will often break because the the TestBed has two phases, a configuration phase, and an instantiation phase. Once a component is instantiated, calling a configuration API would fail unless there was a cleanup.

Therefore, I still can't see the value of exposing pure.

In other frameworks people can disable automatic cleanup to do it manually. For example, to move it into a different hook, or add an extra action before/after cleanup. If this is not advisable with how angular testing works, we don't have to add this entry point

shairez · 2026-01-16T15:28:54Z

docs/api/browser/angular.md

+
+## Setup
+
+Before using `vitest-browser-angular`, you need to set up the test environment using `@analogjs/vitest-angular`:


I think it's best to take the approach that @yjaaidi and I took which is to point to the analog vitest docs (because the setup might change from time to time so you don't want to keep maintaining this).

So we could point to their docs (like with do on the README) and also give a link to our vitest setup file (for the repo's own tests) to show a practical example

To be fair, as someone who is not familiar with angular, I was very confused by the setup instructions in vitest-browser-angular and had to spend more time than I'd like in unrelated (to my eye) documentation (analog)

We try to follow this principle in our docs:

Be Self-Contained - While there are a number of existing tools Vitest pulls in or works like (Chai, Jest, etc…), whenever something is important enough to include in documentation, descriptions and usage examples should be included in the docs instead of linked to an outside source. This will help keep users focused on their task at hand without jumping between multiple tabs to understand a single concept.

#279

Changing a doc if something changes doesn't seem bad in my opinion

The think about Angular is that we currently have two options:

Angular CLI's unit-test builder (the official approach which has limitations as it wraps Vitest instead of providing a plugin)

Analog approach for those who want more features, more control, and more alignment with Vitest.

We could either document the Angular CLI approach and link to the Analog documentation for those who want to use it.
Or document both in different sections or tabs.

For Angular, enabling browser mode resides in adding browsers option in angular.json's test config.
https://angular.dev/guide/testing#running-tests-in-a-browser:~:text=Once%20the%20provider,angular.json

{ "projects": { "your-project-name": { "architect": { "test": { "builder": "@angular/build:unit-test", "options": { "browsers": ["Chromium", "Firefox", "Safari"] // Add "Headless" suffix to enable headless 🤷 } } } } } }

We need to document all possible approaches. Setting this up is frankly annoying without a proper guide. We don't need to document all config options (like the headless note), just how to get started with testing

I agree if the approach is to copy their docs every time they change, we need to show both, not just one way

Sure, let’s show both. We don’t need to copy the whole doc, just the setup with a link to the original doc that expands what we showed. At the moment readme from your package lead me to analog doc that I just copied here. Turns out, it’s not actually correct. Which means the current approach to just simply link is flawed

well each one has its trade-offs IMO, I don't think one is flawed and the other is not, it's just a matter of how many places you want to keep submitting the fix PR to... 😅

(and I'm not sure the analog docs has a mistake, what younes said is that it's just not relevant if one goes with the native angular cli way, but AFAIK you do need the compiler if you go with analog )

I originally had all the setup steps as part of the README of the package, but after talking with @yjaaidi , we agreed that it's best to link to analog's setup as it keeps being updated, than to play catch with it every time it changes.

Angular, unfortunately, has its own way of doing things ( I wish it was just a vite plugin and we could consolidate everything into one thing), and that forces us to instead of showing one way we need to show 2 ways... which is not fun.

But we can show 2 minimal setups, and we'll just need to keep in mind we'll need to maintain them as things change

Hey guys, I've just created a PR for vitest-browser-angular README.
I tried to document both approaches (Angular CLI & Analog) while embedding instructions that should work out of the box.

Once @shairez reviews it, we could use it as a source of inspiration for the docs.

docs/api/browser/angular.md

yjaaidi · 2026-01-23T20:23:17Z

docs/api/browser/angular.md

+  selector: 'app-hello-world',
+  template: '<h1>Hello, {{ name() }}!</h1>',
+})
+export class HelloWorldComponent {


nit: I would remove the Component suffix. The convention was removed from the Angular style guide + it aligns more with other frameworks.

yjaaidi · 2026-01-23T20:36:55Z

docs/api/browser/angular.md

+`vitest-browser-angular` returns APIs that interact well with built-in [locators](/api/browser/locators), [user events](/api/browser/interactivity) and [assertions](/api/browser/assertions): for example, Vitest will automatically retry the element until the assertion is successful, even if it was rerendered between the assertions.
+:::
+
+The package exposes two entry points: `vitest-browser-angular` and `vitest-browser-angular/pure`. They expose identical API, but the `pure` entry point doesn't add a handler to remove the component before the next test has started.


Oh! I didn't know pure was exposed in other packages.
What are the use cases for the pure entry point? Why would users opt-out of cleanup?

Also, there are two Angular specificities:

whether users are using Angular CLI or Analog, cleanup will be registered between tests (either through afterEach or beforeEach depending on an Angular's TestBed flag)

not cleaning up between tests will often break because the the TestBed has two phases, a configuration phase, and an instantiation phase. Once a component is instantiated, calling a configuration API would fail unless there was a cleanup.

Therefore, I still can't see the value of exposing pure.

yjaaidi · 2026-01-23T20:52:03Z

docs/api/browser/angular.md

+
+## Setup
+
+Before using `vitest-browser-angular`, you need to set up the test environment using `@analogjs/vitest-angular`:


The think about Angular is that we currently have two options:

Angular CLI's unit-test builder (the official approach which has limitations as it wraps Vitest instead of providing a plugin)

Analog approach for those who want more features, more control, and more alignment with Vitest.

We could either document the Angular CLI approach and link to the Analog documentation for those who want to use it.
Or document both in different sections or tabs.

For Angular, enabling browser mode resides in adding browsers option in angular.json's test config.
https://angular.dev/guide/testing#running-tests-in-a-browser:~:text=Once%20the%20provider,angular.json

{ "projects": { "your-project-name": { "architect": { "test": { "builder": "@angular/build:unit-test", "options": { "browsers": ["Chromium", "Firefox", "Safari"] // Add "Headless" suffix to enable headless 🤷 } } } } } }

yjaaidi · 2026-01-23T20:59:28Z

docs/api/browser/angular.md

+
+Before using `vitest-browser-angular`, you need to set up the test environment using `@analogjs/vitest-angular`:
+
+::: code-group


With the Angular CLI approach, we don't need the configuration below.

It is very confusing how to configure vitest-browser-angular to work. The readme just redirects to analog, so these examples are from there. If it is not valid, then let's update README and this doc to include all possible setups. I have no idea how to set it up

yjaaidi · 2026-01-23T21:00:49Z

docs/api/browser/angular.md

+
+::: code-group
+```ts [zoneless]
+import '@angular/compiler'


We still have to discuss this with @shairez. @angular/compiler should not be necessary, especially if we enable AOT which is the default behavior with the Angular CLI unit-test builder.

This is an example from analog linked from vitest-browser-angular README

yjaaidi · 2026-01-23T22:28:50Z

docs/api/browser/angular.md

+
+### componentClassInstance
+
+The actual Angular component class instance. Use this to access component methods and properties directly.


I would add a warning here to discourage this usage.
The component instance should be considered an implementation detail.

yjaaidi · 2026-02-04T16:03:57Z

@shairez suggested that we contribute directly to this PR. Would that work for you @sheremet-va?

I just took time to read everything thoroughly and here is a quick summary of the changes that I would make:

I would update the first example to be interactive (e.g. a counter just like other frameworks.
Update setup instructions as in docs: embed setup instructions for Angular CLI & Analog vitest-community/vitest-browser-angular#21
Remove the example from componentProviders option as it can be considered an advanced use case and users should pick the providers option unless they know what they are doing
Do not document the imports option. Users should use providers combined with importProvidersFrom
Do not document the withRouting, componentClassInstance, router, and routerHarness. This is something that we still have to discuss internally but I'd rather not expose these in the docs until we decide whether we keep them or not.
Update fixture example by removing the fixture.detectChanges call — it's better to discourage users from using it.
We could add a link to https://angular.dev/api/core/testing/ComponentFixture# in fixture
Probably remove the examples at the bottom. Having an interactive first example such as a counter is probably enough.

What do you think Shai?
Depending on Shai's feedback we can then:

suggest changes on this PR
make a PR against this PR
remove the angular.md file from this PR so that we do not block other frameworks then submit a dedicated Angular PR

Whatever works for you Vlad.

sheremet-va · 2026-02-05T11:17:29Z

remove the angular.md file from this PR so that we do not block other frameworks then submit a dedicated Angular PR

Let's add the angular one in a separate PR to unblock this one.

…der-functions-examples

docs(browser): add render libraries examples

15146c3

sheremet-va mentioned this pull request Dec 22, 2025

Testing passing children vitest-community/vitest-browser-svelte#16

Open

sheremet-va added 11 commits January 4, 2026 12:50

docs: move to api

15ab21b

Merge branch 'main' of github.com:vitest-dev/vitest into docs/add-ren…

83fca6b

…der-functions-examples

docs: add react api/options

110144c

docs: add base for vue

81c6c86

chore: add warning

b48e029

Merge branch 'main' of github.com:vitest-dev/vitest into docs/add-ren…

35d979d

…der-functions-examples

Merge branch 'main' of github.com:vitest-dev/vitest into docs/add-ren…

3b64030

…der-functions-examples

docs: add svelte example

966fc37

docs: add angular

79d92c5

chore: mark required

252329e

chore: add extend queries

4ae18be

macarie reviewed Jan 14, 2026

View reviewed changes

docs/api/browser/react.md Show resolved Hide resolved

docs/api/browser/react.md Outdated Show resolved Hide resolved

docs/api/browser/react.md Outdated Show resolved Hide resolved

docs/api/browser/react.md Show resolved Hide resolved

chore: review

60fe7a2

mcous reviewed Jan 14, 2026

View reviewed changes

docs: fix svelte examples

b446cf0

shairez reviewed Jan 15, 2026

View reviewed changes

docs/api/browser/angular.md Outdated Show resolved Hide resolved

docs: update angular example

a70261c

shairez reviewed Jan 16, 2026

View reviewed changes

docs/api/browser/angular.md Outdated Show resolved Hide resolved

shairez reviewed Jan 16, 2026

View reviewed changes

docs/api/browser/angular.md Outdated Show resolved Hide resolved

docs: update angular doc

d835ec8

sheremet-va mentioned this pull request Jan 22, 2026

Attach a stable testid to default baseElement vitest-community/vitest-browser-react#44

Merged

yjaaidi reviewed Jan 23, 2026

View reviewed changes

docs: remove angular for now

fdb92e0

sheremet-va added 3 commits February 5, 2026 12:18

Merge branch 'main' of github.com:vitest-dev/vitest into docs/add-ren…

ac441f2

…der-functions-examples

docs: improve vue doc, cleanup others

17daf14

chore: cleanup

b7f7d1e

sheremet-va merged commit 70d4c2e into vitest-dev:main Feb 5, 2026
10 checks passed

sheremet-va deleted the docs/add-render-functions-examples branch February 5, 2026 11:49


		## Setup

		Before using `vitest-browser-angular`, you need to set up the test environment using `@analogjs/vitest-angular`:


		Before using `vitest-browser-angular`, you need to set up the test environment using `@analogjs/vitest-angular`:

		::: code-group


		### componentClassInstance

		The actual Angular component class instance. Use this to access component methods and properties directly.

Uh oh!

Comments

Conversation

sheremet-va commented Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

Tests

Documentation

Changesets

Uh oh!

netlify bot commented Dec 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for vitest-dev ready!

Uh oh!

macarie left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mcous left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sheremet-va Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sheremet-va Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sheremet-va Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

shairez Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sheremet-va Jan 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

sheremet-va commented Dec 22, 2025 •

edited

Loading

netlify bot commented Dec 22, 2025 •

edited

Loading

sheremet-va Jan 16, 2026 •

edited

Loading

sheremet-va Jan 24, 2026 •

edited

Loading

sheremet-va Jan 27, 2026 •

edited

Loading

shairez Jan 27, 2026 •

edited

Loading

sheremet-va Jan 24, 2026 •

edited

Loading