docs: Clarify how to run unit tests in a browser-like environment

[DanielSidhion]

Closes #14239.

The docs had some missing code when setting up vitest for testing in a browser-like environment, which this PR addresses. It also clarifies that this is needed for tests that use $effect.root.

Given that a new svelte project (with vitest) created with the CLI doesn't change vite.config.js to include that browser-like environment config, it's easy to miss this extra config that is needed.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2ee724f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[Rich-Harris]

preview: https://svelte-dev-git-preview-svelte-14243-svelte.vercel.app/

this is an automated message

[dominikg]

see #14239 (comment)

the use of jsdom should be limited

[DanielSidhion]

Can you please explain in more details why using jsdom should be limited, and why it's not the right way? You made these assertions without explanations.

Here's my reasoning for this PR: the docs already have a step to tell vitest to use the browser entry points, and having vitest use jsdom seems like a missed step rather than a new step. This is especially true because the docs have an example that doesn't work (using $effect.root) if you're just following the docs.

If your concern is with bringing the "browser version" of code of all packages into tests, the docs also already have a link to testing-library/svelte-testing-library#222 (comment) which should give people good pointers on how to separate those things.

[dominikg]

if you add jsdom environment to test server code, and then load code that references eg the window global, that code might pass your test, but can fail when deployed into a node environment because there window is not defined.

See the example config i made here: https://github.com/dominikg/vitest-example-svelte5/blob/main/vitest.workspace.ts

where there are 2 "vitest workspaces" for tests, one in a client environment with jsdom and svelte-testing-library, and the other a node environment without client addons. Only files with .svelte in their name get tested in the client environment to avoid tests for server-only not failing as needed.

The template for adding vitest with sv add and our docs need to be updated to better address this. The current issue with "all files are tested in node environment so tests requiring a browser env fail" is not best solved with "lets run all tests in a browser env and risk others failing because of it"

[DanielSidhion]

Thank you! I understand better now the issue. I can do a bigger pass on this docs page to add this information, would that be ok, or is it a requirement to update the docs and sv add at the same time?

[dominikg]

the setup i mentioned earlier has been added to sv and the docs need a more thorough update to that. It was explained a bit in my talk at summit.

@DanielSidhion do you want to take a stab at it?

[DanielSidhion]

@dominikg I can, but I'm currently on vacation until the first week of June, so it'd have to wait a bit before I get to this. If that's not ok, feel free to take over the PR, otherwise I should have something in a couple weeks.

[DanielSidhion]

I'm back from vacation and watched the talk that @dominikg mentioned (here if you're curious). I'm planning to expand the unit test section with pretty much all the relevant content of the talk, and it seems like there's nothing to add regarding the E2E part of the docs when compared to the talk, so I'll keep the scope of this PR as-is.

Making this comment just so folks are aware I'm working on it. btw, thanks for the talk @dominikg ! It was great.

[dominikg]

thanks!!

Scott Spence did a great follow up blog post about it too.

https://scottspence.com/posts/migrating-from-testing-library-svelte-to-vitest-browser-svelte

it has a link to an examples repo as well.

i think it's enough to describe the test setup here and then link to the sv vitest addon docs and scotts examples

[svelte-docs-bot]

Preview: https://svelte-dev-git-preview-svelte-14243-svelte.vercel.app/

[DanielSidhion]

@dominikg I just pushed an initial attempt at updating the docs, would appreciate a review.

[dominikg]

Hey, thank you!!

Scott Spence has been doing a lot of work on https://sveltest.dev and its far more comprehensive than the docs here could be. I think it would be best to limit this section to a very brief overview ala

• use sv add vitest to set up unit and component testing
• one brief example of a unit test (take from sveltest.dev)
• one brief example of a component test
• use sv add playwright to set up end to end testing
• one brief example of an e2e test

and then link to sveltest.dev

• check out https://sveltest.dev for extensive documentation, examples and patterns

The examples in my talk were very basic and did not follow best practices enough (i have regrets).

I'd also leave out documentation of testing with jsdom, as we are in the process of changing the default to use vitest browser mode in sv, which helps cut down here as well because we don't need to document how to mock browser stuff in jsdom anymore. If you think this is still important, it should come in a "alternatives" section at the end with a note reminding that jsdom isn't a real browser and mocking browser things is tedious)

[dominikg]

@manuel3108 is there documentation for the sv vitest addon we can link here too?

[manuel3108]

@manuel3108 is there documentation for the sv vitest addon we can link here too?

There is this: https://svelte.dev/docs/cli/vitest
But it's really basic right now. Don't mind adding anything on there if we have good suggestions here. Or linking to the docs page discussed here. Or something else

[DanielSidhion]

I'd also leave out documentation of testing with jsdom, as we are in the process of changing the default to use vitest browser mode in sv, which helps cut down here as well because we don't need to document how to mock browser stuff in jsdom anymore. If you think this is still important, it should come in a "alternatives" section at the end with a note reminding that jsdom isn't a real browser and mocking browser things is tedious)

IMO it still feels important to keep jsdom. As an example, in a project I have a lot of tests for .svelte.ts files (using runes) which don't really need anything more than the default jsdom testing setup, and bringing an actual browser seems wasteful. I haven't measured the impact yet because I still need to set up playwright for the project. It's way more involved than just an npm add since I'm on non-ubuntu/non-debian Linux, which isn't officially supported by playwright, so I'll likely have to use docker images, which only complicates things more (both locally and in CI).

I don't mind the default from sv being browser mode, but completely getting rid of jsdom seems like a mistake as long as the alternative for unit/component-level testing is "figure out playwright on your system".

I can reorganise the sections and keep the jsdom stuff as an alternative. Do you think it's important to keep the "manual setup" section, or can we defer to sv for everything? This section is likely to be the one to go out of date more often.