@specter-automation/test 1.0.129 → 1.0.131
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/locators/actor-locator.d.ts +20 -0
- package/dist/core/locators/actor-locator.js +44 -0
- package/dist/core/locators/widget-locator.d.ts +7 -0
- package/dist/core/locators/widget-locator.js +11 -0
- package/dist/core/specter-client.d.ts +34 -1
- package/dist/core/specter-client.js +47 -0
- package/dist/core/specter-reporter.d.ts +3 -1
- package/dist/core/specter-reporter.js +52 -4
- package/package.json +1 -1
|
@@ -66,6 +66,26 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
|
|
|
66
66
|
duration?: number;
|
|
67
67
|
color?: string;
|
|
68
68
|
}): Promise<void>;
|
|
69
|
+
/**
|
|
70
|
+
* Clicks the actor.
|
|
71
|
+
*
|
|
72
|
+
* @param options.strategy
|
|
73
|
+
* - 'function' (default): runs its click events (OnClicked, the blueprint's ActorOnClicked) when it has any.
|
|
74
|
+
* When nothing listens for clicks on it, it is clicked through the game view instead.
|
|
75
|
+
* - 'viewport': clicks where it is on screen. The click goes straight to the game's view, so the game reads it like
|
|
76
|
+
* a player's (GetMousePosition, the button press, Enhanced Input, click events) without moving the real mouse
|
|
77
|
+
* or needing focus. Fails when something else is in front of it.
|
|
78
|
+
* - 'broadcast': runs its click events whether or not anything listens.
|
|
79
|
+
* @param options.button 'left' (default), 'right' or 'middle'
|
|
80
|
+
* @param options.timeout How long to keep trying, e.g. while it walks on screen (default: 5000ms)
|
|
81
|
+
* @param options.context Optional text to tell identical steps apart in the report
|
|
82
|
+
*/
|
|
83
|
+
click(options?: {
|
|
84
|
+
strategy?: 'function' | 'viewport' | 'broadcast';
|
|
85
|
+
button?: 'left' | 'right' | 'middle';
|
|
86
|
+
timeout?: number;
|
|
87
|
+
context?: string;
|
|
88
|
+
}): Promise<void>;
|
|
69
89
|
/**
|
|
70
90
|
* Explicitly destroys this actor in the Unreal Engine world.
|
|
71
91
|
*/
|
|
@@ -138,6 +138,50 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
|
|
|
138
138
|
async updateStatsBillboard(options) {
|
|
139
139
|
return this.showStatsBillboard(options);
|
|
140
140
|
}
|
|
141
|
+
/**
|
|
142
|
+
* Clicks the actor.
|
|
143
|
+
*
|
|
144
|
+
* @param options.strategy
|
|
145
|
+
* - 'function' (default): runs its click events (OnClicked, the blueprint's ActorOnClicked) when it has any.
|
|
146
|
+
* When nothing listens for clicks on it, it is clicked through the game view instead.
|
|
147
|
+
* - 'viewport': clicks where it is on screen. The click goes straight to the game's view, so the game reads it like
|
|
148
|
+
* a player's (GetMousePosition, the button press, Enhanced Input, click events) without moving the real mouse
|
|
149
|
+
* or needing focus. Fails when something else is in front of it.
|
|
150
|
+
* - 'broadcast': runs its click events whether or not anything listens.
|
|
151
|
+
* @param options.button 'left' (default), 'right' or 'middle'
|
|
152
|
+
* @param options.timeout How long to keep trying, e.g. while it walks on screen (default: 5000ms)
|
|
153
|
+
* @param options.context Optional text to tell identical steps apart in the report
|
|
154
|
+
*/
|
|
155
|
+
async click(options) {
|
|
156
|
+
const baseName = `Click Actor @ ${this.toString()}`;
|
|
157
|
+
const stepName = options?.context ? `${baseName} [${options.context}]` : baseName;
|
|
158
|
+
return await test_1.default.step(stepName, async () => {
|
|
159
|
+
const strategy = options?.strategy || 'function';
|
|
160
|
+
const button = options?.button || 'left';
|
|
161
|
+
const timeout = options?.timeout ?? 5000;
|
|
162
|
+
const startTime = Date.now();
|
|
163
|
+
let lastError = null;
|
|
164
|
+
while (Date.now() - startTime < timeout) {
|
|
165
|
+
try {
|
|
166
|
+
const response = await this.evaluate('ClickActor', { strategy, button }, undefined, true);
|
|
167
|
+
if (response?.status === 'success') {
|
|
168
|
+
return;
|
|
169
|
+
}
|
|
170
|
+
lastError = new Error(response?.error || 'ClickActor failed');
|
|
171
|
+
}
|
|
172
|
+
catch (err) {
|
|
173
|
+
lastError = err;
|
|
174
|
+
const msg = err instanceof Error ? err.message : String(err);
|
|
175
|
+
if (msg.toLowerCase().includes('strict mode')) {
|
|
176
|
+
throw err;
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
await new Promise(resolve => setTimeout(resolve, 100));
|
|
180
|
+
}
|
|
181
|
+
const details = lastError ? `\nUnderlying Error: ${lastError.message}` : '';
|
|
182
|
+
throw new Error(`[Specter Timeout] Timed out after ${timeout}ms attempting to click actor: ${this.toString()}.${details}`);
|
|
183
|
+
});
|
|
184
|
+
}
|
|
141
185
|
/**
|
|
142
186
|
* Explicitly destroys this actor in the Unreal Engine world.
|
|
143
187
|
*/
|
|
@@ -78,6 +78,13 @@ export declare class WidgetLocator<T = any> extends SpecterLocator<T> {
|
|
|
78
78
|
getByText(text: string | RegExp, options?: {
|
|
79
79
|
exact?: boolean;
|
|
80
80
|
}): WidgetLocator;
|
|
81
|
+
/**
|
|
82
|
+
* Finds UI inside this one by a name that stays the same when its words change: a UMG widget's name in the
|
|
83
|
+
* designer, the test id a hand-drawn HUD reports with FSpecterHUD, or a Slate widget's tag or Automation Driver id.
|
|
84
|
+
*/
|
|
85
|
+
getByTestId(testId: string, options?: {
|
|
86
|
+
exact?: boolean;
|
|
87
|
+
}): WidgetLocator;
|
|
81
88
|
/**
|
|
82
89
|
* Alias for getChild / navigating down the widget hierarchy.
|
|
83
90
|
*/
|
|
@@ -181,6 +181,17 @@ class WidgetLocator extends specter_locator_1.SpecterLocator {
|
|
|
181
181
|
];
|
|
182
182
|
return new WidgetLocator(this.transport, newPipeline);
|
|
183
183
|
}
|
|
184
|
+
/**
|
|
185
|
+
* Finds UI inside this one by a name that stays the same when its words change: a UMG widget's name in the
|
|
186
|
+
* designer, the test id a hand-drawn HUD reports with FSpecterHUD, or a Slate widget's tag or Automation Driver id.
|
|
187
|
+
*/
|
|
188
|
+
getByTestId(testId, options) {
|
|
189
|
+
const newPipeline = [
|
|
190
|
+
...this.pipeline,
|
|
191
|
+
{ action: 'getWidgetByTestId', value: testId, exact: options?.exact ?? true }
|
|
192
|
+
];
|
|
193
|
+
return new WidgetLocator(this.transport, newPipeline);
|
|
194
|
+
}
|
|
184
195
|
/**
|
|
185
196
|
* Alias for getChild / navigating down the widget hierarchy.
|
|
186
197
|
*/
|
|
@@ -196,7 +196,14 @@ export interface SpawnOptions {
|
|
|
196
196
|
name?: string;
|
|
197
197
|
}
|
|
198
198
|
export interface ClickOptions {
|
|
199
|
-
|
|
199
|
+
/**
|
|
200
|
+
* - 'function' (default): runs the click handler directly; falls back to a click when there is none.
|
|
201
|
+
* - 'hardware': a real mouse click through Slate. Moves the real cursor.
|
|
202
|
+
* - 'viewport': a click handed straight to the game's view, as the game reads a player's click. The real cursor
|
|
203
|
+
* doesn't move and the game doesn't need focus. For things the game draws or picks itself: HUD elements.
|
|
204
|
+
* - 'broadcast': only the click handler; fails when there is none.
|
|
205
|
+
*/
|
|
206
|
+
strategy?: 'hardware' | 'broadcast' | 'function' | 'viewport';
|
|
200
207
|
timeout?: number;
|
|
201
208
|
tolerance?: number;
|
|
202
209
|
waitForStable?: boolean;
|
|
@@ -381,6 +388,13 @@ export declare class SpecterWorld {
|
|
|
381
388
|
getByText(text: string | RegExp, options?: {
|
|
382
389
|
exact?: boolean;
|
|
383
390
|
}): WidgetLocator;
|
|
391
|
+
/**
|
|
392
|
+
* Finds UI by a name that stays the same when its words change: a UMG widget's name in the designer, the test
|
|
393
|
+
* id a hand-drawn HUD reports with FSpecterHUD, or a Slate widget's tag or Automation Driver id.
|
|
394
|
+
*/
|
|
395
|
+
getByTestId(testId: string, options?: {
|
|
396
|
+
exact?: boolean;
|
|
397
|
+
}): WidgetLocator;
|
|
384
398
|
getByPlayerId(playerId: number): ActorLocator;
|
|
385
399
|
subsystem(subsystemName: string): SpecterLocator;
|
|
386
400
|
/**
|
|
@@ -388,6 +402,25 @@ export declare class SpecterWorld {
|
|
|
388
402
|
* Returns the base SpecterLocator, as these objects lack spatial or UI properties.
|
|
389
403
|
*/
|
|
390
404
|
uobject(className: string): SpecterLocator;
|
|
405
|
+
/**
|
|
406
|
+
* Pauses the test and opens the in-game inspector, the way `page.pause()` opens Playwright's inspector.
|
|
407
|
+
*
|
|
408
|
+
* The game stays exactly as the test left it. Click actors or widgets in the game view to get locators
|
|
409
|
+
* for them, checked against the live game, along with their tags, attributes and components. The test
|
|
410
|
+
* carries on when you close the inspector. Its timeout is switched off while you look around.
|
|
411
|
+
*
|
|
412
|
+
* For writing and debugging tests on your own machine: it does nothing on CI.
|
|
413
|
+
*
|
|
414
|
+
* ```ts
|
|
415
|
+
* const steel = await server.heroes.steel.spawn({ ... });
|
|
416
|
+
* await world.inspect(); // look around, copy a locator, close the inspector to continue
|
|
417
|
+
* ```
|
|
418
|
+
*
|
|
419
|
+
* @param options.mode What to pick first: `'actors'` in the world (the default) or `'widgets'` of the game's UI.
|
|
420
|
+
*/
|
|
421
|
+
inspect(options?: {
|
|
422
|
+
mode?: 'actors' | 'widgets';
|
|
423
|
+
}): Promise<void>;
|
|
391
424
|
console(commandString: string): Promise<void>;
|
|
392
425
|
/**
|
|
393
426
|
* Adjusts the global time dilation of the Unreal Engine.
|
|
@@ -732,6 +732,13 @@ class SpecterWorld {
|
|
|
732
732
|
const exactMatch = options?.exact ?? (typeof text === 'string' ? true : false);
|
|
733
733
|
return new locators_1.WidgetLocator(this.transport, [{ action: 'getWidgetByText', value: textStr, exact: exactMatch }]);
|
|
734
734
|
}
|
|
735
|
+
/**
|
|
736
|
+
* Finds UI by a name that stays the same when its words change: a UMG widget's name in the designer, the test
|
|
737
|
+
* id a hand-drawn HUD reports with FSpecterHUD, or a Slate widget's tag or Automation Driver id.
|
|
738
|
+
*/
|
|
739
|
+
getByTestId(testId, options) {
|
|
740
|
+
return new locators_1.WidgetLocator(this.transport, [{ action: 'getWidgetByTestId', value: testId, exact: options?.exact ?? true }]);
|
|
741
|
+
}
|
|
735
742
|
getByPlayerId(playerId) {
|
|
736
743
|
return new locators_1.ActorLocator(this.transport, [{ action: 'getByPlayerId', value: playerId.toString() }]);
|
|
737
744
|
}
|
|
@@ -750,6 +757,46 @@ class SpecterWorld {
|
|
|
750
757
|
return new locators_1.SpecterLocator(this.transport, [{ action: 'getUObject', value: className }]);
|
|
751
758
|
}
|
|
752
759
|
// --- Global Commands ---
|
|
760
|
+
/**
|
|
761
|
+
* Pauses the test and opens the in-game inspector, the way `page.pause()` opens Playwright's inspector.
|
|
762
|
+
*
|
|
763
|
+
* The game stays exactly as the test left it. Click actors or widgets in the game view to get locators
|
|
764
|
+
* for them, checked against the live game, along with their tags, attributes and components. The test
|
|
765
|
+
* carries on when you close the inspector. Its timeout is switched off while you look around.
|
|
766
|
+
*
|
|
767
|
+
* For writing and debugging tests on your own machine: it does nothing on CI.
|
|
768
|
+
*
|
|
769
|
+
* ```ts
|
|
770
|
+
* const steel = await server.heroes.steel.spawn({ ... });
|
|
771
|
+
* await world.inspect(); // look around, copy a locator, close the inspector to continue
|
|
772
|
+
* ```
|
|
773
|
+
*
|
|
774
|
+
* @param options.mode What to pick first: `'actors'` in the world (the default) or `'widgets'` of the game's UI.
|
|
775
|
+
*/
|
|
776
|
+
async inspect(options = {}) {
|
|
777
|
+
if (process.env.CI) {
|
|
778
|
+
return;
|
|
779
|
+
}
|
|
780
|
+
await test_1.default.step(`${this.transport.friendlyPortTag}inspect (waiting for the inspector to be closed)`, async () => {
|
|
781
|
+
// You decide how long this takes, so the test can't time out while it waits
|
|
782
|
+
test_1.default.setTimeout(0);
|
|
783
|
+
let onClosed = () => { };
|
|
784
|
+
const closed = new Promise((resolve) => {
|
|
785
|
+
onClosed = () => resolve();
|
|
786
|
+
});
|
|
787
|
+
this.transport.registerEventListener('GLOBAL_inspector-closed', onClosed);
|
|
788
|
+
try {
|
|
789
|
+
await this.transport.sendCommand({
|
|
790
|
+
command: 'OpenInspector',
|
|
791
|
+
payload: { mode: options.mode ?? 'actors' }
|
|
792
|
+
});
|
|
793
|
+
await closed;
|
|
794
|
+
}
|
|
795
|
+
finally {
|
|
796
|
+
this.transport.removeEventListener('GLOBAL_inspector-closed', onClosed);
|
|
797
|
+
}
|
|
798
|
+
});
|
|
799
|
+
}
|
|
753
800
|
async console(commandString) {
|
|
754
801
|
await test_1.default.step(`Specter Console: ${commandString}`, async () => {
|
|
755
802
|
await this.evaluate('ConsoleCommand', { command: commandString });
|
|
@@ -20,11 +20,13 @@ export default class SpecterReporter implements Reporter {
|
|
|
20
20
|
private runHasFailure;
|
|
21
21
|
private runReplay;
|
|
22
22
|
private runReplayWaiters;
|
|
23
|
+
/** Where the engine is writing each test's timeline preview frames (its latest attempt), on the engine's machine */
|
|
24
|
+
private runFrameFolders;
|
|
23
25
|
constructor();
|
|
24
26
|
private connect;
|
|
25
27
|
/**
|
|
26
28
|
* The engine broadcasts everything to every client, so most messages here are other clients' command
|
|
27
|
-
* responses. Only the
|
|
29
|
+
* responses. Only the ones about the run's replay and the tests' preview frames matter to the reporter.
|
|
28
30
|
*/
|
|
29
31
|
private handleEngineMessage;
|
|
30
32
|
private releaseReplayWaiters;
|
|
@@ -125,6 +125,8 @@ class SpecterReporter {
|
|
|
125
125
|
runHasFailure = false;
|
|
126
126
|
runReplay = null;
|
|
127
127
|
runReplayWaiters = [];
|
|
128
|
+
/** Where the engine is writing each test's timeline preview frames (its latest attempt), on the engine's machine */
|
|
129
|
+
runFrameFolders = new Map();
|
|
128
130
|
constructor() {
|
|
129
131
|
this.connect();
|
|
130
132
|
}
|
|
@@ -154,19 +156,23 @@ class SpecterReporter {
|
|
|
154
156
|
}
|
|
155
157
|
/**
|
|
156
158
|
* The engine broadcasts everything to every client, so most messages here are other clients' command
|
|
157
|
-
* responses. Only the
|
|
159
|
+
* responses. Only the ones about the run's replay and the tests' preview frames matter to the reporter.
|
|
158
160
|
*/
|
|
159
161
|
handleEngineMessage(data) {
|
|
160
162
|
try {
|
|
161
163
|
const buffer = Array.isArray(data) ? Buffer.concat(data) : Buffer.isBuffer(data) ? data : Buffer.from(data);
|
|
162
|
-
if (!buffer.includes('run-replay')) {
|
|
164
|
+
if (!buffer.includes('run-replay') && !buffer.includes('test-filmstrip')) {
|
|
163
165
|
return;
|
|
164
166
|
}
|
|
165
167
|
const message = JSON.parse(buffer.toString('utf-8'));
|
|
166
168
|
if (message?.type !== 'event' || !message.data) {
|
|
167
169
|
return;
|
|
168
170
|
}
|
|
169
|
-
if (message.eventName === '
|
|
171
|
+
if (message.eventName === 'test-filmstrip' && message.data.testName && message.data.folder) {
|
|
172
|
+
// The engine is recording small images of the game view for this test (the timeline's hover preview)
|
|
173
|
+
this.runFrameFolders.set(String(message.data.testName), String(message.data.folder));
|
|
174
|
+
}
|
|
175
|
+
else if (message.eventName === 'run-replay-started' && message.data.replayName) {
|
|
170
176
|
// Recording began. Remember where the file will be in case the engine goes away before the run ends.
|
|
171
177
|
this.runReplay = {
|
|
172
178
|
name: String(message.data.replayName),
|
|
@@ -709,6 +715,7 @@ class SpecterReporter {
|
|
|
709
715
|
// run.json what ran, and where everything is
|
|
710
716
|
// tests/001_<name>/trace.json one test: the same content as a single-test trace
|
|
711
717
|
// tests/001_<name>/screenshots/*.png its images
|
|
718
|
+
// tests/001_<name>/frames/f_*.jpg small frames of the game view, for the timeline's hover preview
|
|
712
719
|
// replay/<name>.replay the engine's replay of the run, when it recorded one
|
|
713
720
|
//
|
|
714
721
|
// Tests are staged on disk as they finish, so a long run doesn't sit in memory, and the archive is
|
|
@@ -801,7 +808,11 @@ class SpecterReporter {
|
|
|
801
808
|
* writes it in the background). Returns the file to pack, or null when there is no replay to include.
|
|
802
809
|
*/
|
|
803
810
|
async waitForRunReplay() {
|
|
804
|
-
// The engine announces a recording when the run starts. No announcement: no replay, and no waiting
|
|
811
|
+
// The engine announces a recording when the run starts. No announcement: no replay, and no waiting
|
|
812
|
+
// (beyond a moment for one still on its way after a very short run).
|
|
813
|
+
if (!this.runReplay && this.isConnected) {
|
|
814
|
+
await sleep(300);
|
|
815
|
+
}
|
|
805
816
|
if (!this.runReplay) {
|
|
806
817
|
return null;
|
|
807
818
|
}
|
|
@@ -846,6 +857,35 @@ class SpecterReporter {
|
|
|
846
857
|
return;
|
|
847
858
|
}
|
|
848
859
|
const replayFile = await this.waitForRunReplay();
|
|
860
|
+
// The engine writes preview frames in the background: give the last test's final ones a moment to land
|
|
861
|
+
if (this.runFrameFolders.size > 0) {
|
|
862
|
+
await sleep(250);
|
|
863
|
+
}
|
|
864
|
+
const frameFiles = new Map();
|
|
865
|
+
for (const entry of this.runTests.values()) {
|
|
866
|
+
const frameDir = this.runFrameFolders.get(entry.testName) ?? this.runFrameFolders.get(entry.testName.replace(/\\/g, '/'));
|
|
867
|
+
if (!frameDir) {
|
|
868
|
+
continue;
|
|
869
|
+
}
|
|
870
|
+
try {
|
|
871
|
+
// f_0001240.jpg = 1.240 s into the test. Frames still being written have another extension.
|
|
872
|
+
const names = fs.readdirSync(frameDir).filter(name => /^f_\d+\.jpg$/.test(name)).sort();
|
|
873
|
+
if (names.length > 0) {
|
|
874
|
+
frameFiles.set(entry.testName, names.map(name => path.join(frameDir, name)));
|
|
875
|
+
}
|
|
876
|
+
}
|
|
877
|
+
catch {
|
|
878
|
+
// Not on this machine (the game runs elsewhere): the trace goes without preview frames
|
|
879
|
+
}
|
|
880
|
+
}
|
|
881
|
+
// A plain zip holds 65,535 files. A very large run keeps every Nth frame instead of failing.
|
|
882
|
+
const totalFrames = [...frameFiles.values()].reduce((sum, files) => sum + files.length, 0);
|
|
883
|
+
const frameStride = Math.ceil(totalFrames / 50000);
|
|
884
|
+
if (frameStride > 1) {
|
|
885
|
+
for (const [testName, files] of frameFiles) {
|
|
886
|
+
frameFiles.set(testName, files.filter((_, index) => index % frameStride === 0 || index === files.length - 1));
|
|
887
|
+
}
|
|
888
|
+
}
|
|
849
889
|
const replay = this.runReplay;
|
|
850
890
|
const replayEntry = replay && replayFile
|
|
851
891
|
? `replay/${replay.name.replace(/[^a-zA-Z0-9._-]/g, '_')}.replay`
|
|
@@ -865,6 +905,7 @@ class SpecterReporter {
|
|
|
865
905
|
status: entry.status,
|
|
866
906
|
durationMs: entry.durationMs,
|
|
867
907
|
trace: `${entry.folder}/trace.json`,
|
|
908
|
+
frames: frameFiles.has(entry.testName) ? `${entry.folder}/frames` : undefined,
|
|
868
909
|
replayStart: span?.start,
|
|
869
910
|
replayEnd: span?.end
|
|
870
911
|
};
|
|
@@ -885,6 +926,12 @@ class SpecterReporter {
|
|
|
885
926
|
zip.addFile(`${entry.folder}/screenshots/${image}`, fs.readFileSync(path.join(imageDir, image)), { store: true });
|
|
886
927
|
}
|
|
887
928
|
}
|
|
929
|
+
for (const frame of frameFiles.get(entry.testName) ?? []) {
|
|
930
|
+
try {
|
|
931
|
+
zip.addFile(`${entry.folder}/frames/${path.basename(frame)}`, fs.readFileSync(frame), { store: true });
|
|
932
|
+
}
|
|
933
|
+
catch { }
|
|
934
|
+
}
|
|
888
935
|
}
|
|
889
936
|
if (replayFile && replayEntry) {
|
|
890
937
|
zip.addFile(replayEntry, fs.readFileSync(replayFile));
|
|
@@ -907,6 +954,7 @@ class SpecterReporter {
|
|
|
907
954
|
fs.rmSync(stageDir, { recursive: true, force: true });
|
|
908
955
|
this.runStageDir = null;
|
|
909
956
|
this.runTests.clear();
|
|
957
|
+
this.runFrameFolders.clear();
|
|
910
958
|
}
|
|
911
959
|
}
|
|
912
960
|
async onEnd(result) {
|