@specter-automation/test 1.0.124 → 1.0.126

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.
@@ -503,7 +503,7 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
503
503
  getByComponent<K extends keyof ComponentLocatorMap | RegisteredComponentClasses | (string & {})>(componentType: K, options?: {
504
504
  name?: string;
505
505
  className?: string;
506
- }): K extends keyof ComponentLocatorMap ? ComponentLocatorMap[K] : SpecterLocator;
506
+ }): K extends keyof ComponentLocatorMap ? ComponentLocatorMap[K] : SpecterLocator<K>;
507
507
  /**
508
508
  * Scopes locator to a UMG Widget hosted on this actor (via a UWidgetComponent or widget property).
509
509
  * If no class name is provided, matches any widget hosted on this actor (e.g. floating health bar).
@@ -76,7 +76,6 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
76
76
  await this.callFunction("K2_SetActorLocation", {
77
77
  NewLocation: { X: location.x, Y: location.y, Z: location.z },
78
78
  bSweep: false,
79
- SweepHitResult: {},
80
79
  bTeleport: true
81
80
  });
82
81
  }
@@ -20,6 +20,8 @@ export interface FilterOptions {
20
20
  possessed?: boolean;
21
21
  playerControlled?: boolean;
22
22
  }
23
+ export type AreAllKeysOptional<A> = {} extends A ? true : false;
24
+ export type FunctionArgsTuple<A> = A extends Record<string, never> ? [] : AreAllKeysOptional<A> extends true ? [args?: A] : [args: A];
23
25
  export declare class SpecterLocator<T = any> {
24
26
  pipeline: LocatorStep[];
25
27
  protected transport: SpecterTransport;
@@ -65,13 +67,14 @@ export declare class SpecterLocator<T = any> {
65
67
  toSelectorString(): string;
66
68
  toString(): string;
67
69
  /**
68
- * The "Generic Bridge": Calls any C++ command and returns the raw data.
70
+ * Calls a reflected Unreal Engine C++ / Blueprint UFUNCTION on this entity.
71
+ * Argument types, required vs optional parameters, and return types are strictly validated.
69
72
  */
70
- callFunction<F extends (T extends keyof SpecterFunctionRegistry ? keyof SpecterFunctionRegistry[T] : string)>(functionName: F, ...args: T extends keyof SpecterFunctionRegistry ? (F extends keyof SpecterFunctionRegistry[T] ? (SpecterFunctionRegistry[T][F] extends {
73
+ callFunction: (T extends keyof SpecterFunctionRegistry ? ('callFunction' extends keyof SpecterFunctionRegistry[T] ? SpecterFunctionRegistry[T]['callFunction'] : <F extends (keyof SpecterFunctionRegistry[T] | (string & {}))>(functionName: F, ...args: F extends keyof SpecterFunctionRegistry[T] ? (SpecterFunctionRegistry[T][F] extends {
71
74
  args: infer A;
72
- } ? (A extends Record<string, never> ? [] : [A]) : [Record<string, any>?]) : [Record<string, any>?]) : [Record<string, any>?]): Promise<T extends keyof SpecterFunctionRegistry ? (F extends keyof SpecterFunctionRegistry[T] ? (SpecterFunctionRegistry[T][F] extends {
75
+ } ? FunctionArgsTuple<A> : [Record<string, any>?]) : [Record<string, any>?]) => Promise<F extends keyof SpecterFunctionRegistry[T] ? (SpecterFunctionRegistry[T][F] extends {
73
76
  returnType: infer R;
74
- } ? R : any) : any) : any>;
77
+ } ? R : any) : any>) : (functionName: string, ...args: any[]) => Promise<any>);
75
78
  /**
76
79
  * Alias for `callFunction`. Calls a C++ UFUNCTION and returns the result.
77
80
  */
@@ -211,17 +211,51 @@ class SpecterLocator {
211
211
  // THE "ENTITY" METHODS
212
212
  // ==========================================
213
213
  /**
214
- * The "Generic Bridge": Calls any C++ command and returns the raw data.
214
+ * Calls a reflected Unreal Engine C++ / Blueprint UFUNCTION on this entity.
215
+ * Argument types, required vs optional parameters, and return types are strictly validated.
215
216
  */
216
- async callFunction(functionName, ...args) {
217
+ callFunction = (async (functionName, ...args) => {
217
218
  const payloadArgs = args.length > 0 ? args[0] : {};
218
219
  // Explicitly map args to the 'parameters' key!
219
220
  const response = await this.evaluate("CallFunction", {
220
221
  functionName: functionName,
221
222
  parameters: payloadArgs
222
223
  }, functionName);
223
- return response.data?.ReturnValue || response.data?.returnValue || response.data;
224
- }
224
+ const data = response?.data;
225
+ if (!data || typeof data !== 'object') {
226
+ return data;
227
+ }
228
+ const unpackValue = (val) => {
229
+ if (val && typeof val === 'object' && val.__specterLocator) {
230
+ let loc;
231
+ if (val.locatorKind === 'component' && Array.isArray(val.pipeline) && this.pipeline.length > 0) {
232
+ loc = new SpecterLocator(this.transport, [...this.pipeline, ...val.pipeline]);
233
+ }
234
+ else {
235
+ loc = new SpecterLocator(this.transport, val.pipeline ?? []);
236
+ }
237
+ loc.objectName = val.objectName;
238
+ loc.name = val.objectName;
239
+ loc.className = val.className;
240
+ loc.toString = () => val.objectName;
241
+ loc.valueOf = () => val.objectName;
242
+ return loc;
243
+ }
244
+ return val;
245
+ };
246
+ const keys = Object.keys(data);
247
+ if (keys.length === 1 && (keys[0] === 'ReturnValue' || keys[0] === 'returnValue')) {
248
+ return unpackValue(data[keys[0]]);
249
+ }
250
+ if (keys.length === 0) {
251
+ return undefined;
252
+ }
253
+ const unpackedResult = {};
254
+ for (const k of keys) {
255
+ unpackedResult[k] = unpackValue(data[k]);
256
+ }
257
+ return unpackedResult;
258
+ });
225
259
  /**
226
260
  * Alias for `callFunction`. Calls a C++ UFUNCTION and returns the result.
227
261
  */
@@ -160,6 +160,33 @@ export interface Transform {
160
160
  rotation?: Rotator;
161
161
  scale?: Vector3;
162
162
  }
163
+ export interface HitResult {
164
+ bblockinghit?: boolean;
165
+ bstartpenetrating?: boolean;
166
+ time?: number;
167
+ distance?: number;
168
+ location?: Vector3;
169
+ impactpoint?: Vector3;
170
+ normal?: Vector3;
171
+ impactnormal?: Vector3;
172
+ tracestart?: Vector3;
173
+ traceend?: Vector3;
174
+ penetrationdepth?: number;
175
+ item?: number;
176
+ physmaterial?: string;
177
+ bBlockingHit?: boolean;
178
+ bStartPenetrating?: boolean;
179
+ Time?: number;
180
+ Distance?: number;
181
+ Location?: Vector3;
182
+ ImpactPoint?: Vector3;
183
+ Normal?: Vector3;
184
+ ImpactNormal?: Vector3;
185
+ TraceStart?: Vector3;
186
+ TraceEnd?: Vector3;
187
+ PenetrationDepth?: number;
188
+ [key: string]: any;
189
+ }
163
190
  export interface SpawnOptions {
164
191
  tag?: string;
165
192
  location?: Vector3;
@@ -347,11 +374,19 @@ export declare class SpecterWorld {
347
374
  setTimeScale(multiplier: number): Promise<void>;
348
375
  /**
349
376
  * Captures a screenshot of the active Unreal Engine viewport.
377
+ *
378
+ * The image is attached to the current step, so it shows in Playwright's report and in the
379
+ * in-engine runner next to the step that took it.
350
380
  * @param fileName The name of the saved file.
351
381
  * @param showUI Whether to render the UMG/Slate UI layer into the screenshot (defaults to false).
382
+ * @param options.attachmentName Name shown for the attachment (defaults to the file name).
383
+ * @param options.attach Set to false to only save the file, without attaching it.
352
384
  * @returns The absolute file path where the image was saved on disk.
353
385
  */
354
- takeScreenshot(fileName: string, showUI?: boolean): Promise<string>;
386
+ takeScreenshot(fileName: string, showUI?: boolean, options?: {
387
+ attachmentName?: string;
388
+ attach?: boolean;
389
+ }): Promise<string>;
355
390
  /**
356
391
  * Injects an analog axis value into the global Player Controller (e.g., thumbsticks, triggers).
357
392
  * @param key Unreal Engine Key Name (e.g., "Gamepad_LeftY")
@@ -726,18 +726,34 @@ class SpecterWorld {
726
726
  }
727
727
  /**
728
728
  * Captures a screenshot of the active Unreal Engine viewport.
729
+ *
730
+ * The image is attached to the current step, so it shows in Playwright's report and in the
731
+ * in-engine runner next to the step that took it.
729
732
  * @param fileName The name of the saved file.
730
733
  * @param showUI Whether to render the UMG/Slate UI layer into the screenshot (defaults to false).
734
+ * @param options.attachmentName Name shown for the attachment (defaults to the file name).
735
+ * @param options.attach Set to false to only save the file, without attaching it.
731
736
  * @returns The absolute file path where the image was saved on disk.
732
737
  */
733
- async takeScreenshot(fileName, showUI = false) {
738
+ async takeScreenshot(fileName, showUI = false, options = {}) {
734
739
  let savedPath = '';
735
740
  await test_1.default.step(`Specter: Capturing Screenshot [${fileName}] (UI: ${showUI})`, async () => {
736
741
  const response = await this.evaluate('TakeScreenshot', { fileName, showUI });
737
742
  savedPath = response.data.savedPath;
738
- // CRITICAL BUFFER: Unreal captures the screen at the end of the render frame.
739
- // Give the engine's file system 500ms to actually write the .png to disk.
740
- await new Promise(resolve => setTimeout(resolve, 500));
743
+ // The engine replies once the .png is on disk. Older plugin versions reply as soon as the
744
+ // capture is queued, so give those the time they need to finish writing it.
745
+ if (!response.data.written) {
746
+ await new Promise(resolve => setTimeout(resolve, 500));
747
+ }
748
+ if (options.attach !== false && savedPath) {
749
+ try {
750
+ // Lands on this step; Playwright copies the file into the test's output when it is attached
751
+ test_1.default.info().attachments.push({ name: options.attachmentName ?? fileName, path: savedPath, contentType: 'image/png' });
752
+ }
753
+ catch {
754
+ // Called outside a running test: nothing to attach to
755
+ }
756
+ }
741
757
  });
742
758
  return savedPath;
743
759
  }
@@ -7,6 +7,10 @@ export default class SpecterReporter implements Reporter {
7
7
  private stepIdMap;
8
8
  /** Playwright's outer `Expect "<matcher>"` steps for Specter matchers. They are shown under their wrapper step's name. */
9
9
  private specterExpectSteps;
10
+ /** Image paths already sent to the runner, per test, so step and test attachments aren't sent twice. */
11
+ private sentImages;
12
+ /** The step each test failed at (the first failing step outside hooks), so the failure screenshot can sit next to it. */
13
+ private failedSteps;
10
14
  constructor();
11
15
  private connect;
12
16
  private send;
@@ -22,6 +26,14 @@ export default class SpecterReporter implements Reporter {
22
26
  private locationOf;
23
27
  private customStepDurations;
24
28
  onStepEnd(test: TestCase, result: TestResult, step: TestStep): void;
29
+ private isInsideHook;
30
+ /** The runner row an attachment belongs to: the nearest step (or ancestor) the runner shows. */
31
+ private rowForStep;
32
+ /** Images attached to a step, sent to the runner so it can show them next to the step. */
33
+ private forwardStepImages;
34
+ private sendImage;
35
+ /** Images attached as a buffer have no file yet: write one the runner can read. */
36
+ private writeImageBody;
25
37
  private formatError;
26
38
  onStdOut(chunk: string | Buffer, test: void | TestCase, result: void | TestResult): void;
27
39
  onStdErr(chunk: string | Buffer, test: void | TestCase, result: void | TestResult): void;
@@ -37,7 +37,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
37
37
  };
38
38
  Object.defineProperty(exports, "__esModule", { value: true });
39
39
  const ws_1 = __importDefault(require("ws"));
40
+ const crypto_1 = __importDefault(require("crypto"));
40
41
  const fs = __importStar(require("fs"));
42
+ const os = __importStar(require("os"));
43
+ const path = __importStar(require("path"));
41
44
  const specter_matcher_report_1 = require("./specter-matcher-report");
42
45
  function extractLocatorFromExpectTitle(title) {
43
46
  if (!title.startsWith('expect('))
@@ -97,6 +100,10 @@ class SpecterReporter {
97
100
  stepIdMap = new WeakMap();
98
101
  /** Playwright's outer `Expect "<matcher>"` steps for Specter matchers. They are shown under their wrapper step's name. */
99
102
  specterExpectSteps = new WeakSet();
103
+ /** Image paths already sent to the runner, per test, so step and test attachments aren't sent twice. */
104
+ sentImages = new Map();
105
+ /** The step each test failed at (the first failing step outside hooks), so the failure screenshot can sit next to it. */
106
+ failedSteps = new Map();
100
107
  constructor() {
101
108
  this.connect();
102
109
  }
@@ -245,6 +252,7 @@ class SpecterReporter {
245
252
  customStepDurations = new WeakMap();
246
253
  onStepEnd(test, result, step) {
247
254
  const uniqueTestKey = `${test.parent.title} > ${test.title}`;
255
+ this.forwardStepImages(uniqueTestKey, step);
248
256
  // 1. The wrapper's timing is reported by its outer expect step, which ends right after it
249
257
  if (this.isSpecterWrapper(step) || (step.category === 'test.step' && step.title.startsWith('expect('))) {
250
258
  if (step.parent) {
@@ -277,6 +285,10 @@ class SpecterReporter {
277
285
  if (this.customStepDurations.has(step)) {
278
286
  duration = this.customStepDurations.get(step);
279
287
  }
288
+ if (step.error && !this.failedSteps.has(uniqueTestKey) && !this.isInsideHook(step)) {
289
+ // Steps end innermost first, so the first one to fail is where the test failed
290
+ this.failedSteps.set(uniqueTestKey, { stepName: uniqueStepName, parentStepName: this.getParentStepName(step) });
291
+ }
280
292
  const payload = {
281
293
  testName: uniqueTestKey,
282
294
  stepName: uniqueStepName,
@@ -307,6 +319,80 @@ class SpecterReporter {
307
319
  payload
308
320
  });
309
321
  }
322
+ isInsideHook(step) {
323
+ for (let current = step; current; current = current.parent) {
324
+ if (current.category === 'hook')
325
+ return true;
326
+ }
327
+ return false;
328
+ }
329
+ /** The runner row an attachment belongs to: the nearest step (or ancestor) the runner shows. */
330
+ rowForStep(step) {
331
+ for (let current = step; current; current = current.parent) {
332
+ if (!this.stepIdMap.has(current))
333
+ continue;
334
+ // A matcher wrapper stands in for its outer expect step, which owns the row
335
+ const owner = this.isSpecterWrapper(current) ? current.parent : current;
336
+ return { stepName: this.stepIdMap.get(owner) || owner.title, parentStepName: this.getParentStepName(owner) };
337
+ }
338
+ return undefined;
339
+ }
340
+ /** Images attached to a step, sent to the runner so it can show them next to the step. */
341
+ forwardStepImages(testKey, step) {
342
+ const images = (step.attachments || []).filter(a => a.contentType.startsWith('image/'));
343
+ if (images.length === 0)
344
+ return;
345
+ // Screenshots taken while tearing down a failed test (like the automatic failure screenshot)
346
+ // belong with the step that failed, not with the hook that took them.
347
+ const failed = this.isInsideHook(step) ? this.failedSteps.get(testKey) : undefined;
348
+ const row = failed ?? this.rowForStep(step) ?? { stepName: '', parentStepName: '' };
349
+ for (const image of images) {
350
+ this.sendImage(testKey, image, row.stepName, row.parentStepName);
351
+ }
352
+ }
353
+ sendImage(testKey, attachment, stepName, parentStepName) {
354
+ const imagePath = attachment.path ?? this.writeImageBody(attachment);
355
+ if (!imagePath)
356
+ return;
357
+ let sent = this.sentImages.get(testKey);
358
+ if (!sent) {
359
+ sent = new Set();
360
+ this.sentImages.set(testKey, sent);
361
+ }
362
+ if (sent.has(imagePath))
363
+ return;
364
+ sent.add(imagePath);
365
+ this.send({
366
+ event: 'attachment',
367
+ payload: {
368
+ testName: testKey,
369
+ stepName,
370
+ parentStepName,
371
+ name: attachment.name,
372
+ contentType: attachment.contentType,
373
+ path: path.resolve(imagePath)
374
+ }
375
+ });
376
+ }
377
+ /** Images attached as a buffer have no file yet: write one the runner can read. */
378
+ writeImageBody(attachment) {
379
+ if (!attachment.body)
380
+ return undefined;
381
+ try {
382
+ const extension = attachment.contentType.split('/')[1]?.split('+')[0] || 'png';
383
+ const hash = crypto_1.default.createHash('sha1').update(attachment.body).digest('hex');
384
+ const directory = path.join(os.tmpdir(), 'specter-attachments');
385
+ fs.mkdirSync(directory, { recursive: true });
386
+ const filePath = path.join(directory, `${hash}.${extension}`);
387
+ if (!fs.existsSync(filePath)) {
388
+ fs.writeFileSync(filePath, attachment.body);
389
+ }
390
+ return filePath;
391
+ }
392
+ catch {
393
+ return undefined;
394
+ }
395
+ }
310
396
  formatError(error, result) {
311
397
  let rawMessage = error.message || '';
312
398
  let rawStack = error.stack || '';
@@ -448,6 +534,15 @@ class SpecterReporter {
448
534
  }
449
535
  onTestEnd(test, result) {
450
536
  const uniqueTestKey = `${test.parent.title} > ${test.title}`;
537
+ // Images attached to the test itself rather than a step (sendImage skips ones already sent)
538
+ const failed = this.failedSteps.get(uniqueTestKey);
539
+ for (const attachment of result.attachments) {
540
+ if (attachment.contentType.startsWith('image/')) {
541
+ this.sendImage(uniqueTestKey, attachment, failed?.stepName ?? '', failed?.parentStepName ?? '');
542
+ }
543
+ }
544
+ this.sentImages.delete(uniqueTestKey);
545
+ this.failedSteps.delete(uniqueTestKey);
451
546
  this.send({
452
547
  event: 'test_ended',
453
548
  payload: {
@@ -193,12 +193,8 @@ exports.test = test_1.test.extend({
193
193
  if (testInfo.status !== 'passed' && testInfo.status !== 'skipped') {
194
194
  const safeName = `Specter_Fail_${testInfo.title.replace(/[^a-zA-Z0-9]/g, '_')}`;
195
195
  try {
196
- const imagePath = await world.takeScreenshot(safeName, true);
197
- testInfo.attachments.push({
198
- name: 'Unreal Engine Viewport',
199
- path: imagePath,
200
- contentType: 'image/png'
201
- });
196
+ // Attached by takeScreenshot itself
197
+ await world.takeScreenshot(safeName, true, { attachmentName: 'Unreal Engine Viewport' });
202
198
  }
203
199
  catch (e) {
204
200
  console.error("[Specter] Failed to capture error screenshot:", e);
package/dist/index.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  export { test, expect } from './core/test-wrapper';
2
2
  export { SpecterTransport, SpecterWorld, VectorUtils } from './core/specter-client';
3
- export type { SpecterPayload, SpawnOptions, Vector3, Rotator, LinearColor, Color, Vector2D, SpecterRegistry, SpecterFunctionRegistry, LoadMapOptions, SpecterGrantedAbility, SpecterActiveEffect, SpecterActorSnapshot, RegisteredGameplayTags } from './core/specter-client';
3
+ export type { SpecterPayload, SpawnOptions, Vector3, Rotator, Transform, HitResult, LinearColor, Color, Vector2D, SpecterRegistry, SpecterFunctionRegistry, LoadMapOptions, SpecterGrantedAbility, SpecterActiveEffect, SpecterActorSnapshot, RegisteredGameplayTags } from './core/specter-client';
4
4
  export { SpecterLocator, WidgetLocator, ActorLocator, AiControllerLocator, type WidgetGeometry } from './core/locators';
5
5
  export { default as SpecterReporter } from './core/specter-reporter';
6
6
  export { expectAll } from './core/expect-all';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.124",
3
+ "version": "1.0.126",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",