Web Test Runner Playwright

import { playwrightLauncher, PlaywrightLauncher, devices, playwright, ProductType } from "@web/test-runner-playwright";
import type { LaunchOptions, Browser, BrowserContext, Page } from 'playwright';
import type { TestRunnerCoreConfig, CoverageMapData, SessionResult, BrowserLauncher } from '@web/test-runner-core';

const { playwrightLauncher, PlaywrightLauncher, devices, playwright, ProductType } = require("@web/test-runner-playwright");

import { playwrightLauncher } from "@web/test-runner-playwright";

// Basic launcher configuration
const browsers = [
  playwrightLauncher({ product: 'chromium' }),
  playwrightLauncher({ product: 'firefox' }),
  playwrightLauncher({ product: 'webkit' }),
];

// Web Test Runner config
export default {
  browsers,
  // other config options...
};

import { playwrightLauncher, playwright } from "@web/test-runner-playwright";

// Advanced configuration with custom options
const launcher = playwrightLauncher({
  product: 'chromium',
  launchOptions: {
    headless: false,
    devtools: true,
    args: ['--disable-web-security'],
  },
  createBrowserContext: ({ browser }) => 
    browser.newContext({
      viewport: { width: 1920, height: 1080 },
      locale: 'en-US',
    }),
  createPage: ({ context }) => context.newPage(),
  concurrency: 4,
  __experimentalWindowFocus__: true,
});

/**
 * Factory function that creates a PlaywrightLauncher instance
 * @param args - Optional configuration arguments
 * @returns Configured PlaywrightLauncher instance
 */
function playwrightLauncher(args?: PlaywrightLauncherArgs): PlaywrightLauncher;

interface PlaywrightLauncherArgs {
  /** Browser engine to use - defaults to 'chromium' */
  product?: ProductType;
  /** Playwright launch options for browser startup */
  launchOptions?: LaunchOptions;
  /** Custom function for creating browser contexts */
  createBrowserContext?: CreateBrowserContextFn;
  /** Custom function for creating pages within contexts */
  createPage?: CreatePageFn;
  /** Experimental window focus feature - defaults to false */
  __experimentalWindowFocus__?: boolean;
  /** Maximum number of concurrent browser instances */
  concurrency?: number;
}

/**
 * Main launcher class implementing BrowserLauncher interface
 * Manages browser instances and test sessions
 */
class PlaywrightLauncher implements BrowserLauncher {
  /** Human-readable browser name (e.g., "Chromium", "Firefox") */
  public name: string;
  /** Fixed identifier "playwright" */
  public type: string;
  /** Maximum number of concurrent browser instances */
  public concurrency?: number;
  /** Experimental window focus feature flag */
  public __experimentalWindowFocus__: boolean;

  constructor(
    product: ProductType,
    launchOptions: LaunchOptions,
    createBrowserContextFn: CreateBrowserContextFn,
    createPageFn: CreatePageFn,
    __experimentalWindowFocus__?: boolean,
    concurrency?: number
  );

  /** Initialize the launcher with test runner configuration */
  initialize(config: TestRunnerCoreConfig, testFiles: string[]): Promise<void>;

  /** Stop all browser instances and clean up resources */
  stop(): Promise<void>;

  /** Start a new test session with given session ID and URL */
  startSession(sessionId: string, url: string): Promise<void>;

  /** Check if a session is currently active */
  isActive(sessionId: string): boolean;

  /** Get the current browser URL for a session */
  getBrowserUrl(sessionId: string): string;

  /** Start a debug session with visible browser window */
  startDebugSession(sessionId: string, url: string): Promise<void>;

  /** Stop a session and return test results with optional coverage */
  stopSession(sessionId: string): Promise<SessionResult>;

  /** Get the Playwright page instance for a session */
  getPage(sessionId: string): Page;
}

/**
 * Function type for creating custom browser contexts
 * @param args - Browser and configuration objects
 * @returns Browser context (sync or async)
 */
type CreateBrowserContextFn = (args: CreateArgs) => BrowserContext | Promise<BrowserContext>;

/**
 * Function type for creating custom pages
 * @param args - Browser, context, and configuration objects
 * @returns Promise resolving to a Playwright page
 */
type CreatePageFn = (args: CreateArgs & { context: BrowserContext }) => Promise<Page>;

// CreateArgs interface is defined in the Types section below

/**
 * Browser engine type defining supported Playwright browsers
 * Exported as a standalone type from the package
 */
export type ProductType = 'chromium' | 'firefox' | 'webkit';

/**
 * Complete Playwright API namespace for advanced usage
 * Provides access to all Playwright functionality beyond the launcher
 */
const playwright: typeof import('playwright');

/**
 * Playwright device configurations for mobile testing
 * Contains predefined device settings for various mobile devices
 */
const devices: typeof import('playwright').devices;

// Core type definitions

/**
 * Playwright launch options for browser startup configuration
 * Imported from 'playwright' package
 */
type LaunchOptions = import('playwright').LaunchOptions;

/**
 * Test Runner configuration interface
 * Imported from '@web/test-runner-core'
 */
type TestRunnerCoreConfig = import('@web/test-runner-core').TestRunnerCoreConfig;

/**
 * Istanbul coverage data format
 * Imported from '@web/test-runner-core' (re-exported from 'istanbul-lib-coverage')
 */
type CoverageMapData = import('@web/test-runner-core').CoverageMapData;

/**
 * Playwright browser types
 * Imported from 'playwright' package
 */
type Browser = import('playwright').Browser;
type BrowserContext = import('playwright').BrowserContext;
type Page = import('playwright').Page;

/**
 * Browser launcher interface from @web/test-runner-core
 * Defines the contract for browser launchers in the Web Test Runner ecosystem
 */
type BrowserLauncher = import('@web/test-runner-core').BrowserLauncher;

/**
 * Arguments for browser context and page creation functions
 */
interface CreateArgs {
  /** Playwright browser instance */
  browser: Browser;
  /** Web Test Runner configuration */
  config: TestRunnerCoreConfig;
}

/**
 * Session result interface - imported from @web/test-runner-core
 * Returned when stopping test sessions
 */
interface SessionResult {
  /** Test coverage data if coverage collection is enabled */
  testCoverage?: CoverageMapData;
  /** Array of test execution errors */
  errors?: TestResultError[];
  /** Browser console logs */
  browserLogs?: any[][];
}

interface TestResultError {
  message: string;
  name?: string;
  stack?: string;
  expected?: string;
  actual?: string;
}

try {
  const launcher = playwrightLauncher({ product: 'invalid' as ProductType });
} catch (error) {
  // Error: Invalid product: invalid. Valid product types: chromium, firefox, webkit
}