tessl/npm-vitest--browser

Browser runner for Vitest enabling tests to run in actual browser environments with real DOM APIs and browser-specific features

—

Pending

Overview

Eval results

Files

Providers

Name: tessl/npm-vitest--browser
Author: tessl

Browser automation providers for running tests in different browser environments, each with specific capabilities and configuration options supporting Playwright, WebdriverIO, and preview modes.

Capabilities

Provider System

@vitest/browser supports multiple browser automation providers, each with different strengths and use cases.

/**
 * Playwright provider - Full browser automation with CDP access
 */
const playwright: BrowserProviderModule;

/**
 * WebdriverIO provider - Cross-browser testing with Selenium WebDriver
 */
const webdriverio: BrowserProviderModule;

/**
 * Preview provider - Development mode with simulated interactions
 */
const preview: BrowserProviderModule;

Playwright Provider

Full-featured browser automation with Chrome DevTools Protocol support and advanced testing capabilities.

import { playwright } from "@vitest/browser/providers";

Configuration:

// vitest.config.ts
export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: 'playwright',
      name: 'chromium', // or 'firefox', 'webkit'
      providerOptions: {
        launch: {
          // Playwright launch options
          headless: false,
          slowMo: 100,
          devtools: true
        },
        context: {
          // Browser context options
          viewport: { width: 1280, height: 720 },
          locale: 'en-US',
          actionTimeout: 5000
        }
      }
    }
  }
});

Provider-Specific Type Augmentations:

// Module augmentation for vitest/node
declare module 'vitest/node' {
  interface BrowserProviderOptions {
    /** Playwright launch options */
    launch?: LaunchOptions;
    /** Connect to existing browser */
    connect?: {
      wsEndpoint: string;
      options?: ConnectOptions;
    };
    /** Browser context options */
    context?: Omit<BrowserContextOptions, 'ignoreHTTPSErrors' | 'serviceWorkers'> & {
      /** Maximum timeout for userEvent actions in milliseconds */
      actionTimeout?: number;
    };
  }

  interface BrowserCommandContext {
    /** Playwright page instance */
    page: Page;
    /** Get iframe frame */
    frame(): Promise<Frame>;
    /** Frame locator for iframe */
    iframe: FrameLocator;
    /** Browser context instance */
    context: BrowserContext;
  }
}

// Module augmentation for @vitest/browser/context
declare module '@vitest/browser/context' {
  interface CDPSession {
    /** Send Chrome DevTools Protocol command */
    send<T extends keyof Protocol.CommandParameters>(
      method: T,
      params?: Protocol.CommandParameters[T]
    ): Promise<Protocol.CommandReturnValues[T]>;
    
    /** Add CDP event listener */
    on<T extends keyof Protocol.Events>(
      event: T,
      listener: (payload: Protocol.Events[T]) => void
    ): this;
    
    /** Add one-time CDP event listener */
    once<T extends keyof Protocol.Events>(
      event: T,
      listener: (payload: Protocol.Events[T]) => void
    ): this;
    
    /** Remove CDP event listener */
    off<T extends keyof Protocol.Events>(
      event: T,
      listener: (payload: Protocol.Events[T]) => void
    ): this;
  }
  
  // User event options extend Playwright types
  interface UserEventHoverOptions extends PWHoverOptions {}
  interface UserEventClickOptions extends PWClickOptions {}
  interface UserEventDoubleClickOptions extends PWDoubleClickOptions {}
  interface UserEventTripleClickOptions extends PWClickOptions {}
  interface UserEventFillOptions extends PWFillOptions {}
  interface UserEventSelectOptions extends PWSelectOptions {}
  interface UserEventDragAndDropOptions extends PWDragAndDropOptions {}
  interface UserEventUploadOptions extends PWSetInputFiles {}
  interface ScreenshotOptions extends PWScreenshotOptions {}
}

Usage Examples:

import { cdp } from "@vitest/browser/context";

// Chrome DevTools Protocol usage (Playwright only)
const session = cdp();
await session.send('Runtime.enable');
await session.send('Runtime.evaluate', { expression: 'console.log("Hello CDP")' });

// Provider-specific command context
function myCommand({ page, context, iframe }: BrowserCommandContext) {
  // Access Playwright APIs directly
  await page.waitForLoadState('networkidle');
  await context.addCookies([{ name: 'test', value: 'value', url: 'https://example.com' }]);
  await iframe.locator('input').fill('text');
}

WebdriverIO Provider

Cross-browser testing with Selenium WebDriver protocol support.

import { webdriverio } from "@vitest/browser/providers";

Configuration:

// vitest.config.ts
export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: 'webdriverio',
      name: 'chrome', // or 'firefox', 'safari', 'edge'
      providerOptions: {
        // WebdriverIO remote options
        capabilities: {
          browserName: 'chrome',
          'goog:chromeOptions': {
            args: ['--no-sandbox', '--disable-dev-shm-usage']
          }
        },
        logLevel: 'warn',
        waitforTimeout: 10000,
        connectionRetryTimeout: 90000,
        connectionRetryCount: 3
      }
    }
  }
});

Provider-Specific Type Augmentations:

// Module augmentation for vitest/node
declare module 'vitest/node' {
  interface BrowserProviderOptions extends Partial<Parameters<typeof remote>[0]> {
    // WebdriverIO remote options
    capabilities?: object;
    logLevel?: string;
    waitforTimeout?: number;
    connectionRetryTimeout?: number;
    connectionRetryCount?: number;
  }

  interface BrowserCommandContext {
    /** WebdriverIO browser instance */
    browser: WebdriverIO.Browser;
  }

  interface UserEventClickOptions extends ClickOptions {}

  interface UserEventDragOptions extends DragAndDropOptions {
    sourceX?: number;
    sourceY?: number;
    targetX?: number;
    targetY?: number;
  }
}

Usage Examples:

// Provider-specific command context
function myCommand({ browser }: BrowserCommandContext) {
  // Access WebdriverIO APIs directly
  await browser.maximizeWindow();
  await browser.execute('window.scrollTo(0, document.body.scrollHeight)');
  
  // Use WebdriverIO element methods
  const element = await browser.$('#my-element');
  await element.waitForDisplayed();
  await element.click();
}

// Provider-specific interaction options
await userEvent.click(page.getByRole("button"), {
  button: 'right', // Right click (WebdriverIO ClickOptions)
  x: 10,
  y: 10
});

// Drag and drop with coordinates
await userEvent.dragAndDrop(sourceElement, targetElement, {
  sourceX: 10,
  sourceY: 10,
  targetX: 50,
  targetY: 50
});

Preview Provider

Development mode provider with simulated interactions using @testing-library/user-event.

import { preview } from "@vitest/browser/providers";

Configuration:

// vitest.config.ts
export default defineConfig({
  test: {
    browser: {
      enabled: true,
      provider: 'preview',
      name: 'chromium',
      providerOptions: {
        // Minimal configuration for preview mode
      }
    }
  }
});

Characteristics:

Fastest setup: No external browser automation tools required
Simulated events: Uses @testing-library/user-event for interactions
Development focused: Ideal for rapid development and debugging
Limited features: No real browser automation, no screenshots, no file uploads
No provider context: Limited command context capabilities

Usage Examples:

// Standard user interactions work the same
await userEvent.click(page.getByRole("button"));
await userEvent.type(page.getByLabelText("Input"), "text");

// Some features are not available in preview mode:
// - dragAndDrop() throws an error
// - CDP access is not available
// - File uploads are simulated
// - Screenshots return placeholder data

Provider Selection Guide

Choose the right provider based on your testing needs:

Use Playwright when:

Need CDP (Chrome DevTools Protocol) access
Require advanced browser automation features
Testing modern web applications with complex interactions
Need reliable cross-browser testing
Want comprehensive screenshot and video capabilities

Use WebdriverIO when:

Existing Selenium WebDriver infrastructure
Need to test older browsers
Require specific WebDriver capabilities
Integration with existing WebDriver-based tools
Need mobile browser testing

Use Preview when:

Rapid development and debugging
Unit testing components in isolation
CI/CD environments where speed is critical
Don't need real browser automation
Testing basic user interactions

Provider-Specific Features

Playwright Exclusive:

Chrome DevTools Protocol access via cdp()
Advanced screenshot options (full page, element clipping)
Network interception and mocking
Browser context isolation
Video recording capabilities

WebdriverIO Exclusive:

Mobile browser testing
Legacy browser support
Selenium Grid integration
Custom WebDriver capabilities
Advanced wait strategies

Preview Exclusive:

Fastest test execution
No external dependencies
Perfect for unit testing
Debugging-friendly

Error Handling

Different providers may throw different types of errors:

import { server } from "@vitest/browser/context";

try {
  await userEvent.dragAndDrop(source, target);
} catch (error) {
  if (server.provider === 'preview') {
    // Preview provider doesn't support drag and drop
    console.log('Drag and drop not supported in preview mode');
  } else {
    // Real provider error
    throw error;
  }
}

Types

Provider-related type definitions:

interface BrowserProviderModule {
  // Provider implementation details (internal)
}

// Provider-specific option types are defined in their respective modules
// and extend base interfaces through module augmentation

Install with Tessl CLI