@reasonabletech/config-playwright 0.1.0

package/docs/guides/usage-guide.md

@@ -0,0 +1,111 @@
+# @reasonabletech/config-playwright Usage Guide
+
+This guide covers the canonical setup patterns for `@reasonabletech/config-playwright` in greenfield projects.
+
+## Installation
+
+```bash
+pnpm add -D @reasonabletech/config-playwright @playwright/test
+```
+
+## Quick Start
+
+```ts
+// playwright.config.ts
+import { createPlaywrightConfig } from "@reasonabletech/config-playwright";
+
+export default createPlaywrightConfig({
+  use: {
+    baseURL: "http://localhost:3000",
+  },
+});
+```
+
+## Core Config Factories
+
+### Standard Configuration
+
+```ts
+import { createPlaywrightConfig } from "@reasonabletech/config-playwright";
+
+export default createPlaywrightConfig();
+```
+
+### CI Configuration
+
+```ts
+import { createCIConfig } from "@reasonabletech/config-playwright";
+
+export default createCIConfig({
+  use: {
+    baseURL: "https://staging.example.com",
+  },
+});
+```
+
+### Single-App Presets
+
+```ts
+import {
+  createChromiumConfig,
+  createDesktopConfig,
+  createMobileConfig,
+} from "@reasonabletech/config-playwright/base";
+
+export default createDesktopConfig();
+```
+
+## Cross-App Workflows
+
+`createCrossAppConfig` selects environment settings from `process.env.TEST_ENV` (default: `development`).
+
+```ts
+import { createCrossAppConfig } from "@reasonabletech/config-playwright/cross-app";
+
+const environments = {
+  development: {
+    baseUrls: {
+      app: "http://localhost:3000",
+      admin: "http://localhost:3001",
+    },
+    services: {
+      useRealServices: false,
+      mockExternalAPIs: true,
+    },
+  },
+  staging: {
+    baseUrls: {
+      app: "https://staging.example.com",
+      admin: "https://admin-staging.example.com",
+    },
+    services: {
+      useRealServices: true,
+      mockExternalAPIs: false,
+    },
+  },
+} as const;
+
+export default createCrossAppConfig({ environments });
+```
+
+## Generated Outputs
+
+Default artifact locations:
+
+- `generated/playwright/reports`
+- `generated/playwright/results.json`
+- `generated/playwright/test-results`
+
+## Troubleshooting
+
+### Unknown test environment
+
+If `TEST_ENV` points to an environment key that is missing from your map, `createCrossAppConfig` throws. Ensure your environment map contains all expected deployment keys.
+
+### Local server startup
+
+The base config starts `pnpm dev` outside CI. Override `webServer` if your app uses a different startup command.
+
+## Related Documentation
+
+- [Package README](../../README.md)

package/package.json

@@ -0,0 +1,93 @@
+{
+  "name": "@reasonabletech/config-playwright",
+  "version": "0.1.0",
+  "description": "Shared Playwright configuration for E2E testing",
+  "keywords": [
+    "reasonabletech",
+    "config",
+    "typescript",
+    "playwright",
+    "e2e",
+    "browser-testing",
+    "test-automation"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./base": {
+      "types": "./dist/src/base.d.ts",
+      "import": "./dist/base.js"
+    },
+    "./cross-app": {
+      "types": "./dist/src/cross-app.d.ts",
+      "import": "./dist/cross-app.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs/**/*",
+    "src"
+  ],
+  "dependencies": {
+    "@axe-core/playwright": "^4.11.1",
+    "playwright-lighthouse": "^4.0.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "1.58.2",
+    "@types/node": "25.3.1",
+    "@vitest/coverage-v8": "4.0.18",
+    "eslint": "10.0.2",
+    "lighthouse": "13.0.3",
+    "tsup": "8.5.1",
+    "typescript": "5.9.3",
+    "vitest": "4.0.18",
+    "@reasonabletech/config-eslint": "0.1.0",
+    "@reasonabletech/config-tsup": "0.1.0",
+    "@reasonabletech/config-typescript": "0.1.0",
+    "@reasonabletech/config-vitest": "0.1.0"
+  },
+  "peerDependencies": {
+    "@playwright/test": ">=1.58.2 <2",
+    "lighthouse": ">= 10.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "license": "MIT",
+  "author": "Reasonable Tech Company",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ReasonableTech/core-utils.git",
+    "directory": "packages/config-playwright"
+  },
+  "bugs": {
+    "url": "https://github.com/ReasonableTech/core-utils/issues"
+  },
+  "homepage": "https://github.com/ReasonableTech/core-utils/tree/main/packages/config-playwright",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsup && tsc --emitDeclarationOnly -p tsconfig.build.json",
+    "clean": "rm -rf dist .turbo node_modules tsconfig.tsbuildinfo",
+    "dev": "tsc --watch",
+    "docs:coverage": "tsx ../../../scripts/analysis/check-doc-coverage.ts --html",
+    "lint": "eslint . --fix",
+    "lint:check": "eslint .",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "test:e2e": "vitest run tests/e2e",
+    "test:integration": "vitest run tests/integration",
+    "test:ui": "vitest --ui",
+    "test:unit": "vitest run tests/unit",
+    "test:watch": "vitest --watch",
+    "typecheck": "tsc --noEmit",
+    "verify:release": "pnpm typecheck && pnpm lint:check && pnpm test && pnpm build"
+  }
+}

package/src/base.ts

@@ -0,0 +1,124 @@
+/**
+ * Base browser configuration for Playwright testing
+ * @module @reasonabletech/config-playwright/base
+ */
+
+import { type PlaywrightTestConfig, devices } from "@playwright/test";
+import { baseConfig, type PlaywrightConfig } from "./index.js";
+
+// Empty readonly config for default parameters
+const EMPTY_CONFIG = {} as const satisfies PlaywrightConfig;
+
+/**
+ * Desktop-only browser configuration
+ */
+export const desktopConfig: PlaywrightTestConfig = {
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+    {
+      name: "firefox",
+      use: { ...devices["Desktop Firefox"] },
+    },
+    {
+      name: "webkit",
+      use: { ...devices["Desktop Safari"] },
+    },
+  ],
+};
+
+/**
+ * Mobile-only browser configuration
+ */
+export const mobileConfig: PlaywrightTestConfig = {
+  projects: [
+    {
+      name: "Mobile Chrome",
+      use: { ...devices["Pixel 5"] },
+    },
+    {
+      name: "Mobile Safari",
+      use: { ...devices["iPhone 12"] },
+    },
+  ],
+};
+
+/**
+ * Chromium-only configuration for faster development testing
+ */
+export const chromiumOnlyConfig: PlaywrightTestConfig = {
+  projects: [
+    {
+      name: "chromium",
+      use: { ...devices["Desktop Chrome"] },
+    },
+  ],
+};
+
+/**
+ * Creates a base Playwright configuration for single-app testing
+ * @param customConfig - Additional configuration options
+ * @returns A Playwright configuration for standard single-app testing
+ */
+export function createBaseConfig(
+  customConfig: PlaywrightConfig = EMPTY_CONFIG,
+): PlaywrightTestConfig {
+  return {
+    ...baseConfig,
+    ...customConfig,
+    use: {
+      ...baseConfig.use,
+      ...customConfig.use,
+      // Single-app specific settings
+      storageState: undefined, // No cross-app auth state by default
+    },
+    projects: customConfig.projects ?? baseConfig.projects,
+  };
+}
+
+/**
+ * Creates a desktop-only configuration for faster testing cycles
+ * @param customConfig - Additional configuration options
+ * @returns A Playwright configuration for desktop browsers only
+ */
+export function createDesktopConfig(
+  customConfig: PlaywrightConfig = EMPTY_CONFIG,
+): PlaywrightTestConfig {
+  return createBaseConfig({
+    ...customConfig,
+    projects: desktopConfig.projects,
+  });
+}
+
+/**
+ * Creates a mobile-only configuration for mobile-specific testing
+ * @param customConfig - Additional configuration options
+ * @returns A Playwright configuration for mobile browsers only
+ */
+export function createMobileConfig(
+  customConfig: PlaywrightConfig = EMPTY_CONFIG,
+): PlaywrightTestConfig {
+  return createBaseConfig({
+    ...customConfig,
+    projects: mobileConfig.projects,
+  });
+}
+
+/**
+ * Creates a Chromium-only configuration for development
+ * @param customConfig - Additional configuration options
+ * @returns A Playwright configuration for Chromium browser only
+ */
+export function createChromiumConfig(
+  customConfig: PlaywrightConfig = EMPTY_CONFIG,
+): PlaywrightTestConfig {
+  return createBaseConfig({
+    ...customConfig,
+    projects: chromiumOnlyConfig.projects,
+    workers: 1, // Single worker for development
+  });
+}
+
+export default createBaseConfig;

package/src/cross-app.ts

@@ -0,0 +1,299 @@
+/**
+ * Cross-app Playwright configuration for multi-frontend testing
+ * @module @reasonabletech/config-playwright/cross-app
+ */
+
+import { type PlaywrightTestConfig } from "@playwright/test";
+import {
+  baseConfig,
+  type PlaywrightConfig,
+  type TestEnvironmentConfig,
+} from "./index.js";
+
+// Empty readonly config for default parameters
+const EMPTY_CONFIG = {} as const satisfies PlaywrightConfig;
+
+/**
+ * Cross-app specific configuration options
+ */
+export const crossAppConfig: PlaywrightTestConfig = {
+  testDir: "./tests/acceptance/cross-app",
+  testMatch: "**/*.{test,spec}.{ts,js}",
+
+  use: {
+    // Extended timeout for cross-app navigation
+    actionTimeout: 10000,
+    navigationTimeout: 15000,
+
+    // Cross-domain configuration
+    extraHTTPHeaders: {
+      Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+    },
+
+    // Authentication state for cross-app flows
+    storageState: "tests/fixtures/auth/cross-app-authenticated.json",
+
+    // Enable video for complex cross-app debugging
+    video: "retain-on-failure",
+    trace: "retain-on-failure",
+  },
+};
+
+/**
+ * Accessibility testing configuration with axe-core
+ */
+export const accessibilityConfig: PlaywrightTestConfig = {
+  testDir: "./tests/acceptance/accessibility",
+  testMatch: "**/*.{test,spec}.{ts,js}",
+
+  use: {
+    // Slower execution for accessibility checks
+    actionTimeout: 15000,
+    navigationTimeout: 20000,
+  },
+};
+
+/**
+ * Performance testing configuration for Lighthouse integration
+ */
+export const performanceConfig: PlaywrightTestConfig = {
+  testDir: "./tests/acceptance/performance",
+  testMatch: "**/*.{test,spec}.{ts,js}",
+
+  // Sequential execution for accurate performance measurements
+  fullyParallel: false,
+  workers: 1,
+
+  use: {
+    // Extended timeouts for performance measurements
+    actionTimeout: 30000,
+    navigationTimeout: 45000,
+
+    // Minimal interference for accurate measurements
+    video: "off",
+    screenshot: "off",
+    trace: "off",
+  },
+};
+
+/**
+ * Options for creating a cross-domain authentication workflow configuration.
+ */
+export interface AuthWorkflowOptions {
+  /** The cookie domain (e.g. ".example.com"). */
+  domain: string;
+  /**
+   * List of subdomains where authentication cookies should persist
+   * (e.g. ["accounts.example.com", "app.example.com"]).
+   */
+  expectedPersistence: readonly string[];
+}
+
+/**
+ * Configuration shape returned by {@link createAuthWorkflowConfig}.
+ */
+export interface AuthWorkflowConfig {
+  /**
+   * Cookie settings used for cross-domain authentication.
+   */
+  readonly cookieConfig: {
+    readonly domain: string;
+    readonly secure: true;
+    readonly httpOnly: true;
+    readonly sameSite: "lax";
+  };
+  /**
+   * Subdomains where authentication should remain valid.
+   */
+  readonly expectedPersistence: readonly string[];
+}
+
+/**
+ * Creates a cross-domain authentication configuration for the given domain.
+ * @param options - Domain and persistence settings
+ * @returns An authentication workflow config object
+ */
+export function createAuthWorkflowConfig(
+  options: AuthWorkflowOptions,
+): AuthWorkflowConfig {
+  return {
+    cookieConfig: {
+      domain: options.domain,
+      secure: true,
+      httpOnly: true,
+      sameSite: "lax" as const,
+    },
+    expectedPersistence: options.expectedPersistence,
+  } as const;
+}
+
+/**
+ * Options for creating a cross-app Playwright configuration.
+ */
+export interface CrossAppConfigOptions {
+  /**
+   * Map of environment names to their configuration.
+   * The key used is determined by the `TEST_ENV` environment variable,
+   * falling back to `"development"`.
+   */
+  environments: Readonly<Record<string, TestEnvironmentConfig | undefined>>;
+  /** Additional Playwright configuration overrides. */
+  customConfig?: PlaywrightConfig;
+}
+
+/**
+ * Creates a Playwright configuration for cross-app workflows.
+ *
+ * Consumers must supply their own environment map so that base URLs are not
+ * hardcoded in this shared package.
+ * @param options - Environments map and optional custom config overrides
+ * @returns A Playwright configuration optimized for cross-app testing
+ */
+export function createCrossAppConfig(
+  options: CrossAppConfigOptions,
+): PlaywrightTestConfig {
+  const { environments, customConfig = EMPTY_CONFIG } = options;
+
+  const environment = process.env.TEST_ENV ?? "development";
+  const envConfig = environments[environment];
+
+  if (envConfig === undefined) {
+    throw new Error(
+      `Unknown test environment "${environment}". Available environments: ${Object.keys(environments).join(", ")}`,
+    );
+  }
+
+  const defaultBaseUrl = Object.values(envConfig.baseUrls).at(0);
+
+  if (defaultBaseUrl === undefined) {
+    throw new Error(
+      `Environment "${environment}" must define at least one base URL`,
+    );
+  }
+
+  return {
+    ...baseConfig,
+    ...crossAppConfig,
+    ...customConfig,
+    use: {
+      ...baseConfig.use,
+      ...crossAppConfig.use,
+      ...(customConfig as PlaywrightTestConfig).use,
+      // Set base URL to the first entry in baseUrls (typically the landing page)
+      baseURL: defaultBaseUrl,
+    },
+    projects: [
+      // Desktop browsers for cross-app flows
+      {
+        name: "cross-app-chromium",
+        testDir: "./tests/acceptance/cross-app",
+        use: {
+          ...baseConfig.projects?.[0]?.use,
+          // Cross-app specific browser settings
+          viewport: { width: 1920, height: 1080 },
+        },
+      },
+      {
+        name: "cross-app-firefox",
+        testDir: "./tests/acceptance/cross-app",
+        use: {
+          ...baseConfig.projects?.[1]?.use,
+          viewport: { width: 1920, height: 1080 },
+        },
+      },
+      {
+        name: "cross-app-webkit",
+        testDir: "./tests/acceptance/cross-app",
+        use: {
+          ...baseConfig.projects?.[2]?.use,
+          viewport: { width: 1920, height: 1080 },
+        },
+      },
+    ],
+  };
+}
+
+/**
+ * Creates a configuration for accessibility testing with axe-core
+ * @param customConfig - Additional configuration options
+ * @returns A Playwright configuration with accessibility testing setup
+ */
+export function createAccessibilityConfig(
+  customConfig: PlaywrightConfig = EMPTY_CONFIG,
+): PlaywrightTestConfig {
+  return {
+    ...baseConfig,
+    ...accessibilityConfig,
+    ...customConfig,
+    use: {
+      ...baseConfig.use,
+      ...accessibilityConfig.use,
+      ...(customConfig as PlaywrightTestConfig).use,
+    },
+    projects: [
+      {
+        name: "accessibility-chromium",
+        testDir: "./tests/acceptance/accessibility",
+        use: {
+          ...baseConfig.projects?.[0]?.use,
+          viewport: { width: 1280, height: 720 },
+        },
+      },
+    ],
+  };
+}
+
+/**
+ * Creates a configuration for performance testing with Lighthouse
+ * @param customConfig - Additional configuration options
+ * @returns A Playwright configuration with performance testing setup
+ */
+export function createPerformanceConfig(
+  customConfig: PlaywrightConfig = EMPTY_CONFIG,
+): PlaywrightTestConfig {
+  return {
+    ...baseConfig,
+    ...performanceConfig,
+    ...customConfig,
+    use: {
+      ...baseConfig.use,
+      ...performanceConfig.use,
+      ...(customConfig as PlaywrightTestConfig).use,
+    },
+    projects: [
+      {
+        name: "performance-chromium",
+        testDir: "./tests/acceptance/performance",
+        use: {
+          ...baseConfig.projects?.[0]?.use,
+          viewport: { width: 1920, height: 1080 },
+        },
+      },
+    ],
+  };
+}
+
+/**
+ * Creates a configuration optimized for authentication workflow testing
+ * @param options - Cross-app config options (environments map and optional custom config)
+ * @returns A Playwright configuration for auth workflow testing
+ */
+export function createAuthTestConfig(
+  options: CrossAppConfigOptions,
+): PlaywrightTestConfig {
+  const { environments, customConfig = EMPTY_CONFIG } = options;
+  return createCrossAppConfig({
+    environments,
+    customConfig: {
+      ...customConfig,
+      testDir: "./tests/acceptance/auth",
+      use: {
+        ...(customConfig as PlaywrightTestConfig).use,
+        // No pre-authenticated state for auth tests
+        storageState: undefined,
+      },
+    },
+  });
+}
+
+export default createCrossAppConfig;