close
Rstest
  • English

      • Getting started

      This guide will help you configure and run Browser Mode tests in your project.

      Automatic initialization

      The quickest way is to use the @rstest/core init browser command for automatic configuration:

      npm
      yarn
      pnpm
      bun
      deno
      npx @rstest/core init browser

      Initialization process

      When you run the command, Rstest automatically:

      1. Generates boilerplate code: Rstest detects your project's framework (for example, React), language (for example, TypeScript or JavaScript), test directory (for example, common directories like tests/, test/, or __tests__/, depending on what is detected), and package manager, then generates sample components and test files. The generated files adapt based on detection results:

        • Test directory: Files are placed in the detected test directory
        • Framework: React projects get JSX component tests, others get native DOM examples
        • Language: TypeScript projects get .ts/.tsx files, others get .js/.jsx files

      2. Creates configuration file: Creates rstest.browser.config.ts in your project root with basic Browser Mode configuration.

      3. Updates package.json: Adds a test:browser script.

      Here's an example output for a React project:

      Set up Rstest browser mode

  Detecting project...
  ✓ Found React 19.0.0
  ✓ Using playwright as browser provider
  ✓ Test directory: tests/

  Created files:
    - rstest.browser.config.ts
    - tests/Counter.jsx
    - tests/Counter.test.jsx
    - Updated package.json

  Next steps:
    pnpm i
    pnpm dlx playwright install --with-deps
    pnpm run test:browser

└ Done!

      Next steps

      After initialization, follow the "Next steps" instructions in the output: install project dependencies, install browser drivers, then run tests.

      Non-interactive Environments

      In CI or other non-interactive environments, add the --yes flag to skip all prompts and use detected configuration:

      npx @rstest/core init browser --yes

      Manual configuration

      1. Install dependencies

      First, install the Rstest core package and Browser Mode support package:

      npm
      yarn
      pnpm
      bun
      deno
      npm add @rstest/core @rstest/browser -D

      Browser Mode requires Playwright as the browser driver. Install the corresponding browser:

      npx playwright install chromium

      You can also install other browsers:

      # Install Firefox
npx playwright install firefox

# Install WebKit (Safari)
npx playwright install webkit

# Install all browsers
npx playwright install

      2. Create configuration file

      Create or update your rstest.config.ts configuration file:

      rstest.config.ts
      import { defineConfig } from '@rstest/core';

export default defineConfig({
  browser: {
    enabled: true,
    provider: 'playwright',
  },
});

      3. Write tests

      Create a browser test file. The recommended approach is to use the Locator API for element queries and interactions:

      tests/counter.test.ts
      import { page } from '@rstest/browser';
import { expect, test } from '@rstest/core';

test('counter increments on click', async () => {
  document.body.innerHTML = `
    <button id="count-btn">Count: 0</button>
  `;

  let count = 0;
  document.getElementById('count-btn')!.addEventListener('click', (e) => {
    count++;
    (e.target as HTMLButtonElement).textContent = `Count: ${count}`;
  });

  await expect
    .element(page.getByRole('button', { name: 'Count: 0' }))
    .toBeVisible();
  await page.getByRole('button', { name: 'Count: 0' }).click();
  await expect.element(page.getByText('Count: 1')).toBeVisible();
});

      This example uses page.getByRole() to locate a button by its semantic role, triggers an interaction with click(), and asserts the result with expect.element().toBeVisible(). The assertion automatically waits for the element state to change — no manual polling needed.

      Headless vs headed mode

      By default, Browser Mode automatically selects the running mode based on the environment:

      • CI environment: Automatically uses headless mode (no UI)
      • Local development: Uses headed mode by default (shows browser window)

      Configuring headless mode

      You can explicitly specify this in your configuration file:

      rstest.config.ts
      import { defineConfig } from '@rstest/core';

export default defineConfig({
  browser: {
    enabled: true,
    provider: 'playwright',
    headless: true, // Always use headless mode
  },
});

      Configuration reference

      For complete configuration reference, see browser configuration.

      Next steps