@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,352 @@
1
+ import WebSocket from 'ws';
2
+ import { ActorLocator, LocatorStep, SpecterLocator, WidgetLocator, WidgetRole, WidgetRoleOptions } from './locators';
3
+ import { WorldEventMap, EventPredicate, WaitForEventOptions } from './events';
4
+ import { SpecterKeyboard } from './specter-keyboard';
5
+ import { UnrealKey } from './specter-keys';
6
+ import { SpecterInputSequence } from './specter-input-sequence';
7
+ import { SpecterNetwork } from './specter-network';
8
+ export interface SpecterRegistry {
9
+ }
10
+ export interface SpecterFunctionRegistry {
11
+ }
12
+ export type RegisteredActorClasses = SpecterRegistry extends {
13
+ ActorClasses: infer T;
14
+ } ? T : string;
15
+ export type RegisteredComponentClasses = SpecterRegistry extends {
16
+ ComponentClasses: infer T;
17
+ } ? T : string;
18
+ export type RegisteredWidgetClasses = SpecterRegistry extends {
19
+ WidgetClasses: infer T;
20
+ } ? T : string;
21
+ export interface SpecterPayload {
22
+ messageId?: string;
23
+ command: string;
24
+ locatorPipeline?: LocatorStep[];
25
+ payload?: any;
26
+ }
27
+ export declare enum SpecterEventType {
28
+ StandardVariable = "StandardVariable",
29
+ GameplayAttribute = "GameplayAttribute",
30
+ AssertionFailure = "AssertionFailure",
31
+ GameEvent = "GameEvent",
32
+ GameplayTag = "GameplayTag"
33
+ }
34
+ export interface SpecterTimelineEvent {
35
+ timestamp: number;
36
+ eventName: string;
37
+ description: string;
38
+ eventType: SpecterEventType;
39
+ oldValue: string;
40
+ newValue: string;
41
+ instigator?: string;
42
+ effectCauser?: string;
43
+ gameplayEffect?: string;
44
+ ability?: string;
45
+ }
46
+ export interface Vector3 {
47
+ x: number;
48
+ y: number;
49
+ z: number;
50
+ }
51
+ export interface LinearColor {
52
+ R?: number;
53
+ G?: number;
54
+ B?: number;
55
+ A?: number;
56
+ }
57
+ export interface Color {
58
+ B?: number;
59
+ G?: number;
60
+ R?: number;
61
+ A?: number;
62
+ Hex?: string;
63
+ }
64
+ export interface Vector2D {
65
+ X?: number;
66
+ Y?: number;
67
+ }
68
+ export declare const VectorUtils: {
69
+ addOffset: (location: Vector3, direction: Vector3, offset: number) => Vector3;
70
+ };
71
+ export interface Rotator {
72
+ pitch: number;
73
+ yaw: number;
74
+ roll: number;
75
+ }
76
+ export interface Transform {
77
+ location: Vector3;
78
+ rotation?: Rotator;
79
+ scale?: Vector3;
80
+ }
81
+ export interface SpawnOptions {
82
+ tag?: string;
83
+ location?: Vector3;
84
+ rotation?: Rotator;
85
+ properties?: Record<string, any>;
86
+ spawnController?: boolean;
87
+ }
88
+ export interface ClickOptions {
89
+ strategy?: 'hardware' | 'broadcast' | 'function';
90
+ timeout?: number;
91
+ tolerance?: number;
92
+ waitForStable?: boolean;
93
+ }
94
+ export declare class SpecterTransport {
95
+ private static instance;
96
+ ws: WebSocket;
97
+ isConnected: boolean;
98
+ private url;
99
+ currentMap: string;
100
+ clientName?: string;
101
+ private pendingRequests;
102
+ private eventListeners;
103
+ static getInstance(url?: string): SpecterTransport;
104
+ get port(): string;
105
+ get friendlyPortTag(): string;
106
+ constructor(url?: string);
107
+ connect(timeoutMs?: number): Promise<void>;
108
+ private setupMessageRouter;
109
+ sendCommand(payload: SpecterPayload): Promise<any>;
110
+ disconnect(): void;
111
+ /**
112
+ * Registers a callback to fire when a specific unsolicited event arrives from the engine.
113
+ */
114
+ registerEventListener(eventKey: string, callback: (data: any) => void): void;
115
+ /**
116
+ * Cleans up an event listener.
117
+ */
118
+ removeEventListener(eventKey: string, callback: (data: any) => void): void;
119
+ }
120
+ export interface LoadMapOptions {
121
+ gameMode?: string;
122
+ listen?: boolean;
123
+ force?: boolean;
124
+ timeout?: number;
125
+ }
126
+ export declare class SpecterWorld {
127
+ private transport;
128
+ readonly keyboard: SpecterKeyboard;
129
+ readonly network: SpecterNetwork;
130
+ constructor(transport: SpecterTransport);
131
+ static connect(url?: string): Promise<SpecterWorld>;
132
+ /**
133
+ * Waits for the given `timeout` in milliseconds.
134
+ * Matches Playwright's `page.waitForTimeout()` method.
135
+ *
136
+ * @param timeout Milliseconds to wait.
137
+ */
138
+ waitForTimeout(timeout: number): Promise<void>;
139
+ /**
140
+ * Draws a 3D debug wireframe sphere in the world (e.g. For AOE radius, explosion bounds).
141
+ */
142
+ drawDebugSphere(options: {
143
+ center: Vector3;
144
+ radius?: number;
145
+ color?: string;
146
+ duration?: number;
147
+ segments?: number;
148
+ thickness?: number;
149
+ }): Promise<void>;
150
+ /**
151
+ * Draws a 3D debug bounding box in the world.
152
+ */
153
+ drawDebugBox(options: {
154
+ center: Vector3;
155
+ extent?: Vector3;
156
+ color?: string;
157
+ duration?: number;
158
+ thickness?: number;
159
+ }): Promise<void>;
160
+ /**
161
+ * Draws a 3D debug line trace between two points in the world.
162
+ */
163
+ drawDebugLine(options: {
164
+ start: Vector3;
165
+ end: Vector3;
166
+ color?: string;
167
+ duration?: number;
168
+ thickness?: number;
169
+ }): Promise<void>;
170
+ /**
171
+ * Advances the engine simulation tick-by-tick (frame stepping).
172
+ * @param frames Number of frames to step forward (default: 1).
173
+ */
174
+ stepFrame(frames?: number): Promise<void>;
175
+ /**
176
+ * Clears all active debug lines, boxes, spheres, trails, and Specter billboard text widgets.
177
+ */
178
+ clearDebugVisuals(): Promise<void>;
179
+ /**
180
+ * Waits for a global engine or game event, with optional predicate filtering.
181
+ */
182
+ waitForEvent<K extends keyof WorldEventMap>(eventName: K | (string & {}), optionsOrPredicate?: number | EventPredicate<K extends keyof WorldEventMap ? WorldEventMap[K] : any> | WaitForEventOptions<K extends keyof WorldEventMap ? WorldEventMap[K] : any>): Promise<K extends keyof WorldEventMap ? WorldEventMap[K] : any>;
183
+ joinHost(ipAddress: string, expectedMap?: string): Promise<void>;
184
+ /**
185
+ * Executes a global command on the Unreal Engine that is NOT tied to a specific locator or pipeline.
186
+ * Use this for global systems like Hardware Input, Level Loading, or Time Dilation.
187
+ * * @param commandName The engine command to execute
188
+ * @param payload The data payload to send
189
+ * @param context Optional string to distinguish identical commands in the UI (e.g., "Attacker" or "Player 1")
190
+ */
191
+ evaluate(commandName: string, payload?: any, context?: string, targetLocator?: string): Promise<any>;
192
+ setTimeDilation(speed: number): Promise<void>;
193
+ spawnActor(assetPath: string, options?: SpawnOptions): Promise<ActorLocator>;
194
+ actor<T extends RegisteredActorClasses | (string & {})>(selector: T): ActorLocator<T>;
195
+ actorByTag(tagName: string): ActorLocator;
196
+ widget<T extends RegisteredWidgetClasses | (string & {})>(className: T): WidgetLocator<T>;
197
+ getByWidget<T extends RegisteredWidgetClasses | (string & {})>(className: T): WidgetLocator<T>;
198
+ getByRole(role: WidgetRole | string, options?: WidgetRoleOptions): WidgetLocator;
199
+ getByText(text: string | RegExp, options?: {
200
+ exact?: boolean;
201
+ }): WidgetLocator;
202
+ getByPlayerId(playerId: number): ActorLocator;
203
+ subsystem(subsystemName: string): SpecterLocator;
204
+ /**
205
+ * Queries pure UObjects in memory (e.g., UGameInstance, USaveGame).
206
+ * Returns the base SpecterLocator, as these objects lack spatial or UI properties.
207
+ */
208
+ uobject(className: string): SpecterLocator;
209
+ console(commandString: string): Promise<void>;
210
+ /**
211
+ * Adjusts the global time dilation of the Unreal Engine.
212
+ * Useful for fast-forwarding through intro sequences or slowing down
213
+ * the game to validate frame-perfect physics/animations.
214
+ * * @param multiplier 1.0 is normal speed. > 1.0 is faster. < 1.0 is slower.
215
+ */
216
+ setTimeScale(multiplier: number): Promise<void>;
217
+ /**
218
+ * Captures a screenshot of the active Unreal Engine viewport.
219
+ * @param fileName The name of the saved file.
220
+ * @param showUI Whether to render the UMG/Slate UI layer into the screenshot (defaults to false).
221
+ * @returns The absolute file path where the image was saved on disk.
222
+ */
223
+ takeScreenshot(fileName: string, showUI?: boolean): Promise<string>;
224
+ /**
225
+ * Injects an analog axis value into the global Player Controller (e.g., thumbsticks, triggers).
226
+ * @param key Unreal Engine Key Name (e.g., "Gamepad_LeftY")
227
+ * @param value Analog float value (typically -1.0 to 1.0)
228
+ */
229
+ injectAxis(key: UnrealKey, value: number): Promise<void>;
230
+ /**
231
+ * Gets the current match state string from the server's AGameState or AGameMode (e.g. "InProgress", "WaitingToStart", "WaitingPostMatch").
232
+ */
233
+ getMatchState(): Promise<string>;
234
+ /**
235
+ * Gets the total number of connected players registered in AGameState.PlayerArray.
236
+ */
237
+ getPlayerCount(): Promise<number>;
238
+ /**
239
+ * Gets the current server world time in seconds (AGameState.GetServerWorldTimeSeconds()).
240
+ */
241
+ getServerWorldTime(): Promise<number>;
242
+ /**
243
+ * Pauses test execution until the GameState / GameMode enters the expected match state.
244
+ * @param expectedState Target match state (e.g. "InProgress", "WaitingPostMatch")
245
+ * @param options.timeout Max timeout in ms (default: 10000)
246
+ */
247
+ waitForMatchState(expectedState: string, options?: {
248
+ timeout?: number;
249
+ }): Promise<void>;
250
+ /**
251
+ * Gets all registered sub-levels and World Partition cells and their streaming state.
252
+ */
253
+ getStreamingLevels(): Promise<Array<{
254
+ levelName: string;
255
+ packagePath: string;
256
+ isLoaded: boolean;
257
+ isVisible: boolean;
258
+ isPending: boolean;
259
+ }>>;
260
+ /**
261
+ * Checks if a sub-level or World Partition cell is loaded into memory.
262
+ * @param levelName Level package name (e.g. "SubLevel_BossRoom")
263
+ */
264
+ isLevelLoaded(levelName: string): Promise<boolean>;
265
+ /**
266
+ * Checks if a sub-level or World Partition cell is visible in the viewport.
267
+ * @param levelName Level package name (e.g. "SubLevel_BossRoom")
268
+ */
269
+ isLevelVisible(levelName: string): Promise<boolean>;
270
+ /**
271
+ * Pauses test execution until the sub-level / World Partition cell is loaded.
272
+ * @param levelName Level package name (e.g. "SubLevel_BossRoom")
273
+ * @param options.timeout Max time in ms (default: 10000)
274
+ */
275
+ waitForLevelLoad(levelName: string, options?: {
276
+ timeout?: number;
277
+ }): Promise<void>;
278
+ /**
279
+ * Pauses test execution until the sub-level / World Partition cell is visible in the viewport.
280
+ * @param levelName Level package name (e.g. "SubLevel_BossRoom")
281
+ * @param options.timeout Max time in ms (default: 10000)
282
+ */
283
+ waitForLevelVisible(levelName: string, options?: {
284
+ timeout?: number;
285
+ }): Promise<void>;
286
+ /**
287
+ * Dynamically triggers level streaming for a sub-level.
288
+ * @param levelName Level package name (e.g. "SubLevel_BossRoom")
289
+ * @param makeVisible Whether to make the level visible upon loading (default: true)
290
+ */
291
+ loadLevelStream(levelName: string, makeVisible?: boolean): Promise<void>;
292
+ /**
293
+ * Opens a level (absolute travel) via UGameplayStatics::OpenLevel
294
+ */
295
+ loadLevel(levelName: string, options?: string): Promise<void>;
296
+ /**
297
+ * Plays a high-resolution input sequence generated by SpecterInputSequence.
298
+ * @param sequence The input pattern to play.
299
+ * @param options Additional playback options (e.g., looping).
300
+ */
301
+ playSequence(sequence: SpecterInputSequence, options?: {
302
+ loops?: number;
303
+ }): Promise<void>;
304
+ loadMap(mapName: string, options?: LoadMapOptions): Promise<void>;
305
+ waitForMapLoad(mapName: string, timeout?: number): Promise<void>;
306
+ get currentMap(): string;
307
+ getNetworkStatus(): Promise<{
308
+ netMode: 'Standalone' | 'Client' | 'ListenServer' | 'DedicatedServer';
309
+ map: string;
310
+ serverAddress: string;
311
+ }>;
312
+ cleanup(): Promise<void>;
313
+ /**
314
+ * Restores the primary PlayerController to its pre-possession state
315
+ * (re-possessing original pawn, restoring view target, and resetting control rotation).
316
+ */
317
+ restorePlayer(): Promise<void>;
318
+ waitForVariable(varName: string, expectedValue: string, timeout?: number): Promise<SpecterTimelineEvent>;
319
+ close(): Promise<void>;
320
+ /**
321
+ * Retrieves current engine performance metrics (FPS, Frame Time in ms, Used Memory in MB).
322
+ */
323
+ getPerformanceMetrics(): Promise<{
324
+ fps: number;
325
+ frameTimeMs: number;
326
+ memoryMb: number;
327
+ }>;
328
+ /**
329
+ * Checks if a navigation path exists between start and end vectors on the NavMesh.
330
+ */
331
+ isPointReachable(start: {
332
+ x: number;
333
+ y: number;
334
+ z: number;
335
+ }, end: {
336
+ x: number;
337
+ y: number;
338
+ z: number;
339
+ }): Promise<boolean>;
340
+ /**
341
+ * Checks if a Level Sequence cutscene is currently playing.
342
+ */
343
+ isSequencePlaying(sequenceName: string): Promise<boolean>;
344
+ /**
345
+ * Gets the playback position in seconds of a Level Sequence cutscene.
346
+ */
347
+ getSequencePlaybackPosition(sequenceName: string): Promise<number>;
348
+ /**
349
+ * Scrubs a Level Sequence cutscene to a specific playback position in seconds.
350
+ */
351
+ scrubSequence(sequenceName: string, positionSeconds: number): Promise<void>;
352
+ }