For AI agents: the complete documentation index is available at https://rstest.rs/llms.txt, the full documentation bundle is available at https://rstest.rs/llms-full.txt, and this page is available as Markdown at https://rstest.rs/config/test/browser.md.
close
  • English
  • browser

    • Type:
    type BrowserViewport =
      | {
          width: number;
          height: number;
        }
      | DevicePreset;
    
    type DevicePreset =
      | 'iPhoneSE'
      | 'iPhoneXR'
      | 'iPhone12Pro'
      | 'iPhone14ProMax'
      | 'Pixel7'
      | 'SamsungGalaxyS8Plus'
      | 'SamsungGalaxyS20Ultra'
      | 'iPadMini'
      | 'iPadAir'
      | 'iPadPro'
      | 'SurfacePro7'
      | 'SurfaceDuo'
      | 'GalaxyZFold5'
      | 'AsusZenbookFold'
      | 'SamsungGalaxyA51A71'
      | 'NestHub'
      | 'NestHubMax';
    
    type BrowserModeConfig = {
      enabled?: boolean;
      provider: 'playwright';
      /** @deprecated Use `instances` instead. Will be removed in 1.0. */
      browser?: 'chromium' | 'firefox' | 'webkit';
      headless?: boolean;
      screenshotFailures?: boolean;
      port?: number;
      viewport?: BrowserViewport;
      strictPort?: boolean;
      providerOptions?: Record<string, unknown>;
      /** @default [{ browserName: 'chromium' }] */
      instances?: BrowserInstanceConfig[];
      expect?: BrowserExpectConfig;
    };
    
    type BrowserExpectConfig = {
      toMatchScreenshot?: BrowserScreenshotMatcherConfig;
    };
    
    type BrowserInstanceConfig = {
      browserName: BrowserName;
      headless?: boolean;
      viewport?: BrowserViewport;
      screenshotFailures?: boolean;
      expect?: BrowserExpectConfig;
      providerOptions?: Record<string, unknown>;
    };
    
    type BrowserScreenshotPathOptions = {
      testFilePath: string;
      projectName: string;
      testName: string;
      browserName: 'chromium' | 'firefox' | 'webkit';
      platform: string;
      screenshotAssertionOrdinal?: number;
    };
    • Default:
    const defaultBrowser = {
      enabled: false,
      provider: 'playwright',
      instances: [{ browserName: 'chromium' }],
      headless: true, // CI environment; false for local development
      screenshotFailures: true, // Defaults to the headless setting
      port: undefined, // Random available port
      viewport: undefined, // Browser UI fills the preview panel
      strictPort: false,
      providerOptions: {},
    };

    Browser Mode configuration. When enabled, tests run in a real browser instead of the Node.js environment.

    Options

    screenshotFailures

    Capture a PNG screenshot for each failed browser test. Defaults to the headless setting. Screenshots are saved under .rstest/screenshots/ in the project root, with the test file and test name in the filename. Set this to false to disable capture.

    • Type: boolean
    • Default: browser.headless
    • CLI: --browser.screenshotFailures

    enabled

    • Type: boolean
    • Default: false
    • CLI: --browser, --browser.enabled

    Enable Browser Mode.

    rstest.config.ts
    import { defineConfig } from '@rstest/core';
    
    export default defineConfig({
      browser: {
        enabled: true,
        provider: 'playwright',
      },
    });
    Tip

    Enabling Browser Mode requires installing the @rstest/browser package and Playwright browsers.

    npm add @rstest/browser -D
    npx playwright install chromium

    provider

    • Type: 'playwright'
    • Default: 'playwright'

    Browser driver provider. Currently only Playwright is supported.

    rstest.config.ts
    import { defineConfig } from '@rstest/core';
    
    export default defineConfig({
      browser: {
        enabled: true,
        provider: 'playwright',
      },
    });

    browser (deprecated)

    Deprecated

    browser.browser is deprecated and will be removed in 1.0. Use instances instead, e.g. instances: [{ browserName: 'firefox' }]. Rstest prints a deprecation warning once per run when this field is set. --browser.name is the deprecated CLI form.

    • Type: 'chromium' | 'firefox' | 'webkit'
    • Default: 'chromium'
    • CLI: --browser.name <name> (deprecated)

    The single browser type to use for testing. Setting this field is normalized to instances: [{ browserName: browser }].

    Setting both browser and instances on a browser project is a config error.

    • chromium - Google Chrome, Microsoft Edge
    • firefox - Mozilla Firefox
    • webkit - Safari
    rstest.config.ts
    import { defineConfig } from '@rstest/core';
    
    export default defineConfig({
      browser: {
        enabled: true,
        provider: 'playwright',
        browser: 'firefox', // deprecated; prefer instances: [{ browserName: 'firefox' }]
      },
    });

    You need to install the corresponding browser before use:

    # Install chromium
    npx playwright install chromium
    
    # Install Firefox
    npx playwright install firefox
    
    # Install WebKit
    npx playwright install webkit
    
    # Install all browsers
    npx playwright install

    instances

    • Type: BrowserInstanceConfig[]
    • Default: [{ browserName: 'chromium' }]
    • CLI: --browser.instances <names> (comma-separated and/or repeatable; filters the configured instances)

    Browser instances this project runs on, one per browser. Every instance of a project shares one build and one dev server — multi-browser runs do not multiply build time.

    rstest.config.ts
    import { defineConfig } from '@rstest/core';
    
    export default defineConfig({
      browser: {
        enabled: true,
        provider: 'playwright',
        instances: [{ browserName: 'chromium' }, { browserName: 'firefox' }],
      },
    });

    Each item is a BrowserInstanceConfig object: browserName is required, and every other field overrides the project-level value for that browser. A bare browser name such as instances: ['chromium'] is a config error; write { browserName: 'chromium' }:

    rstest.config.ts
    import { defineConfig } from '@rstest/core';
    
    export default defineConfig({
      browser: {
        enabled: true,
        provider: 'playwright',
        providerOptions: {
          launch: { slowMo: 100 },
          context: { locale: 'en-US' },
        },
        instances: [
          { browserName: 'firefox' },
          {
            browserName: 'chromium',
            viewport: { width: 800, height: 600 },
            providerOptions: {
              launch: { channel: 'chrome' },
            },
          },
        ],
      },
    });

    BrowserInstanceConfig accepts only runtime-effective overrides; build-scoped options (enabled, provider, port, strictPort) stay on the project-level browser config:

    FieldDefault
    browserNamerequired
    headlessproject browser.headless
    viewportproject browser.viewport
    screenshotFailuresproject browser.screenshotFailures
    expectproject browser.expect
    providerOptionsproject browser.providerOptions

    Merge rules per instance: an instance field wins, then the project-level browser.* field, then the built-in default. providerOptions merges per top-level key (launch, context) instead of whole-field: an instance launch replaces the project launch key entirely (Playwright options may contain functions and class instances, so sibling keys under it are not merged), while keys the instance does not set keep the project value — in the example above the chromium instance launches with channel: 'chrome' alone, and its context keeps the project-level locale: 'en-US'.

    A project runs exactly one browser per instance; two result rows come back for the same file, each reported under its own project name — see Multi-browser reporting.

    Validation rules:

    • The same browserName may be configured at most once per project (duplicate names are a config error).
    • instances must not be empty — remove the option to run the default Chromium instead.
    • At most one (project, browser) pair may run headed (headless: false) per run; see Launch rules.
    • coverage.provider: 'v8' requires every selected browser to be Chromium; see Launch rules.

    headless

    • Type: boolean
    • Default: true in CI environments, false for local development
    • CLI: --browser.headless

    Whether to run the browser in headless mode (without UI). Items in instances can override it per browser, subject to the one headed browser per run rule.

    rstest.config.ts
    CI (GitHub Actions)
    import { defineConfig } from '@rstest/core';
    
    export default defineConfig({
      browser: {
        enabled: true,
        provider: 'playwright',
        headless: true,
      },
    });

    During local development, setting headless: false shows the browser window for easier debugging.

    Dynamic Configuration Based on Environment

    If you want headed mode for local debugging and headless in CI, control it with environment variables:

    rstest.config.ts
    import { defineConfig } from '@rstest/core';
    
    export default defineConfig({
      browser: {
        enabled: true,
        provider: 'playwright',
        headless: process.env.CI === 'true',
      },
    });

    viewport

    • Type: BrowserViewport
    • Default: undefined

    Set the default runner iframe viewport for Browser Mode tests. When not specified, the Browser UI fills the preview panel. Items in instances can override the viewport per browser.

    type BrowserViewport =
      | {
          width: number;
          height: number;
        }
      | DevicePreset;

    Use an explicit size when you want all files in a browser project to run with the same viewport:

    rstest.config.ts
    import { defineConfig } from '@rstest/core';
    
    export default defineConfig({
      browser: {
        enabled: true,
        provider: 'playwright',
        viewport: { width: 390, height: 844 },
      },
    });

    You can also use a built-in device preset:

    rstest.config.ts
    import { defineConfig } from '@rstest/core';
    
    export default defineConfig({
      browser: {
        enabled: true,
        provider: 'playwright',
        viewport: 'iPhone12Pro',
      },
    });

    Supported presets:

    PresetSize
    iPhoneSE375 x 667
    iPhoneXR414 x 896
    iPhone12Pro390 x 844
    iPhone14ProMax430 x 932
    Pixel7412 x 915
    SamsungGalaxyS8Plus360 x 740
    SamsungGalaxyS20Ultra412 x 915
    iPadMini768 x 1024
    iPadAir820 x 1180
    iPadPro1024 x 1366
    SurfacePro7912 x 1368
    SurfaceDuo540 x 720
    GalaxyZFold5344 x 882
    AsusZenbookFold853 x 1280
    SamsungGalaxyA51A71412 x 914
    NestHub1024 x 600
    NestHubMax1280 x 800
    Tip

    browser.viewport controls the test runner iframe viewport. If you need Playwright context options such as locale, color scheme, or permissions, configure them through providerOptions.context.

    port

    • Type: number
    • Default: undefined (automatically selects an available port)
    • CLI: --browser.port <port>

    The port number for the Browser Mode Dev Server.

    rstest.config.ts
    import { defineConfig } from '@rstest/core';
    
    export default defineConfig({
      browser: {
        enabled: true,
        provider: 'playwright',
        port: 5173,
      },
    });

    If you set port and the port is already in use, the behavior is controlled by strictPort: when strictPort: true, Rstest throws an error and exits; when strictPort: false, it falls back to another available port. If port is not specified, an available port is always selected automatically.

    strictPort

    • Type: boolean
    • Default: false
    • CLI: --browser.strictPort

    When port is specified, whether the port must be available:

    • true: throw an error and exit if the port is in use
    • false: fall back to another available port if the port is in use
    rstest.config.ts
    import { defineConfig } from '@rstest/core';
    
    export default defineConfig({
      browser: {
        enabled: true,
        provider: 'playwright',
        port: 5173,
        strictPort: true,
      },
    });

    providerOptions

    • Type: Record<string, unknown>
    • Default: {}
    • CLI: --browser.providerOptions.*

    Playwright options passed through to browser launch and context creation. Rstest does not validate or interpret the contents of this object — it forwards the values as-is to Playwright.

    Each BrowserInstanceConfig in instances can carry its own providerOptions: top-level keys (launch, context) set on the instance replace the project-level keys, and keys the instance does not set keep the project-level value.

    See Playwright provider options below for the supported fields.

    rstest.config.ts
    import { defineConfig } from '@rstest/core';
    
    export default defineConfig({
      browser: {
        enabled: true,
        provider: 'playwright',
        providerOptions: {
          launch: {
            timeout: 60_000,
          },
        },
      },
    });

    You can also pass nested Playwright options from the CLI:

    npx rstest --browser.providerOptions.launch.channel=chrome

    expect.toMatchScreenshot

    • Type: BrowserScreenshotMatcherConfig
    • Default:
    {
      comparatorOptions: {
        threshold: 0.1,
        maxDiffPixels: 0,
      },
      stabilityTimeout: 2000,
      maskColor: '#FF00FF',
      caret: 'hide',
      scale: 'device',
      omitBackground: false,
    }

    maxDiffPixelRatio also defaults to 0; configure it instead of maxDiffPixels when you want to set a ratio. style is not injected by default. mask is assertion-only and defaults to no masks.

    Configure defaults for toMatchScreenshot() across a Browser Mode project. Put pixel-comparison tolerances under comparatorOptions; capture and path options are siblings of it. Assertion-level values override the corresponding global values. mask remains assertion-specific because it uses browser Locator objects.

    The defaults below apply when an option is omitted. Playwright supplies the capture defaults for maskColor, caret, scale, and omitBackground.

    OptionDefaultDescription
    comparatorOptions.threshold0.1Per-pixel color distance threshold from 0 (strict) to 1 (loose).
    comparatorOptions.maxDiffPixels0Maximum number of pixels allowed to differ.
    comparatorOptions.maxDiffPixelRatio0Maximum fraction of pixels allowed to differ.
    stabilityTimeout2000Maximum time to wait for consecutive captures to match, in ms.
    maskColor#FF00FFColor used to cover masked content.
    styleNot setNo additional CSS is injected.
    carethideHides the text caret during capture.
    scaledeviceCaptures at the device pixel ratio.
    omitBackgroundfalseKeeps the page background in the screenshot.
    screenshotDirectory__screenshots__Directory for references beside each test file.
    resolveScreenshotPathBuilt-inUses the path layout described below.

    Set either comparatorOptions.maxDiffPixels or comparatorOptions.maxDiffPixelRatio, not both. A relative screenshotDirectory is resolved from each test file's directory. If omitted, it defaults to __screenshots__. A shared directory keeps references separate by project name and test file, so paths stay stable across checkouts. When the chosen directory is the test file's own directory, Rstest places references in its __screenshots__ subdirectory.

    By default, references are stored in this layout:

    <test-directory>/__screenshots__/<test-file>/<reference-name>-<browser>-<platform>.png

    The reference name comes from the explicit name or the test name, sanitized for use as a path. Names that could collide after sanitization receive a stable suffix. Every unnamed assertion gets a sequence number starting at 1, including a test's only screenshot (for example, <test-name>-1). Explicitly named assertions do not get this number.

    Project names are not part of the default path, so projects using the same test file, screenshot name, browser, and platform share a reference. Use resolveScreenshotPath to isolate project-specific references. Existing references from Rstest's previous hashed layout are not moved automatically; move them to the new paths or regenerate them with --update.

    Use resolveScreenshotPath when you need a different layout. It receives the absolute test file path, project and test names, browser, platform, and an optional ordinal for unnamed assertions. The first unnamed assertion receives no ordinal; later ones start at 2. Return an absolute path or a path relative to the project root. When configured, the resolver takes precedence over screenshotDirectory.

    rstest.config.ts
    import path from 'node:path';
    import { defineConfig } from '@rstest/core';
    
    export default defineConfig({
      browser: {
        enabled: true,
        provider: 'playwright',
        expect: {
          toMatchScreenshot: {
            comparatorOptions: {
              threshold: 0.1,
              maxDiffPixels: 10,
            },
            resolveScreenshotPath: ({
              testFilePath,
              projectName,
              testName,
              browserName,
              platform,
            }) =>
              path.join(
                'visual-baselines',
                projectName,
                path.relative(process.cwd(), testFilePath),
                `${testName}-${browserName}-${platform}.png`,
              ),
          },
        },
      },
    });

    Launch rules

    Every rstest run launches one browser per (provider, browserName, headless, providerOptions.launch) combination across all Browser Mode projects. Two projects that configure the same browser with the same launch key share one browser instance; different providerOptions.launch values or a different headless setting produce separate launches. Within a project, every browser of the project shares one build and one dev server.

    The following rules are validated before any browser launches:

    • One headed browser per run. Browser mode opens a single debug window, so at most one (project, browser) pair may set headless: false; every other browser must set headless: true. The error names the concrete fix:

      Only one (project, browser) pair can run headed per run: "web" ("chromium"). Browser mode opens one debug window, so every other browser must set headless: true. Most often this comes from --browser.headless=false on a multi-browser run: select a single headless pair with --browser.instances <name> or narrow the projects with --project.

    • Watch mode does not support mixing headed and headless browsers. A watch session where one browser runs headed and another headless is rejected at validation; every configured browser must set headless: true, or run without watch.

    • Coverage provider v8 requires Chromium. With coverage.enabled and coverage.provider: 'v8', a browser project selecting a non-Chromium browser fails validation. Switch to coverage.provider: 'istanbul', or select Chromium only (--browser.instances chromium).

    For strict browser-per-environment coverage you can still run separate executions (for example, in a CI matrix) with the --browser.instances filter:

    npx rstest --browser.instances chromium
    npx rstest --browser.instances firefox
    npx rstest --browser.instances webkit

    CLI browser filters

    --browser.instances <names> (repeatable and/or comma-separated) only filters, like --project: it selects the configured instances whose browserName is listed and never creates an instance from a name. The default Chromium instance (when nothing is configured) and the instance of the deprecated browser.browser count as configured instances.

    • A browser project where none of its instances match is skipped for the run; node projects are unaffected.
    • A listed name that no selected browser project configures is an error naming the name and the configured browsers per project.
    • Duplicated names and names other than chromium, firefox and webkit are errors.

    --browser.name <name> stays as a deprecated option and emits a deprecation warning once per run. The project runs that single browser: with the configured instance's overrides when one has that browserName, otherwise as a plain instance with project-level defaults. It cannot be combined with --browser.instances.

    Multi-browser reporting

    Reporters do not see browsers. When a project selects more than one browser, each (project, browser) pair is reported as its own project named <project> (<browserName>), for example web (chromium) and web (firefox). A project that selects a single browser keeps its original name.

    • Reporter payloads, rstest list results, and blob reports use this name as project, so the same file run by two browsers yields two distinct results. Built-in reporters show it like any other project name, e.g. ✓ [web (chromium)] tests/basic.test.ts.
    • The pairs are a reporting view only: every browser of a project still shares one build and one dev server, and --project filters by the configured project name.
    • Two configured project names must not collide with a generated <project> (<browserName>) name; a collision is a config error.

    Multi-project config isolation

    When using projects in Browser Mode, each project still compiles and executes with its own build config (for example plugins, include, and framework-specific setup).

    Browser build-scoped options stay per project (provider, port, strictPort), while the browser instances, defaults, and per-browser overrides (instances, headless, viewport, providerOptions) are project-owned: two browser projects may run different browsers in one run. When two projects configure the same browser, launch sharing applies.

    rstest.config.ts
    import { defineConfig } from '@rstest/core';
    
    export default defineConfig({
      projects: ['./project-b/rstest.config.ts', './project-a/rstest.config.ts'],
    });
    project-a/rstest.config.ts
    import { pluginReact } from '@rsbuild/plugin-react';
    import { defineConfig } from '@rstest/core';
    
    export default defineConfig({
      name: 'project-a',
      plugins: [pluginReact()],
      include: ['tests/**/*.test.tsx'],
      browser: {
        enabled: true,
        provider: 'playwright',
      },
    });

    Mixing with node tests

    You can configure both browser tests and Node.js tests together:

    rstest.config.ts
    import { defineConfig } from '@rstest/core';
    
    export default defineConfig({
      projects: [
        {
          name: 'browser',
          include: ['src/**/*.browser.test.ts'],
          browser: {
            enabled: true,
            provider: 'playwright',
          },
        },
        {
          name: 'node',
          include: ['src/**/*.node.test.ts'],
          testEnvironment: 'node',
        },
        {
          name: 'jsdom',
          include: ['src/**/*.test.ts'],
          exclude: ['src/**/*.browser.test.ts', 'src/**/*.node.test.ts'],
          testEnvironment: 'jsdom',
        },
      ],
    });

    Provider options

    Playwright

    When using provider: 'playwright', the Playwright provider recognizes the following fields in providerOptions:

    1. launch — Passed to Playwright's browserType.launch(). Controls how the browser process is started.
    2. context — Passed to Playwright's browser.newContext(). Controls the browser context created for each test file.

    Since providerOptions is typed as Record<string, unknown>, you won't get IntelliSense out of the box. To get type checking and autocompletion, import types directly from the playwright package and use TypeScript's satisfies operator:

    rstest.config.ts
    import type { LaunchOptions, BrowserContextOptions } from 'playwright';
    import { defineConfig } from '@rstest/core';
    
    type PlaywrightProviderOptions = {
      launch?: LaunchOptions;
      context?: BrowserContextOptions;
    };
    
    export default defineConfig({
      browser: {
        enabled: true,
        provider: 'playwright',
        providerOptions: {
          launch: {
            timeout: 60_000,
          },
          context: {
            locale: 'en-US',
            colorScheme: 'dark',
          },
        } satisfies PlaywrightProviderOptions,
      },
    });