Assertions & Auto-Waiting

Auto-Retrying Assertions

When asserting dynamic game state (like waiting for a character to finish an animation, or a projectile to hit a target), the game engine needs time to simulate. Use await expect(locator).to... to tell Specter to auto-retry the condition until it passes or the timeout is reached.

// ❌ BAD: Manual sleeping is flaky and wastes CI time
await world.waitForTimeout(2000);
const state = await boss.hasGameplayTag('Status.Stunned');
expect(state).toBe(true);

// ✅ GOOD: Auto-retries instantly pass the moment the tag is applied
await expect(boss).toHaveGameplayTag('Status.Stunned');

By default, async matchers will wait up to 5000ms. You can override this globally in your config or per-assertion via { timeout: 10000 }.

Gameplay & State Matchers

Specter exposes specific matchers for querying Unreal Engine's native systems:

UI & Widget Matchers

When testing UMG user interfaces, Specter provides DOM-like assertions for native Slate widgets:

Material & Visual Matchers

Specter provides first-class assertions and inspection for Unreal Engine Materials across both 3D Actors/Meshes (Static Mesh, Skeletal Mesh) and 2D UMG Widgets (dynamic materials applied to Images, Borders, or nested in containers).

Example: UMG Material Assertions

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

test('Minion health bar updates material percent on damage', async ({ world }) => {
    const healthBar = world.specter.widget('WBP_MinionHealthBar');

    // Automatically inspects the Image nested inside the SizeBox:
    await expect(healthBar.locator('SizeBox_Health')).toHaveMaterialScalarParameter('Percent', 1.0, {
        operator: '==='
    });

    // Or target the Image directly:
    const healthImage = healthBar.locator('Image_Health');
    await expect(healthImage).toBeDynamicMaterial();
    await expect(healthImage).toHaveMaterialVectorParameter('HealthColor', '#00FF00');

    // Simulate damage and poll for scalar change:
    await expect(healthImage).toHaveMaterialScalarParameter('Percent', 0.5, {
        operator: '<=',
        timeout: 3000
    });
});

Pure Event-Driven GAS & expectAll() Atomic Verification

When verifying multi-actor combat exchanges (e.g. AoE damage, status effects, and knockbacks), sequential assertions introduce race conditions if the game state ticks or changes between checks. expectAll() evaluates multiple assertions concurrently and guarantees that all conditions pass atomically against a synchronized game state snapshot.

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

test('Atomic multi-actor verification on combo impact', async ({ world, steelActor, howitzerActor }) => {
  await howitzerActor.triggerAbility('Ability.Slot.Q');

  // Pure event-driven, atomic evaluation across multiple actors
  await expectAll([
    expect(steelActor).toHaveAttributeValue('HealthSet', 'Health', 2000),
    expect(steelActor).toHaveActiveGameplayEffect('GE_ShieldBuff', { stacks: 3, level: 1 }),
    expect(howitzerActor).toHaveGameplayTag('Cooldown.Ability.Q'),
  ]);
});

Multi-Assertion Matrix in In-Engine Trace Viewer

Unlike traditional assertions that fail on the very first broken condition and hide what happened to the other actors, Specter captures the entire multi-assertion batch and renders an interactive 2D Results Matrix Grid directly in Unreal Editor.

The matrix maps target actors along the Y-axis against assertions on the X-axis, displaying real-time cell diffs (e.g. ✓ 1100 → 1000 or ❌ 46.7cm) and an AggregateError breakdown. Learn more in the In-Engine Trace Viewer Multi-Assertion Matrix documentation.

Visual Assertions (toMatchScreenshot)

Logic assertions alone can't tell you if a character mesh is T-posing, a ground crack particle effect failed to spawn, or a material shader is rendering magenta. Specter integrates directly with Playwright's snapshot engine (__snapshots__) to capture rendered frames from Unreal Engine's active viewport and verify them against golden reference images.

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

test('Shield Slam ground fracture matches visual reference', async ({ world, steelActor }) => {
  await steelActor.triggerAbilityWithTarget('Ability.Slot.R', { x: 500, y: 0, z: 0 });

  // Wait for the impact visual and assert against golden snapshot
  await expect(world).toMatchScreenshot('steel_shield_slam_impact.png', {
    threshold: 0.15,           // 15% color perception threshold
    maxDiffPixelRatio: 0.02,   // Allow up to 2% differing pixels
    showUI: false,             // Ignore HUD/UMG overlays
    timeout: 2000,             // Retries until visual stabilizes
  });
});

Performance Budget Assertions (FPS & Memory Guardrails)

A newly added Niagara particle system or complex ability script might pass functional tests while tanking frame rate from 60 FPS to 15 FPS. Specter lets you enforce performance budgets in CI with granular assertions for minimum FPS, maximum frame time spikes, and memory ceilings.

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

test('Ultimate ability respects 60 FPS performance budget', async ({ world, steelActor }) => {
  await steelActor.triggerAbility('Ability.Slot.R');

  // Enforce continuous performance budget across a 5-second sample window
  await expect(world).toMaintainPerformanceBudget({
    minFps: 60,
    maxFrameTimeMs: 16.6,
    maxMemoryMb: 4096,
    sampleDurationSec: 5.0,
  });

  // Granular assertions for frame spikes & frame rate ceilings
  await expect(world).toHaveFPS(60, { operator: '>=' });
  await expect(world).toHaveFrameTimeBelow(16.6);
});

Generic Playwright Matchers

Because Specter is built on top of Playwright's test runner, you have full access to all standard Playwright matchers for checking simple JavaScript values, primitives, and objects. For the complete list of built-in runner matchers, check out the official Playwright Assertions documentation:

Negating Matchers

You can invert any async matcher by adding .not. It will automatically wait until the condition is false.

// Wait until the Loading Screen widget is removed or collapsed
await expect(loadingScreen).not.toBeVisible();

// Wait until the debuff wears off
await expect(player).not.toHaveGameplayTag('Status.Stunned');