@frontend-testing/vitest-browser-navigate

Browser navigation command for Vitest browser mode. Simulates SPA navigation by updating browser history and dispatching popstate events.

Features

• 🧭 SPA Navigation - Navigate programmatically in browser tests
• 🎭 Playwright Support - Works with @vitest/browser-playwright
• 🚗 WebdriverIO Support - Works with @vitest/browser-webdriverio
• 📦 TypeScript - Full type support with automatic commands.navigate() types

Installation

npm install -D @frontend-testing/vitest-browser-navigate

Peer Dependencies: vitest >= 4.0.0

Quick Start

1. Configure Vitest

// vitest.config.ts
import { navigate } from "@frontend-testing/vitest-browser-navigate";
import { defineConfig } from "vitest/config";

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: "playwright", // or "webdriverio"
      instances: [{ browser: "chromium" }],
      commands: { navigate },
    },
  },
});

2. Use in Tests

import { commands } from "vitest/browser";

describe("MyPage", () => {
  it("navigates to dashboard", async () => {
    await commands.navigate("/dashboard");
    expect(window.location.pathname).toBe("/dashboard");
  });
});

TypeScript Support

Types for commands.navigate() are included automatically. If your IDE doesn't recognize the types, add a side-effect import:

Option A: In your test setup file (recommended)

// src/test/setup.ts
import "@frontend-testing/vitest-browser-navigate";
// ... rest of your setup

Option B: In individual test files

// my-component.spec.tsx
import "@frontend-testing/vitest-browser-navigate";
import { commands } from "vitest/browser";

// Now commands.navigate() has full type support
await commands.navigate("/dashboard");

Note: After adding the import, you may need to restart your TypeScript server (Cmd+Shift+P → "TypeScript: Restart TS Server").

API

commands.navigate(path: string): Promise<void>

Navigates to the specified path by:

1. Calling window.history.pushState()
2. Dispatching a popstate event (triggers SPA routers like React Router)
3. Waiting for the browser to process the navigation

// Basic navigation
await commands.navigate("/login");

// With route parameters
await commands.navigate("/users/123");

// With query parameters
await commands.navigate("/search?q=test&page=1");

How It Works

The command executes inside the browser context and simulates navigation without a full page reload - exactly how SPA routers work. This makes it perfect for testing React Router, Vue Router, or any other client-side routing solution.

License

MIT