> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 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:


```sh [npx]
npx @rstest/core init browser
```

```sh [yarn]
yarn dlx @rstest/core init browser
```

```sh [pnpm]
pnpm dlx @rstest/core init browser
```

```sh [bunx]
bunx @rstest/core init browser
```

```sh [deno]
deno run -A npm:@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:

```bash
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.

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

```bash
npx @rstest/core init browser --yes
```

:::

## Manual configuration

### 1. Install dependencies

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


```sh [npm]
npm add @rstest/core @rstest/browser -D
```

```sh [yarn]
yarn add @rstest/core @rstest/browser -D
```

```sh [pnpm]
pnpm add @rstest/core @rstest/browser -D
```

```sh [bun]
bun add @rstest/core @rstest/browser -D
```

```sh [deno]
deno add npm:@rstest/core npm:@rstest/browser -D
```

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

```bash
npx playwright install chromium
```

You can also install other browsers:

```bash
# 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:

```ts title="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:

```ts title="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:

```ts title="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](/config/test/browser.md).

## Next steps

- [User interactions](/guide/browser-testing/user-interactions.md#locator-api) - Use `page` + `expect.element` for semantic queries and assertions
- [Framework guides](/guide/browser-testing/framework-guides.md) - Complete configuration and component testing examples for each framework
- [User interactions](/guide/browser-testing/user-interactions.md) - Simulate user actions