How to Run E2E Tests with Playwright for UI Coverage in Routa

Routa uses two Playwright configuration files to run the identical E2E test suite against both its Next.js web frontend (port 3000) and its Tauri desktop frontend (port 3210), ensuring consistent UI coverage across both platforms.

Routa’s architecture uniquely combines a Next.js web application with a Tauri desktop application backed by a Rust/Axum server. To guarantee UI consistency across these dual surfaces, the repository maintains a unified test suite in tests/e2e/ that targets both runtimes through environment-specific Playwright configurations. Understanding how to run e2e tests with Playwright for UI coverage in Routa requires familiarity with these dual configuration files and their respective base URLs.

Understanding the Dual-Config Architecture

Routa ships with two distinct Playwright configuration files to handle its bifurcated frontend architecture:

• playwright.config.ts: Targets the web application served at http://localhost:3000
• playwright.tauri.config.ts: Targets the desktop application served at http://127.0.0.1:3210

Both configurations share the same test directory (tests/e2e/), but the desktop variant increases the default timeout to accommodate Tauri’s slower startup process. This design ensures that when you run e2e tests with Playwright for UI coverage in Routa, you are validating identical user flows against both the browser and the native desktop wrapper.

Prerequisites and Installation

Install Node Dependencies

Begin by installing the project dependencies defined in package.json:

npm ci

Install Playwright Browsers

Install the required browser binaries (Chromium, Firefox, and WebKit) globally for the project:

npx playwright install

Running E2E Tests Against the Web Frontend

To execute the test suite against the web version of Routa:

1. Start the Next.js development server:

   npm run dev

2. Run the Playwright tests using the default web configuration:

   npx playwright test

   Or explicitly specify the configuration:

   npx playwright test --config=playwright.config.ts

The web configuration resolves API calls to the Next.js API layer running at http://localhost:3000.

Running E2E Tests Against the Desktop Frontend

Testing the Tauri desktop application requires the Axum backend to be running on port 3210:

1. Launch the desktop application in development mode:

   npm run dev:desktop

   This command starts both the Tauri wrapper and the Rust/Axum server.

2. Execute the tests using the Tauri-specific configuration:

   npx playwright test --config=playwright.tauri.config.ts

This configuration uses http://127.0.0.1:3210 as the base URL and exercises the same desktopAwareFetch utility found in src/client/utils/diagnostics.ts that the production desktop client uses to communicate with the backend.

Configuration Deep Dive

Web Configuration (playwright.config.ts)

Located at the repository root, this file defines the standard web testing environment:

import { defineConfig, devices } from '@playwright/test';

export default defineConfig({
  testDir: './tests/e2e',
  fullyParallel: true,
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
  },
  projects: [
    { name: 'Chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'Firefox',  use: { ...devices['Desktop Firefox'] } },
    { name: 'WebKit',   use: { ...devices['Desktop Safari'] } },
  ],
});

Desktop Configuration (playwright.tauri.config.ts)

This configuration extends the base settings while overriding critical parameters for desktop execution:

import baseConfig from './playwright.config';

export default {
  ...baseConfig,
  use: {
    ...baseConfig.use,
    baseURL: 'http://127.0.0.1:3210',
    timeout: 60_000,
  },
};

The increased timeout value accounts for Tauri’s initialization overhead, preventing premature test failures during the desktop application startup sequence.

Troubleshooting Common Issues

• Connection refused on http://127.0.0.1:3210: Ensure you have started the desktop dev process with npm run dev:desktop before launching the Playwright command.
• Timeout errors in desktop tests: The default 30-second Playwright timeout is insufficient for Tauri startup. The playwright.tauri.config.ts file sets this to 60 seconds; you can override further with --timeout=60000.
• Missing UI elements: Verify you are using the correct configuration flag. Running the desktop config against the web server (or vice versa) will cause element selection failures.
• Browser binary errors: If Playwright reports missing browsers, re-run npx playwright install to ensure Chromium, Firefox, and WebKit binaries are present.

Summary

• Routa maintains identical UI coverage across web and desktop platforms using a single test suite located in tests/e2e/.
• Use playwright.config.ts to test against the Next.js web server at localhost:3000.
• Use playwright.tauri.config.ts to test against the Tauri desktop application at 127.0.0.1:3210 with extended timeouts.
• Always start the appropriate development server (npm run dev for web, npm run dev:desktop for desktop) before executing tests.
• The desktopAwareFetch utility ensures API call semantics remain consistent between both testing environments.

Frequently Asked Questions

Why does Routa require two separate Playwright configuration files?

Routa’s dual-backend architecture necessitates different base URLs and timeout settings for web versus desktop testing. The web frontend runs on localhost:3000 while the Tauri desktop frontend serves the UI from 127.0.0.1:3210. By separating these into distinct configuration files, the project ensures the correct environment variables and timeouts are applied without modifying test code.

Can I run the same test files against both web and desktop versions?

Yes. All E2E tests are stored in tests/e2e/ and are designed to be runtime-agnostic. Because both frontends share identical API semantics and DOM structures, the same assertions and interaction chains validate behavior across both platforms when you switch configurations using the --config flag.

What causes timeout errors when running desktop E2E tests?

Timeout errors typically occur because Tauri’s startup process—including the Rust/Axum backend initialization—takes significantly longer than a standard Next.js dev server. The playwright.tauri.config.ts addresses this by setting timeout: 60_000 (60 seconds), but you may need to increase this further on slower machines using the --timeout CLI option.

Do I need separate browser installations for Tauri testing?

No. Tauri uses the system WebView (WebKit on macOS, WebView2 on Windows, WebKitGTK on Linux), but Playwright still requires its own browser binaries to drive the automation. Running npx playwright install once installs Chromium, Firefox, and WebKit binaries that Playwright uses to interface with the Tauri application during E2E execution.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}