Browser navigation command for Vitest browser mode
npm install @frontend-testing/vitest-browser-navigateBrowser navigation command for Vitest browser mode. Simulates SPA navigation by updating browser history and dispatching popstate events.
- 🧠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
``bash`
npm install -D @frontend-testing/vitest-browser-navigate
Peer Dependencies: vitest >= 4.0.0
`typescript
// 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 },
},
},
});
`
`typescript
import { commands } from "vitest/browser";
describe("MyPage", () => {
it("navigates to dashboard", async () => {
await commands.navigate("/dashboard");
expect(window.location.pathname).toBe("/dashboard");
});
});
`
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)
`typescript`
// src/test/setup.ts
import "@frontend-testing/vitest-browser-navigate";
// ... rest of your setup
Option B: In individual test files
`typescript
// 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").
Navigates to the specified path by:
1. Calling window.history.pushState()
2. Dispatching a event (triggers SPA routers like React Router)
3. Waiting for the browser to process the navigation
`typescript
// 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");
``
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.
MIT