@specter-automation/test 1.0.107

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (47) hide show
  1. package/dist/core/component-registry.d.ts +12 -0
  2. package/dist/core/component-registry.js +25 -0
  3. package/dist/core/conditions/input-conditions.d.ts +81 -0
  4. package/dist/core/conditions/input-conditions.js +197 -0
  5. package/dist/core/events.d.ts +133 -0
  6. package/dist/core/events.js +6 -0
  7. package/dist/core/locators/actor-locator.d.ts +425 -0
  8. package/dist/core/locators/actor-locator.js +1006 -0
  9. package/dist/core/locators/ai-controller-locator.d.ts +6 -0
  10. package/dist/core/locators/ai-controller-locator.js +19 -0
  11. package/dist/core/locators/index.d.ts +6 -0
  12. package/dist/core/locators/index.js +22 -0
  13. package/dist/core/locators/movement-locator.d.ts +27 -0
  14. package/dist/core/locators/movement-locator.js +78 -0
  15. package/dist/core/locators/skeleton-locator.d.ts +13 -0
  16. package/dist/core/locators/skeleton-locator.js +35 -0
  17. package/dist/core/locators/specter-locator.d.ts +110 -0
  18. package/dist/core/locators/specter-locator.js +323 -0
  19. package/dist/core/locators/widget-locator.d.ts +104 -0
  20. package/dist/core/locators/widget-locator.js +297 -0
  21. package/dist/core/specter-client.d.ts +352 -0
  22. package/dist/core/specter-client.js +883 -0
  23. package/dist/core/specter-input-sequence.d.ts +96 -0
  24. package/dist/core/specter-input-sequence.js +180 -0
  25. package/dist/core/specter-keyboard.d.ts +21 -0
  26. package/dist/core/specter-keyboard.js +63 -0
  27. package/dist/core/specter-keys.d.ts +1 -0
  28. package/dist/core/specter-keys.js +2 -0
  29. package/dist/core/specter-network.d.ts +34 -0
  30. package/dist/core/specter-network.js +59 -0
  31. package/dist/core/specter-reporter.d.ts +23 -0
  32. package/dist/core/specter-reporter.js +403 -0
  33. package/dist/core/test-wrapper.d.ts +25 -0
  34. package/dist/core/test-wrapper.js +200 -0
  35. package/dist/index.d.ts +13 -0
  36. package/dist/index.js +29 -0
  37. package/dist/matchers/actor-matchers.d.ts +492 -0
  38. package/dist/matchers/actor-matchers.js +841 -0
  39. package/dist/matchers/gas-matchers.d.ts +198 -0
  40. package/dist/matchers/gas-matchers.js +539 -0
  41. package/dist/matchers/locator-matchers.d.ts +80 -0
  42. package/dist/matchers/locator-matchers.js +214 -0
  43. package/dist/matchers/material-matchers.d.ts +74 -0
  44. package/dist/matchers/material-matchers.js +295 -0
  45. package/dist/matchers/widget-matchers.d.ts +81 -0
  46. package/dist/matchers/widget-matchers.js +110 -0
  47. package/package.json +33 -0
@@ -0,0 +1,425 @@
1
+ import { ComponentLocatorMap } from "../component-registry";
2
+ import { SpecterLocator } from "../locators/specter-locator";
3
+ import { Rotator, Transform, Vector3, RegisteredComponentClasses, RegisteredWidgetClasses, SpecterWorld } from "../specter-client";
4
+ import { WidgetLocator, WidgetRole, WidgetRoleOptions } from "./widget-locator";
5
+ import { UnrealKey } from "../specter-keys";
6
+ import { ActorEventMap, EventPredicate, WaitForEventOptions } from "../events";
7
+ import { SpecterInputSequence } from "../specter-input-sequence";
8
+ import { InputConditionalOptions, SpecterCondition, ConditionFunction } from '../conditions/input-conditions';
9
+ export interface PossessAsPlayerOptions {
10
+ world?: SpecterWorld | {
11
+ world: SpecterWorld;
12
+ };
13
+ playerId?: number;
14
+ playerIndex?: number;
15
+ timeout?: number;
16
+ }
17
+ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
18
+ waitForEvent<K extends keyof ActorEventMap>(eventName: K | (string & {}), optionsOrPredicate?: number | EventPredicate<K extends keyof ActorEventMap ? ActorEventMap[K] : any> | WaitForEventOptions<K extends keyof ActorEventMap ? ActorEventMap[K] : any>): Promise<K extends keyof ActorEventMap ? ActorEventMap[K] : any>;
19
+ getLocation(): Promise<Vector3>;
20
+ /**
21
+ * Calculates the Euclidean distance from this actor to another actor or 3D point.
22
+ */
23
+ getDistanceTo(target: ActorLocator | Vector3): Promise<number>;
24
+ getForwardVector(): Promise<Vector3>;
25
+ setLocation(location: Vector3): Promise<void>;
26
+ setRotation(rotation: Rotator): Promise<void>;
27
+ setTransform(transform: Transform): Promise<void>;
28
+ highlight(stateInfo?: string): Promise<void>;
29
+ /**
30
+ * Draws a persistent 3D line trail tracking this actor's movement path.
31
+ */
32
+ drawTrail(options?: {
33
+ duration?: number;
34
+ color?: string;
35
+ thickness?: number;
36
+ segmentDuration?: number;
37
+ }): Promise<void>;
38
+ /**
39
+ * Draws a 3D directional arrow originating from this actor (facing or velocity vector).
40
+ */
41
+ drawDirectionArrow(options?: {
42
+ length?: number;
43
+ color?: string;
44
+ duration?: number;
45
+ arrowSize?: number;
46
+ thickness?: number;
47
+ useVelocity?: boolean;
48
+ }): Promise<void>;
49
+ /**
50
+ * Spawns a camera-facing 3D text panel floating above this actor displaying live GAS attributes and/or UProperties.
51
+ * Automatically updates in real time as stats change and tracks the actor's world position.
52
+ */
53
+ showStatsBillboard(options?: {
54
+ attributes?: string[];
55
+ properties?: string[];
56
+ duration?: number;
57
+ color?: string;
58
+ }): Promise<void>;
59
+ /**
60
+ * Updates or reconfigures the live-tracking 3D stats billboard for this actor.
61
+ */
62
+ updateStatsBillboard(options?: {
63
+ attributes?: string[];
64
+ properties?: string[];
65
+ duration?: number;
66
+ color?: string;
67
+ }): Promise<void>;
68
+ /**
69
+ * Explicitly destroys this actor in the Unreal Engine world.
70
+ */
71
+ destroy(): Promise<void>;
72
+ /**
73
+ * Checks if this actor has been destroyed or no longer exists in the world.
74
+ */
75
+ isDestroyed(): Promise<boolean>;
76
+ /**
77
+ * Pins this actor in the Unreal Engine world with a unique tag and registers it
78
+ * into the engine's O(1) fast-path hash map. Returns a new ActorLocator pinned directly to that tag.
79
+ * Ideal for pre-existing map actors before running high-frequency polling assertions (like location/transform).
80
+ */
81
+ pin(customTag?: string): Promise<ActorLocator>;
82
+ /**
83
+ * Clears all debug lines, boxes, spheres, trails, and billboard text widgets.
84
+ */
85
+ clearDebugVisuals(): Promise<void>;
86
+ checkVisibility(checkOnScreen?: boolean): Promise<boolean>;
87
+ /**
88
+ * Filters the current set of Actors down to only those possessed by the local human player.
89
+ * Perfect for filtering out AI Bots in Lyra!
90
+ */
91
+ isLocallyControlled(locallyControlled?: boolean): ActorLocator;
92
+ /**
93
+ * Filters the current set of Actors down to only those that are possessed by a controller.
94
+ * Pass false to get unpossessed pawns.
95
+ */
96
+ isPossessed(possessed?: boolean): ActorLocator;
97
+ /**
98
+ * Filters the current set of Actors down to only those that are possessed by a human player.
99
+ * Excludes AI controllers, bots, and dummy level actors.
100
+ */
101
+ isPlayerControlled(playerControlled?: boolean): ActorLocator;
102
+ getPlayerId(): Promise<number>;
103
+ /**
104
+ * Queries detailed controller possession state for this Pawn.
105
+ */
106
+ getControllerInfo(): Promise<{
107
+ isPossessed: boolean;
108
+ isPlayerControlled: boolean;
109
+ isLocallyControlled: boolean;
110
+ controllerClass: string;
111
+ controllerName: string;
112
+ }>;
113
+ /**
114
+ * Commands the PlayerController to possess this Pawn.
115
+ * If the Pawn is currently possessed by an AI Controller, it will cleanly unpossess it first.
116
+ *
117
+ * @param clientOrOptions Optional client SpecterWorld (or object with world / playerId / playerIndex)
118
+ * to command a specific client's PlayerController on the server. When provided, returns an ActorLocator
119
+ * bound to that client's world targeting the possessed actor.
120
+ */
121
+ possessAsPlayer(clientOrOptions?: SpecterWorld | {
122
+ world: SpecterWorld;
123
+ } | PossessAsPlayerOptions): Promise<ActorLocator<T>>;
124
+ /**
125
+ * Restores the PlayerController to its pre-possession state (original pawn, view target, and camera rotation).
126
+ */
127
+ unpossess(): Promise<void>;
128
+ getAttributeValue(attributeSet: string, attributeName: string): Promise<number>;
129
+ hasGameplayTag(tag: string): Promise<boolean>;
130
+ /**
131
+ * Waits for a Gameplay Tag to be added or removed.
132
+ */
133
+ waitForGameplayTag(tag: string, expectedState: boolean, timeout?: number): Promise<boolean>;
134
+ /**
135
+ * Waits for a Gameplay Attribute to reach a specific value, tracking its history.
136
+ */
137
+ waitForAttributeValue(attributeSet: string, attributeName: string, expectedValue: number, timeout?: number): Promise<{
138
+ finalValue: number;
139
+ history: number[];
140
+ }>;
141
+ /**
142
+ * Presses or releases a hardware key on this Actor's PlayerController, optionally holding until/while a condition is met.
143
+ */
144
+ pressKey(key: UnrealKey, eventType?: 'Pressed' | 'Released', options?: boolean | InputConditionalOptions): Promise<void>;
145
+ /**
146
+ * Holds a key down until/while a condition is satisfied on this Actor.
147
+ */
148
+ holdKey(key: UnrealKey, options: InputConditionalOptions): Promise<void>;
149
+ /**
150
+ * Injects an analog axis value for a specific key/input (e.g., thumbsticks, triggers).
151
+ * Supports continuous driving with condition options (until, while, when).
152
+ * @param key Unreal Engine Key Name (e.g., "Gamepad_LeftY")
153
+ * @param value Analog float value (typically -1.0 to 1.0)
154
+ * @param options Optional boolean for bHideStep or InputConditionalOptions
155
+ */
156
+ injectAxis(key: UnrealKey, value: number, options?: boolean | InputConditionalOptions): Promise<void>;
157
+ /**
158
+ * Triggers a UE5 Enhanced Input Action (UInputAction) on this Actor / PlayerController.
159
+ * Supports continuous driving with condition options (until, while, when).
160
+ * @param action Short action name (e.g. "IA_Jump"), or full asset path (e.g. "/Game/Input/Actions/IA_Jump").
161
+ * @param value Optional input magnitude (boolean, float number, or Vector {x, y, z}). Defaults to true (pressed).
162
+ * @param options Optional boolean for bHideStep or InputConditionalOptions
163
+ */
164
+ triggerInputAction(action: string, value?: boolean | number | {
165
+ x: number;
166
+ y?: number;
167
+ z?: number;
168
+ }, options?: boolean | InputConditionalOptions): Promise<void>;
169
+ /**
170
+ * Checks if a UE5 Input Mapping Context (UInputMappingContext) is actively applied to the player's Enhanced Input Subsystem.
171
+ * @param context Short context name (e.g. "IMC_Vehicle"), or full asset path.
172
+ */
173
+ hasInputMappingContext(context: string): Promise<boolean>;
174
+ /**
175
+ * Gets the current evaluation value of a UE5 Enhanced Input Action.
176
+ * @param action Short action name or asset path.
177
+ */
178
+ getInputActionValue(action: string): Promise<{
179
+ value: number;
180
+ boolValue: boolean;
181
+ vector: {
182
+ x: number;
183
+ y: number;
184
+ z: number;
185
+ };
186
+ }>;
187
+ /**
188
+ * Retrieves the connected PlayerState info for this Actor / PlayerController.
189
+ * Returns { score, playerId, playerName, ping }.
190
+ */
191
+ getPlayerStateInfo(): Promise<{
192
+ score: number;
193
+ playerId: number;
194
+ playerName: string;
195
+ ping: number;
196
+ }>;
197
+ /**
198
+ * Checks if this Actor's UNiagaraComponent is currently active and spawning particles.
199
+ */
200
+ isNiagaraActive(): Promise<boolean>;
201
+ /**
202
+ * Retrieves the asset name of the UNiagaraSystem attached to this Actor.
203
+ */
204
+ getNiagaraAsset(): Promise<string>;
205
+ /**
206
+ * Sets a user variable parameter on this Actor's UNiagaraComponent.
207
+ * @param variableName Parameter name (e.g. "User.SpawnRate", "User.Color")
208
+ * @param value Float, Int, Bool, or Vector value
209
+ */
210
+ setNiagaraVariable(variableName: string, value: number | boolean | {
211
+ x: number;
212
+ y?: number;
213
+ z?: number;
214
+ }): Promise<void>;
215
+ /**
216
+ * Checks if this Actor's UAudioComponent is currently playing audio.
217
+ */
218
+ isAudioPlaying(): Promise<boolean>;
219
+ /**
220
+ * Retrieves the attached USoundBase asset name (e.g. MetaSound or SoundCue).
221
+ */
222
+ getSoundAsset(): Promise<string>;
223
+ /**
224
+ * Gets the volume multiplier of this Actor's UAudioComponent.
225
+ */
226
+ getAudioVolume(): Promise<number>;
227
+ /**
228
+ * Plays the audio on this Actor's UAudioComponent.
229
+ */
230
+ playAudio(): Promise<void>;
231
+ /**
232
+ * Stops the audio on this Actor's UAudioComponent.
233
+ */
234
+ stopAudio(): Promise<void>;
235
+ /**
236
+ * Applies a physical impulse to this Actor's root/primitive component.
237
+ * @param impulse 3D impulse vector {x, y, z}
238
+ * @param options Target bone name or velocity change flag
239
+ */
240
+ addImpulse(impulse: {
241
+ x: number;
242
+ y: number;
243
+ z: number;
244
+ }, options?: {
245
+ boneName?: string;
246
+ velChange?: boolean;
247
+ }): Promise<void>;
248
+ /**
249
+ * Checks if physics simulation is currently active on this Actor.
250
+ */
251
+ isPhysicsSimulating(boneName?: string): Promise<boolean>;
252
+ /**
253
+ * Checks if this Actor's rigid body is currently asleep (sleeping physics body).
254
+ */
255
+ isPhysicsAsleep(boneName?: string): Promise<boolean>;
256
+ /**
257
+ * Retrieves linear/angular velocity and speed of this Actor's rigid body.
258
+ */
259
+ getPhysicsVelocity(boneName?: string): Promise<{
260
+ linearVelocity: {
261
+ x: number;
262
+ y: number;
263
+ z: number;
264
+ };
265
+ angularVelocity: {
266
+ x: number;
267
+ y: number;
268
+ z: number;
269
+ };
270
+ speed: number;
271
+ }>;
272
+ /**
273
+ * Gets the Field Of View (FOV) angle of this Actor's camera component / camera manager.
274
+ */
275
+ getCameraFOV(): Promise<number>;
276
+ /**
277
+ * Sets the Field Of View (FOV) angle for this Actor's camera.
278
+ */
279
+ setCameraFOV(fov: number): Promise<void>;
280
+ /**
281
+ * Checks if a camera shake is currently playing on the player's camera manager.
282
+ */
283
+ isCameraShaking(): Promise<boolean>;
284
+ /**
285
+ * Retrieves the current View Target Actor name of the active camera manager.
286
+ */
287
+ getCameraViewTarget(): Promise<string>;
288
+ /**
289
+ * Checks if this AI Pawn / Controller is actively moving along a NavMesh path.
290
+ */
291
+ isAINavigating(): Promise<boolean>;
292
+ /**
293
+ * Retrieves current NavMesh destination location of this AI Pawn / Controller.
294
+ */
295
+ getAINavGoal(): Promise<{
296
+ x: number;
297
+ y: number;
298
+ z: number;
299
+ }>;
300
+ /**
301
+ * Retrieves all Gameplay Tags owned by this Actor (requires IGameplayTagAssetInterface).
302
+ */
303
+ getGameplayTags(): Promise<string[]>;
304
+ /**
305
+ * Retrieves the Generic Team ID for this AI or Pawn (requires IGenericTeamAgentInterface).
306
+ */
307
+ getTeamId(): Promise<number>;
308
+ /**
309
+ * Retrieves the Team Attitude of this Actor towards another Actor (requires IGenericTeamAgentInterface).
310
+ */
311
+ getTeamAttitudeTowards(other: ActorLocator): Promise<'Friendly' | 'Hostile' | 'Neutral'>;
312
+ /**
313
+ * Plays a high-resolution input sequence generated by SpecterInputSequence on this specific Actor.
314
+ * @param sequence The input pattern to play.
315
+ * @param options Additional playback options (e.g., looping).
316
+ */
317
+ playSequence(sequence: SpecterInputSequence, options?: {
318
+ loops?: number;
319
+ until?: SpecterCondition | ConditionFunction;
320
+ while?: SpecterCondition | ConditionFunction;
321
+ timeout?: number;
322
+ }): Promise<void>;
323
+ /**
324
+ * Simulates typing a string of text sequentially by sending Pressed and Released events for each character.
325
+ * @param text The text to type.
326
+ * @param delayMs Optional delay between keystrokes in milliseconds.
327
+ */
328
+ type(text: string, delayMs?: number): Promise<void>;
329
+ triggerAbilityByTag(inputTag: string): Promise<void>;
330
+ triggerAbilityWithTarget(abilityTag: string, target: SpecterLocator | Vector3): Promise<void>;
331
+ applyGameplayEffect(effectClassPath: string, level?: number): Promise<void>;
332
+ hasActiveGameplayEffect(effectClassPath: string): Promise<boolean>;
333
+ hasGameplayEffect(effectClassPath: string): Promise<boolean>;
334
+ hasGameplayAbility(abilityClassPath: string): Promise<boolean>;
335
+ getAbilityCooldown(abilityClassPath: string): Promise<number>;
336
+ getGameplayEffectStackCount(effectClassPath: string): Promise<number>;
337
+ getGameplayEffectLevel(effectClassPath: string): Promise<number>;
338
+ getAttributeBaseValue(attributeSet: string, attributeName: string): Promise<number>;
339
+ isAbilityExecuting(abilityClassPath: string): Promise<boolean>;
340
+ cancelAbility(abilityClassPath: string): Promise<void>;
341
+ getGameplayTagCount(tag: string): Promise<number>;
342
+ hasAnyGameplayTags(tags: string[]): Promise<boolean>;
343
+ hasAllGameplayTags(tags: string[]): Promise<boolean>;
344
+ getVelocitySize(): Promise<number>;
345
+ isFalling(): Promise<boolean>;
346
+ isCrouching(): Promise<boolean>;
347
+ isFlying(): Promise<boolean>;
348
+ isSwimming(): Promise<boolean>;
349
+ isMovingOnGround(): Promise<boolean>;
350
+ getMovementMode(): Promise<{
351
+ movementMode: string;
352
+ isFalling: boolean;
353
+ isSwimming: boolean;
354
+ isFlying: boolean;
355
+ isMovingOnGround: boolean;
356
+ isCrouching: boolean;
357
+ }>;
358
+ /**
359
+ * Hybrid event waiter: Checks current state first (0ms if already falling),
360
+ * then attaches to native OnMovementModeChanged delegate.
361
+ */
362
+ waitForFalling(options?: {
363
+ timeout?: number;
364
+ }): Promise<void>;
365
+ /**
366
+ * Hybrid event waiter: Checks current state first (0ms if already on ground),
367
+ * then attaches to native OnLanded / OnMovementModeChanged delegate.
368
+ */
369
+ waitForLanded(options?: {
370
+ timeout?: number;
371
+ }): Promise<{
372
+ impactPoint?: {
373
+ x: number;
374
+ y: number;
375
+ z: number;
376
+ };
377
+ impactNormal?: {
378
+ x: number;
379
+ y: number;
380
+ z: number;
381
+ };
382
+ }>;
383
+ /**
384
+ * Hybrid event waiter: Checks current state first (0ms if already swimming),
385
+ * then attaches to native OnMovementModeChanged delegate.
386
+ */
387
+ waitForSwimming(options?: {
388
+ timeout?: number;
389
+ }): Promise<void>;
390
+ /**
391
+ * Hybrid event waiter: Checks current state first (0ms if already flying),
392
+ * then attaches to native OnMovementModeChanged delegate.
393
+ */
394
+ waitForFlying(options?: {
395
+ timeout?: number;
396
+ }): Promise<void>;
397
+ /**
398
+ * Hybrid event waiter for any arbitrary movement mode.
399
+ */
400
+ waitForMovementMode(mode: 'Walking' | 'Falling' | 'Swimming' | 'Flying' | 'NavWalking' | 'Custom' | 'None' | string, options?: {
401
+ timeout?: number;
402
+ }): Promise<void>;
403
+ /**
404
+ * Traverses down the hierarchy to find a specific component,
405
+ * returning a strongly-typed specialized locator.
406
+ */
407
+ getByComponent<K extends keyof ComponentLocatorMap | RegisteredComponentClasses | (string & {})>(componentType: K, options?: {
408
+ name?: string;
409
+ className?: string;
410
+ }): K extends keyof ComponentLocatorMap ? ComponentLocatorMap[K] : SpecterLocator;
411
+ /**
412
+ * Scopes locator to a UMG Widget hosted on this actor (via a UWidgetComponent or widget property).
413
+ * If no class name is provided, matches any widget hosted on this actor (e.g. floating health bar).
414
+ */
415
+ widget<W extends RegisteredWidgetClasses | (string & {}) = any>(widgetClassOrName?: W): WidgetLocator<W>;
416
+ /**
417
+ * Scopes locator to a UMG widget hosted on this actor via a specific UWidgetComponent by name.
418
+ */
419
+ widgetComponent(componentName?: string): WidgetLocator;
420
+ /**
421
+ * Finds a child widget on this actor by semantic role (button, image, text, slider, etc.)
422
+ * and optional accessible name.
423
+ */
424
+ getByRole(role: WidgetRole | string, options?: WidgetRoleOptions): WidgetLocator;
425
+ }