close
Rstest
  • English

      • Browser mode (experimental)

      Rstest provides Browser Mode, allowing you to run tests in a real browser instead of simulated environments like jsdom or happy-dom.

      What is browser Mode?

      Browser Mode uses Playwright to execute your test code in real browsers (Chromium, Firefox, or WebKit). This means your tests run with the exact same browser APIs and behaviors as in production.

      Note

      Like Node mode, Browser Mode fails a test file when an unhandled error or promise rejection escapes it — even if every test in the file passed. If a rejection is expected, await the promise or attach a handler inside the test so it does not leak to the page.

      Locator API

      Browser Mode now supports a Playwright-style Locator workflow: you can use page.getBy* for element queries, then use expect.element(locator) for auto-waiting assertions.

      This approach is ideal when you want semantic queries (role/label/text) and chainable assertions, making component tests and DOM tests closer to real user interaction semantics.

      See User interactions for detailed usage.

      When to use browser mode

      Use this decision tree to determine if you need Browser Mode:

      Depends on real browser APIs? ─── Yes ─▶ ✅ Browser Mode
         │ No
         ▼
Need cross-browser testing?  ─── Yes ─▶ ✅ Browser Mode
         │ No
         ▼
Unexpected behavior in jsdom? ── Yes ─▶ ✅ Browser Mode
         │ No
         ▼
    💡 jsdom is fine
      Recommendation

      Even if your tests work fine in jsdom, we still recommend using Browser Mode. See the comparison table below for specific advantages.

      Browser mode vs jsdom/happy-dom

      Browser Mode and jsdom/happy-dom represent different trade-offs: Browser Mode provides full browser compatibility and visual debugging but consumes more resources; jsdom/happy-dom runs faster and lighter but can only simulate a subset of browser APIs.

      FeatureBrowser Modejsdom / happy-dom
      Browser API coverage✅ Full support⚠️ Partial simulation
      Canvas / WebGL✅ Native support❌ Unsupported or needs polyfill
      CSS computed styles✅ Real rendering⚠️ Limited support
      Web Workers✅ Native support❌ Unsupported
      Execution speed⚠️ Slower✅ Faster
      Resource usage⚠️ Higher✅ Lower
      Debugging experience✅ Visual debugging⚠️ Console only
      Cross-browser testing✅ Multiple browsers❌ Unsupported

      Config compatibility

      Most config options behave the same in Browser Mode. The table below collects the exceptions in one place — node-only options that are ignored (with a one-time warning when set to a non-default value), features not supported yet, and options whose scheduling semantics differ:

      Option / APIBehavior in Browser Mode
      coverage.provider: 'v8'Not supported. A browser-only run fails with an error (except rstest list); a mixed node + browser run warns, and browser files get no coverage while node projects still use v8. Use the default istanbul provider for browser coverage.
      rs.mock familyNot supported yet — rs.mock, rs.doMock, rs.importActual, rs.mockRequire throw in browser tests.
      includeSourceNot supported yet. In-source test blocks only run in node-mode projects.
      isolateIgnored — each test file always runs in a fresh browser context/page. A browser-only run with isolate: false warns.
      pool.type / pool.execArgvIgnored — node process mechanisms.
      pool.maxWorkersHeadless runs execute files in parallel across up to maxWorkers browser contexts. Headed runs always execute files serially, because all tests share the single visible container page.
      testEnvironmentIgnored — the real browser is the environment.
      detectAsyncLeaks, logHeapUsageIgnored — node-only mechanisms.
      bailSupported in headless runs: once the failure budget is reached, Rstest stops dispatching the remaining files. Files already running in parallel finish first, so a few more results can still appear. The headed debugging UI (headless: false) does not apply bail.

      Next steps