@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.
@@ -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
- strategy?: 'hardware' | 'broadcast' | 'function';
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 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.131",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",