@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.
- package/dist/core/component-registry.d.ts +12 -0
- package/dist/core/component-registry.js +25 -0
- package/dist/core/conditions/input-conditions.d.ts +81 -0
- package/dist/core/conditions/input-conditions.js +197 -0
- package/dist/core/events.d.ts +133 -0
- package/dist/core/events.js +6 -0
- package/dist/core/locators/actor-locator.d.ts +425 -0
- package/dist/core/locators/actor-locator.js +1006 -0
- package/dist/core/locators/ai-controller-locator.d.ts +6 -0
- package/dist/core/locators/ai-controller-locator.js +19 -0
- package/dist/core/locators/index.d.ts +6 -0
- package/dist/core/locators/index.js +22 -0
- package/dist/core/locators/movement-locator.d.ts +27 -0
- package/dist/core/locators/movement-locator.js +78 -0
- package/dist/core/locators/skeleton-locator.d.ts +13 -0
- package/dist/core/locators/skeleton-locator.js +35 -0
- package/dist/core/locators/specter-locator.d.ts +110 -0
- package/dist/core/locators/specter-locator.js +323 -0
- package/dist/core/locators/widget-locator.d.ts +104 -0
- package/dist/core/locators/widget-locator.js +297 -0
- package/dist/core/specter-client.d.ts +352 -0
- package/dist/core/specter-client.js +883 -0
- package/dist/core/specter-input-sequence.d.ts +96 -0
- package/dist/core/specter-input-sequence.js +180 -0
- package/dist/core/specter-keyboard.d.ts +21 -0
- package/dist/core/specter-keyboard.js +63 -0
- package/dist/core/specter-keys.d.ts +1 -0
- package/dist/core/specter-keys.js +2 -0
- package/dist/core/specter-network.d.ts +34 -0
- package/dist/core/specter-network.js +59 -0
- package/dist/core/specter-reporter.d.ts +23 -0
- package/dist/core/specter-reporter.js +403 -0
- package/dist/core/test-wrapper.d.ts +25 -0
- package/dist/core/test-wrapper.js +200 -0
- package/dist/index.d.ts +13 -0
- package/dist/index.js +29 -0
- package/dist/matchers/actor-matchers.d.ts +492 -0
- package/dist/matchers/actor-matchers.js +841 -0
- package/dist/matchers/gas-matchers.d.ts +198 -0
- package/dist/matchers/gas-matchers.js +539 -0
- package/dist/matchers/locator-matchers.d.ts +80 -0
- package/dist/matchers/locator-matchers.js +214 -0
- package/dist/matchers/material-matchers.d.ts +74 -0
- package/dist/matchers/material-matchers.js +295 -0
- package/dist/matchers/widget-matchers.d.ts +81 -0
- package/dist/matchers/widget-matchers.js +110 -0
- package/package.json +33 -0
|
@@ -0,0 +1,883 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
3
|
+
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
4
|
+
};
|
|
5
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
|
+
exports.SpecterWorld = exports.SpecterTransport = exports.VectorUtils = exports.SpecterEventType = void 0;
|
|
7
|
+
const ws_1 = __importDefault(require("ws"));
|
|
8
|
+
const crypto_1 = __importDefault(require("crypto"));
|
|
9
|
+
const locators_1 = require("./locators");
|
|
10
|
+
const test_1 = __importDefault(require("@playwright/test"));
|
|
11
|
+
const specter_keyboard_1 = require("./specter-keyboard");
|
|
12
|
+
const specter_network_1 = require("./specter-network");
|
|
13
|
+
var SpecterEventType;
|
|
14
|
+
(function (SpecterEventType) {
|
|
15
|
+
SpecterEventType["StandardVariable"] = "StandardVariable";
|
|
16
|
+
SpecterEventType["GameplayAttribute"] = "GameplayAttribute";
|
|
17
|
+
SpecterEventType["AssertionFailure"] = "AssertionFailure";
|
|
18
|
+
SpecterEventType["GameEvent"] = "GameEvent";
|
|
19
|
+
SpecterEventType["GameplayTag"] = "GameplayTag";
|
|
20
|
+
})(SpecterEventType || (exports.SpecterEventType = SpecterEventType = {}));
|
|
21
|
+
exports.VectorUtils = {
|
|
22
|
+
addOffset: (location, direction, offset) => {
|
|
23
|
+
return {
|
|
24
|
+
x: location.x + (direction.x * offset),
|
|
25
|
+
y: location.y + (direction.y * offset),
|
|
26
|
+
z: location.z + (direction.z * offset)
|
|
27
|
+
};
|
|
28
|
+
}
|
|
29
|
+
};
|
|
30
|
+
// ==========================================
|
|
31
|
+
// THE TRANSPORT LAYER (Hidden from End-User)
|
|
32
|
+
// ==========================================
|
|
33
|
+
class SpecterTransport {
|
|
34
|
+
static instance = null;
|
|
35
|
+
ws;
|
|
36
|
+
isConnected = false;
|
|
37
|
+
url;
|
|
38
|
+
currentMap = 'Unknown';
|
|
39
|
+
clientName;
|
|
40
|
+
// The Enterprise Fix: Routing responses to the correct Promise
|
|
41
|
+
pendingRequests = new Map();
|
|
42
|
+
eventListeners = new Map();
|
|
43
|
+
static getInstance(url = 'ws://127.0.0.1:8080') {
|
|
44
|
+
if (!SpecterTransport.instance) {
|
|
45
|
+
SpecterTransport.instance = new SpecterTransport(url);
|
|
46
|
+
}
|
|
47
|
+
return SpecterTransport.instance;
|
|
48
|
+
}
|
|
49
|
+
get port() {
|
|
50
|
+
try {
|
|
51
|
+
return new URL(this.url).port;
|
|
52
|
+
}
|
|
53
|
+
catch {
|
|
54
|
+
return '';
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
get friendlyPortTag() {
|
|
58
|
+
if (this.clientName) {
|
|
59
|
+
return `[${this.clientName}] `;
|
|
60
|
+
}
|
|
61
|
+
const portStr = this.port;
|
|
62
|
+
if (!portStr)
|
|
63
|
+
return '';
|
|
64
|
+
const portNum = parseInt(portStr, 10);
|
|
65
|
+
if (portNum === 8080) {
|
|
66
|
+
return '[Server] ';
|
|
67
|
+
}
|
|
68
|
+
if (portNum > 8080 && portNum <= 8100) {
|
|
69
|
+
return `[Client ${portNum - 8080}] `;
|
|
70
|
+
}
|
|
71
|
+
return `[Client ${portStr}] `;
|
|
72
|
+
}
|
|
73
|
+
constructor(url = 'ws://127.0.0.1:8080') {
|
|
74
|
+
this.url = url;
|
|
75
|
+
this.ws = new ws_1.default(url);
|
|
76
|
+
this.ws.on('error', () => { }); // Prevent unhandled exception if closed while connecting
|
|
77
|
+
this.ws.on('close', () => { this.isConnected = false; });
|
|
78
|
+
if (!SpecterTransport.instance) {
|
|
79
|
+
SpecterTransport.instance = this;
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
async connect(timeoutMs = 20000) {
|
|
83
|
+
if (this.isConnected) {
|
|
84
|
+
return;
|
|
85
|
+
}
|
|
86
|
+
const startTime = Date.now();
|
|
87
|
+
let lastError = null;
|
|
88
|
+
while (Date.now() - startTime < timeoutMs) {
|
|
89
|
+
try {
|
|
90
|
+
await new Promise((resolve, reject) => {
|
|
91
|
+
if (this.ws.readyState === ws_1.default.CONNECTING || this.ws.readyState === ws_1.default.OPEN) {
|
|
92
|
+
try {
|
|
93
|
+
this.ws.on('error', () => { }); // Suppress close errors
|
|
94
|
+
this.ws.close();
|
|
95
|
+
}
|
|
96
|
+
catch (e) { }
|
|
97
|
+
}
|
|
98
|
+
this.ws = new ws_1.default(this.url);
|
|
99
|
+
this.ws.on('error', () => { });
|
|
100
|
+
this.ws.on('close', () => { this.isConnected = false; });
|
|
101
|
+
const handshakeListener = (data) => {
|
|
102
|
+
const msgString = data.toString('utf-8');
|
|
103
|
+
try {
|
|
104
|
+
const payload = JSON.parse(msgString);
|
|
105
|
+
if (payload.event === 'EngineReady') {
|
|
106
|
+
console.log(`[SPECTER] Unreal Engine Ready! Map: ${payload.map}`);
|
|
107
|
+
this.currentMap = payload.map || 'Unknown';
|
|
108
|
+
this.isConnected = true;
|
|
109
|
+
this.ws.off('message', handshakeListener);
|
|
110
|
+
this.setupMessageRouter();
|
|
111
|
+
resolve();
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
catch (err) {
|
|
115
|
+
// Ignore non-JSON
|
|
116
|
+
}
|
|
117
|
+
};
|
|
118
|
+
this.ws.on('message', handshakeListener);
|
|
119
|
+
this.ws.once('error', (err) => {
|
|
120
|
+
reject(err);
|
|
121
|
+
});
|
|
122
|
+
});
|
|
123
|
+
return;
|
|
124
|
+
}
|
|
125
|
+
catch (err) {
|
|
126
|
+
lastError = err;
|
|
127
|
+
await new Promise(resolve => setTimeout(resolve, 1000));
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
throw new Error(`Specter Connection Timeout: Could not connect to Unreal Engine on URL ${this.url} after ${timeoutMs}ms. Details: ${lastError?.message}`);
|
|
131
|
+
}
|
|
132
|
+
// The core router that prevents race conditions and parses JSON automatically
|
|
133
|
+
setupMessageRouter() {
|
|
134
|
+
this.ws.on('message', (data) => {
|
|
135
|
+
const responseStr = data.toString('utf-8');
|
|
136
|
+
let responseObj;
|
|
137
|
+
try {
|
|
138
|
+
responseObj = JSON.parse(responseStr);
|
|
139
|
+
}
|
|
140
|
+
catch (e) {
|
|
141
|
+
console.error("[Specter] Failed to parse engine response:", responseStr);
|
|
142
|
+
return;
|
|
143
|
+
}
|
|
144
|
+
// 1. IS THIS AN UNSOLICITED EVENT?
|
|
145
|
+
// We look for the exact "type: event" flag broadcasted by C++
|
|
146
|
+
if (responseObj.type === 'event') {
|
|
147
|
+
if (responseObj.eventName === 'MapLoaded' && responseObj.data && responseObj.data.map) {
|
|
148
|
+
this.currentMap = responseObj.data.map;
|
|
149
|
+
}
|
|
150
|
+
const eventKey = `${responseObj.locatorId}_${responseObj.eventName}`;
|
|
151
|
+
// If a test script is currently waiting for this event...
|
|
152
|
+
if (this.eventListeners.has(eventKey)) {
|
|
153
|
+
const callbacks = this.eventListeners.get(eventKey);
|
|
154
|
+
// Fire every callback waiting for it
|
|
155
|
+
// Callers are responsible for unregistering themselves if they only wanted it once!
|
|
156
|
+
[...callbacks].forEach(cb => cb(responseObj.data));
|
|
157
|
+
}
|
|
158
|
+
return; // Early exit! Do not process this as a standard command.
|
|
159
|
+
}
|
|
160
|
+
// 2. IS THIS A STANDARD COMMAND RESPONSE?
|
|
161
|
+
if (responseObj.messageId && this.pendingRequests.has(responseObj.messageId)) {
|
|
162
|
+
const promiseHandlers = this.pendingRequests.get(responseObj.messageId);
|
|
163
|
+
if (responseObj.status === 'error') {
|
|
164
|
+
const errMsg = responseObj.error.startsWith('Specter C++ Error:')
|
|
165
|
+
? responseObj.error
|
|
166
|
+
: `Specter C++ Error: ${responseObj.error}`;
|
|
167
|
+
const error = new Error(errMsg);
|
|
168
|
+
if (promiseHandlers.callSiteStack) {
|
|
169
|
+
error.stack = `${error.name}: ${error.message}\n` + promiseHandlers.callSiteStack.split('\n').slice(2).join('\n');
|
|
170
|
+
}
|
|
171
|
+
promiseHandlers.reject(error);
|
|
172
|
+
}
|
|
173
|
+
else {
|
|
174
|
+
promiseHandlers.resolve(responseObj);
|
|
175
|
+
}
|
|
176
|
+
this.pendingRequests.delete(responseObj.messageId);
|
|
177
|
+
}
|
|
178
|
+
else {
|
|
179
|
+
// Catch-all for anything else the engine might spit out
|
|
180
|
+
console.log("[SPECTER] Unhandled Engine Broadcast:", responseObj);
|
|
181
|
+
}
|
|
182
|
+
});
|
|
183
|
+
}
|
|
184
|
+
async sendCommand(payload) {
|
|
185
|
+
if (!this.isConnected) {
|
|
186
|
+
await this.connect();
|
|
187
|
+
}
|
|
188
|
+
if (!payload.messageId) {
|
|
189
|
+
payload.messageId = crypto_1.default.randomUUID();
|
|
190
|
+
}
|
|
191
|
+
const callSiteError = new Error();
|
|
192
|
+
return new Promise((resolve, reject) => {
|
|
193
|
+
// Register the promise BEFORE sending the payload
|
|
194
|
+
this.pendingRequests.set(payload.messageId, { resolve, reject, callSiteStack: callSiteError.stack });
|
|
195
|
+
// 5-second timeout safety net
|
|
196
|
+
setTimeout(() => {
|
|
197
|
+
if (this.pendingRequests.has(payload.messageId)) {
|
|
198
|
+
const handlers = this.pendingRequests.get(payload.messageId);
|
|
199
|
+
this.pendingRequests.delete(payload.messageId);
|
|
200
|
+
const error = new Error(`Specter Timeout: No response for command [${payload.command}] after 5000ms.`);
|
|
201
|
+
if (handlers.callSiteStack) {
|
|
202
|
+
error.stack = `${error.name}: ${error.message}\n` + handlers.callSiteStack.split('\n').slice(2).join('\n');
|
|
203
|
+
}
|
|
204
|
+
reject(error);
|
|
205
|
+
}
|
|
206
|
+
}, 5000);
|
|
207
|
+
this.ws.send(JSON.stringify(payload));
|
|
208
|
+
});
|
|
209
|
+
}
|
|
210
|
+
disconnect() {
|
|
211
|
+
if (this.ws.readyState === ws_1.default.OPEN) {
|
|
212
|
+
this.ws.close();
|
|
213
|
+
this.isConnected = false;
|
|
214
|
+
}
|
|
215
|
+
}
|
|
216
|
+
// ==========================================
|
|
217
|
+
// EVENT LISTENER REGISTRATION
|
|
218
|
+
// ==========================================
|
|
219
|
+
/**
|
|
220
|
+
* Registers a callback to fire when a specific unsolicited event arrives from the engine.
|
|
221
|
+
*/
|
|
222
|
+
registerEventListener(eventKey, callback) {
|
|
223
|
+
if (!this.eventListeners.has(eventKey)) {
|
|
224
|
+
this.eventListeners.set(eventKey, []);
|
|
225
|
+
}
|
|
226
|
+
this.eventListeners.get(eventKey).push(callback);
|
|
227
|
+
}
|
|
228
|
+
/**
|
|
229
|
+
* Cleans up an event listener.
|
|
230
|
+
*/
|
|
231
|
+
removeEventListener(eventKey, callback) {
|
|
232
|
+
if (this.eventListeners.has(eventKey)) {
|
|
233
|
+
const callbacks = this.eventListeners.get(eventKey);
|
|
234
|
+
const index = callbacks.indexOf(callback);
|
|
235
|
+
if (index !== -1) {
|
|
236
|
+
callbacks.splice(index, 1);
|
|
237
|
+
}
|
|
238
|
+
if (callbacks.length === 0) {
|
|
239
|
+
this.eventListeners.delete(eventKey);
|
|
240
|
+
}
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
exports.SpecterTransport = SpecterTransport;
|
|
245
|
+
class SpecterWorld {
|
|
246
|
+
transport;
|
|
247
|
+
keyboard;
|
|
248
|
+
network;
|
|
249
|
+
constructor(transport) {
|
|
250
|
+
this.transport = transport;
|
|
251
|
+
this.keyboard = new specter_keyboard_1.SpecterKeyboard(this);
|
|
252
|
+
this.network = new specter_network_1.SpecterNetwork(this);
|
|
253
|
+
}
|
|
254
|
+
// Factory method matches the Playwright style: await SpecterPage.connect()
|
|
255
|
+
static async connect(url) {
|
|
256
|
+
const transport = new SpecterTransport(url);
|
|
257
|
+
// Wait for the engine to handshake
|
|
258
|
+
await transport.connect();
|
|
259
|
+
// Inject the connected transport into the new world
|
|
260
|
+
return new SpecterWorld(transport);
|
|
261
|
+
}
|
|
262
|
+
/**
|
|
263
|
+
* Waits for the given `timeout` in milliseconds.
|
|
264
|
+
* Matches Playwright's `page.waitForTimeout()` method.
|
|
265
|
+
*
|
|
266
|
+
* @param timeout Milliseconds to wait.
|
|
267
|
+
*/
|
|
268
|
+
async waitForTimeout(timeout) {
|
|
269
|
+
const portTag = this.transport.friendlyPortTag;
|
|
270
|
+
const stepTitle = `${portTag}waitForTimeout (${timeout}ms)`;
|
|
271
|
+
return await test_1.default.step(stepTitle, async () => {
|
|
272
|
+
await new Promise(resolve => setTimeout(resolve, timeout));
|
|
273
|
+
});
|
|
274
|
+
}
|
|
275
|
+
/**
|
|
276
|
+
* Draws a 3D debug wireframe sphere in the world (e.g. For AOE radius, explosion bounds).
|
|
277
|
+
*/
|
|
278
|
+
async drawDebugSphere(options) {
|
|
279
|
+
await this.evaluate("DrawDebugSphere", {
|
|
280
|
+
center: options.center,
|
|
281
|
+
radius: options.radius ?? 100,
|
|
282
|
+
color: options.color ?? "cyan",
|
|
283
|
+
duration: options.duration ?? 3,
|
|
284
|
+
segments: options.segments ?? 16,
|
|
285
|
+
thickness: options.thickness ?? 2
|
|
286
|
+
});
|
|
287
|
+
}
|
|
288
|
+
/**
|
|
289
|
+
* Draws a 3D debug bounding box in the world.
|
|
290
|
+
*/
|
|
291
|
+
async drawDebugBox(options) {
|
|
292
|
+
await this.evaluate("DrawDebugBox", {
|
|
293
|
+
center: options.center,
|
|
294
|
+
extent: options.extent ?? { x: 50, y: 50, z: 50 },
|
|
295
|
+
color: options.color ?? "cyan",
|
|
296
|
+
duration: options.duration ?? 3,
|
|
297
|
+
thickness: options.thickness ?? 2
|
|
298
|
+
});
|
|
299
|
+
}
|
|
300
|
+
/**
|
|
301
|
+
* Draws a 3D debug line trace between two points in the world.
|
|
302
|
+
*/
|
|
303
|
+
async drawDebugLine(options) {
|
|
304
|
+
await this.evaluate("DrawDebugLine", {
|
|
305
|
+
start: options.start,
|
|
306
|
+
end: options.end,
|
|
307
|
+
color: options.color ?? "yellow",
|
|
308
|
+
duration: options.duration ?? 3,
|
|
309
|
+
thickness: options.thickness ?? 2
|
|
310
|
+
});
|
|
311
|
+
}
|
|
312
|
+
/**
|
|
313
|
+
* Advances the engine simulation tick-by-tick (frame stepping).
|
|
314
|
+
* @param frames Number of frames to step forward (default: 1).
|
|
315
|
+
*/
|
|
316
|
+
async stepFrame(frames = 1) {
|
|
317
|
+
await this.evaluate("StepFrame", { frames });
|
|
318
|
+
}
|
|
319
|
+
/**
|
|
320
|
+
* Clears all active debug lines, boxes, spheres, trails, and Specter billboard text widgets.
|
|
321
|
+
*/
|
|
322
|
+
async clearDebugVisuals() {
|
|
323
|
+
await this.evaluate("ClearDebugVisuals", {});
|
|
324
|
+
}
|
|
325
|
+
/**
|
|
326
|
+
* Waits for a global engine or game event, with optional predicate filtering.
|
|
327
|
+
*/
|
|
328
|
+
async waitForEvent(eventName, optionsOrPredicate) {
|
|
329
|
+
let timeoutMs = 5000;
|
|
330
|
+
let predicate;
|
|
331
|
+
if (typeof optionsOrPredicate === 'number') {
|
|
332
|
+
timeoutMs = optionsOrPredicate;
|
|
333
|
+
}
|
|
334
|
+
else if (typeof optionsOrPredicate === 'function') {
|
|
335
|
+
predicate = optionsOrPredicate;
|
|
336
|
+
}
|
|
337
|
+
else if (optionsOrPredicate && typeof optionsOrPredicate === 'object') {
|
|
338
|
+
timeoutMs = optionsOrPredicate.timeout ?? 5000;
|
|
339
|
+
predicate = optionsOrPredicate.predicate;
|
|
340
|
+
}
|
|
341
|
+
const eventKey = `GLOBAL_${String(eventName)}`;
|
|
342
|
+
return await new Promise((resolve, reject) => {
|
|
343
|
+
let timer;
|
|
344
|
+
const listener = (data) => {
|
|
345
|
+
if (predicate && !predicate(data)) {
|
|
346
|
+
return;
|
|
347
|
+
}
|
|
348
|
+
clearTimeout(timer);
|
|
349
|
+
this.transport.removeEventListener(eventKey, listener);
|
|
350
|
+
resolve(data);
|
|
351
|
+
};
|
|
352
|
+
timer = setTimeout(() => {
|
|
353
|
+
this.transport.removeEventListener(eventKey, listener);
|
|
354
|
+
reject(new Error(`Specter Timeout: World Event [${String(eventName)}] did not fire matching criteria within ${timeoutMs}ms.`));
|
|
355
|
+
}, timeoutMs);
|
|
356
|
+
this.transport.registerEventListener(eventKey, listener);
|
|
357
|
+
this.transport.sendCommand({
|
|
358
|
+
command: 'ListenForGlobalEvent',
|
|
359
|
+
payload: { eventName: String(eventName) }
|
|
360
|
+
}).catch(() => { });
|
|
361
|
+
});
|
|
362
|
+
}
|
|
363
|
+
async joinHost(ipAddress, expectedMap) {
|
|
364
|
+
const status = await this.getNetworkStatus();
|
|
365
|
+
if (status.netMode === 'Client' && status.serverAddress.includes(ipAddress)) {
|
|
366
|
+
const mapShort = expectedMap ? (expectedMap.split('/').pop()?.split('.')[0] || expectedMap) : '';
|
|
367
|
+
if (!expectedMap || status.map.includes(mapShort)) {
|
|
368
|
+
console.log(`[SPECTER] Already connected to host at ${ipAddress} on map ${status.map}. Skipping joinHost.`);
|
|
369
|
+
return;
|
|
370
|
+
}
|
|
371
|
+
}
|
|
372
|
+
let mapLoaded = false;
|
|
373
|
+
const cleanups = [];
|
|
374
|
+
const travelPromise = expectedMap ? new Promise((resolve) => {
|
|
375
|
+
const expectedMapShort = expectedMap.split('/').pop()?.split('.')[0] || expectedMap;
|
|
376
|
+
const listener = (data) => {
|
|
377
|
+
const loadedMap = data?.map || '';
|
|
378
|
+
if (loadedMap === expectedMapShort || loadedMap.includes(expectedMapShort)) {
|
|
379
|
+
mapLoaded = true;
|
|
380
|
+
resolve();
|
|
381
|
+
}
|
|
382
|
+
};
|
|
383
|
+
this.transport.registerEventListener('GLOBAL_MapLoaded', listener);
|
|
384
|
+
cleanups.push(() => {
|
|
385
|
+
this.transport.removeEventListener('GLOBAL_MapLoaded', listener);
|
|
386
|
+
});
|
|
387
|
+
}) : Promise.resolve();
|
|
388
|
+
const disconnectPromise = expectedMap ? new Promise((resolve) => {
|
|
389
|
+
const closeListener = () => {
|
|
390
|
+
resolve();
|
|
391
|
+
};
|
|
392
|
+
this.transport.ws.once('close', closeListener);
|
|
393
|
+
cleanups.push(() => {
|
|
394
|
+
this.transport.ws.off('close', closeListener);
|
|
395
|
+
});
|
|
396
|
+
}) : Promise.resolve();
|
|
397
|
+
try {
|
|
398
|
+
await this.evaluate("JoinHost", { ip: ipAddress });
|
|
399
|
+
if (expectedMap) {
|
|
400
|
+
await Promise.race([travelPromise, disconnectPromise]);
|
|
401
|
+
if (!mapLoaded) {
|
|
402
|
+
console.log(`[SPECTER] Connection dropped during joinHost. Waiting for reconnection...`);
|
|
403
|
+
this.transport.isConnected = false;
|
|
404
|
+
await this.transport.connect();
|
|
405
|
+
console.log(`[SPECTER] Reconnected successfully after joinHost.`);
|
|
406
|
+
}
|
|
407
|
+
}
|
|
408
|
+
}
|
|
409
|
+
finally {
|
|
410
|
+
cleanups.forEach(c => c());
|
|
411
|
+
}
|
|
412
|
+
}
|
|
413
|
+
/**
|
|
414
|
+
* Executes a global command on the Unreal Engine that is NOT tied to a specific locator or pipeline.
|
|
415
|
+
* Use this for global systems like Hardware Input, Level Loading, or Time Dilation.
|
|
416
|
+
* * @param commandName The engine command to execute
|
|
417
|
+
* @param payload The data payload to send
|
|
418
|
+
* @param context Optional string to distinguish identical commands in the UI (e.g., "Attacker" or "Player 1")
|
|
419
|
+
*/
|
|
420
|
+
async evaluate(commandName, payload = {}, context, targetLocator) {
|
|
421
|
+
const formattedCommand = commandName.charAt(0).toLowerCase() + commandName.slice(1);
|
|
422
|
+
const portTag = this.transport.friendlyPortTag;
|
|
423
|
+
// Format the title based on whether context was provided
|
|
424
|
+
let stepTitle = context
|
|
425
|
+
? `${portTag}${formattedCommand} [${context}]`
|
|
426
|
+
: `${portTag}${formattedCommand}`;
|
|
427
|
+
if (targetLocator) {
|
|
428
|
+
stepTitle += ` @ ${targetLocator}`;
|
|
429
|
+
}
|
|
430
|
+
return await test_1.default.step(stepTitle, async () => {
|
|
431
|
+
const response = await this.transport.sendCommand({
|
|
432
|
+
command: commandName,
|
|
433
|
+
payload: payload
|
|
434
|
+
});
|
|
435
|
+
return response;
|
|
436
|
+
});
|
|
437
|
+
}
|
|
438
|
+
// Example: Speed up the game to bypass long animations during tests
|
|
439
|
+
async setTimeDilation(speed) {
|
|
440
|
+
return this.setTimeScale(speed);
|
|
441
|
+
}
|
|
442
|
+
async spawnActor(assetPath, options) {
|
|
443
|
+
// Generate a unique tag if the user didn't provide one
|
|
444
|
+
const uniqueId = crypto_1.default.randomBytes(4).toString('hex');
|
|
445
|
+
const tag = options?.tag || `Spawned_${uniqueId}`;
|
|
446
|
+
const location = options?.location || { x: 0, y: 0, z: 0 };
|
|
447
|
+
const rotation = options?.rotation || { pitch: 0, yaw: 0, roll: 0 };
|
|
448
|
+
const assetName = assetPath.split('/').pop()?.split('.')[0];
|
|
449
|
+
await this.evaluate("SpawnActor", { assetPath, tag, location, rotation }, assetName, tag);
|
|
450
|
+
return this.actorByTag(tag);
|
|
451
|
+
}
|
|
452
|
+
// ==========================================
|
|
453
|
+
// THE ACTOR ENTRY POINTS
|
|
454
|
+
// ==========================================
|
|
455
|
+
// Replaces 'getByClass'. Defaults to finding an Actor by class, or supports selector prefixes like 'Tag:Tagname' or 'tag=Tagname'.
|
|
456
|
+
actor(selector) {
|
|
457
|
+
if (typeof selector === 'string' && /^(tag[:=]|Tag[:=])/i.test(selector)) {
|
|
458
|
+
const tagName = selector.replace(/^(tag[:=]|Tag[:=])/i, '');
|
|
459
|
+
return this.actorByTag(tagName);
|
|
460
|
+
}
|
|
461
|
+
return new locators_1.ActorLocator(this.transport, [{ action: 'getByClass', value: selector }]);
|
|
462
|
+
}
|
|
463
|
+
actorByTag(tagName) {
|
|
464
|
+
return new locators_1.ActorLocator(this.transport, [{ action: 'getByTag', value: tagName }]);
|
|
465
|
+
}
|
|
466
|
+
// ==========================================
|
|
467
|
+
// THE WIDGET ENTRY POINTS
|
|
468
|
+
// ==========================================
|
|
469
|
+
// Replaces 'getWidgetByClass'. Clean, short, and returns the specialized WidgetLocator.
|
|
470
|
+
widget(className) {
|
|
471
|
+
return new locators_1.WidgetLocator(this.transport, [{ action: 'getWidgetByClass', value: className }]);
|
|
472
|
+
}
|
|
473
|
+
getByWidget(className) {
|
|
474
|
+
return this.widget(className);
|
|
475
|
+
}
|
|
476
|
+
getByRole(role, options) {
|
|
477
|
+
const rolePayload = JSON.stringify({
|
|
478
|
+
role,
|
|
479
|
+
name: options?.name instanceof RegExp ? options.name.source : options?.name || '',
|
|
480
|
+
exact: options?.exact ?? (typeof options?.name === 'string' ? true : false)
|
|
481
|
+
});
|
|
482
|
+
return new locators_1.WidgetLocator(this.transport, [{ action: 'getWidgetByRole', value: rolePayload, exact: options?.exact }]);
|
|
483
|
+
}
|
|
484
|
+
getByText(text, options) {
|
|
485
|
+
const textStr = text instanceof RegExp ? text.source : text;
|
|
486
|
+
const exactMatch = options?.exact ?? (typeof text === 'string' ? true : false);
|
|
487
|
+
return new locators_1.WidgetLocator(this.transport, [{ action: 'getWidgetByText', value: textStr, exact: exactMatch }]);
|
|
488
|
+
}
|
|
489
|
+
getByPlayerId(playerId) {
|
|
490
|
+
return new locators_1.ActorLocator(this.transport, [{ action: 'getByPlayerId', value: playerId.toString() }]);
|
|
491
|
+
}
|
|
492
|
+
// ==========================================
|
|
493
|
+
// THE BASE ENTRY POINTS
|
|
494
|
+
// ==========================================
|
|
495
|
+
// Subsystems don't need actor/widget methods, so returning the base SpecterLocator is perfect here.
|
|
496
|
+
subsystem(subsystemName) {
|
|
497
|
+
return new locators_1.SpecterLocator(this.transport, [{ action: 'getSubsystem', value: subsystemName }]);
|
|
498
|
+
}
|
|
499
|
+
/**
|
|
500
|
+
* Queries pure UObjects in memory (e.g., UGameInstance, USaveGame).
|
|
501
|
+
* Returns the base SpecterLocator, as these objects lack spatial or UI properties.
|
|
502
|
+
*/
|
|
503
|
+
uobject(className) {
|
|
504
|
+
return new locators_1.SpecterLocator(this.transport, [{ action: 'getUObject', value: className }]);
|
|
505
|
+
}
|
|
506
|
+
// --- Global Commands ---
|
|
507
|
+
async console(commandString) {
|
|
508
|
+
await test_1.default.step(`Specter Console: ${commandString}`, async () => {
|
|
509
|
+
await this.evaluate('ConsoleCommand', { command: commandString });
|
|
510
|
+
});
|
|
511
|
+
}
|
|
512
|
+
/**
|
|
513
|
+
* Adjusts the global time dilation of the Unreal Engine.
|
|
514
|
+
* Useful for fast-forwarding through intro sequences or slowing down
|
|
515
|
+
* the game to validate frame-perfect physics/animations.
|
|
516
|
+
* * @param multiplier 1.0 is normal speed. > 1.0 is faster. < 1.0 is slower.
|
|
517
|
+
*/
|
|
518
|
+
async setTimeScale(multiplier) {
|
|
519
|
+
// Enforce a positive number so QA doesn't accidentally freeze/crash the engine
|
|
520
|
+
if (multiplier <= 0) {
|
|
521
|
+
throw new Error(`[Specter Error] setTimeScale multiplier must be greater than 0. Received: ${multiplier}`);
|
|
522
|
+
}
|
|
523
|
+
await test_1.default.step(`Specter: Set Global Time Scale [${multiplier}x]`, async () => {
|
|
524
|
+
// Under the hood, this simply routes through our new console bridge
|
|
525
|
+
await this.console(`slomo ${multiplier}`);
|
|
526
|
+
});
|
|
527
|
+
}
|
|
528
|
+
/**
|
|
529
|
+
* Captures a screenshot of the active Unreal Engine viewport.
|
|
530
|
+
* @param fileName The name of the saved file.
|
|
531
|
+
* @param showUI Whether to render the UMG/Slate UI layer into the screenshot (defaults to false).
|
|
532
|
+
* @returns The absolute file path where the image was saved on disk.
|
|
533
|
+
*/
|
|
534
|
+
async takeScreenshot(fileName, showUI = false) {
|
|
535
|
+
let savedPath = '';
|
|
536
|
+
await test_1.default.step(`Specter: Capturing Screenshot [${fileName}] (UI: ${showUI})`, async () => {
|
|
537
|
+
const response = await this.evaluate('TakeScreenshot', { fileName, showUI });
|
|
538
|
+
savedPath = response.data.savedPath;
|
|
539
|
+
// CRITICAL BUFFER: Unreal captures the screen at the end of the render frame.
|
|
540
|
+
// Give the engine's file system 500ms to actually write the .png to disk.
|
|
541
|
+
await new Promise(resolve => setTimeout(resolve, 500));
|
|
542
|
+
});
|
|
543
|
+
return savedPath;
|
|
544
|
+
}
|
|
545
|
+
/**
|
|
546
|
+
* Injects an analog axis value into the global Player Controller (e.g., thumbsticks, triggers).
|
|
547
|
+
* @param key Unreal Engine Key Name (e.g., "Gamepad_LeftY")
|
|
548
|
+
* @param value Analog float value (typically -1.0 to 1.0)
|
|
549
|
+
*/
|
|
550
|
+
async injectAxis(key, value) {
|
|
551
|
+
await this.evaluate("InjectAxis", { key, value });
|
|
552
|
+
}
|
|
553
|
+
/**
|
|
554
|
+
* Gets the current match state string from the server's AGameState or AGameMode (e.g. "InProgress", "WaitingToStart", "WaitingPostMatch").
|
|
555
|
+
*/
|
|
556
|
+
async getMatchState() {
|
|
557
|
+
const response = await this.evaluate("GetMatchState", {});
|
|
558
|
+
return response.data?.matchState ?? "Unknown";
|
|
559
|
+
}
|
|
560
|
+
/**
|
|
561
|
+
* Gets the total number of connected players registered in AGameState.PlayerArray.
|
|
562
|
+
*/
|
|
563
|
+
async getPlayerCount() {
|
|
564
|
+
const response = await this.evaluate("GetPlayerCount", {});
|
|
565
|
+
return response.data?.count ?? 0;
|
|
566
|
+
}
|
|
567
|
+
/**
|
|
568
|
+
* Gets the current server world time in seconds (AGameState.GetServerWorldTimeSeconds()).
|
|
569
|
+
*/
|
|
570
|
+
async getServerWorldTime() {
|
|
571
|
+
const response = await this.evaluate("GetServerWorldTime", {});
|
|
572
|
+
return response.data?.serverWorldTime ?? 0;
|
|
573
|
+
}
|
|
574
|
+
/**
|
|
575
|
+
* Pauses test execution until the GameState / GameMode enters the expected match state.
|
|
576
|
+
* @param expectedState Target match state (e.g. "InProgress", "WaitingPostMatch")
|
|
577
|
+
* @param options.timeout Max timeout in ms (default: 10000)
|
|
578
|
+
*/
|
|
579
|
+
async waitForMatchState(expectedState, options) {
|
|
580
|
+
const timeout = options?.timeout ?? 10000;
|
|
581
|
+
const startTime = Date.now();
|
|
582
|
+
await test_1.default.step(`Specter: Wait For Match State [${expectedState}]`, async () => {
|
|
583
|
+
while (Date.now() - startTime < timeout) {
|
|
584
|
+
const currentState = await this.getMatchState();
|
|
585
|
+
if (currentState.toLowerCase() === expectedState.toLowerCase())
|
|
586
|
+
return;
|
|
587
|
+
await new Promise(r => setTimeout(r, 100));
|
|
588
|
+
}
|
|
589
|
+
throw new Error(`[Specter] Timed out after ${timeout}ms waiting for match state "${expectedState}".`);
|
|
590
|
+
});
|
|
591
|
+
}
|
|
592
|
+
/**
|
|
593
|
+
* Gets all registered sub-levels and World Partition cells and their streaming state.
|
|
594
|
+
*/
|
|
595
|
+
async getStreamingLevels() {
|
|
596
|
+
const response = await this.evaluate("GetStreamingLevels", {});
|
|
597
|
+
return response.data?.levels ?? [];
|
|
598
|
+
}
|
|
599
|
+
/**
|
|
600
|
+
* Checks if a sub-level or World Partition cell is loaded into memory.
|
|
601
|
+
* @param levelName Level package name (e.g. "SubLevel_BossRoom")
|
|
602
|
+
*/
|
|
603
|
+
async isLevelLoaded(levelName) {
|
|
604
|
+
const response = await this.evaluate("IsLevelLoaded", { levelName });
|
|
605
|
+
return response.data?.isLoaded ?? false;
|
|
606
|
+
}
|
|
607
|
+
/**
|
|
608
|
+
* Checks if a sub-level or World Partition cell is visible in the viewport.
|
|
609
|
+
* @param levelName Level package name (e.g. "SubLevel_BossRoom")
|
|
610
|
+
*/
|
|
611
|
+
async isLevelVisible(levelName) {
|
|
612
|
+
const response = await this.evaluate("IsLevelVisible", { levelName });
|
|
613
|
+
return response.data?.isVisible ?? false;
|
|
614
|
+
}
|
|
615
|
+
/**
|
|
616
|
+
* Pauses test execution until the sub-level / World Partition cell is loaded.
|
|
617
|
+
* @param levelName Level package name (e.g. "SubLevel_BossRoom")
|
|
618
|
+
* @param options.timeout Max time in ms (default: 10000)
|
|
619
|
+
*/
|
|
620
|
+
async waitForLevelLoad(levelName, options) {
|
|
621
|
+
const timeout = options?.timeout ?? 10000;
|
|
622
|
+
const startTime = Date.now();
|
|
623
|
+
await test_1.default.step(`Specter: Wait For Level Load [${levelName}]`, async () => {
|
|
624
|
+
while (Date.now() - startTime < timeout) {
|
|
625
|
+
if (await this.isLevelLoaded(levelName))
|
|
626
|
+
return;
|
|
627
|
+
await new Promise(r => setTimeout(r, 100));
|
|
628
|
+
}
|
|
629
|
+
throw new Error(`[Specter] Timed out after ${timeout}ms waiting for level "${levelName}" to load.`);
|
|
630
|
+
});
|
|
631
|
+
}
|
|
632
|
+
/**
|
|
633
|
+
* Pauses test execution until the sub-level / World Partition cell is visible in the viewport.
|
|
634
|
+
* @param levelName Level package name (e.g. "SubLevel_BossRoom")
|
|
635
|
+
* @param options.timeout Max time in ms (default: 10000)
|
|
636
|
+
*/
|
|
637
|
+
async waitForLevelVisible(levelName, options) {
|
|
638
|
+
const timeout = options?.timeout ?? 10000;
|
|
639
|
+
const startTime = Date.now();
|
|
640
|
+
await test_1.default.step(`Specter: Wait For Level Visibility [${levelName}]`, async () => {
|
|
641
|
+
while (Date.now() - startTime < timeout) {
|
|
642
|
+
if (await this.isLevelVisible(levelName))
|
|
643
|
+
return;
|
|
644
|
+
await new Promise(r => setTimeout(r, 100));
|
|
645
|
+
}
|
|
646
|
+
throw new Error(`[Specter] Timed out after ${timeout}ms waiting for level "${levelName}" to become visible.`);
|
|
647
|
+
});
|
|
648
|
+
}
|
|
649
|
+
/**
|
|
650
|
+
* Dynamically triggers level streaming for a sub-level.
|
|
651
|
+
* @param levelName Level package name (e.g. "SubLevel_BossRoom")
|
|
652
|
+
* @param makeVisible Whether to make the level visible upon loading (default: true)
|
|
653
|
+
*/
|
|
654
|
+
async loadLevelStream(levelName, makeVisible = true) {
|
|
655
|
+
await test_1.default.step(`Specter: Load Stream Level [${levelName}] (Visible: ${makeVisible})`, async () => {
|
|
656
|
+
await this.evaluate("LoadStreamingLevel", { levelName, makeVisible });
|
|
657
|
+
});
|
|
658
|
+
}
|
|
659
|
+
/**
|
|
660
|
+
* Opens a level (absolute travel) via UGameplayStatics::OpenLevel
|
|
661
|
+
*/
|
|
662
|
+
async loadLevel(levelName, options = "") {
|
|
663
|
+
await test_1.default.step(`Specter: Load Level [${levelName}]`, async () => {
|
|
664
|
+
await this.evaluate("OpenLevel", { levelName, options });
|
|
665
|
+
});
|
|
666
|
+
}
|
|
667
|
+
/**
|
|
668
|
+
* Plays a high-resolution input sequence generated by SpecterInputSequence.
|
|
669
|
+
* @param sequence The input pattern to play.
|
|
670
|
+
* @param options Additional playback options (e.g., looping).
|
|
671
|
+
*/
|
|
672
|
+
async playSequence(sequence, options) {
|
|
673
|
+
const loops = options?.loops || 1;
|
|
674
|
+
const keyframes = sequence.getKeyframes();
|
|
675
|
+
if (keyframes.length === 0)
|
|
676
|
+
return;
|
|
677
|
+
for (let l = 0; l < loops; l++) {
|
|
678
|
+
const startTime = performance.now();
|
|
679
|
+
let frameIndex = 0;
|
|
680
|
+
while (frameIndex < keyframes.length) {
|
|
681
|
+
const now = performance.now();
|
|
682
|
+
const elapsed = now - startTime;
|
|
683
|
+
if (elapsed >= keyframes[frameIndex].timeMs) {
|
|
684
|
+
const kf = keyframes[frameIndex];
|
|
685
|
+
if (kf.axes) {
|
|
686
|
+
for (const [axis, val] of Object.entries(kf.axes)) {
|
|
687
|
+
this.injectAxis(axis, val).catch(() => { });
|
|
688
|
+
}
|
|
689
|
+
}
|
|
690
|
+
if (kf.buttons) {
|
|
691
|
+
for (const [btn, state] of Object.entries(kf.buttons)) {
|
|
692
|
+
this.keyboard.press(btn, state === 'Pressed' ? -1 : 0).catch(() => { });
|
|
693
|
+
}
|
|
694
|
+
}
|
|
695
|
+
frameIndex++;
|
|
696
|
+
}
|
|
697
|
+
else {
|
|
698
|
+
// Yield to the event loop and wait 1ms
|
|
699
|
+
await new Promise(r => setTimeout(r, 1));
|
|
700
|
+
}
|
|
701
|
+
}
|
|
702
|
+
}
|
|
703
|
+
}
|
|
704
|
+
async loadMap(mapName, options) {
|
|
705
|
+
await test_1.default.step(`Specter: Load Map [${mapName}]`, async () => {
|
|
706
|
+
const expectedMap = mapName.split('/').pop()?.split('.')[0] || mapName;
|
|
707
|
+
const status = await this.getNetworkStatus();
|
|
708
|
+
const correctMode = options?.listen ? status.netMode === 'ListenServer' : true;
|
|
709
|
+
if (!options?.force && (status.map === expectedMap || status.map.includes(expectedMap)) && correctMode) {
|
|
710
|
+
console.log(`[SPECTER] Already on map ${expectedMap} with correct netMode. Skipping loadMap.`);
|
|
711
|
+
return;
|
|
712
|
+
}
|
|
713
|
+
const payload = { levelName: mapName };
|
|
714
|
+
if (options) {
|
|
715
|
+
const urlOptions = [];
|
|
716
|
+
if (options.gameMode) {
|
|
717
|
+
urlOptions.push(`?game=${options.gameMode}`);
|
|
718
|
+
}
|
|
719
|
+
if (options.listen) {
|
|
720
|
+
urlOptions.push('?listen');
|
|
721
|
+
}
|
|
722
|
+
if (urlOptions.length > 0) {
|
|
723
|
+
payload.options = urlOptions.join('');
|
|
724
|
+
}
|
|
725
|
+
}
|
|
726
|
+
// Set up the MapLoaded listener in case connection stays up
|
|
727
|
+
let mapLoaded = false;
|
|
728
|
+
const cleanups = [];
|
|
729
|
+
const mapLoadedPromise = new Promise((resolve) => {
|
|
730
|
+
const listener = (data) => {
|
|
731
|
+
const loadedMap = data?.map || '';
|
|
732
|
+
if (loadedMap === expectedMap || loadedMap.includes(expectedMap)) {
|
|
733
|
+
mapLoaded = true;
|
|
734
|
+
resolve();
|
|
735
|
+
}
|
|
736
|
+
};
|
|
737
|
+
this.transport.registerEventListener('GLOBAL_MapLoaded', listener);
|
|
738
|
+
cleanups.push(() => {
|
|
739
|
+
this.transport.removeEventListener('GLOBAL_MapLoaded', listener);
|
|
740
|
+
});
|
|
741
|
+
});
|
|
742
|
+
// Set up a disconnect listener
|
|
743
|
+
const disconnectPromise = new Promise((resolve) => {
|
|
744
|
+
const closeListener = () => {
|
|
745
|
+
resolve();
|
|
746
|
+
};
|
|
747
|
+
this.transport.ws.once('close', closeListener);
|
|
748
|
+
cleanups.push(() => {
|
|
749
|
+
this.transport.ws.off('close', closeListener);
|
|
750
|
+
});
|
|
751
|
+
});
|
|
752
|
+
try {
|
|
753
|
+
await this.evaluate("LoadLevel", payload);
|
|
754
|
+
// Wait for either the MapLoaded event OR a disconnect (with a configurable timeout)
|
|
755
|
+
const timeoutMs = options?.timeout ?? 30000;
|
|
756
|
+
let timeoutId;
|
|
757
|
+
const timeoutPromise = new Promise((_, reject) => {
|
|
758
|
+
timeoutId = setTimeout(() => {
|
|
759
|
+
reject(new Error(`Timed out waiting for map [${mapName}] to load after ${timeoutMs}ms.`));
|
|
760
|
+
}, timeoutMs);
|
|
761
|
+
});
|
|
762
|
+
await Promise.race([mapLoadedPromise, disconnectPromise, timeoutPromise]);
|
|
763
|
+
clearTimeout(timeoutId);
|
|
764
|
+
if (!mapLoaded) {
|
|
765
|
+
// If it was a disconnect, wait for reconnection
|
|
766
|
+
console.log(`[SPECTER] Connection dropped during loadMap. Waiting for reconnection...`);
|
|
767
|
+
this.transport.isConnected = false;
|
|
768
|
+
await this.transport.connect();
|
|
769
|
+
console.log(`[SPECTER] Reconnected successfully after loadMap.`);
|
|
770
|
+
}
|
|
771
|
+
}
|
|
772
|
+
finally {
|
|
773
|
+
cleanups.forEach(c => c());
|
|
774
|
+
}
|
|
775
|
+
});
|
|
776
|
+
}
|
|
777
|
+
async waitForMapLoad(mapName, timeout = 15000) {
|
|
778
|
+
await test_1.default.step(`Specter: Wait For Map Load [${mapName}]`, async () => {
|
|
779
|
+
const expectedMap = mapName.split('/').pop()?.split('.')[0] || mapName;
|
|
780
|
+
await new Promise((resolve, reject) => {
|
|
781
|
+
let timeoutId;
|
|
782
|
+
const listener = (data) => {
|
|
783
|
+
const loadedMap = data?.map || '';
|
|
784
|
+
if (loadedMap === expectedMap || loadedMap.includes(expectedMap)) {
|
|
785
|
+
this.transport.removeEventListener('GLOBAL_MapLoaded', listener);
|
|
786
|
+
clearTimeout(timeoutId);
|
|
787
|
+
resolve();
|
|
788
|
+
}
|
|
789
|
+
};
|
|
790
|
+
timeoutId = setTimeout(() => {
|
|
791
|
+
this.transport.removeEventListener('GLOBAL_MapLoaded', listener);
|
|
792
|
+
reject(new Error(`Timed out waiting for map ${mapName} to load after ${timeout}ms.`));
|
|
793
|
+
}, timeout);
|
|
794
|
+
this.transport.registerEventListener('GLOBAL_MapLoaded', listener);
|
|
795
|
+
});
|
|
796
|
+
});
|
|
797
|
+
}
|
|
798
|
+
get currentMap() {
|
|
799
|
+
return this.transport.currentMap;
|
|
800
|
+
}
|
|
801
|
+
async getNetworkStatus() {
|
|
802
|
+
const response = await this.evaluate("GetNetworkStatus", {});
|
|
803
|
+
return response.data;
|
|
804
|
+
}
|
|
805
|
+
async cleanup() {
|
|
806
|
+
if (!this.transport.isConnected)
|
|
807
|
+
return;
|
|
808
|
+
try {
|
|
809
|
+
await this.evaluate("ClearAllSpawned", {});
|
|
810
|
+
}
|
|
811
|
+
catch (e) {
|
|
812
|
+
// Ignore cleanup timeouts during test teardown if connection is closing/closed
|
|
813
|
+
}
|
|
814
|
+
}
|
|
815
|
+
/**
|
|
816
|
+
* Restores the primary PlayerController to its pre-possession state
|
|
817
|
+
* (re-possessing original pawn, restoring view target, and resetting control rotation).
|
|
818
|
+
*/
|
|
819
|
+
async restorePlayer() {
|
|
820
|
+
await this.evaluate("RestorePlayerState", {});
|
|
821
|
+
}
|
|
822
|
+
async waitForVariable(varName, expectedValue, timeout = 5000) {
|
|
823
|
+
return await test_1.default.step(`Specter: Wait For Variable [${varName} == ${expectedValue}]`, async () => {
|
|
824
|
+
return new Promise((resolve, reject) => {
|
|
825
|
+
let timeoutId;
|
|
826
|
+
const listener = (event) => {
|
|
827
|
+
if (event.eventType === SpecterEventType.StandardVariable &&
|
|
828
|
+
event.eventName === varName &&
|
|
829
|
+
event.newValue === expectedValue) {
|
|
830
|
+
clearTimeout(timeoutId);
|
|
831
|
+
this.transport.removeEventListener('GLOBAL_timeline-event', listener);
|
|
832
|
+
resolve(event);
|
|
833
|
+
}
|
|
834
|
+
};
|
|
835
|
+
timeoutId = setTimeout(() => {
|
|
836
|
+
this.transport.removeEventListener('GLOBAL_timeline-event', listener);
|
|
837
|
+
reject(new Error(`Timed out after ${timeout}ms waiting for variable '${varName}' to track value '${expectedValue}'`));
|
|
838
|
+
}, timeout);
|
|
839
|
+
this.transport.registerEventListener('GLOBAL_timeline-event', listener);
|
|
840
|
+
});
|
|
841
|
+
});
|
|
842
|
+
}
|
|
843
|
+
async close() {
|
|
844
|
+
this.transport.disconnect();
|
|
845
|
+
}
|
|
846
|
+
/**
|
|
847
|
+
* Retrieves current engine performance metrics (FPS, Frame Time in ms, Used Memory in MB).
|
|
848
|
+
*/
|
|
849
|
+
async getPerformanceMetrics() {
|
|
850
|
+
const response = await this.evaluate("GetPerformanceMetrics", {});
|
|
851
|
+
return response.data ?? { fps: 60, frameTimeMs: 16.66, memoryMb: 0 };
|
|
852
|
+
}
|
|
853
|
+
/**
|
|
854
|
+
* Checks if a navigation path exists between start and end vectors on the NavMesh.
|
|
855
|
+
*/
|
|
856
|
+
async isPointReachable(start, end) {
|
|
857
|
+
const response = await this.evaluate("IsPointReachable", { start, end });
|
|
858
|
+
return response.data?.isReachable ?? false;
|
|
859
|
+
}
|
|
860
|
+
/**
|
|
861
|
+
* Checks if a Level Sequence cutscene is currently playing.
|
|
862
|
+
*/
|
|
863
|
+
async isSequencePlaying(sequenceName) {
|
|
864
|
+
const response = await this.evaluate("IsSequencePlaying", { name: sequenceName });
|
|
865
|
+
return response.data?.isPlaying ?? false;
|
|
866
|
+
}
|
|
867
|
+
/**
|
|
868
|
+
* Gets the playback position in seconds of a Level Sequence cutscene.
|
|
869
|
+
*/
|
|
870
|
+
async getSequencePlaybackPosition(sequenceName) {
|
|
871
|
+
const response = await this.evaluate("GetSequencePlaybackPosition", { name: sequenceName });
|
|
872
|
+
return response.data?.positionSeconds ?? 0.0;
|
|
873
|
+
}
|
|
874
|
+
/**
|
|
875
|
+
* Scrubs a Level Sequence cutscene to a specific playback position in seconds.
|
|
876
|
+
*/
|
|
877
|
+
async scrubSequence(sequenceName, positionSeconds) {
|
|
878
|
+
await test_1.default.step(`Specter: Scrub Sequence [${sequenceName}] to ${positionSeconds}s`, async () => {
|
|
879
|
+
await this.evaluate("ScrubSequence", { name: sequenceName, positionSeconds });
|
|
880
|
+
});
|
|
881
|
+
}
|
|
882
|
+
}
|
|
883
|
+
exports.SpecterWorld = SpecterWorld;
|