Writing Your First Test

In this guide, we'll write a simple test for the standard Unreal Engine 5 Third Person Template. We'll connect to the game, make the mannequin jump, and verify that the jump actually worked.

The Test Script

Create a new file named first.spec.ts in your project. If you've ever used Playwright for web testing, this syntax will look incredibly familiar.

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

test('Mannequin can jump', async ({ world }) => {
  // 1. Query the player's character using its Blueprint class name
  const player = world.actor('BP_ThirdPersonCharacter');

  // 2. Simulate pressing the SpaceBar hardware key
  await player.pressKey('SpaceBar');

  // 3. Assert that the character actually transitioned to the falling state
  await expect(player).toBeFalling();
});

Step-by-Step Breakdown

1. The Actor Locator

Notice how we didn't have to manually connect to Unreal Engine? Specter's test runner automatically handles WebSocket connections, waits for the map to load, and injects the active world instance as a fixture into your test! The world.actor() method is Specter's equivalent of Playwright's page.locator(). By passing the Blueprint name ('BP_ThirdPersonCharacter'), Specter queries the engine's memory for the mannequin. This locator is lazy-evaluated and auto-retrying, so it won't fail immediately if the actor takes a few frames to spawn.

2 & 3. Action & Assertion

We simulate a raw hardware keystroke using player.pressKey('SpaceBar'). Since Specter understands Unreal Engine's internal states, we can directly assert the outcome using expect(player).toBeFalling() without needing to write brittle timeout loops or query the character movement component manually.

Automated Failure Screenshots

If a test fails or times out in your pipeline, Specter's built-in autoScreenshot fixture automatically captures a high-resolution PNG of the active Unreal Engine viewport and attaches it directly to your Playwright HTML Report under "Unreal Engine Viewport".