Docs Menu

Introduction to Specter

Specter is an end-to-end automation testing framework for Unreal Engine 5, combining a native C++ Unreal Engine Plugin (SpecterEnginePlugin) with a powerful TypeScript/Playwright wrapper (@specter-automation/test).

How It Works

Unlike traditional C++ Gauntlet tests which run synchronously inside the game thread and require constant recompilation, Specter moves the test logic entirely to Node.js. Playwright spins up test worker processes that connect to your Unreal Engine game client over WebSockets (the SpecterTransport layer).

import { test, expect } from '@specter-automation/test';

test('Combat system initialization', async ({ world }) => {
  // 1. Load test arena map
  await world.loadMap('/Game/Maps/TestArena');
  
  // 2. Query player and assert initial state
  const player = world.actorByTag('Player1');
  await expect(player).toBeVisible();
  await expect(player).toHaveHealth(100);
});

The Bridge Architecture

Specter connects Node.js and Unreal Engine through three integrated systems:

  • Specter.uplugin: Registers as a standard UE5 Runtime module (installable as a Project Plugin or Engine Plugin). Listens on ws://127.0.0.1 and fires EngineReady when the map loads.
  • Playwright Fixtures: Specter injects custom fixtures (world, specter) directly into the test object, maintaining a dedicated socket connection per worker process.
  • Message Router: Dynamically resolves synchronous commands (with promises and timeouts) and unsolicited telemetry broadcasts.
Setup & Installation →