From affc6d82d6b7f48f261422a173180144e38fa691 Mon Sep 17 00:00:00 2001 From: Mohammad Bagher Abiat Date: Wed, 5 Apr 2023 11:35:02 +0330 Subject: [PATCH] docs: add the motivation section for more context (#3104) Co-authored-by: Christian Bromann Co-authored-by: Vladimir Sheremet --- docs/api/vi.md | 4 ++++ docs/guide/browser.md | 26 ++++++++++++++++++++++++++ 2 files changed, 30 insertions(+) diff --git a/docs/api/vi.md b/docs/api/vi.md index 75f71af24..1c79384c4 100644 --- a/docs/api/vi.md +++ b/docs/api/vi.md @@ -126,6 +126,10 @@ import { vi } from 'vitest' Vitest statically analyzes your files to hoist `vi.mock`. It means that you cannot use `vi` that was not imported directly from `vitest` package (for example, from some utility file). To fix this, always use `vi.mock` with `vi` imported from `vitest`, or enable [`globals`](/config/#globals) config option. ::: + ::: warning + Mocking modules is not currently supported in the [browser mode](/guide/browser). You can track this feature in the GitHub issue. + ::: + If `factory` is defined, all imports will return its result. Vitest calls factory only once and caches result for all subsequent imports until [`vi.unmock`](#vi-unmock) or [`vi.doUnmock`](#vi-dounmock) is called. Unlike in `jest`, the factory can be asynchronous, so you can use [`vi.importActual`](#vi-importactual) or a helper, received as the first argument, inside to get the original module. diff --git a/docs/guide/browser.md b/docs/guide/browser.md index fa30197a6..161814a85 100644 --- a/docs/guide/browser.md +++ b/docs/guide/browser.md @@ -6,6 +6,32 @@ title: Browser Mode | Guide This page provides information about the experimental browser mode feature in the Vitest API, which allows you to run your tests in the browser natively, providing access to browser globals like window and document. This feature is currently under development, and APIs may change in the future. +## Motivation + +We developed the Vitest browser mode feature to help improve testing workflows and achieve more accurate and reliable test results. This experimental addition to our testing API allows developers to run tests in a native browser environment. In this section, we'll explore the motivations behind this feature and its benefits for testing. + +### Different ways of testing + +There are different ways to test JavaScript code. Some testing frameworks simulate browser environments in Node.js, while others run tests in real browsers. In this context, [jsdom](https://www.npmjs.com/package/jsdom) is an example of a spec implementation that simulates a browser environment by being used with a test runner like Jest or Vitest, while other testing tools such as [WebdriverIO](https://webdriver.io/) or [Cypress](https://www.cypress.io/) allow developers to test their applications in a real browser or in case of [Playwright](https://playwright.dev/) provide you a browser engine. + +### The simulation caveat + +Testing JavaScript programs in simulated environments such as jsdom or happy-dom has simplified the test setup and provided an easy-to-use API, making them suitable for many projects and increasing confidence in test results. However, it is crucial to keep in mind that these tools only simulate a browser environment and not an actual browser, which may result in some discrepancies between the simulated environment and the real environment. Therefore, false positives or negatives in test results may occur. + +To achieve the highest level of confidence in our tests, it's crucial to test in a real browser environment. This is why we developed the browser mode feature in Vitest, allowing developers to run tests natively in a browser and gain more accurate and reliable test results. With browser-level testing, developers can be more confident that their application will work as intended in a real-world scenario. + +## Drawbacks + +When using Vitest browser, it is important to consider the following drawbacks: + +### Early Development + +The browser mode feature of Vitest is still in its early stages of development. As such, it may not yet be fully optimized, and there may be some bugs or issues that have not yet been ironed out. It is recommended that users augment their Vitest browser experience with a standalone browser-side test runner like WebdriverIO, Cypress or Playwright. + +### Longer Initialization + +Vitest browser requires spinning up the provider and the browser during the initialization process, which can take some time. This can result in longer initialization times compared to other testing patterns. + ## Configuration To activate browser mode in your Vitest configuration, you can use the `--browser` flag or set the `browser.enabled` field to `true` in your Vitest configuration file. Here is an example configuration using the browser field: -- 2.51.2