test: add headless Playwright E2E coverage for the standalone WebUI

- add fixture-based and emulator-backed Playwright suites
- add standalone server and emulator harness helpers
- support DATA_DIR isolation and dynamic emulator ports
- fix AD5X and legacy emulator compatibility issues
- document the new test workflow and runtime data path behavior

Author: GhostTypes

CHANGELOG.md

@@ -9,6 +9,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Playwright E2E testing framework with dual configuration:
+  - Fixture-based E2E tests (`e2e/`) for fast WebUI validation with a stub HTTP+WebSocket server
+  - Emulator-backed E2E tests (`e2e-emulator/`) for full lifecycle testing with `flashforge-emulator-v2` printer emulator
+  - Fixture specs: WebUI smoke tests (asset versioning, context switching) and authentication flow (login, token persistence, logout)
+  - Emulator specs: direct connection for all 5 printer models, network discovery flow, multi-printer context switching
+  - Test helpers: emulator harness, standalone server harness, lifecycle runner, scenario definitions, WebUI page object model
+  - `tsconfig.e2e.json` for E2E TypeScript type checking
+- Comprehensive npm test scripts for all test suites:
+  - `test:e2e`, `test:e2e:smoke`, `test:e2e:auth` for fixture E2E subsets
+  - `test:e2e:emulator`, `test:e2e:emulator:direct`, `test:e2e:emulator:discovery`, `test:e2e:emulator:multi` for emulator E2E subsets
+  - `test:e2e:all` for all Playwright suites and `test:all` for Jest + Playwright combined
+  - `test:e2e:install` for Chromium browser installation
+- `@playwright/test` (^1.58.2) as dev dependency for E2E browser automation
 - go2rtc-based camera streaming with:
   - bundled platform binaries in `resources/bin/`
   - `scripts/download-go2rtc.cjs` postinstall download flow
@@ -27,6 +40,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- `type-check` script now runs both `type-check:app` and `type-check:e2e` for full TypeScript validation
 - Camera streaming migrated from the legacy proxy/RTSP stack to go2rtc-managed per-context streams
 - Frontend camera playback now uses the bundled `video-rtc` player instead of the previous streaming path
 - Backend build pipeline now bundles `src/index.ts` before pkg packaging, while leaving runtime packages external for compatibility

CLAUDE.md

@@ -55,14 +55,43 @@ npm run format            # Preview Biome formatting changes
 npm run format:fix        # Apply Biome formatting changes
 npm run check             # Run Biome check (lint + format combined)
 npm run check:fix         # Auto-fix Biome check issues
-npm run type-check        # TypeScript type checking without emit
+npm run type-check        # TypeScript type checking (app + e2e)
+npm run type-check:app    # Type check main application only
+npm run type-check:e2e    # Type check e2e tests only (tsconfig.e2e.json)
 npm run docs:check        # Validate @fileoverview coverage in source files
 npm run docs:check:debug  # Debug fileoverview validation output
-npm test                  # Run Jest tests
-npm run test:watch        # Run tests in watch mode
-npm run test:coverage     # Run tests with coverage
-npm run test:verbose      # Run tests with verbose output
 npm run clean             # Remove dist directory
+npm run download:go2rtc   # Manually download go2rtc binary
+```
+
+### Testing
+```bash
+# Jest app tests
+npm test                            # Run all Jest tests
+npm run test:watch                  # Jest watch mode
+npm run test:coverage               # Jest with coverage
+npm run test:verbose                # Jest verbose output
+
+# Playwright fixture E2E (fast, stub server)
+npm run test:e2e:install            # Install Chromium for Playwright
+npm run test:e2e                    # Run all fixture E2E specs
+npm run test:e2e:smoke              # Smoke tests only
+npm run test:e2e:auth               # Auth tests only
+
+# Playwright emulator E2E (full server + emulator, workers=1)
+npm run test:e2e:emulator           # Run all emulator E2E specs
+npm run test:e2e:emulator:direct    # Direct connection spec
+npm run test:e2e:emulator:discovery # Discovery spec
+npm run test:e2e:emulator:multi    # Multi-printer spec
+
+# Combined
+npm run test:e2e:all                # All Playwright suites (fixture + emulator)
+npm run test:all                    # Everything (Jest + all Playwright)
+
+# Passthrough: append extra args after --
+# npm run test:e2e -- --grep "login"
+# npm run test:e2e:emulator:direct -- --grep "connect"
+# npm test -- --testPathPattern=Config
 ```
 
 ## Runtime Modes
@@ -147,12 +176,20 @@ src/index.ts                    # Entry point - initializes all singletons, conn
 - `DiscordNotificationService` - Discord webhook notifications for print events and periodic status updates
 - `SavedPrinterService` - Persistent printer storage in `data/printer_details.json`
 - `SpoolmanIntegrationService` / `SpoolmanService` - Spoolman connectivity and synchronization
+- `PrinterDiscoveryService` - Network printer discovery protocol
+- `ConnectionEstablishmentService` - Connection establishment flow orchestration
+- `ConnectionStateManager` - Tracks connection state per context
+- `EnvironmentService` - Package detection, path resolution, environment state
+- `PrinterPollingService` - Per-context status polling (used by `MultiContextPollingCoordinator`)
+- `AutoConnectService` - Auto-reconnect logic for saved printers
+- `PrinterDataTransformer` - Normalizes raw printer data to unified status format
+- `ThumbnailRequestQueue` - Queued thumbnail fetching for print files
 
 **WebUI**:
 - `WebUIManager` - Express HTTP server and static file serving
 - `WebSocketManager` - Real-time bidirectional communication with the frontend
 - `AuthManager` - Optional password authentication
-- API routes organized by feature (printer-control, job, camera, spoolman, theme, discovery, etc.)
+- API routes organized by feature (context, printer-control, printer-status, printer-detection, printer-management, job, camera, temperature, filtration, spoolman, theme, discovery)
 - Frontend uses GridStack for dashboard layout and the bundled `video-rtc` player for go2rtc-backed camera streaming
 
 ### Data Directory
@@ -224,7 +261,8 @@ Default config values live in `src/types/config.ts` and are loaded through `Conf
 - TypeScript 5.7
 - Biome 2 for linting and formatting
 - `esbuild` for backend bundling
-- `jest`, `ts-jest`, `supertest` for testing
+- `jest`, `ts-jest`, `supertest` for unit/integration testing
+- `@playwright/test` for E2E browser testing
 - `concurrently` for parallel build tasks
 - `nodemon` for dev server reloads
 - `tsx` for build scripts
@@ -335,15 +373,32 @@ class Service extends EventEmitter<EventMap> {
 
 ## Testing Notes
 
-Core functionality has been tested and verified:
+**Jest unit/integration tests** (`src/`):
+- ConfigManager, EnvironmentService, DiscordNotificationService, error utilities, WebUIManager integration
+
+**Playwright fixture E2E** (`e2e/`):
+- Fast headless tests against the built WebUI served by a stub HTTP+WebSocket server
+- Specs: smoke (asset versioning, context switching), auth (login, token persistence, logout)
+- Global setup runs `npm run build` before the suite
+- Config: `playwright.config.ts` (30s timeout, single worker)
+
+**Playwright emulator E2E** (`e2e-emulator/`):
+- Full integration tests using the standalone server and `flashforge-emulator-v2` printer emulator
+- Specs: direct connection (all 5 printer models), discovery flow, multi-printer context switching
+- Helpers: emulator harness, standalone server harness, lifecycle runner, scenario definitions, page object model
+- Config: `playwright.emulator.config.ts` (180s timeout, single worker)
+- Requires `flashforge-emulator-v2` cloned at `../flashforge-emulator-v2` (or `FF_EMULATOR_ROOT` env var)
+
+**Verified and tested**:
 - Multi-printer context switching
 - Spoolman integration
 - Platform-specific binary builds (Linux ARM, Linux x64, Windows, macOS)
 - WebUI authentication
 - Static file serving in packaged binaries
 - Discord notification service behavior
+- Direct connection, discovery, and multi-printer E2E workflows via Playwright
 
-Areas for continued testing:
+**Areas for continued testing**:
 - go2rtc binary download and startup across all supported platforms
 - Temperature anomaly detection edge cases
 - Wrapped build flows and packaging verification

README.md

@@ -145,7 +145,7 @@ Or if accessing from another device on your network:
 http://<server-ip>:3000
 ```
 
-**Default Login:** The default password is `changeme`. You should change this in `data/config.json` or via the `--webui-password` flag.
+**Default Login:** The default password is `changeme`. You should change this in the active config file (by default `data/config.json`, or the directory pointed to by `DATA_DIR`) or via the `--webui-password` flag.
 
 <div align="center">
   <h2>Command Line Options</h2>
@@ -168,7 +168,18 @@ http://<server-ip>:3000
   <h2>Configuration</h2>
 </div>
 
-The application automatically creates a configuration file at `data/config.json` on first run.
+The application automatically creates a configuration file in the active data directory on first run. By default this is `data/config.json`.
+
+By default, runtime data is stored in `./data` under the working directory. Set `DATA_DIR` to move configuration, logs, and saved printer state elsewhere.
+
+```bash
+# Linux/macOS
+DATA_DIR=/path/to/flashforge-data npm start
+
+# PowerShell
+$env:DATA_DIR = 'C:\FlashForgeWebUI\data'
+npm start
+```
 
 <div align="center">
 
@@ -183,6 +194,53 @@ The application automatically creates a configuration file at `data/config.json`
 
 </div>
 
+<div align="center">
+  <h2>Testing</h2>
+</div>
+
+```bash
+# Jest app tests
+npm test
+
+# TypeScript checks
+npm run type-check
+
+# Playwright browser E2E (fixture/stub server)
+npm run test:e2e:install
+npm run test:e2e
+npm run test:e2e:smoke
+npm run test:e2e:auth
+
+# Playwright emulator-backed E2E (headless, single worker)
+npm run test:e2e:emulator
+npm run test:e2e:emulator:direct
+npm run test:e2e:emulator:discovery
+npm run test:e2e:emulator:multi
+
+# Combined entry points
+npm run test:e2e:all
+npm run test:all
+```
+
+The fixture Playwright suite in `e2e/` runs against a built standalone WebUI with a local stub server.
+
+The emulator-backed suite in `e2e-emulator/` runs headless Chromium against the real standalone server plus `flashforge-emulator-v2`. Clone the emulator repo next to this one at `../flashforge-emulator-v2`, or point `FF_EMULATOR_ROOT` at it explicitly.
+
+```bash
+# Linux/macOS
+FF_EMULATOR_ROOT=../flashforge-emulator-v2 npm run test:e2e:emulator
+
+# PowerShell
+$env:FF_EMULATOR_ROOT = 'C:\Users\coper\Documents\GitHub\flashforge-emulator-v2'
+npm run test:e2e:emulator
+```
+
+All Playwright scripts support npm passthrough arguments:
+
+```bash
+npm run test:e2e:emulator:direct -- --grep "Adventurer 3"
+```
+
 <div align="center">
   <h2>Building from Source</h2>
 </div>
@@ -207,7 +265,7 @@ npm run build:mac-arm      # macOS ARM (Apple Silicon)
 | --- | --- |
 | **"Cannot GET /" or blank page when accessing WebUI** | If running from source: Make sure you ran `npm run build` before `npm start`<br>If using a pre-1.0.2 binary: Update to version 1.0.2 or later (fixes static file serving bug) |
 | **"Permission denied" when running binary** | Run `chmod +x flashforge-webui-linux-*` to make executable |
-| **Port already in use** | Change the port in `data/config.json` or use `--webui-port=3001` |
+| **Port already in use** | Change the port in the active config file (default `data/config.json`, or the directory pointed to by `DATA_DIR`) or use `--webui-port=3001` |
 | **Cannot connect to printer** | Ensure your printer is on the same network as the device running WebUI<br>Check that the printer's IP address is correct<br>For legacy printers, ensure TCP port 8899 is accessible |
 | **Selecting the correct binary for your platform** | Windows: `flashforge-webui-win-x64.exe`<br>macOS Intel: `flashforge-webui-macos-x64`<br>macOS Apple Silicon: `flashforge-webui-macos-arm64`<br>Linux x64: `flashforge-webui-linux-x64`<br>Raspberry Pi (64-bit OS): `flashforge-webui-linux-arm64`<br>Raspberry Pi (32-bit OS): `flashforge-webui-linux-armv7`<br>Check your architecture with `uname -m` (x86_64 = x64, aarch64 = ARM64, armv7l = ARMv7) |
 

e2e-emulator/direct.spec.ts

@@ -0,0 +1,65 @@
+/**
+ * @fileoverview Headless direct-connection emulator lifecycle coverage for the standalone WebUI.
+ */
+
+import { test } from '@playwright/test';
+import {
+  AD5X_MULTI_COLOR_MAPPINGS,
+  AD5X_SCENARIO,
+  ALL_LIFECYCLE_SCENARIOS,
+  createForceLegacySeededPrinter,
+  FORCE_LEGACY_DIRECT_SCENARIOS,
+} from './helpers/scenarios';
+import { runSingleModelFlow } from './helpers/lifecycle-runner';
+
+test.describe('standalone emulator direct flows', () => {
+  for (const scenario of ALL_LIFECYCLE_SCENARIOS) {
+    test(`direct ${scenario.label}: connect + lifecycle + controls`, async ({ page }) => {
+      test.slow();
+      await runSingleModelFlow({
+        page,
+        scenario,
+        connectionMode: 'direct',
+      });
+    });
+  }
+
+  test('direct AD5X: multi-color start + lifecycle + controls', async ({ page }) => {
+    test.slow();
+    await runSingleModelFlow({
+      page,
+      scenario: AD5X_SCENARIO,
+      connectionMode: 'direct',
+      fileName: 'e2e-ad5x-direct-multicolor.3mf',
+      seedFile: {
+        gcodeToolCnt: AD5X_MULTI_COLOR_MAPPINGS.length,
+        useMatlStation: true,
+        materialMappings: AD5X_MULTI_COLOR_MAPPINGS,
+      },
+      expectMaterialMatching: true,
+      materialSlotAssignments: AD5X_MULTI_COLOR_MAPPINGS.map((mapping) => ({
+        toolId: mapping.toolId,
+        slotId: mapping.slotId,
+      })),
+    });
+  });
+
+  for (const scenario of FORCE_LEGACY_DIRECT_SCENARIOS) {
+    test(`direct ${scenario.label}: reconnect saved + lifecycle + controls`, async ({ page }) => {
+      test.slow();
+      await runSingleModelFlow({
+        page,
+        scenario,
+        connectionMode: 'saved',
+        seededPrinters: [
+          createForceLegacySeededPrinter({
+            scenario,
+            ipAddress: '127.0.0.1',
+            commandPort: 8899,
+            httpPort: 8898,
+          }),
+        ],
+      });
+    });
+  }
+});

e2e-emulator/discovery.spec.ts

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Headless discovery-based emulator lifecycle coverage for the standalone WebUI.
+ */
+
+import { test } from '@playwright/test';
+import {
+  AD5X_MULTI_COLOR_MAPPINGS,
+  AD5X_SCENARIO,
+  ALL_LIFECYCLE_SCENARIOS,
+} from './helpers/scenarios';
+import { runSingleModelFlow } from './helpers/lifecycle-runner';
+
+test.describe('standalone emulator discovery flows', () => {
+  for (const scenario of ALL_LIFECYCLE_SCENARIOS) {
+    test(`discovery ${scenario.label}: connect + lifecycle + controls`, async ({ page }) => {
+      test.slow();
+      await runSingleModelFlow({
+        page,
+        scenario,
+        connectionMode: 'discovery',
+      });
+    });
+  }
+
+  test('discovery AD5X: multi-color start + lifecycle + controls', async ({ page }) => {
+    test.slow();
+    await runSingleModelFlow({
+      page,
+      scenario: AD5X_SCENARIO,
+      connectionMode: 'discovery',
+      fileName: 'e2e-ad5x-discovery-multicolor.3mf',
+      seedFile: {
+        gcodeToolCnt: AD5X_MULTI_COLOR_MAPPINGS.length,
+        useMatlStation: true,
+        materialMappings: AD5X_MULTI_COLOR_MAPPINGS,
+      },
+      expectMaterialMatching: true,
+      materialSlotAssignments: AD5X_MULTI_COLOR_MAPPINGS.map((mapping) => ({
+        toolId: mapping.toolId,
+        slotId: mapping.slotId,
+      })),
+    });
+  });
+});