@specter-automation/test 1.0.132 → 1.0.134

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.
@@ -375,7 +375,12 @@ export declare class SpecterWorld {
375
375
  * @param seconds In-game simulation seconds to wait.
376
376
  */
377
377
  waitForGameSeconds(seconds: number): Promise<void>;
378
- spawnActor(assetPath: string, options?: SpawnOptions): Promise<ActorLocator>;
378
+ /**
379
+ * Spawns an Actor in the active world by Blueprint name (e.g. `'BP_Hero_Steel'`),
380
+ * C++ class name (e.g. `'HotsHeroCharacter'`), or full asset path.
381
+ * Throws an error if multiple assets match the given short name.
382
+ */
383
+ spawnActor<T extends RegisteredActorClasses | (string & {})>(classNameOrAssetPath: T, options?: SpawnOptions): Promise<ActorLocator<T>>;
379
384
  actor<T extends RegisteredActorClasses | (string & {})>(selector: T): ActorLocator<T>;
380
385
  actorByTag(tagName: string): ActorLocator;
381
386
  /**
@@ -671,12 +671,18 @@ class SpecterWorld {
671
671
  await new Promise(resolve => setTimeout(resolve, wallClockMs));
672
672
  });
673
673
  }
674
- async spawnActor(assetPath, options) {
674
+ /**
675
+ * Spawns an Actor in the active world by Blueprint name (e.g. `'BP_Hero_Steel'`),
676
+ * C++ class name (e.g. `'HotsHeroCharacter'`), or full asset path.
677
+ * Throws an error if multiple assets match the given short name.
678
+ */
679
+ async spawnActor(classNameOrAssetPath, options) {
675
680
  // Generate a unique tag if the user didn't provide one
676
681
  const uniqueId = crypto_1.default.randomBytes(4).toString('hex');
677
682
  const tag = options?.tag || `Spawned_${uniqueId}`;
678
683
  const location = options?.location || { x: 0, y: 0, z: 0 };
679
684
  const rotation = options?.rotation || { pitch: 0, yaw: 0, roll: 0 };
685
+ const assetPath = String(classNameOrAssetPath);
680
686
  const assetName = assetPath.split('/').pop()?.split('.')[0];
681
687
  const properties = options?.properties;
682
688
  const spawnController = options?.spawnController;
@@ -1193,7 +1199,7 @@ class SpecterWorld {
1193
1199
  const portTag = this.transport.friendlyPortTag;
1194
1200
  const stepTitle = `${portTag}Measure performance: ${name}`;
1195
1201
  return await test_1.default.step(stepTitle, async () => {
1196
- await this.transport.sendCommand({ command: 'StartPerfCapture', payload: { name, hitchMs } });
1202
+ await this.transport.sendCommand({ command: 'StartPerfCapture', payload: { name, hitchMs, timelinePreview: options.timelinePreview ?? false } });
1197
1203
  let failed = false;
1198
1204
  let failure;
1199
1205
  try {
@@ -51,7 +51,7 @@ function isSpecterMatcher(name) {
51
51
  * Returns null for titles that are not a Specter matcher (built-ins, custom messages).
52
52
  */
53
53
  function parseSpecterExpectTitle(title) {
54
- const match = title.match(/^Expect "(?:poll )?(?:soft )?(not )?([A-Za-z]+)"$/);
54
+ const match = title.match(/^Expect "(?:poll )?(?:soft )?(not )?([A-Za-z][A-Za-z0-9]*)"$/);
55
55
  if (!match || !isSpecterMatcher(match[2])) {
56
56
  return null;
57
57
  }
@@ -18,9 +18,19 @@ export interface PerformanceHitch {
18
18
  gameMs: number;
19
19
  renderMs: number;
20
20
  gpuMs: number;
21
- /** Whichever took longest that frame: "Game thread", "Render thread" or "GPU". A hint for where to look. */
21
+ /** Slate's tick: UI layout and painting (in the editor, the whole editor UI). */
22
+ slateMs: number;
23
+ /** Time the game thread spent waiting for the render thread, the GPU, or a frame rate limit. */
24
+ gameThreadWaitMs: number;
25
+ /**
26
+ * Where the frame's time went, as a hint for where to look: "Game thread", "Game thread waiting", "Slate UI",
27
+ * "Render thread", "GPU", or "Unaccounted" when none of them explains most of the frame.
28
+ */
22
29
  bound: string;
23
- /** Garbage collection, level streaming and timeline events from that frame and the one before it. */
30
+ /**
31
+ * What happened in that frame or the one before it: garbage collection, level streaming, Specter commands,
32
+ * test steps, timeline preview frames, and the game's timeline events.
33
+ */
24
34
  events: string[];
25
35
  }
26
36
  /**
@@ -53,6 +63,19 @@ export interface PerformanceCapture {
53
63
  gameThreadMs: PerformanceStat;
54
64
  renderThreadMs: PerformanceStat;
55
65
  gpuMs: PerformanceStat;
66
+ /** Slate's tick: UI layout and painting (in the editor, the whole editor UI, the Specter runner included). */
67
+ slateMs: PerformanceStat;
68
+ /** Time the game thread spent waiting for the render thread, the GPU, or a frame rate limit. */
69
+ gameThreadWaitMs: PerformanceStat;
70
+ /**
71
+ * Whether the engine reported these at all during the capture. Some stay at 0 in places (the editor on some
72
+ * platforms), and a 0 that means "not measured" isn't shown or checked.
73
+ */
74
+ reported: {
75
+ renderThread: boolean;
76
+ gpu: boolean;
77
+ drawCalls: boolean;
78
+ };
56
79
  drawCalls: {
57
80
  avg: number;
58
81
  max: number;
@@ -75,6 +98,8 @@ export interface PerformanceCapture {
75
98
  gameMs: number[];
76
99
  renderMs: number[];
77
100
  gpuMs: number[];
101
+ slateMs: number[];
102
+ gameThreadWaitMs: number[];
78
103
  drawCalls: number[];
79
104
  memoryMb: number[];
80
105
  };
@@ -84,6 +109,11 @@ export interface MeasurePerformanceOptions {
84
109
  name?: string;
85
110
  /** Frames slower than this many milliseconds count as hitches. Default: 50. */
86
111
  hitchMs?: number;
112
+ /**
113
+ * Keep recording the runner's timeline preview frames while measuring. Default: false, so the preview's own
114
+ * cost isn't counted against the game. Turn it on to measure what the preview costs.
115
+ */
116
+ timelinePreview?: boolean;
87
117
  }
88
118
  export declare function isPerformanceCapture(value: unknown): value is PerformanceCapture;
89
119
  /** "112 ms at 4.20 s in the test (Game thread): Garbage collection (38.0 ms); GE Applied [Stun]" */
@@ -292,6 +292,10 @@ exports.performanceExpect = test_1.expect.extend((0, instrument_1.instrumentMatc
292
292
  },
293
293
  async toHaveDrawCallsBelow(receiver, maxDrawCalls, options) {
294
294
  const capture = requireCapture(receiver, 'toHaveDrawCallsBelow');
295
+ if (capture.reported && !capture.reported.drawCalls) {
296
+ throw new Error(`The engine didn't report draw calls during "${capture.name}" (they stayed at 0), so they can't be checked. ` +
297
+ `The editor doesn't fill them in on every platform: measure in a standalone or packaged build.`);
298
+ }
295
299
  const stat = options?.stat ?? 'avg';
296
300
  const actual = stat === 'max' ? capture.drawCalls.max : capture.drawCalls.avg;
297
301
  return captureCheck(this.isNot, capture, stat === 'max' ? 'most draw calls in a frame' : 'average draw calls a frame', actual <= maxDrawCalls, `<= ${maxDrawCalls}`, `${Math.round(actual)}`, actual, maxDrawCalls);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.132",
3
+ "version": "1.0.134",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",