LocatorAssertions

await expect(enemy).toHaveGameplayTag("Status.Stunned", { timeout: 10000 });

await expect(enemy).toHaveAnyGameplayTags(["Status.Stunned", "Status.Rooted"]);

await expect(enemy).toHaveAllGameplayTags(["Status.Stunned", "Status.Burning"]);

await expect(enemy).toHaveGameplayTagCount("Status.Poisoned", 3);

await expect(defender).toHaveAttributeValue("MMAttributeSet", "Health", 10);

await expect(defender).toHaveAttributeBaseValue("MMAttributeSet", "MaxHealth", 100);

await expect(defender).toHaveAttributeChange("MMAttributeSet", "Health", {
  delta: -attackerDamage,
  instigator: attacker,
  ability: "Default__GA_Marshmallow_Punch_C"
}, async () => {
  await attacker.triggerAbilityByTag("Ability.Attack.Melee");
});

await expect(hero).toHaveGameplayEffect("/Game/Effects/GE_Shield");

await expect(hero).toHaveGameplayEffectStackCount("/Game/Effects/GE_Bleed", 5);

await expect(hero).toHaveGameplayEffectLevel("/Game/Effects/GE_Buff", 2);

// Assert an instant damage effect was applied exactly once by Howitzer
await expect(steelActor).toHaveAppliedGameplayEffect(
  "GE_Howitzer_BasicAttack",
  { count: 1, instigator: howitzerActor }
);

// Assert a buff/debuff effect is applied without strict count
await expect(steelActor).toHaveAppliedGameplayEffect("GE_SlowDebuff");

// Assert an effect was NOT applied
await expect(steelActor).not.toHaveAppliedGameplayEffect("GE_Stun");

// Assert an active shield buff with exact 3 stacks
await expect(steelActor).toHaveActiveGameplayEffect("GE_ShieldBuff", {
  stacks: 3,
  level: 1,
});

await expect(hero).toHaveGameplayAbility("/Game/Abilities/GA_Dash");

// Assert Howitzer's basic attack activates exactly once
await expect(howitzerActor).toHaveActivatedAbility(
  "Ability.Slot.BasicAttack.SingleShot",
  { times: 1 }
);

// Inline trigger action with exact count verification
await expect(howitzerActor).toHaveActivatedAbility(
  "Ability.Slot.Q",
  { times: 1 },
  async () => {
    await howitzerActor.pressKey("Q");
  }
);

await expect(hero).toBeExecutingAbility("/Game/Abilities/GA_Ultimate");

await expect(hero).toHaveAbilityCooldown("/Game/Abilities/GA_Dash", { operator: "<=", expectedValue: 0 });

import { expectAll } from "@specter-automation/test";

// Atomically verify state across multiple actors and systems
await expectAll([
  expect(steelActor).toHaveAttributeValue("HealthSet", "Health", 2000),
  expect(steelActor).toHaveActiveGameplayEffect("GE_ShieldBuff"),
  expect(howitzerActor).toHaveGameplayTag("Cooldown.Ability.Q"),
]);

await expect(enemy).toBeFalling();

await expect(player).toBeCrouching();

await expect(drone).toBeFlying();

// Pass if speed >= 600 cm/s
await expect(playerActor).toHaveVelocity(600);

// Pass if specific bone is moving with high velocity
await expect(playerActor).toHaveVelocity(1200, { boneName: 'weapon_r', operator: '>=' });

await expect(enemy).toBeWithinDistanceOf(world.actor('Player'), 200);

await expect(turret).toBeFacing(world.actor('Player'));

const startPos = await enemy.getLocation();
await world.console('cheat knockback');

await expect(enemy).toHaveMovedFurtherThan(startPos, 500, { timeout: 8000 });

await expect(enemy).toHaveLocation({ x: 100, y: 200, z: 0 }, 10.0, { timeout: 8000 });

await expect(heroSkeleton).toBePlayingMontage("/Game/Animations/AM_Attack");

await expect(heroSkeleton).toHaveMontageSection("Recovery");

await expect(aiCon).toBeRunningBehaviorTree("/Game/AI/BT_Zombie");

await expect(aiCon).toHaveBlackboardValue("TargetActor", world.actor('Player'));

await expect(aiCon).toHaveLineOfSightTo(world.actor('Player'));

// Assert AI is navigating towards the player
await expect(aiPawn).toBeAINavigating();

// Assert AI has stopped navigating
await expect(aiPawn).not.toBeAINavigating({ timeout: 10000 });

await expect(player).toHaveCameraFOV(90, { tolerance: 1.0 });

// Assert camera is shaking after explosion
await expect(player).toBeCameraShaking();

// Assert camera is NOT shaking after it subsides
await expect(player).not.toBeCameraShaking();

await expect(player).toHaveCameraViewTarget('BP_PlayerCharacter');

// Assert minion is possessed
await expect(minion).toBePossessed();

// Assert vehicle is currently unpossessed / empty
await expect(emptyCar).not.toBePossessed();

// Assert hero is driven by a real player
await expect(playerMarshmallow).toBePlayerControlled();

// Assert minion is driven by AI, not a human player
await expect(aiMinion).not.toBePlayerControlled();

// Assert pawn belongs to the active client connection
await expect(localPlayer).toBeLocallyControlled();

// Assert attached to specific AI controller class
await expect(boss).toHaveController("BP_BossAIController");

// Assert attached to player controller
await expect(player).toHaveController("BP_MarshmallowPlayerController");

// Verify any controller is attached
await expect(pawn).toHaveController();

await expect(player).toHaveTeamId(0);
await expect(spectator).not.toHaveTeamId(1);

await expect(player).toBeHostileTowards(enemy);
await expect(player).not.toBeHostileTowards(ally);

await expect(world.actor('BP_Minion')).toHaveCount(5);

await expect(world.actor('BP_Minion_Range')).toBeVisible({ onScreen: true, timeout: 10000 });

await expect(enemy).toBeInViewport();

// Assert actor is destroyed after lethal damage
await expect(enemyKeep).toBeDestroyed();

// Assert actor has NOT been destroyed
await expect(player).not.toBeDestroyed();

await expect(explosionEffect).toBeNiagaraActive();

await expect(fireVFX).toHaveNiagaraAsset("NS_Fire_Loop");

await expect(footstepAudio).toBeAudioPlaying();

await expect(bgmAudio).toHaveSoundAsset("SoundWave_BossTheme");

await expect(deadEnemy).toBePhysicsSimulating({ boneName: "pelvis" });

await expect(crate).toBePhysicsAsleep();

await expect(player).toHaveInputMappingContext("IMC_DefaultPlayer");

await expect(player).toHaveInputActionValue("IA_Sprint", true);

await expect(player).toHavePlayerScore(100, { operator: ">=" });

const modal = world.widget("ConfirmPurchaseModal");
await expect(modal).toBeVisible();

const submitBtn = world.widget("SubmitButton");
await expect(submitBtn).toBeEnabled();

const title = world.widget("HeaderTitle");
await expect(title).toHaveText("Main Menu");

const subtitle = world.widget("WBP_Modal").getChild("SubtitleText");
await expect(subtitle).toContainText("cannot be undone");

const usernameInput = world.widget("WBP_Login").getChild("UsernameInput");
await expect(usernameInput).toHaveValue("Player1");

await expect(healthImage).toHaveMaterialScalarParameter('Percent', 0.5, { operator: '<=' });

await expect(shield).toHaveMaterialVectorParameter('GlowColor', '#00FFCC');

await expect(terrain).toHaveMaterial('M_Snow');

await expect(healthBarImage).toBeDynamicMaterial();

await expect(emblem).toHaveMaterialTextureParameter('Icon', 'T_Skull');

// Wait for 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
});

// Enforce a strict 60 FPS performance budget during ultimate VFX
await expect(world).toMaintainPerformanceBudget({
  minFps: 60,
  maxFrameTimeMs: 16.6,
  maxMemoryMb: 4096,
  sampleDurationSec: 5.0,
});

// Assert viewport maintains at least 60 FPS
await expect(world).toHaveFPS(60, { operator: ">=" });

// Catch hitches and frame spikes exceeding 16.6ms
await expect(world).toHaveFrameTimeBelow(16.6);