diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 918690cb3638..840ca6bf1bf7 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -120,9 +120,6 @@ jobs: - name: Test Examples run: pnpm run test:examples - - name: Unit Test UI - run: pnpm run -C packages/ui test:ui - - uses: actions/upload-artifact@v6 if: ${{ !cancelled() }} with: diff --git a/docs/api/browser/commands.md b/docs/api/browser/commands.md index c53503fde814..d8f08f54a460 100644 --- a/docs/api/browser/commands.md +++ b/docs/api/browser/commands.md @@ -17,6 +17,8 @@ By default, Vitest uses `utf-8` encoding but you can override it with options. ::: tip This API follows [`server.fs`](https://vitejs.dev/config/server-options.html#server-fs-allow) limitations for security reasons. + +If [`browser.api.allowWrite`](/config/browser/api) or [`api.allowWrite`](/config/api#api-allowwrite) are disabled, `writeFile` and `removeFile` functions won't do anything. ::: ```ts diff --git a/docs/api/browser/locators.md b/docs/api/browser/locators.md index e3cc3fce453e..b7eb6211f9fc 100644 --- a/docs/api/browser/locators.md +++ b/docs/api/browser/locators.md @@ -7,7 +7,7 @@ outline: [2, 3] A locator is a representation of an element or a number of elements. Every locator is defined by a string called a selector. Vitest abstracts this selector by providing convenient methods that generate them behind the scenes. -The locator API uses a fork of [Playwright's locators](https://playwright.dev/docs/api/class-locator) called [Ivya](https://npmjs.com/ivya). However, Vitest provides this API to every [provider](/config/browser#browser-provider), not just playwright. +The locator API uses a fork of [Playwright's locators](https://playwright.dev/docs/api/class-locator) called [Ivya](https://npmjs.com/ivya). However, Vitest provides this API to every [provider](/config/browser/provider), not just playwright. ::: tip This page covers API usage. To better understand locators and their usage, read [Playwright's "Locators" documentation](https://playwright.dev/docs/locators). diff --git a/docs/config/api.md b/docs/config/api.md index 2bb16ecf51ea..61d4031187b3 100644 --- a/docs/config/api.md +++ b/docs/config/api.md @@ -5,8 +5,28 @@ outline: deep # api -- **Type:** `boolean | number` +- **Type:** `boolean | number | object` - **Default:** `false` - **CLI:** `--api`, `--api.port`, `--api.host`, `--api.strictPort` Listen to port and serve API for [the UI](/guide/ui) or [browser server](/guide/browser/). When set to `true`, the default port is `51204`. + +## api.allowWrite 4.1.0 {#api-allowwrite} + +- **Type:** `boolean` +- **Default:** `true` if not exposed to the network, `false` otherwise + +Vitest server can save test files or snapshot files via the API. This allows anyone who can connect to the API the ability to run any arbitary code on your machine. + +::: danger SECURITY ADVICE +Vitest does not expose the API to the internet by default and only listens on `localhost`. However if `host` is manually exposed to the network, anyone who connects to it can run arbitrary code on your machine, unless `api.allowWrite` and `api.allowExec` are set to `false`. + +If the host is set to anything other than `localhost` or `127.0.0.1`, Vitest will set `api.allowWrite` and `api.allowExec` to `false` by default. This means that any write operations (like changing the code in the UI) will not work. However, if you understand the security implications, you can override them. +::: + +## api.allowExec 4.1.0 {#api-allowexec} + +- **Type:** `boolean` +- **Default:** `true` if not exposed to the network, `false` otherwise + +Allows running any test file via the API. See the security advice in [`api.allowWrite`](#api-allowwrite). diff --git a/docs/config/browser.md b/docs/config/browser.md deleted file mode 100644 index ff977c09ab39..000000000000 --- a/docs/config/browser.md +++ /dev/null @@ -1,626 +0,0 @@ ---- -title: Browser Config Reference | Config -outline: deep ---- - -# Browser Config Reference - -You can change the browser configuration by updating the `test.browser` field in your [config file](/config/). An example of a simple config file: - -```ts [vitest.config.ts] -import { defineConfig } from 'vitest/config' -import { playwright } from '@vitest/browser-playwright' - -export default defineConfig({ - test: { - browser: { - enabled: true, - provider: playwright(), - instances: [ - { - browser: 'chromium', - setupFile: './chromium-setup.js', - }, - ], - }, - }, -}) -``` - -Please, refer to the ["Config Reference"](/config/) article for different config examples. - -::: warning -_All listed options_ on this page are located within a `test` property inside the configuration: - -```ts [vitest.config.js] -export default defineConfig({ - test: { - browser: {}, - }, -}) -``` -::: - -## browser.enabled - -- **Type:** `boolean` -- **Default:** `false` -- **CLI:** `--browser`, `--browser.enabled=false` - -Run all tests inside a browser by default. Note that `--browser` only works if you have at least one [`browser.instances`](#browser-instances) item. - -## browser.instances - -- **Type:** `BrowserConfig` -- **Default:** `[]` - -Defines multiple browser setups. Every config has to have at least a `browser` field. - -You can specify most of the [project options](/config/) (not marked with a icon) and some of the `browser` options like `browser.testerHtmlPath`. - -::: warning -Every browser config inherits options from the root config: - -```ts{3,9} [vitest.config.ts] -export default defineConfig({ - test: { - setupFile: ['./root-setup-file.js'], - browser: { - enabled: true, - testerHtmlPath: './custom-path.html', - instances: [ - { - // will have both setup files: "root" and "browser" - setupFile: ['./browser-setup-file.js'], - // implicitly has "testerHtmlPath" from the root config // [!code warning] - // testerHtmlPath: './custom-path.html', // [!code warning] - }, - ], - }, - }, -}) -``` - -For more examples, refer to the ["Multiple Setups" guide](/guide/browser/multiple-setups). -::: - -List of available `browser` options: - -- [`browser.headless`](#browser-headless) -- [`browser.locators`](#browser-locators) -- [`browser.viewport`](#browser-viewport) -- [`browser.testerHtmlPath`](#browser-testerhtmlpath) -- [`browser.screenshotDirectory`](#browser-screenshotdirectory) -- [`browser.screenshotFailures`](#browser-screenshotfailures) -- [`browser.provider`](#browser-provider) -- [`browser.detailsPanelPosition`](#browser-detailspanelposition) - -Under the hood, Vitest transforms these instances into separate [test projects](/api/advanced/test-project) sharing a single Vite server for better caching performance. - -## browser.headless - -- **Type:** `boolean` -- **Default:** `process.env.CI` -- **CLI:** `--browser.headless`, `--browser.headless=false` - -Run the browser in a `headless` mode. If you are running Vitest in CI, it will be enabled by default. - -## browser.isolate - -- **Type:** `boolean` -- **Default:** the same as [`--isolate`](/config/#isolate) -- **CLI:** `--browser.isolate`, `--browser.isolate=false` - -Run every test in a separate iframe. - -::: danger DEPRECATED -This option is deprecated. Use [`isolate`](/config/#isolate) instead. -::: - -## browser.testerHtmlPath - -- **Type:** `string` - -A path to the HTML entry point. Can be relative to the root of the project. This file will be processed with [`transformIndexHtml`](https://vite.dev/guide/api-plugin#transformindexhtml) hook. - -## browser.api - -- **Type:** `number | { port?, strictPort?, host? }` -- **Default:** `63315` -- **CLI:** `--browser.api=63315`, `--browser.api.port=1234, --browser.api.host=example.com` - -Configure options for Vite server that serves code in the browser. Does not affect [`test.api`](#api) option. By default, Vitest assigns port `63315` to avoid conflicts with the development server, allowing you to run both in parallel. - -## browser.provider {#browser-provider} - -- **Type:** `BrowserProviderOption` -- **Default:** `'preview'` -- **CLI:** `--browser.provider=playwright` - -The return value of the provider factory. You can import the factory from `@vitest/browser-` or make your own provider: - -```ts{8-10} -import { playwright } from '@vitest/browser-playwright' -import { webdriverio } from '@vitest/browser-webdriverio' -import { preview } from '@vitest/browser-preview' - -export default defineConfig({ - test: { - browser: { - provider: playwright(), - provider: webdriverio(), - provider: preview(), // default - }, - }, -}) -``` - -To configure how provider initializes the browser, you can pass down options to the factory function: - -```ts{7-13,20-26} -import { playwright } from '@vitest/browser-playwright' - -export default defineConfig({ - test: { - browser: { - // shared provider options between all instances - provider: playwright({ - launchOptions: { - slowMo: 50, - channel: 'chrome-beta', - }, - actionTimeout: 5_000, - }), - instances: [ - { browser: 'chromium' }, - { - browser: 'firefox', - // overriding options only for a single instance - // this will NOT merge options with the parent one - provider: playwright({ - launchOptions: { - firefoxUserPrefs: { - 'browser.startup.homepage': 'https://example.com', - }, - }, - }) - } - ], - }, - }, -}) -``` - -### Custom Provider advanced - -::: danger ADVANCED API -The custom provider API is highly experimental and can change between patches. If you just need to run tests in a browser, use the [`browser.instances`](#browser-instances) option instead. -::: - -```ts -export interface BrowserProvider { - name: string - mocker?: BrowserModuleMocker - readonly initScripts?: string[] - /** - * @experimental opt-in into file parallelisation - */ - supportsParallelism: boolean - getCommandsContext: (sessionId: string) => Record - openPage: (sessionId: string, url: string) => Promise - getCDPSession?: (sessionId: string) => Promise - close: () => Awaitable -} -``` - -## browser.ui - -- **Type:** `boolean` -- **Default:** `!isCI` -- **CLI:** `--browser.ui=false` - -Should Vitest UI be injected into the page. By default, injects UI iframe during development. - -## browser.detailsPanelPosition - -- **Type:** `'right' | 'bottom'` -- **Default:** `'right'` -- **CLI:** `--browser.detailsPanelPosition=bottom`, `--browser.detailsPanelPosition=right` - -Controls the default position of the details panel in the Vitest UI when running browser tests. See [`browser.detailsPanelPosition`](/config/browser/detailspanelposition) for more details. - -## browser.viewport - -- **Type:** `{ width, height }` -- **Default:** `414x896` - -Default iframe's viewport. - -## browser.locators - -Options for built-in [browser locators](/api/browser/locators). - -### browser.locators.testIdAttribute - -- **Type:** `string` -- **Default:** `data-testid` - -Attribute used to find elements with `getByTestId` locator. - -## browser.screenshotDirectory - -- **Type:** `string` -- **Default:** `__screenshots__` in the test file directory - -Path to the screenshots directory relative to the `root`. - -## browser.screenshotFailures - -- **Type:** `boolean` -- **Default:** `!browser.ui` - -Should Vitest take screenshots if the test fails. - -## browser.orchestratorScripts - -- **Type:** `BrowserScript[]` -- **Default:** `[]` - -Custom scripts that should be injected into the orchestrator HTML before test iframes are initiated. This HTML document only sets up iframes and doesn't actually import your code. - -The script `src` and `content` will be processed by Vite plugins. Script should be provided in the following shape: - -```ts -export interface BrowserScript { - /** - * If "content" is provided and type is "module", this will be its identifier. - * - * If you are using TypeScript, you can add `.ts` extension here for example. - * @default `injected-${index}.js` - */ - id?: string - /** - * JavaScript content to be injected. This string is processed by Vite plugins if type is "module". - * - * You can use `id` to give Vite a hint about the file extension. - */ - content?: string - /** - * Path to the script. This value is resolved by Vite so it can be a node module or a file path. - */ - src?: string - /** - * If the script should be loaded asynchronously. - */ - async?: boolean - /** - * Script type. - * @default 'module' - */ - type?: string -} -``` - -## browser.commands - -- **Type:** `Record` -- **Default:** `{ readFile, writeFile, ... }` - -Custom [commands](/api/browser/commands) that can be imported during browser tests from `vitest/browser`. - -## browser.connectTimeout - -- **Type:** `number` -- **Default:** `60_000` - -The timeout in milliseconds. If connection to the browser takes longer, the test suite will fail. - -::: info -This is the time it should take for the browser to establish the WebSocket connection with the Vitest server. In normal circumstances, this timeout should never be reached. -::: - -## browser.trace - -- **Type:** `'on' | 'off' | 'on-first-retry' | 'on-all-retries' | 'retain-on-failure' | object` -- **CLI:** `--browser.trace=on`, `--browser.trace=retain-on-failure` -- **Default:** `'off'` - -Capture a trace of your browser test runs. You can preview traces with [Playwright Trace Viewer](https://trace.playwright.dev/). - -This options supports the following values: - -- `'on'` - capture trace for all tests. (not recommended as it's performance heavy) -- `'off'` - do not capture traces. -- `'on-first-retry'` - capture trace only when retrying the test for the first time. -- `'on-all-retries'` - capture trace on every retry of the test. -- `'retain-on-failure'` - capture trace only for tests that fail. This will automatically delete traces for tests that pass. -- `object` - an object with the following shape: - -```ts -interface TraceOptions { - mode: 'on' | 'off' | 'on-first-retry' | 'on-all-retries' | 'retain-on-failure' - /** - * The directory where all traces will be stored. By default, Vitest - * stores all traces in `__traces__` folder close to the test file. - */ - tracesDir?: string - /** - * Whether to capture screenshots during tracing. Screenshots are used to build a timeline preview. - * @default true - */ - screenshots?: boolean - /** - * If this option is true tracing will - * - capture DOM snapshot on every action - * - record network activity - * @default true - */ - snapshots?: boolean -} -``` - -::: danger WARNING -This option is supported only by the [**playwright**](/config/browser/playwright) provider. -::: - -## browser.trackUnhandledErrors - -- **Type:** `boolean` -- **Default:** `true` - -Enables tracking uncaught errors and exceptions so they can be reported by Vitest. - -If you need to hide certain errors, it is recommended to use [`onUnhandledError`](/config/#onunhandlederror) option instead. - -Disabling this will completely remove all Vitest error handlers, which can help debugging with the "Pause on exceptions" checkbox turned on. - -## browser.expect - -- **Type:** `ExpectOptions` - -### browser.expect.toMatchScreenshot - -Default options for the -[`toMatchScreenshot` assertion](/api/browser/assertions.html#tomatchscreenshot). -These options will be applied to all screenshot assertions. - -::: tip -Setting global defaults for screenshot assertions helps maintain consistency -across your test suite and reduces repetition in individual tests. You can still -override these defaults at the assertion level when needed for specific test cases. -::: - -```ts -import { defineConfig } from 'vitest/config' - -export default defineConfig({ - test: { - browser: { - enabled: true, - expect: { - toMatchScreenshot: { - comparatorName: 'pixelmatch', - comparatorOptions: { - threshold: 0.2, - allowedMismatchedPixels: 100, - }, - resolveScreenshotPath: ({ arg, browserName, ext, testFileName }) => - `custom-screenshots/${testFileName}/${arg}-${browserName}${ext}`, - }, - }, - }, - }, -}) -``` - -[All options available in the `toMatchScreenshot` assertion](/api/browser/assertions#options) -can be configured here. Additionally, two path resolution functions are -available: `resolveScreenshotPath` and `resolveDiffPath`. - -#### browser.expect.toMatchScreenshot.resolveScreenshotPath - -- **Type:** `(data: PathResolveData) => string` -- **Default output:** `` `${root}/${testFileDirectory}/${screenshotDirectory}/${testFileName}/${arg}-${browserName}-${platform}${ext}` `` - -A function to customize where reference screenshots are stored. The function -receives an object with the following properties: - -- `arg: string` - - Path **without** extension, sanitized and relative to the test file. - - This comes from the arguments passed to `toMatchScreenshot`; if called - without arguments this will be the auto-generated name. - - ```ts - test('calls `onClick`', () => { - expect(locator).toMatchScreenshot() - // arg = "calls-onclick-1" - }) - - expect(locator).toMatchScreenshot('foo/bar/baz.png') - // arg = "foo/bar/baz" - - expect(locator).toMatchScreenshot('../foo/bar/baz.png') - // arg = "foo/bar/baz" - ``` - -- `ext: string` - - Screenshot extension, with leading dot. - - This can be set through the arguments passed to `toMatchScreenshot`, but - the value will fall back to `'.png'` if an unsupported extension is used. - -- `browserName: string` - - The instance's browser name. - -- `platform: NodeJS.Platform` - - The value of - [`process.platform`](https://nodejs.org/docs/v22.16.0/api/process.html#processplatform). - -- `screenshotDirectory: string` - - The value provided to - [`browser.screenshotDirectory`](/config/browser/screenshotdirectory), - if none is provided, its default value. - -- `root: string` - - Absolute path to the project's [`root`](/config/#root). - -- `testFileDirectory: string` - - Path to the test file, relative to the project's [`root`](/config/#root). - -- `testFileName: string` - - The test's filename. - -- `testName: string` - - The [`test`](/api/test)'s name, including parent - [`describe`](/api/describe), sanitized. - -- `attachmentsDir: string` - - The value provided to [`attachmentsDir`](/config/#attachmentsdir), if none is - provided, its default value. - -For example, to group screenshots by browser: - -```ts -resolveScreenshotPath: ({ arg, browserName, ext, root, testFileName }) => - `${root}/screenshots/${browserName}/${testFileName}/${arg}${ext}` -``` - -#### browser.expect.toMatchScreenshot.resolveDiffPath - -- **Type:** `(data: PathResolveData) => string` -- **Default output:** `` `${root}/${attachmentsDir}/${testFileDirectory}/${testFileName}/${arg}-${browserName}-${platform}${ext}` `` - -A function to customize where diff images are stored when screenshot comparisons -fail. Receives the same data object as -[`resolveScreenshotPath`](#browser-expect-tomatchscreenshot-resolvescreenshotpath). - -For example, to store diffs in a subdirectory of attachments: - -```ts -resolveDiffPath: ({ arg, attachmentsDir, browserName, ext, root, testFileName }) => - `${root}/${attachmentsDir}/screenshot-diffs/${testFileName}/${arg}-${browserName}${ext}` -``` - -#### browser.expect.toMatchScreenshot.comparators - -- **Type:** `Record` - -Register custom screenshot comparison algorithms, like [SSIM](https://en.wikipedia.org/wiki/Structural_similarity_index_measure) or other perceptual similarity metrics. - -To create a custom comparator, you need to register it in your config. If using TypeScript, declare its options in the `ScreenshotComparatorRegistry` interface. - -```ts -import { defineConfig } from 'vitest/config' - -// 1. Declare the comparator's options type -declare module 'vitest/browser' { - interface ScreenshotComparatorRegistry { - myCustomComparator: { - sensitivity?: number - ignoreColors?: boolean - } - } -} - -// 2. Implement the comparator -export default defineConfig({ - test: { - browser: { - expect: { - toMatchScreenshot: { - comparators: { - myCustomComparator: async ( - reference, - actual, - { - createDiff, // always provided by Vitest - sensitivity = 0.01, - ignoreColors = false, - } - ) => { - // ...algorithm implementation - return { pass, diff, message } - }, - }, - }, - }, - }, - }, -}) -``` - -Then use it in your tests: - -```ts -await expect(locator).toMatchScreenshot({ - comparatorName: 'myCustomComparator', - comparatorOptions: { - sensitivity: 0.08, - ignoreColors: true, - }, -}) -``` - -**Comparator Function Signature:** - -```ts -type Comparator = ( - reference: { - metadata: { height: number; width: number } - data: TypedArray - }, - actual: { - metadata: { height: number; width: number } - data: TypedArray - }, - options: { - createDiff: boolean - } & Options -) => Promise<{ - pass: boolean - diff: TypedArray | null - message: string | null -}> | { - pass: boolean - diff: TypedArray | null - message: string | null -} -``` - -The `reference` and `actual` images are decoded using the appropriate codec (currently only PNG). The `data` property is a flat `TypedArray` (`Buffer`, `Uint8Array`, or `Uint8ClampedArray`) containing pixel data in RGBA format: - -- **4 bytes per pixel**: red, green, blue, alpha (from `0` to `255` each) -- **Row-major order**: pixels are stored left-to-right, top-to-bottom -- **Total length**: `width × height × 4` bytes -- **Alpha channel**: always present. Images without transparency have alpha values set to `255` (fully opaque) - -::: tip Performance Considerations -The `createDiff` option indicates whether a diff image is needed. During [stable screenshot detection](/guide/browser/visual-regression-testing#how-visual-tests-work), Vitest calls comparators with `createDiff: false` to avoid unnecessary work. - -**Respect this flag to keep your tests fast**. -::: - -::: warning Handle Missing Options -The `options` parameter in `toMatchScreenshot()` is optional, so users might not provide all your comparator options. Always make them optional with default values: - -```ts -myCustomComparator: ( - reference, - actual, - { createDiff, threshold = 0.1, maxDiff = 100 }, -) => { - // ...comparison logic -} -``` -::: diff --git a/docs/config/browser/api.md b/docs/config/browser/api.md index b1491e146473..23e50339a24a 100644 --- a/docs/config/browser/api.md +++ b/docs/config/browser/api.md @@ -5,8 +5,24 @@ outline: deep # browser.api -- **Type:** `number | { port?, strictPort?, host? }` +- **Type:** `number | object` - **Default:** `63315` - **CLI:** `--browser.api=63315`, `--browser.api.port=1234, --browser.api.host=example.com` Configure options for Vite server that serves code in the browser. Does not affect [`test.api`](#api) option. By default, Vitest assigns port `63315` to avoid conflicts with the development server, allowing you to run both in parallel. + +## api.allowWrite 4.1.0 {#api-allowwrite} + +- **Type:** `boolean` +- **Default:** `true` if not exposed to the network, `false` otherwise + +Vitest saves [annotation attachments](/guide/test-annotations), [artifacts](/api/advanced/artifacts) and [snapshots](/guide/snapshot) by receiving a WebSocket connection from the browser. This allows anyone who can connect to the API write any arbitary code on your machine within the root of your project (configured by [`fs.allow`](https://vite.dev/config/server-options#server-fs-allow)). + +If browser server is not exposed to the internet (the host is `localhost`), this should not be a problem, so the default value in that case is `true`. If you override the host, Vitest will set `allowWrite` to `false` by default to prevent potentially harmful writes. + +## api.allowExec 4.1.0 {#api-allowexec} + +- **Type:** `boolean` +- **Default:** `true` if not exposed to the network, `false` otherwise + +Allows running any test file via the UI. This only applies to the interactive elements (and the server code behind them) in the [UI](/guide/ui) that can run the code. If UI is disabled, this has no effect. See [`api.allowExec`](/config/api#api-allowexec) for more information. diff --git a/docs/config/ui.md b/docs/config/ui.md index e3bac62aa148..76d430a7c747 100644 --- a/docs/config/ui.md +++ b/docs/config/ui.md @@ -14,3 +14,7 @@ Enable [Vitest UI](/guide/ui). ::: warning This features requires a [`@vitest/ui`](https://www.npmjs.com/package/@vitest/ui) package to be installed. If you do not have it already, Vitest will install it when you run the test command for the first time. ::: + +::: danger SECURITY ADVICE +Make sure that your UI server is not exposed to the network. Since Vitest 4.1 setting [`api.host`](/config/api) to anything other than `localhost` will disable the buttons to save the code or run any tests for security reasons, effectively making UI a readonly reporter. +::: diff --git a/docs/guide/cli-generated.md b/docs/guide/cli-generated.md index ad3141c7d545..5b8acd881de7 100644 --- a/docs/guide/cli-generated.md +++ b/docs/guide/cli-generated.md @@ -70,6 +70,20 @@ Specify which IP addresses the server should listen on. Set this to `0.0.0.0` or Set to true to exit if port is already in use, instead of automatically trying the next available port +### api.allowExec + +- **CLI:** `--api.allowExec` +- **Config:** [api.allowExec](/config/api#api-allowexec) + +Allow API to execute code. (Be careful when enabling this option in untrusted environments) + +### api.allowWrite + +- **CLI:** `--api.allowWrite` +- **Config:** [api.allowWrite](/config/api#api-allowwrite) + +Allow API to edit files. (Be careful when enabling this option in untrusted environments) + ### silent - **CLI:** `--silent [value]` @@ -332,6 +346,20 @@ Specify which IP addresses the server should listen on. Set this to `0.0.0.0` or Set to true to exit if port is already in use, instead of automatically trying the next available port +### browser.api.allowExec + +- **CLI:** `--browser.api.allowExec` +- **Config:** [browser.api.allowExec](/config/browser/api#api-allowexec) + +Allow API to execute code. (Be careful when enabling this option in untrusted environments) + +### browser.api.allowWrite + +- **CLI:** `--browser.api.allowWrite` +- **Config:** [browser.api.allowWrite](/config/browser/api#api-allowwrite) + +Allow API to edit files. (Be careful when enabling this option in untrusted environments) + ### browser.isolate - **CLI:** `--browser.isolate` diff --git a/netlify.toml b/netlify.toml index 041e1799a5bc..e3df27427f4f 100755 --- a/netlify.toml +++ b/netlify.toml @@ -25,6 +25,11 @@ from = "/config/file" to = "/config/" status = 301 +[[redirects]] +from = "/config/browser" +to = "/config/browser/enabled" +status = 301 + [[redirects]] from = "/guide/workspace" to = "/guide/projects" diff --git a/packages/browser/src/node/commands/fs.ts b/packages/browser/src/node/commands/fs.ts index d9558106023f..d921f3b111a7 100644 --- a/packages/browser/src/node/commands/fs.ts +++ b/packages/browser/src/node/commands/fs.ts @@ -3,12 +3,13 @@ import type { BrowserCommand, TestProject } from 'vitest/node' import fs, { promises as fsp } from 'node:fs' import { basename, dirname, resolve } from 'node:path' import mime from 'mime/lite' -import { isFileServingAllowed } from 'vitest/node' +import { isFileLoadingAllowed } from 'vitest/node' +import { slash } from '../utils' function assertFileAccess(path: string, project: TestProject) { if ( - !isFileServingAllowed(path, project.vite) - && !isFileServingAllowed(path, project.vitest.vite) + !isFileLoadingAllowed(project.vite.config, path) + && !isFileLoadingAllowed(project.vitest.vite.config, path) ) { throw new Error( `Access denied to "${path}". See Vite config documentation for "server.fs": https://vitejs.dev/config/server-options.html#server-fs-strict.`, @@ -16,11 +17,17 @@ function assertFileAccess(path: string, project: TestProject) { } } +function assertWrite(path: string, project: TestProject) { + if (!project.config.browser.api.allowWrite || !project.vitest.config.api.allowWrite) { + throw new Error(`Cannot modify file "${path}". File writing is disabled because server is exposed to the internet, see https://vitest.dev/config/browser/api.`) + } +} + export const readFile: BrowserCommand< Parameters > = async ({ project }, path, options = {}) => { const filepath = resolve(project.config.root, path) - assertFileAccess(filepath, project) + assertFileAccess(slash(filepath), project) // never return a Buffer if (typeof options === 'object' && !options.encoding) { options.encoding = 'utf-8' @@ -31,8 +38,9 @@ export const readFile: BrowserCommand< export const writeFile: BrowserCommand< Parameters > = async ({ project }, path, data, options) => { + assertWrite(path, project) const filepath = resolve(project.config.root, path) - assertFileAccess(filepath, project) + assertFileAccess(slash(filepath), project) const dir = dirname(filepath) if (!fs.existsSync(dir)) { await fsp.mkdir(dir, { recursive: true }) @@ -43,14 +51,15 @@ export const writeFile: BrowserCommand< export const removeFile: BrowserCommand< Parameters > = async ({ project }, path) => { + assertWrite(path, project) const filepath = resolve(project.config.root, path) - assertFileAccess(filepath, project) + assertFileAccess(slash(filepath), project) await fsp.rm(filepath) } export const _fileInfo: BrowserCommand<[path: string, encoding: BufferEncoding]> = async ({ project }, path, encoding) => { const filepath = resolve(project.config.root, path) - assertFileAccess(filepath, project) + assertFileAccess(slash(filepath), project) const content = await fsp.readFile(filepath, encoding || 'base64') return { content, diff --git a/packages/browser/src/node/rpc.ts b/packages/browser/src/node/rpc.ts index 200ddb5f9873..1733afd9e26e 100644 --- a/packages/browser/src/node/rpc.ts +++ b/packages/browser/src/node/rpc.ts @@ -12,7 +12,7 @@ import { ServerMockResolver } from '@vitest/mocker/node' import { createBirpc } from 'birpc' import { parse, stringify } from 'flatted' import { dirname, join, resolve } from 'pathe' -import { createDebugger, isFileServingAllowed, isValidApiRequest } from 'vitest/node' +import { createDebugger, isFileLoadingAllowed, isValidApiRequest } from 'vitest/node' import { WebSocketServer } from 'ws' const debug = createDebugger('vitest:browser:api') @@ -113,13 +113,22 @@ export function setupBrowserRpc(globalServer: ParentBrowserProject, defaultMocke } function checkFileAccess(path: string) { - if (!isFileServingAllowed(path, vite)) { + if (!isFileLoadingAllowed(vite.config, path)) { throw new Error( `Access denied to "${path}". See Vite config documentation for "server.fs": https://vitejs.dev/config/server-options.html#server-fs-strict.`, ) } } + function canWrite(project: TestProject) { + return ( + project.config.browser.api.allowWrite + && project.vitest.config.browser.api.allowWrite + && project.config.api.allowWrite + && project.vitest.config.api.allowWrite + ) + } + function setupClient(project: TestProject, rpcId: string, ws: WebSocket) { const mockResolver = new ServerMockResolver(globalServer.vite, { moduleDirectories: project.config?.deps?.moduleDirectories, @@ -152,6 +161,23 @@ export function setupBrowserRpc(globalServer: ParentBrowserProject, defaultMocke } }, async onTaskArtifactRecord(id, artifact) { + if (!canWrite(project)) { + if (artifact.type === 'internal:annotation' && artifact.annotation.attachment) { + artifact.annotation.attachment = undefined + vitest.logger.error( + `[vitest] Cannot record annotation attachment because file writing is disabled. See https://vitest.dev/config/browser/api.`, + ) + } + // remove attachments if cannot write + if (artifact.attachments?.length) { + const attachments = artifact.attachments.map(n => n.path).filter(r => !!r).join('", "') + artifact.attachments = [] + vitest.logger.error( + `[vitest] Cannot record attachments ("${attachments}") because file writing is disabled, removing attachments from artifact "${artifact.type}". See https://vitest.dev/config/browser/api.`, + ) + } + } + return vitest._testRun.recordArtifact(id, artifact) }, async onTaskUpdate(method, packs, events) { @@ -193,15 +219,27 @@ export function setupBrowserRpc(globalServer: ParentBrowserProject, defaultMocke }, async saveSnapshotFile(id, content) { checkFileAccess(id) + if (!canWrite(project)) { + vitest.logger.error( + `[vitest] Cannot save snapshot file "${id}". File writing is disabled because server is exposed to the internet, see https://vitest.dev/config/browser/api.`, + ) + return + } await fs.mkdir(dirname(id), { recursive: true }) - return fs.writeFile(id, content, 'utf-8') + await fs.writeFile(id, content, 'utf-8') }, async removeSnapshotFile(id) { checkFileAccess(id) + if (!canWrite(project)) { + vitest.logger.error( + `[vitest] Cannot remove snapshot file "${id}". File writing is disabled because server is exposed to the internet, see https://vitest.dev/config/browser/api.`, + ) + return + } if (!existsSync(id)) { throw new Error(`Snapshot file "${id}" does not exist.`) } - return fs.unlink(id) + await fs.unlink(id) }, getBrowserFileSourceMap(id) { const mod = globalServer.vite.moduleGraph.getModuleById(id) diff --git a/packages/ui/client/components/ModuleGraphImportBreakdown.vue b/packages/ui/client/components/ModuleGraphImportBreakdown.vue index b4eaaa9447ba..725eb5fc9e93 100644 --- a/packages/ui/client/components/ModuleGraphImportBreakdown.vue +++ b/packages/ui/client/components/ModuleGraphImportBreakdown.vue @@ -25,11 +25,11 @@ const emit = defineEmits<{ const imports = computed(() => { const file = currentModule.value const importDurations = file?.importDurations - if (!importDurations) { + const root = config.value.root + if (!importDurations || !root) { return [] } - const root = config.value.root const allImports: ImportEntry[] = [] for (const filePath in importDurations) { const duration = importDurations[filePath] diff --git a/packages/ui/client/components/ModuleTransformResultView.vue b/packages/ui/client/components/ModuleTransformResultView.vue index b70d746f97f9..892dc9c7727a 100644 --- a/packages/ui/client/components/ModuleTransformResultView.vue +++ b/packages/ui/client/components/ModuleTransformResultView.vue @@ -96,13 +96,17 @@ function onMousedown(editor: Editor, e: MouseEvent) { function buildShadowImportsHtml(imports: Experimental.UntrackedModuleDefinitionDiagnostic[]) { const shadowImportsDiv = document.createElement('div') shadowImportsDiv.classList.add('mb-5') + const root = config.value.root + if (!root) { + return + } imports.forEach(({ resolvedId, totalTime, external }) => { const importDiv = document.createElement('div') importDiv.append(document.createTextNode('import ')) const sourceDiv = document.createElement('span') - const url = relative(config.value.root, resolvedId) + const url = relative(root, resolvedId) sourceDiv.textContent = `"/${url}"` sourceDiv.className = 'hover:underline decoration-gray cursor-pointer select-none' importDiv.append(sourceDiv) @@ -152,6 +156,9 @@ function markImportDurations(codemirror: EditorFromTextArea) { if (untrackedModules?.length) { const importDiv = buildShadowImportsHtml(untrackedModules) + if (!importDiv) { + return + } widgetElements.push(importDiv) lineWidgets.push(codemirror.addLineWidget(0, importDiv, { above: true })) } diff --git a/packages/ui/client/components/Navigation.vue b/packages/ui/client/components/Navigation.vue index 7c1eb132659f..3bcaf7d2bada 100644 --- a/packages/ui/client/components/Navigation.vue +++ b/packages/ui/client/components/Navigation.vue @@ -3,7 +3,7 @@ import type { RunnerTestFile } from 'vitest' import { Tooltip as VueTooltip } from 'floating-vue' import { computed, nextTick } from 'vue' import { isDark, toggleDark } from '~/composables' -import { client, isReport, runAll, runFiles } from '~/composables/client' +import { client, config, isReport, runAll, runFiles } from '~/composables/client' import { explorerTree } from '~/composables/explorer' import { initialized, shouldShowExpandAll } from '~/composables/explorer/state' import { @@ -26,6 +26,10 @@ function updateSnapshot() { const toggleMode = computed(() => isDark.value ? 'light' : 'dark') async function onRunAll(files?: RunnerTestFile[]) { + if (config.value.api?.allowExec === false) { + return + } + if (coverageEnabled.value) { disableCoverage.value = true await nextTick() @@ -49,6 +53,13 @@ function collapseTests() { function expandTests() { explorerTree.expandAllNodes() } + +function getRerunTooltip(filteredFiles: RunnerTestFile[] | undefined) { + if (config.value.api?.allowExec === false) { + return 'Cannot run tests when `api.allowExec` is `false`. Did you expose UI to the internet?' + } + return filteredFiles ? (filteredFiles.length === 0 ? 'No test to run (clear filter)' : 'Rerun filtered') : 'Rerun all' +}