@specter-automation/test 1.0.129 → 1.0.130
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.
|
@@ -388,6 +388,25 @@ export declare class SpecterWorld {
|
|
|
388
388
|
* Returns the base SpecterLocator, as these objects lack spatial or UI properties.
|
|
389
389
|
*/
|
|
390
390
|
uobject(className: string): SpecterLocator;
|
|
391
|
+
/**
|
|
392
|
+
* Pauses the test and opens the in-game inspector, the way `page.pause()` opens Playwright's inspector.
|
|
393
|
+
*
|
|
394
|
+
* The game stays exactly as the test left it. Click actors or widgets in the game view to get locators
|
|
395
|
+
* for them, checked against the live game, along with their tags, attributes and components. The test
|
|
396
|
+
* carries on when you close the inspector. Its timeout is switched off while you look around.
|
|
397
|
+
*
|
|
398
|
+
* For writing and debugging tests on your own machine: it does nothing on CI.
|
|
399
|
+
*
|
|
400
|
+
* ```ts
|
|
401
|
+
* const steel = await server.heroes.steel.spawn({ ... });
|
|
402
|
+
* await world.inspect(); // look around, copy a locator, close the inspector to continue
|
|
403
|
+
* ```
|
|
404
|
+
*
|
|
405
|
+
* @param options.mode What to pick first: `'actors'` in the world (the default) or `'widgets'` of the game's UI.
|
|
406
|
+
*/
|
|
407
|
+
inspect(options?: {
|
|
408
|
+
mode?: 'actors' | 'widgets';
|
|
409
|
+
}): Promise<void>;
|
|
391
410
|
console(commandString: string): Promise<void>;
|
|
392
411
|
/**
|
|
393
412
|
* Adjusts the global time dilation of the Unreal Engine.
|
|
@@ -750,6 +750,46 @@ class SpecterWorld {
|
|
|
750
750
|
return new locators_1.SpecterLocator(this.transport, [{ action: 'getUObject', value: className }]);
|
|
751
751
|
}
|
|
752
752
|
// --- Global Commands ---
|
|
753
|
+
/**
|
|
754
|
+
* Pauses the test and opens the in-game inspector, the way `page.pause()` opens Playwright's inspector.
|
|
755
|
+
*
|
|
756
|
+
* The game stays exactly as the test left it. Click actors or widgets in the game view to get locators
|
|
757
|
+
* for them, checked against the live game, along with their tags, attributes and components. The test
|
|
758
|
+
* carries on when you close the inspector. Its timeout is switched off while you look around.
|
|
759
|
+
*
|
|
760
|
+
* For writing and debugging tests on your own machine: it does nothing on CI.
|
|
761
|
+
*
|
|
762
|
+
* ```ts
|
|
763
|
+
* const steel = await server.heroes.steel.spawn({ ... });
|
|
764
|
+
* await world.inspect(); // look around, copy a locator, close the inspector to continue
|
|
765
|
+
* ```
|
|
766
|
+
*
|
|
767
|
+
* @param options.mode What to pick first: `'actors'` in the world (the default) or `'widgets'` of the game's UI.
|
|
768
|
+
*/
|
|
769
|
+
async inspect(options = {}) {
|
|
770
|
+
if (process.env.CI) {
|
|
771
|
+
return;
|
|
772
|
+
}
|
|
773
|
+
await test_1.default.step(`${this.transport.friendlyPortTag}inspect (waiting for the inspector to be closed)`, async () => {
|
|
774
|
+
// You decide how long this takes, so the test can't time out while it waits
|
|
775
|
+
test_1.default.setTimeout(0);
|
|
776
|
+
let onClosed = () => { };
|
|
777
|
+
const closed = new Promise((resolve) => {
|
|
778
|
+
onClosed = () => resolve();
|
|
779
|
+
});
|
|
780
|
+
this.transport.registerEventListener('GLOBAL_inspector-closed', onClosed);
|
|
781
|
+
try {
|
|
782
|
+
await this.transport.sendCommand({
|
|
783
|
+
command: 'OpenInspector',
|
|
784
|
+
payload: { mode: options.mode ?? 'actors' }
|
|
785
|
+
});
|
|
786
|
+
await closed;
|
|
787
|
+
}
|
|
788
|
+
finally {
|
|
789
|
+
this.transport.removeEventListener('GLOBAL_inspector-closed', onClosed);
|
|
790
|
+
}
|
|
791
|
+
});
|
|
792
|
+
}
|
|
753
793
|
async console(commandString) {
|
|
754
794
|
await test_1.default.step(`Specter Console: ${commandString}`, async () => {
|
|
755
795
|
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) {
|