@specter-automation/test 1.0.123 → 1.0.125

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.
@@ -155,7 +155,7 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
155
155
  */
156
156
  unpossess(): Promise<void>;
157
157
  getAttributeValue(attributeSet: string, attributeName: string): Promise<number>;
158
- hasGameplayTag(tag: RegisteredGameplayTags): Promise<boolean>;
158
+ hasGameplayTag(tag: RegisteredGameplayTags, bHideStep?: boolean): Promise<boolean>;
159
159
  /**
160
160
  * Waits for a Gameplay Tag to be added or removed.
161
161
  */
@@ -434,9 +434,9 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
434
434
  getAttributeBaseValue(attributeSet: string, attributeName: string): Promise<number>;
435
435
  isAbilityExecuting(abilityOrClassPath: string): Promise<boolean>;
436
436
  cancelAbility(abilityOrTagOrClassPath: RegisteredGameplayTags): Promise<void>;
437
- getGameplayTagCount(tag: RegisteredGameplayTags): Promise<number>;
438
- hasAnyGameplayTags(tags: RegisteredGameplayTags[]): Promise<boolean>;
439
- hasAllGameplayTags(tags: RegisteredGameplayTags[]): Promise<boolean>;
437
+ getGameplayTagCount(tag: RegisteredGameplayTags, bHideStep?: boolean): Promise<number>;
438
+ hasAnyGameplayTags(tags: RegisteredGameplayTags[], bHideStep?: boolean): Promise<boolean>;
439
+ hasAllGameplayTags(tags: RegisteredGameplayTags[], bHideStep?: boolean): Promise<boolean>;
440
440
  getVelocitySize(): Promise<number>;
441
441
  isFalling(): Promise<boolean>;
442
442
  isCrouching(): Promise<boolean>;
@@ -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
  }
@@ -396,9 +395,9 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
396
395
  const response = await this.evaluate("GetAttributeValue", { attributeSet, attributeName }, attributeName);
397
396
  return parseFloat(response.data.value);
398
397
  }
399
- async hasGameplayTag(tag) {
400
- const response = await this.evaluate("HasGameplayTag", { tag });
401
- return response.data.hasTag;
398
+ async hasGameplayTag(tag, bHideStep = false) {
399
+ const response = await this.evaluate("HasGameplayTag", { tag }, tag, bHideStep);
400
+ return response.data?.hasTag ?? false;
402
401
  }
403
402
  /**
404
403
  * Waits for a Gameplay Tag to be added or removed.
@@ -408,30 +407,58 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
408
407
  const { SpecterEventType } = await Promise.resolve().then(() => __importStar(require('../specter-client')));
409
408
  return await test.step(`Specter: Wait For Tag [${tag} == ${expectedState}]`, async () => {
410
409
  const locatorId = this.resolvedPath;
411
- const response = await this.evaluate("TrackGameplayTag", { tag, locatorId });
412
- let hasTag = response.data.hasTag;
410
+ const targetName = await this.getObjectName().catch(() => undefined);
411
+ const response = await this.evaluate("TrackGameplayTag", { tag, locatorId }, undefined, true);
412
+ let hasTag = response.data?.hasTag;
413
413
  if (hasTag === expectedState) {
414
414
  return hasTag;
415
415
  }
416
416
  return await new Promise((resolve, reject) => {
417
417
  let timeoutId;
418
+ let isResolved = false;
419
+ const cleanup = () => {
420
+ if (isResolved)
421
+ return;
422
+ isResolved = true;
423
+ clearTimeout(timeoutId);
424
+ this.transport.removeEventListener('GLOBAL_timeline-event', listener);
425
+ };
418
426
  const listener = (event) => {
419
- if (event.eventType === SpecterEventType.GameplayTag &&
420
- event.eventName === tag &&
421
- event.description === locatorId) {
422
- const isTagPresent = event.newValue === 'true';
423
- if (isTagPresent === expectedState) {
424
- clearTimeout(timeoutId);
425
- this.transport.removeEventListener('GLOBAL_timeline-event', listener);
426
- resolve(isTagPresent);
427
+ if (isResolved)
428
+ return;
429
+ if (event.eventType !== SpecterEventType.GameplayTag && event.eventType !== 'GameplayTag') {
430
+ return;
431
+ }
432
+ const name = event.eventName || '';
433
+ const desc = event.description || '';
434
+ if (!name.includes(tag) && !desc.includes(tag)) {
435
+ return;
436
+ }
437
+ if (targetName) {
438
+ const evTarget = (event.target || '').trim();
439
+ if (evTarget && !evTarget.includes(targetName) && !targetName.includes(evTarget)) {
440
+ return;
427
441
  }
428
442
  }
443
+ const isAdded = name.startsWith('Added') || event.newValue === 'true' || parseInt(event.newValue || '0') > 0;
444
+ if (isAdded === expectedState) {
445
+ cleanup();
446
+ resolve(isAdded);
447
+ }
429
448
  };
430
- timeoutId = setTimeout(() => {
431
- this.transport.removeEventListener('GLOBAL_timeline-event', listener);
449
+ this.transport.registerEventListener('GLOBAL_timeline-event', listener);
450
+ timeoutId = setTimeout(async () => {
451
+ cleanup();
452
+ try {
453
+ const finalCheck = await this.hasGameplayTag(tag, true);
454
+ if (finalCheck === expectedState) {
455
+ resolve(finalCheck);
456
+ return;
457
+ }
458
+ }
459
+ catch { }
432
460
  reject(new Error(`Timed out after ${timeout}ms waiting for GAS Tag '${tag}' to be '${expectedState}'.`));
433
461
  }, timeout);
434
- this.transport.registerEventListener('GLOBAL_timeline-event', listener);
435
462
  });
436
463
  });
437
464
  }
@@ -1049,17 +1076,17 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
1049
1076
  abilityClassPath: abilityOrTagOrClassPath
1050
1077
  });
1051
1078
  }
1052
- async getGameplayTagCount(tag) {
1053
- const response = await this.evaluate("GetGameplayTagCount", { tag });
1054
- return response.data.count;
1079
+ async getGameplayTagCount(tag, bHideStep = false) {
1080
+ const response = await this.evaluate("GetGameplayTagCount", { tag }, tag, bHideStep);
1081
+ return response.data?.count ?? 0;
1055
1082
  }
1056
- async hasAnyGameplayTags(tags) {
1057
- const response = await this.evaluate("HasAnyGameplayTags", { tags });
1058
- return response.data.hasAny;
1083
+ async hasAnyGameplayTags(tags, bHideStep = false) {
1084
+ const response = await this.evaluate("HasAnyGameplayTags", { tags }, undefined, bHideStep);
1085
+ return response.data?.hasAny ?? false;
1059
1086
  }
1060
- async hasAllGameplayTags(tags) {
1061
- const response = await this.evaluate("HasAllGameplayTags", { tags });
1062
- return response.data.hasAll;
1087
+ async hasAllGameplayTags(tags, bHideStep = false) {
1088
+ const response = await this.evaluate("HasAllGameplayTags", { tags }, undefined, bHideStep);
1089
+ return response.data?.hasAll ?? false;
1063
1090
  }
1064
1091
  async getVelocitySize() {
1065
1092
  const response = await this.evaluate("GetVelocitySize", {});
@@ -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,18 +67,19 @@ 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<F extends (T extends keyof SpecterFunctionRegistry ? (keyof SpecterFunctionRegistry[T] | (string & {})) : string)>(functionName: F, ...args: T extends keyof SpecterFunctionRegistry ? (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>?]) : [Record<string, any>?]): Promise<T extends keyof SpecterFunctionRegistry ? (F extends keyof SpecterFunctionRegistry[T] ? (SpecterFunctionRegistry[T][F] extends {
73
76
  returnType: infer R;
74
77
  } ? R : any) : any) : any>;
75
78
  /**
76
79
  * Alias for `callFunction`. Calls a C++ UFUNCTION and returns the result.
77
80
  */
78
81
  callFunctionWithReturn(functionName: string, parameters?: Record<string, any>): Promise<any>;
79
- hasGameplayTag(tagToCheck: string): Promise<boolean>;
82
+ hasGameplayTag(tagToCheck: string, bHideStep?: boolean): Promise<boolean>;
80
83
  getObjectName(): Promise<string>;
81
84
  getPropertyValue(propertyName: string): Promise<any>;
82
85
  getMaterialScalarParameter(parameterName: string, options?: {
@@ -211,7 +211,8 @@ 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
217
  async callFunction(functionName, ...args) {
217
218
  const payloadArgs = args.length > 0 ? args[0] : {};
@@ -220,7 +221,40 @@ class SpecterLocator {
220
221
  functionName: functionName,
221
222
  parameters: payloadArgs
222
223
  }, functionName);
223
- return response.data?.ReturnValue || response.data?.returnValue || response.data;
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;
224
258
  }
225
259
  /**
226
260
  * Alias for `callFunction`. Calls a C++ UFUNCTION and returns the result.
@@ -228,9 +262,9 @@ class SpecterLocator {
228
262
  async callFunctionWithReturn(functionName, parameters) {
229
263
  return this.callFunction(functionName, parameters);
230
264
  }
231
- async hasGameplayTag(tagToCheck) {
232
- const response = await this.evaluate("HasGameplayTag", { tag: tagToCheck }, tagToCheck);
233
- return response.data.hasTag === true;
265
+ async hasGameplayTag(tagToCheck, bHideStep = false) {
266
+ const response = await this.evaluate("HasGameplayTag", { tag: tagToCheck }, tagToCheck, bHideStep);
267
+ return response.data?.hasTag === true;
234
268
  }
235
269
  async getObjectName() {
236
270
  const response = await this.evaluate("GetObjectName", {}, undefined, true);
@@ -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';
@@ -80,9 +80,6 @@ declare global {
80
80
  toBeAINavigating(options?: {
81
81
  timeout?: number;
82
82
  }): T extends ActorLocator ? Promise<R> : never;
83
- toHaveGameplayTag(expectedTag: string, options?: {
84
- timeout?: number;
85
- }): T extends ActorLocator ? Promise<R> : never;
86
83
  toHaveTeamId(expectedTeamId: number, options?: {
87
84
  timeout?: number;
88
85
  }): T extends ActorLocator ? Promise<R> : never;
@@ -167,9 +164,6 @@ export interface ActorMatchers {
167
164
  toBeAINavigating(options?: {
168
165
  timeout?: number;
169
166
  }): Promise<void>;
170
- toHaveGameplayTag(expectedTag: string, options?: {
171
- timeout?: number;
172
- }): Promise<void>;
173
167
  toHaveTeamId(expectedTeamId: number, options?: {
174
168
  timeout?: number;
175
169
  }): Promise<void>;
@@ -397,12 +391,6 @@ export declare const actorExpect: import("playwright/test").Expect<{
397
391
  pass: boolean;
398
392
  message: () => string;
399
393
  }>;
400
- toHaveGameplayTag(this: import("playwright/test").ExpectMatcherState, locator: any, expectedTag: string, options?: {
401
- timeout?: number;
402
- }): Promise<{
403
- pass: boolean;
404
- message: () => string;
405
- }>;
406
394
  toHaveTeamId(this: import("playwright/test").ExpectMatcherState, locator: any, expectedTeamId: number, options?: {
407
395
  timeout?: number;
408
396
  }): Promise<{
@@ -405,26 +405,6 @@ exports.actorExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)(
405
405
  message: () => `Expected AI to${isNot ? ' not' : ''} be actively navigating on NavMesh, but it was${lastState ? '' : ' not'}.`
406
406
  };
407
407
  },
408
- async toHaveGameplayTag(locator, expectedTag, options) {
409
- const isNot = this.isNot;
410
- const timeout = options?.timeout ?? 5000;
411
- const startTime = Date.now();
412
- let lastHas = false;
413
- while (Date.now() - startTime < timeout) {
414
- try {
415
- lastHas = await locator.hasGameplayTag(expectedTag);
416
- if (lastHas === !isNot) {
417
- return { pass: !isNot, message: () => 'passed' };
418
- }
419
- }
420
- catch (e) { }
421
- await new Promise(r => setTimeout(r, 100));
422
- }
423
- return {
424
- pass: isNot,
425
- message: () => `Expected Actor to${isNot ? ' not' : ''} have Gameplay Tag "${expectedTag}", but it did${lastHas ? '' : ' not'}.`
426
- };
427
- },
428
408
  async toHaveTeamId(locator, expectedTeamId, options) {
429
409
  const isNot = this.isNot;
430
410
  const timeout = options?.timeout ?? 5000;
@@ -14,7 +14,9 @@ declare global {
14
14
  gameplayEffect?: string;
15
15
  ability?: string;
16
16
  }, triggerAction?: () => Promise<void>): T extends SpecterLocator ? Promise<R> : never;
17
- toHaveGameplayTag(tag: RegisteredGameplayTags): T extends SpecterLocator ? Promise<R> : never;
17
+ toHaveGameplayTag(tag: RegisteredGameplayTags, options?: {
18
+ timeout?: number;
19
+ }): T extends SpecterLocator ? Promise<R> : never;
18
20
  toHaveGameplayEffect(effectClassPath: string): T extends SpecterLocator ? Promise<R> : never;
19
21
  toHaveAppliedGameplayEffect(effectNameOrClass: string, options?: {
20
22
  count?: number;
@@ -57,7 +59,9 @@ export interface GasMatchers {
57
59
  timeout?: number;
58
60
  tolerance?: number;
59
61
  }, triggerAction?: () => Promise<void>): Promise<void>;
60
- toHaveGameplayTag(tag: RegisteredGameplayTags): Promise<void>;
62
+ toHaveGameplayTag(tag: RegisteredGameplayTags, options?: {
63
+ timeout?: number;
64
+ }): Promise<void>;
61
65
  toHaveGameplayEffect(effectClassPath: string): Promise<void>;
62
66
  toHaveAppliedGameplayEffect(effectNameOrClass: string, options?: {
63
67
  count?: number;
@@ -118,7 +122,9 @@ export declare const gasExpect: import("playwright/test").Expect<{
118
122
  tolerance?: number;
119
123
  };
120
124
  }>;
121
- toHaveGameplayTag(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, tag: RegisteredGameplayTags): Promise<{
125
+ toHaveGameplayTag(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, tag: RegisteredGameplayTags, options?: {
126
+ timeout?: number;
127
+ }): Promise<{
122
128
  pass: boolean;
123
129
  message: () => string;
124
130
  actual: boolean;
@@ -612,36 +612,165 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
612
612
  }
613
613
  })();
614
614
  },
615
- async toHaveGameplayTag(locator, tag) {
615
+ async toHaveGameplayTag(locator, tag, options) {
616
616
  const assertionName = 'toHaveGameplayTag';
617
617
  const isNot = this.isNot;
618
+ const timeout = options?.timeout ?? 5000;
618
619
  return await (async () => {
619
- const timeout = 5000;
620
- let hasTag = false;
620
+ const transport = locator.transport;
621
+ const causalityEvents = [];
622
+ let lastEvent;
623
+ let targetName;
624
+ // 1. Immediately register live listener to catch push events
625
+ const capturedEvents = [];
626
+ let onLiveEvent = null;
627
+ const liveListener = (event) => {
628
+ capturedEvents.push(event);
629
+ causalityEvents.push(event);
630
+ if (onLiveEvent) {
631
+ onLiveEvent(event);
632
+ }
633
+ };
634
+ if (transport && typeof transport.registerEventListener === 'function') {
635
+ transport.registerEventListener('GLOBAL_timeline-event', liveListener);
636
+ }
621
637
  try {
622
- hasTag = await locator.waitForGameplayTag(tag, !isNot, timeout);
638
+ // In parallel: resolve target name, track tag in C++, and check initial state
639
+ const [resolvedTargetName, initialHasTag] = await Promise.all([
640
+ locator.getObjectName().catch(() => undefined),
641
+ locator.hasGameplayTag(tag, true).catch(() => undefined),
642
+ locator.evaluate("TrackGameplayTag", { tag }, undefined, true).catch(() => undefined),
643
+ ]);
644
+ targetName = resolvedTargetName;
645
+ const evaluateEvent = (event) => {
646
+ if (event.eventType !== specter_client_1.SpecterEventType.GameplayTag && event.eventType !== 'GameplayTag') {
647
+ return false;
648
+ }
649
+ const name = event.eventName || '';
650
+ const desc = event.description || '';
651
+ const matchesTag = name === tag || name.includes(`[${tag}]`) || name.includes(tag) || desc.includes(tag);
652
+ if (!matchesTag) {
653
+ return false;
654
+ }
655
+ if (targetName) {
656
+ const evTarget = (event.target || '').trim();
657
+ if (evTarget && !evTarget.includes(targetName) && !targetName.includes(evTarget)) {
658
+ return false;
659
+ }
660
+ }
661
+ lastEvent = event;
662
+ const isAdded = name.startsWith('Added') || event.newValue === 'true' || parseInt(event.newValue || '0') > 0;
663
+ const isRemoved = name.startsWith('Removed') || event.newValue === 'false' || parseInt(event.newValue || '0') === 0;
664
+ if (!isNot && isAdded)
665
+ return true;
666
+ if (isNot && isRemoved)
667
+ return true;
668
+ return false;
669
+ };
670
+ // Check initial state
671
+ if (initialHasTag !== undefined && (initialHasTag === !isNot)) {
672
+ return {
673
+ pass: !isNot,
674
+ message: () => 'passed',
675
+ actual: initialHasTag,
676
+ expected: !isNot
677
+ };
678
+ }
679
+ // Check any events received during initial read
680
+ for (const ev of capturedEvents) {
681
+ if (evaluateEvent(ev)) {
682
+ return {
683
+ pass: !isNot,
684
+ message: () => 'passed',
685
+ actual: !isNot,
686
+ expected: !isNot
687
+ };
688
+ }
689
+ }
690
+ // Wait for live event
691
+ await new Promise((resolve, reject) => {
692
+ let timeoutId;
693
+ let isResolved = false;
694
+ const cleanup = () => {
695
+ if (isResolved)
696
+ return;
697
+ isResolved = true;
698
+ clearTimeout(timeoutId);
699
+ };
700
+ onLiveEvent = (event) => {
701
+ if (isResolved)
702
+ return;
703
+ if (evaluateEvent(event)) {
704
+ cleanup();
705
+ resolve();
706
+ }
707
+ };
708
+ timeoutId = setTimeout(async () => {
709
+ cleanup();
710
+ // One final check before giving up in case an event was missed
711
+ try {
712
+ const finalHasTag = await locator.hasGameplayTag(tag, true);
713
+ if (finalHasTag !== undefined && (finalHasTag === !isNot)) {
714
+ resolve();
715
+ return;
716
+ }
717
+ }
718
+ catch { }
719
+ reject(new Error(`Timed out after ${timeout}ms waiting for Gameplay Tag '${tag}' to be ${isNot ? 'removed from' : 'present on'} '${locator.toString()}'.`));
720
+ }, timeout);
721
+ });
623
722
  return {
624
723
  pass: !isNot,
625
724
  message: () => 'passed',
626
- actual: hasTag,
725
+ actual: !isNot,
627
726
  expected: !isNot
628
727
  };
629
728
  }
630
729
  catch (e) {
631
- if (!e.message.includes('Timed out')) {
730
+ if (!e.message?.includes('Timed out')) {
632
731
  throw e;
633
732
  }
634
- hasTag = isNot;
733
+ let diagStr = '';
734
+ try {
735
+ const diags = await locator.getDiagnostics({ limit: 20 });
736
+ diagStr = formatAiDiagnostics(diags);
737
+ if (diags?.flightRecorder && Array.isArray(diags.flightRecorder)) {
738
+ for (const ev of diags.flightRecorder) {
739
+ causalityEvents.push(ev);
740
+ }
741
+ }
742
+ }
743
+ catch { }
744
+ const timelineStr = formatCausalityTimeline(causalityEvents);
745
+ try {
746
+ const testInfo = test_1.default.info();
747
+ if (testInfo && timelineStr) {
748
+ testInfo.attachments.push({
749
+ name: 'Specter Causality Timeline',
750
+ contentType: 'text/markdown',
751
+ body: Buffer.from(timelineStr)
752
+ });
753
+ }
754
+ }
755
+ catch { }
635
756
  return {
636
757
  pass: isNot,
637
758
  message: () => `${this.utils.matcherHint(assertionName, locator.toString(), tag)}\n\n` +
638
- `Timed out after ${timeout}ms waiting for tag on "${locator.toString()}".\n` +
759
+ `Timed out after ${timeout}ms waiting for Gameplay Tag on "${locator.toString()}".\n` +
639
760
  `Expected: ${isNot ? 'not to have tag' : 'to have tag'} ${tag}\n` +
640
- `Received: ${hasTag ? 'has tag' : 'does not have tag'}`,
641
- actual: hasTag,
761
+ `Received: ${isNot ? 'has tag' : 'does not have tag'}\n` +
762
+ `Last matched event: ${lastEvent ? JSON.stringify(lastEvent, null, 2) : 'None'}` +
763
+ timelineStr +
764
+ diagStr,
765
+ actual: isNot,
642
766
  expected: !isNot
643
767
  };
644
768
  }
769
+ finally {
770
+ if (transport && typeof transport.removeEventListener === 'function') {
771
+ transport.removeEventListener('GLOBAL_timeline-event', liveListener);
772
+ }
773
+ }
645
774
  })();
646
775
  },
647
776
  async toHaveGameplayEffect(locator, effectClassPath) {
@@ -1365,7 +1494,7 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
1365
1494
  let count = 0;
1366
1495
  while (Date.now() - startTime < timeout) {
1367
1496
  try {
1368
- count = await locator.getGameplayTagCount(tag);
1497
+ count = await locator.getGameplayTagCount(tag, true);
1369
1498
  if ((count === expectedCount) === !isNot)
1370
1499
  return { pass: !isNot, message: () => 'passed' };
1371
1500
  }
@@ -1383,7 +1512,7 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
1383
1512
  let has = false;
1384
1513
  while (Date.now() - startTime < timeout) {
1385
1514
  try {
1386
- has = await locator.hasAnyGameplayTags(tags);
1515
+ has = await locator.hasAnyGameplayTags(tags, true);
1387
1516
  if (has === !isNot)
1388
1517
  return { pass: !isNot, message: () => 'passed' };
1389
1518
  }
@@ -1401,7 +1530,7 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
1401
1530
  let has = false;
1402
1531
  while (Date.now() - startTime < timeout) {
1403
1532
  try {
1404
- has = await locator.hasAllGameplayTags(tags);
1533
+ has = await locator.hasAllGameplayTags(tags, true);
1405
1534
  if (has === !isNot)
1406
1535
  return { pass: !isNot, message: () => 'passed' };
1407
1536
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.123",
3
+ "version": "1.0.125",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",