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.tsin your project. If you've ever used Playwright for web testing, this syntax will look immediately familiar:
import { test, expect } from '@specter-automation/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().
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".