@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 two about the run's replay matter to the reporter.
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 two about the run's replay matter to the reporter.
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 === 'run-replay-started' && message.data.replayName) {
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) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.129",
3
+ "version": "1.0.130",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",