@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 "@frontend-testing/vitest-browser-navigate"; // For types
import { commands } from "vitest/browser";
import { render } from "vitest-browser-react";

describe("MyPage", () => {
  it("navigates to dashboard", async () => {
    await commands.navigate("/dashboard");
    await render(<App />);

    expect(window.location.pathname).toBe("/dashboard");
  });
});

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