Docs Menu

class: SpecterLocator

The base locator class. Locators are lazy-evaluated pipelines that do not execute until you await an action or assertion. Specter provides powerful filtering options to narrow down your queries in the hierarchy.

Strictness

Locators are strict. This means that all operations on locators that imply some target element will throw an exception if more than one element matches. For example, the following call throws if there are several buttons in the world:

await world.widget('Button').hardwareFocus();

locator.filter

Narrows existing locator matches by filtering on specific properties or text.
const activeEnemies = world.actorByTag('Enemy').filter({ hasProperty: { 'IsAlive': true } });

Arguments

NameTypeDescription
options ObjectFilter options containing hasProperty or hasText.
Returns:SpecterLocator

locator.and

Creates a locator that matches elements that satisfy both the original locator and the provided locator.
const healthPotionSlot = world.widget('InventorySlot').and(world.widgetByText('Health Potion'));

Arguments

NameTypeDescription
locator SpecterLocatorThe locator to intersect with.
Returns:SpecterLocator

locator.or

Creates a locator that matches elements that satisfy either the original locator or the provided locator.
const anyMinion = world.actor('BP_Minion_Melee').or(world.actor('BP_Minion_Range'));

Arguments

NameTypeDescription
locator SpecterLocatorThe locator to union with.
Returns:SpecterLocator

locator.all

Returns an array of locator pipelines pointing to their respective matches. This is useful when you need to iterate over multiple matched actors or widgets.
const minions = await world.actor('BP_Minion').all();
for (const minion of minions) {
  await expect(minion).toBeVisible();
}
Returns:Promise<SpecterLocator[]>

locator.first

Returns a locator that resolves to the first matching element in the queried set.
const firstMinion = world.actor('BP_Minion').first();
Returns:SpecterLocator

locator.last

Returns a locator that resolves to the last matching element in the queried set.
const lastMinion = world.actor('BP_Minion').last();
Returns:SpecterLocator

locator.nth

Returns a locator that resolves to the n-th matching element in the queried set. It's zero based, nth(0) selects the first element.
const thirdMinion = world.actor('BP_Minion').nth(2);

Arguments

NameTypeDescription
index numberThe zero-based index of the element to select.
Returns:SpecterLocator

locator.count

Returns the number of elements matching the locator pipeline in the engine.
const numMinions = await world.actor('BP_Minion').count();
console.log(numMinions);
Returns:Promise<number>

Engine Bindings & Execution

Low-level methods for directly binding to C++ delegates, retrieving property values, and executing UFunctions.

locator.waitForEvent

Natively waits for a C++ UObject delegate or Blueprint Multicast delegate to broadcast on this specific target. Supports domain-specific autocomplete, predicate filtering, and payload typing.
// Resolve only when damage is greater than 50
await bossActor.waitForEvent('OnTakeAnyDamage', (data) => data.damage > 50);

// You can add full IntelliSense for custom events via module augmentation!
// In your test or setup file:
declare module '@specter/test' {
    interface CustomActorEvents {
        OnShieldBroken: { currentShield: number; maxShield: number };
    }
}
const shieldInfo = await playerActor.waitForEvent('OnShieldBroken');
console.log(shieldInfo.maxShield); // Fully typed number

Arguments

NameTypeDescription
eventName stringThe name of the delegate to bind to.
optionsOrPredicate optionalFunction | ObjectA predicate function (payload) => boolean, or an options object { timeout, predicate }.
Returns:Promise<any>

locator.waitForExist

Polls the engine until the locator resolves to at least 1 object. Bypasses Strict Mode during the wait.
await world.widget('VictoryScreen').waitForExist();

Arguments

NameTypeDescription
timeout optionalnumberTimeout in milliseconds (Default: 5000).
Returns:Promise<void>

locator.client

Clones the locator and binds it to a different player/client's world connection, allowing you to query objects on a specific client's machine.
const player2Boss = bossLocator.client(world2);
await expect(player2Boss).toBeVisible();

Arguments

NameTypeDescription
world SpecterWorldThe target client's world fixture.
Returns:this

locator.callFunction

The Generic Bridge: Calls any C++ UFunction or Blueprint Callable function on the target object.
await player.callFunction("K2_DestroyActor");

Arguments

NameTypeDescription
functionName stringThe exact name of the Unreal Engine function.
args optionalobjectA key-value map of parameters to pass.
Returns:Promise<any>

locator.callFunctionWithReturn

Similar to callFunction, but specifically extracts and returns the 'ReturnValue' from the C++ response.
const distance = await player.callFunctionWithReturn("GetDistanceTo", { OtherActor: boss });

Arguments

NameTypeDescription
functionName stringThe exact name of the Unreal Engine function.
args optionalobjectA key-value map of parameters to pass.
Returns:Promise<any>

locator.getPropertyValue

Directly reads the value of a UPROPERTY on the target object.
const health = await player.getPropertyValue("CurrentHealth");

Arguments

NameTypeDescription
propertyName stringThe name of the UPROPERTY.
Returns:Promise<any>

locator.trackProperty

Dynamically tracks a UPROPERTY value. The C++ plugin will poll it and emit Timeline events whenever it changes.
await player.trackProperty("CurrentHealth");

Arguments

NameTypeDescription
propertyName stringThe name of the UPROPERTY.
Returns:Promise<void>

locator.trackAttribute

Dynamically tracks a GAS attribute. The C++ plugin will listen via delegate events.
await player.trackAttribute("HealthSet", "Health");

Arguments

NameTypeDescription
attributeSet stringThe Attribute Set class name.
attributeName stringThe specific attribute name.
Returns:Promise<void>