@specter-automation/test 1.0.108 → 1.0.110

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.
@@ -425,4 +425,12 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
425
425
  * and optional accessible name.
426
426
  */
427
427
  getByRole(role: WidgetRole | string, options?: WidgetRoleOptions): WidgetLocator;
428
+ /**
429
+ * Fetches comprehensive AI diagnostics for this actor (and an optional instigator),
430
+ * including attribute snapshot, active gameplay tags, effects, identity, and flight recorder events.
431
+ */
432
+ getDiagnostics(options?: {
433
+ instigator?: ActorLocator | SpecterLocator;
434
+ limit?: number;
435
+ }): Promise<any>;
428
436
  }
@@ -851,6 +851,14 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
851
851
  let payload = { abilityTag };
852
852
  if (target instanceof specter_locator_1.SpecterLocator) {
853
853
  payload.targetLocatorPipeline = target.pipeline;
854
+ if (typeof target.getLocation === 'function') {
855
+ try {
856
+ payload.targetLocation = await target.getLocation();
857
+ }
858
+ catch {
859
+ // Fallback to server-side pipeline resolution if getLocation fails
860
+ }
861
+ }
854
862
  }
855
863
  else {
856
864
  payload.targetLocation = target;
@@ -1051,5 +1059,19 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
1051
1059
  { action: 'getWidgetByRole', value: rolePayload, exact: options?.exact }
1052
1060
  ]);
1053
1061
  }
1062
+ /**
1063
+ * Fetches comprehensive AI diagnostics for this actor (and an optional instigator),
1064
+ * including attribute snapshot, active gameplay tags, effects, identity, and flight recorder events.
1065
+ */
1066
+ async getDiagnostics(options) {
1067
+ const payload = {
1068
+ limit: options?.limit ?? 30,
1069
+ targetLocatorPipeline: this.pipeline
1070
+ };
1071
+ if (options?.instigator) {
1072
+ payload.instigatorLocatorPipeline = options.instigator.pipeline;
1073
+ }
1074
+ return await this.transport.sendCommand("GetActorDiagnostics", this.pipeline, payload);
1075
+ }
1054
1076
  }
1055
1077
  exports.ActorLocator = ActorLocator;
@@ -42,6 +42,60 @@ export interface SpecterTimelineEvent {
42
42
  effectCauser?: string;
43
43
  gameplayEffect?: string;
44
44
  ability?: string;
45
+ target?: string;
46
+ }
47
+ export interface SpecterActiveEffect {
48
+ name: string;
49
+ duration: number;
50
+ remainingTime: number;
51
+ stackCount: number;
52
+ instigator?: string;
53
+ }
54
+ export interface SpecterActorSnapshot {
55
+ name: string;
56
+ class: string;
57
+ tags: string[];
58
+ location: Vector3;
59
+ rotation: Rotator;
60
+ forward: Vector3;
61
+ velocity: Vector3;
62
+ teamId?: number;
63
+ asc?: string;
64
+ ascOwner?: string;
65
+ attributes?: Record<string, number>;
66
+ gameplayTags?: string[];
67
+ activeEffects?: SpecterActiveEffect[];
68
+ }
69
+ export interface SpecterDiagnosticsReport {
70
+ target?: SpecterActorSnapshot;
71
+ instigator?: SpecterActorSnapshot;
72
+ distance?: number;
73
+ relativeDirection?: string;
74
+ facingDotProduct?: number;
75
+ actorMap?: Record<string, {
76
+ name: string;
77
+ class: string;
78
+ asc?: string;
79
+ ascOwner?: string;
80
+ }>;
81
+ flightRecorder?: Array<{
82
+ timestamp: number;
83
+ eventName: string;
84
+ description: string;
85
+ eventType: string;
86
+ oldValue?: string;
87
+ newValue?: string;
88
+ instigator?: string;
89
+ effectCauser?: string;
90
+ gameplayEffect?: string;
91
+ ability?: string;
92
+ target?: string;
93
+ }>;
94
+ engine?: {
95
+ map: string;
96
+ worldTime: number;
97
+ deltaSeconds: number;
98
+ };
45
99
  }
46
100
  export interface Vector3 {
47
101
  x: number;
@@ -100,6 +154,11 @@ export declare class SpecterTransport {
100
154
  clientName?: string;
101
155
  private pendingRequests;
102
156
  private eventListeners;
157
+ recentEvents: Array<{
158
+ eventKey: string;
159
+ data: any;
160
+ timestamp: number;
161
+ }>;
103
162
  static getInstance(url?: string): SpecterTransport;
104
163
  get port(): string;
105
164
  get friendlyPortTag(): string;
@@ -116,6 +175,18 @@ export declare class SpecterTransport {
116
175
  * Cleans up an event listener.
117
176
  */
118
177
  removeEventListener(eventKey: string, callback: (data: any) => void): void;
178
+ /**
179
+ * Records an unsolicited event into the circular ring buffer.
180
+ */
181
+ recordRecentEvent(eventKey: string, data: any): void;
182
+ /**
183
+ * Returns recent events matching the eventKey, optionally filtered to events since a given timestamp.
184
+ */
185
+ getRecentEvents(eventKey?: string, sinceTimestamp?: number): Array<{
186
+ eventKey: string;
187
+ data: any;
188
+ timestamp: number;
189
+ }>;
119
190
  }
120
191
  export interface LoadMapOptions {
121
192
  gameMode?: string;
@@ -129,6 +200,23 @@ export declare class SpecterWorld {
129
200
  readonly network: SpecterNetwork;
130
201
  constructor(transport: SpecterTransport);
131
202
  static connect(url?: string): Promise<SpecterWorld>;
203
+ /**
204
+ * Queries comprehensive runtime diagnostics from the engine, including
205
+ * actor identity mapping, attribute/tag snapshots, spatial relations, and recent Flight Recorder events.
206
+ */
207
+ getDiagnostics(options?: {
208
+ target?: SpecterLocator | ActorLocator;
209
+ instigator?: SpecterLocator | ActorLocator;
210
+ limit?: number;
211
+ }): Promise<SpecterDiagnosticsReport>;
212
+ /**
213
+ * Commands Unreal Engine to safely reload or load a game module (e.g. "Hots") using FModuleManager.
214
+ */
215
+ reloadModule(moduleName: string): Promise<{
216
+ success: boolean;
217
+ message: string;
218
+ wasLoaded: boolean;
219
+ }>;
132
220
  /**
133
221
  * Waits for the given `timeout` in milliseconds.
134
222
  * Matches Playwright's `page.waitForTimeout()` method.
@@ -40,6 +40,8 @@ class SpecterTransport {
40
40
  // The Enterprise Fix: Routing responses to the correct Promise
41
41
  pendingRequests = new Map();
42
42
  eventListeners = new Map();
43
+ // Buffered recent events to eliminate race conditions between event arrival and listener attachment
44
+ recentEvents = [];
43
45
  static getInstance(url = 'ws://127.0.0.1:8080') {
44
46
  if (!SpecterTransport.instance) {
45
47
  SpecterTransport.instance = new SpecterTransport(url);
@@ -148,6 +150,8 @@ class SpecterTransport {
148
150
  this.currentMap = responseObj.data.map;
149
151
  }
150
152
  const eventKey = `${responseObj.locatorId}_${responseObj.eventName}`;
153
+ // Buffer recent events with timestamps to eliminate race conditions
154
+ this.recordRecentEvent(eventKey, responseObj.data);
151
155
  // If a test script is currently waiting for this event...
152
156
  if (this.eventListeners.has(eventKey)) {
153
157
  const callbacks = this.eventListeners.get(eventKey);
@@ -240,6 +244,27 @@ class SpecterTransport {
240
244
  }
241
245
  }
242
246
  }
247
+ /**
248
+ * Records an unsolicited event into the circular ring buffer.
249
+ */
250
+ recordRecentEvent(eventKey, data) {
251
+ this.recentEvents.push({ eventKey, data, timestamp: Date.now() });
252
+ if (this.recentEvents.length > 200) {
253
+ this.recentEvents.shift();
254
+ }
255
+ }
256
+ /**
257
+ * Returns recent events matching the eventKey, optionally filtered to events since a given timestamp.
258
+ */
259
+ getRecentEvents(eventKey, sinceTimestamp) {
260
+ return this.recentEvents.filter(e => {
261
+ if (eventKey && e.eventKey !== eventKey)
262
+ return false;
263
+ if (sinceTimestamp !== undefined && e.timestamp < sinceTimestamp)
264
+ return false;
265
+ return true;
266
+ });
267
+ }
243
268
  }
244
269
  exports.SpecterTransport = SpecterTransport;
245
270
  class SpecterWorld {
@@ -259,6 +284,30 @@ class SpecterWorld {
259
284
  // Inject the connected transport into the new world
260
285
  return new SpecterWorld(transport);
261
286
  }
287
+ /**
288
+ * Queries comprehensive runtime diagnostics from the engine, including
289
+ * actor identity mapping, attribute/tag snapshots, spatial relations, and recent Flight Recorder events.
290
+ */
291
+ async getDiagnostics(options) {
292
+ const payload = {
293
+ limit: options?.limit ?? 30
294
+ };
295
+ if (options?.target) {
296
+ payload.targetLocatorPipeline = options.target.pipeline;
297
+ }
298
+ if (options?.instigator) {
299
+ payload.instigatorLocatorPipeline = options.instigator.pipeline;
300
+ }
301
+ const res = await this.evaluate("GetActorDiagnostics", payload);
302
+ return res;
303
+ }
304
+ /**
305
+ * Commands Unreal Engine to safely reload or load a game module (e.g. "Hots") using FModuleManager.
306
+ */
307
+ async reloadModule(moduleName) {
308
+ const res = await this.evaluate("ReloadModule", { module: moduleName });
309
+ return res;
310
+ }
262
311
  /**
263
312
  * Waits for the given `timeout` in milliseconds.
264
313
  * Matches Playwright's `page.waitForTimeout()` method.
@@ -446,7 +495,9 @@ class SpecterWorld {
446
495
  const location = options?.location || { x: 0, y: 0, z: 0 };
447
496
  const rotation = options?.rotation || { pitch: 0, yaw: 0, roll: 0 };
448
497
  const assetName = assetPath.split('/').pop()?.split('.')[0];
449
- await this.evaluate("SpawnActor", { assetPath, tag, location, rotation }, assetName, tag);
498
+ const properties = options?.properties;
499
+ const spawnController = options?.spawnController;
500
+ await this.evaluate("SpawnActor", { assetPath, tag, location, rotation, properties, spawnController }, assetName, tag);
450
501
  return this.actorByTag(tag);
451
502
  }
452
503
  // ==========================================
@@ -195,6 +195,29 @@ exports.test = test_1.test.extend({
195
195
  catch (e) {
196
196
  console.error("[Specter] Failed to capture error screenshot:", e);
197
197
  }
198
+ try {
199
+ const diagnostics = await world.getDiagnostics({ limit: 35 });
200
+ if (diagnostics) {
201
+ const formattedSummary = (0, gas_matchers_1.formatAiDiagnostics)(diagnostics);
202
+ console.log('\n' + formattedSummary + '\n');
203
+ const alreadyAttached = testInfo.attachments.some(a => a.name.includes('Specter AI Diagnostics'));
204
+ if (!alreadyAttached) {
205
+ testInfo.attachments.push({
206
+ name: 'Specter AI Diagnostics (JSON)',
207
+ contentType: 'application/json',
208
+ body: Buffer.from(JSON.stringify(diagnostics, null, 2))
209
+ });
210
+ testInfo.attachments.push({
211
+ name: 'Specter AI Diagnostics (Markdown)',
212
+ contentType: 'text/markdown',
213
+ body: Buffer.from(formattedSummary)
214
+ });
215
+ }
216
+ }
217
+ }
218
+ catch (e) {
219
+ console.error("[Specter] Failed to capture AI diagnostics on test failure:", e);
220
+ }
198
221
  }
199
222
  }, { auto: true }]
200
223
  });
@@ -1,5 +1,4 @@
1
1
  import { SpecterLocator, ActorLocator } from '../core/locators';
2
- import { SpecterTimelineEvent } from '../core/specter-client';
3
2
  declare global {
4
3
  namespace PlaywrightTest {
5
4
  interface Matchers<R, T> {
@@ -45,6 +44,8 @@ export interface GasMatchers {
45
44
  effectCauser?: string | ActorLocator;
46
45
  gameplayEffect?: string;
47
46
  ability?: string;
47
+ timeout?: number;
48
+ tolerance?: number;
48
49
  }, triggerAction?: () => Promise<void>): Promise<void>;
49
50
  toHaveGameplayTag(tag: string): Promise<void>;
50
51
  toHaveGameplayEffect(effectClassPath: string): Promise<void>;
@@ -64,6 +65,7 @@ export interface GasMatchers {
64
65
  toHaveAnyGameplayTags(tags: string[]): Promise<void>;
65
66
  toHaveAllGameplayTags(tags: string[]): Promise<void>;
66
67
  }
68
+ export declare function formatAiDiagnostics(diagnostics: any): string;
67
69
  export declare const gasExpect: import("playwright/test").Expect<{
68
70
  toHaveAttributeValue(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, attributeSet: string, attributeName: string, expectedValue: number, options?: {
69
71
  timeout?: number;
@@ -80,16 +82,20 @@ export declare const gasExpect: import("playwright/test").Expect<{
80
82
  effectCauser?: string | ActorLocator;
81
83
  gameplayEffect?: string;
82
84
  ability?: string;
85
+ timeout?: number;
86
+ tolerance?: number;
83
87
  }, triggerAction?: () => Promise<void>): Promise<{
84
88
  pass: boolean;
85
89
  message: () => string;
86
- actual: SpecterTimelineEvent | undefined;
90
+ actual: any;
87
91
  expected: {
88
92
  delta?: number;
89
93
  instigator?: string | ActorLocator;
90
94
  effectCauser?: string | ActorLocator;
91
95
  gameplayEffect?: string;
92
96
  ability?: string;
97
+ timeout?: number;
98
+ tolerance?: number;
93
99
  };
94
100
  }>;
95
101
  toHaveGameplayTag(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, tag: string): Promise<{
@@ -34,8 +34,91 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.gasExpect = void 0;
37
+ exports.formatAiDiagnostics = formatAiDiagnostics;
37
38
  const test_1 = __importStar(require("@playwright/test"));
38
39
  const specter_client_1 = require("../core/specter-client");
40
+ function formatAiDiagnostics(diagnostics) {
41
+ if (!diagnostics)
42
+ return '';
43
+ const lines = [];
44
+ lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
45
+ lines.push('🧠 SPECTER AI DIAGNOSTICS REPORT');
46
+ lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
47
+ // 1. Actor Identity Mapping
48
+ if (diagnostics.actorMap && Object.keys(diagnostics.actorMap).length > 0) {
49
+ lines.push('📍 Actor Identity Mapping:');
50
+ for (const [tag, info] of Object.entries(diagnostics.actorMap)) {
51
+ lines.push(` • [${tag}] -> ${info.name} (${info.class}) | ASC: ${info.asc || 'N/A'}${info.ascOwner ? ` (Owner: ${info.ascOwner})` : ''}`);
52
+ }
53
+ lines.push('');
54
+ }
55
+ // 2. Target Actor Current State
56
+ if (diagnostics.target) {
57
+ lines.push(`🎯 Target Actor: ${diagnostics.target.name} (${diagnostics.target.class})`);
58
+ if (diagnostics.target.attributes) {
59
+ const attrEntries = Object.entries(diagnostics.target.attributes)
60
+ .slice(0, 12)
61
+ .map(([k, v]) => `${k}: ${v}`)
62
+ .join(', ');
63
+ lines.push(` • Attributes: { ${attrEntries} }`);
64
+ }
65
+ if (diagnostics.target.gameplayTags && diagnostics.target.gameplayTags.length > 0) {
66
+ lines.push(` • Active Tags: [ ${diagnostics.target.gameplayTags.join(', ')} ]`);
67
+ }
68
+ if (diagnostics.target.activeEffects && diagnostics.target.activeEffects.length > 0) {
69
+ const effectStrs = diagnostics.target.activeEffects.map((e) => `${e.name} (stacks: ${e.stackCount}, remaining: ${Number(e.remainingTime).toFixed(1)}s)`);
70
+ lines.push(` • Active Effects: [ ${effectStrs.join(', ')} ]`);
71
+ }
72
+ lines.push('');
73
+ }
74
+ // 3. Instigator Actor Current State
75
+ if (diagnostics.instigator) {
76
+ lines.push(`⚔️ Instigator Actor: ${diagnostics.instigator.name} (${diagnostics.instigator.class})`);
77
+ if (diagnostics.instigator.attributes) {
78
+ const attrEntries = Object.entries(diagnostics.instigator.attributes)
79
+ .slice(0, 8)
80
+ .map(([k, v]) => `${k}: ${v}`)
81
+ .join(', ');
82
+ lines.push(` • Attributes: { ${attrEntries} }`);
83
+ }
84
+ if (diagnostics.instigator.gameplayTags && diagnostics.instigator.gameplayTags.length > 0) {
85
+ lines.push(` • Active Tags: [ ${diagnostics.instigator.gameplayTags.join(', ')} ]`);
86
+ }
87
+ lines.push('');
88
+ }
89
+ // 4. Spatial Analysis
90
+ if (diagnostics.distance !== undefined) {
91
+ lines.push(`📐 Spatial Context: Distance = ${Number(diagnostics.distance).toFixed(1)} units | Facing Zone = ${diagnostics.relativeDirection || 'N/A'} (Dot: ${Number(diagnostics.facingDotProduct || 0).toFixed(2)})`);
92
+ lines.push('');
93
+ }
94
+ // 5. Recent Flight Recorder Events
95
+ if (diagnostics.flightRecorder && diagnostics.flightRecorder.length > 0) {
96
+ lines.push('⏱️ Recent Flight Recorder Events (most recent last):');
97
+ const recentSlice = diagnostics.flightRecorder.slice(-12);
98
+ for (const ev of recentSlice) {
99
+ lines.push(` [${Number(ev.timestamp).toFixed(2)}s] ${ev.eventName} - ${ev.description || ''}`);
100
+ }
101
+ lines.push('');
102
+ }
103
+ lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
104
+ try {
105
+ const testInfo = test_1.default.info();
106
+ if (testInfo) {
107
+ testInfo.attachments.push({
108
+ name: 'Specter AI Diagnostics (JSON)',
109
+ contentType: 'application/json',
110
+ body: Buffer.from(JSON.stringify(diagnostics, null, 2))
111
+ });
112
+ testInfo.attachments.push({
113
+ name: 'Specter AI Diagnostics (Summary)',
114
+ contentType: 'text/markdown',
115
+ body: Buffer.from(lines.join('\n'))
116
+ });
117
+ }
118
+ }
119
+ catch { }
120
+ return '\n\n' + lines.join('\n');
121
+ }
39
122
  exports.gasExpect = test_1.expect.extend({
40
123
  async toHaveAttributeValue(locator, attributeSet, attributeName, expectedValue, options) {
41
124
  const assertionName = 'toHaveAttributeValue';
@@ -146,12 +229,19 @@ exports.gasExpect = test_1.expect.extend({
146
229
  if (!e.message?.includes('Timed out')) {
147
230
  throw e;
148
231
  }
232
+ let diagStr = '';
233
+ try {
234
+ const diags = await locator.getDiagnostics({ limit: 20 });
235
+ diagStr = formatAiDiagnostics(diags);
236
+ }
237
+ catch { }
149
238
  return {
150
239
  pass: isNot,
151
240
  message: () => `${this.utils.matcherHint(assertionName, locator.toString(), expectedValue.toString())}\n\n` +
152
241
  `Expected: ${this.utils.printExpected(expectedValue)}\n` +
153
242
  `Received: ${lastValue !== undefined ? this.utils.printReceived(lastValue) : 'Timeout'}\n` +
154
- `History: [${valueHistory.join(', ')}]`,
243
+ `History: [${valueHistory.join(', ')}]` +
244
+ diagStr,
155
245
  actual: lastValue,
156
246
  expected: expectedValue
157
247
  };
@@ -162,6 +252,9 @@ exports.gasExpect = test_1.expect.extend({
162
252
  const assertionName = 'toHaveAttributeChange';
163
253
  const isNot = this.isNot;
164
254
  const prefix = isNot ? 'not.toHaveAttributeChange' : 'toHaveAttributeChange';
255
+ const timeout = expectedChange.timeout ?? 10000;
256
+ const tolerance = expectedChange.tolerance ?? 0.01;
257
+ const startTime = Date.now();
165
258
  // Format expectations for description
166
259
  const expectedParts = [];
167
260
  if (expectedChange.delta !== undefined)
@@ -181,97 +274,228 @@ exports.gasExpect = test_1.expect.extend({
181
274
  const stepName = `${prefix}('${attributeSet}', '${attributeName}', { ${expectedParts.join(', ')} }) @ ${locator.toString()}`;
182
275
  return await test_1.default.step(stepName, async () => {
183
276
  const transport = locator.transport;
184
- const timeout = 10000;
185
- // Trigger C++ tracking of this attribute by reading its value once
186
- await locator.getAttributeValue(attributeSet, attributeName);
187
- // Resolve target expected names for locators
188
- let expectedInstigatorName;
189
- if (expectedChange.instigator) {
190
- if (typeof expectedChange.instigator === 'string') {
191
- expectedInstigatorName = expectedChange.instigator;
192
- }
193
- else {
194
- expectedInstigatorName = await expectedChange.instigator.getObjectName();
277
+ let lastEvent;
278
+ let lastFailedReasons = [];
279
+ let initialValue;
280
+ // Synchronously register live listener immediately to capture all events during setup & action
281
+ const capturedEvents = [];
282
+ let onLiveEvent = null;
283
+ const liveListener = (event) => {
284
+ capturedEvents.push(event);
285
+ if (onLiveEvent) {
286
+ onLiveEvent(event);
195
287
  }
288
+ };
289
+ if (transport && typeof transport.registerEventListener === 'function') {
290
+ transport.registerEventListener('GLOBAL_timeline-event', liveListener);
196
291
  }
197
- let expectedEffectCauserName;
198
- if (expectedChange.effectCauser) {
199
- if (typeof expectedChange.effectCauser === 'string') {
200
- expectedEffectCauserName = expectedChange.effectCauser;
292
+ try {
293
+ // In parallel: resolve initial value and locator names
294
+ const [resolvedInitialVal, expectedInstigatorName, expectedEffectCauserName] = await Promise.all([
295
+ locator.getAttributeValue(attributeSet, attributeName).catch(() => undefined),
296
+ expectedChange.instigator
297
+ ? (typeof expectedChange.instigator === 'string' ? Promise.resolve(expectedChange.instigator) : expectedChange.instigator.getObjectName().catch(() => undefined))
298
+ : Promise.resolve(undefined),
299
+ expectedChange.effectCauser
300
+ ? (typeof expectedChange.effectCauser === 'string' ? Promise.resolve(expectedChange.effectCauser) : expectedChange.effectCauser.getObjectName().catch(() => undefined))
301
+ : Promise.resolve(undefined),
302
+ ]);
303
+ initialValue = resolvedInitialVal;
304
+ // Evaluates whether an event matches all expected criteria
305
+ const evaluateEvent = (event) => {
306
+ if (event.eventType !== specter_client_1.SpecterEventType.GameplayAttribute && event.eventType !== 'GameplayAttribute') {
307
+ return false;
308
+ }
309
+ if (event.eventName !== attributeName && !event.eventName?.includes(attributeName)) {
310
+ return false;
311
+ }
312
+ lastEvent = event;
313
+ lastFailedReasons = [];
314
+ let isMatch = true;
315
+ // 1. Delta check
316
+ if (expectedChange.delta !== undefined) {
317
+ const oldVal = parseFloat(event.oldValue);
318
+ const newVal = parseFloat(event.newValue);
319
+ const actualDelta = newVal - oldVal;
320
+ const expDelta = expectedChange.delta;
321
+ // Check signed delta match, or magnitude match (e.g. damage written as positive vs negative)
322
+ const deltaMatch = Math.abs(actualDelta - expDelta) <= tolerance ||
323
+ Math.abs(Math.abs(actualDelta) - Math.abs(expDelta)) <= tolerance;
324
+ if (!deltaMatch) {
325
+ isMatch = false;
326
+ lastFailedReasons.push(`delta (expected: ${expDelta}, actual: ${actualDelta})`);
327
+ }
328
+ }
329
+ // 2. Instigator check
330
+ if (expectedInstigatorName !== undefined) {
331
+ const inst = (event.instigator || '').trim();
332
+ if (!inst || (!inst.includes(expectedInstigatorName) && !expectedInstigatorName.includes(inst))) {
333
+ isMatch = false;
334
+ lastFailedReasons.push(`instigator (expected to include: '${expectedInstigatorName}', actual: '${event.instigator}')`);
335
+ }
336
+ }
337
+ // 3. Effect Causer check
338
+ if (expectedEffectCauserName !== undefined) {
339
+ const causer = (event.effectCauser || '').trim();
340
+ if (!causer || (!causer.includes(expectedEffectCauserName) && !expectedEffectCauserName.includes(causer))) {
341
+ isMatch = false;
342
+ lastFailedReasons.push(`effectCauser (expected to include: '${expectedEffectCauserName}', actual: '${event.effectCauser}')`);
343
+ }
344
+ }
345
+ // 4. Gameplay Effect check
346
+ if (expectedChange.gameplayEffect !== undefined) {
347
+ if (!event.gameplayEffect || (!event.gameplayEffect.includes(expectedChange.gameplayEffect) && !expectedChange.gameplayEffect.includes(event.gameplayEffect))) {
348
+ isMatch = false;
349
+ lastFailedReasons.push(`gameplayEffect (expected to include: '${expectedChange.gameplayEffect}', actual: '${event.gameplayEffect}')`);
350
+ }
351
+ }
352
+ // 5. Ability check
353
+ if (expectedChange.ability !== undefined) {
354
+ if (!event.ability || (!event.ability.includes(expectedChange.ability) && !expectedChange.ability.includes(event.ability))) {
355
+ isMatch = false;
356
+ lastFailedReasons.push(`ability (expected to include: '${expectedChange.ability}', actual: '${event.ability}')`);
357
+ }
358
+ }
359
+ return isMatch;
360
+ };
361
+ // --- 1. TRY ONCE IMMEDIATELY ---
362
+ // A. Check events captured in real-time during setup
363
+ for (const ev of capturedEvents) {
364
+ if (evaluateEvent(ev)) {
365
+ return {
366
+ pass: !isNot,
367
+ message: () => 'passed',
368
+ actual: ev,
369
+ expected: expectedChange
370
+ };
371
+ }
201
372
  }
202
- else {
203
- expectedEffectCauserName = await expectedChange.effectCauser.getObjectName();
373
+ // B. Check transport recent events ring buffer (events from just before or during call)
374
+ if (transport && typeof transport.getRecentEvents === 'function') {
375
+ const recent = transport.getRecentEvents('GLOBAL_timeline-event', startTime - 3000);
376
+ for (const item of recent) {
377
+ if (evaluateEvent(item.data)) {
378
+ return {
379
+ pass: !isNot,
380
+ message: () => 'passed',
381
+ actual: item.data,
382
+ expected: expectedChange
383
+ };
384
+ }
385
+ }
204
386
  }
205
- }
206
- let matchEvent;
207
- let lastEvent;
208
- let lastFailedReasons = [];
209
- try {
210
- // Wait for the timeline event matching the criteria
211
- const matchPromise = new Promise((resolve, reject) => {
212
- let timeoutId;
213
- const listener = (event) => {
214
- if (event.eventType === specter_client_1.SpecterEventType.GameplayAttribute &&
215
- (event.eventName === attributeName || event.eventName.includes(attributeName))) {
216
- lastEvent = event;
217
- lastFailedReasons = [];
218
- let isMatch = true;
219
- // 1. Delta check
220
- if (expectedChange.delta !== undefined) {
221
- const oldVal = parseFloat(event.oldValue);
222
- const newVal = parseFloat(event.newValue);
223
- const actualDelta = newVal - oldVal;
224
- // Use close comparison for floats (e.g. within 0.01 tolerance)
225
- if (Math.abs(actualDelta - expectedChange.delta) > 0.01) {
226
- isMatch = false;
227
- lastFailedReasons.push(`delta (expected: ${expectedChange.delta}, actual: ${actualDelta})`);
228
- }
229
- }
230
- // 2. Instigator check
231
- if (expectedInstigatorName !== undefined) {
232
- if (event.instigator !== expectedInstigatorName && !event.instigator?.includes(expectedInstigatorName)) {
233
- isMatch = false;
234
- lastFailedReasons.push(`instigator (expected to include: '${expectedInstigatorName}', actual: '${event.instigator}')`);
235
- }
236
- }
237
- // 3. Effect Causer check
238
- if (expectedEffectCauserName !== undefined) {
239
- if (event.effectCauser !== expectedEffectCauserName && !event.effectCauser?.includes(expectedEffectCauserName)) {
240
- isMatch = false;
241
- lastFailedReasons.push(`effectCauser (expected to include: '${expectedEffectCauserName}', actual: '${event.effectCauser}')`);
242
- }
243
- }
244
- // 4. Gameplay Effect check
245
- if (expectedChange.gameplayEffect !== undefined) {
246
- if (event.gameplayEffect !== expectedChange.gameplayEffect && !event.gameplayEffect?.includes(expectedChange.gameplayEffect)) {
247
- isMatch = false;
248
- lastFailedReasons.push(`gameplayEffect (expected to include: '${expectedChange.gameplayEffect}', actual: '${event.gameplayEffect}')`);
249
- }
387
+ // --- 2. EXECUTE TRIGGER ACTION IF PROVIDED ---
388
+ if (triggerAction) {
389
+ await triggerAction();
390
+ // Re-check captured events immediately after trigger action completes
391
+ for (const ev of capturedEvents) {
392
+ if (evaluateEvent(ev)) {
393
+ return {
394
+ pass: !isNot,
395
+ message: () => 'passed',
396
+ actual: ev,
397
+ expected: expectedChange
398
+ };
399
+ }
400
+ }
401
+ }
402
+ // --- 3. HANDLE DELTA: 0 (assertion that value has not changed) ---
403
+ if (expectedChange.delta === 0) {
404
+ const observationMs = Math.min(timeout, 500);
405
+ await new Promise(r => setTimeout(r, observationMs));
406
+ // Verify whether any conflicting attribute change events arrived
407
+ const conflictingEvent = capturedEvents.find(ev => (ev.eventType === specter_client_1.SpecterEventType.GameplayAttribute || ev.eventType === 'GameplayAttribute') &&
408
+ (ev.eventName === attributeName || ev.eventName?.includes(attributeName)) &&
409
+ parseFloat(ev.oldValue) !== parseFloat(ev.newValue));
410
+ if (!conflictingEvent) {
411
+ const currentVal = await locator.getAttributeValue(attributeSet, attributeName).catch(() => initialValue);
412
+ if (initialValue !== undefined && currentVal !== undefined) {
413
+ const delta = currentVal - initialValue;
414
+ if (Math.abs(delta) <= tolerance) {
415
+ return {
416
+ pass: !isNot,
417
+ message: () => 'passed',
418
+ actual: { delta, value: currentVal },
419
+ expected: expectedChange
420
+ };
250
421
  }
251
- // 5. Ability check
252
- if (expectedChange.ability !== undefined) {
253
- if (event.ability !== expectedChange.ability && !event.ability?.includes(expectedChange.ability)) {
254
- isMatch = false;
255
- lastFailedReasons.push(`ability (expected to include: '${expectedChange.ability}', actual: '${event.ability}')`);
422
+ }
423
+ else if (currentVal !== undefined) {
424
+ return {
425
+ pass: !isNot,
426
+ message: () => 'passed',
427
+ actual: { delta: 0, value: currentVal },
428
+ expected: expectedChange
429
+ };
430
+ }
431
+ }
432
+ }
433
+ // --- 4. LISTEN FOR ATTRIBUTE CHANGE EVENT WITH POLLING FALLBACK ---
434
+ const matchEvent = await new Promise((resolve, reject) => {
435
+ let timeoutId;
436
+ let pollIntervalId;
437
+ let isResolved = false;
438
+ const cleanup = () => {
439
+ if (isResolved)
440
+ return;
441
+ isResolved = true;
442
+ clearTimeout(timeoutId);
443
+ clearInterval(pollIntervalId);
444
+ };
445
+ onLiveEvent = (event) => {
446
+ if (isResolved)
447
+ return;
448
+ if (evaluateEvent(event)) {
449
+ cleanup();
450
+ resolve(event);
451
+ }
452
+ };
453
+ // Check any events that arrived right as onLiveEvent was wired
454
+ for (const ev of capturedEvents) {
455
+ if (evaluateEvent(ev)) {
456
+ cleanup();
457
+ resolve(ev);
458
+ return;
459
+ }
460
+ }
461
+ // Parallel polling fallback
462
+ pollIntervalId = setInterval(async () => {
463
+ if (isResolved)
464
+ return;
465
+ try {
466
+ const currentVal = await locator.getAttributeValue(attributeSet, attributeName);
467
+ if (isResolved)
468
+ return;
469
+ if (currentVal !== undefined && initialValue !== undefined && expectedChange.delta !== undefined) {
470
+ const actualDelta = currentVal - initialValue;
471
+ const expDelta = expectedChange.delta;
472
+ const deltaMatch = Math.abs(actualDelta - expDelta) <= tolerance ||
473
+ Math.abs(Math.abs(actualDelta) - Math.abs(expDelta)) <= tolerance;
474
+ if (deltaMatch) {
475
+ // If no specific instigator/causer was demanded, or if we saw an event matching them:
476
+ if (!expectedInstigatorName && !expectedEffectCauserName && !expectedChange.gameplayEffect && !expectedChange.ability) {
477
+ cleanup();
478
+ resolve(lastEvent || {
479
+ timestamp: Date.now(),
480
+ eventName: attributeName,
481
+ eventType: specter_client_1.SpecterEventType.GameplayAttribute,
482
+ oldValue: String(initialValue),
483
+ newValue: String(currentVal),
484
+ description: `Attribute ${attributeName} changed by ${actualDelta}`,
485
+ });
486
+ }
256
487
  }
257
488
  }
258
- if (isMatch) {
259
- clearTimeout(timeoutId);
260
- transport.removeEventListener('GLOBAL_timeline-event', listener);
261
- resolve(event);
262
- }
263
489
  }
264
- };
490
+ catch {
491
+ // Transient poll errors are suppressed during wait
492
+ }
493
+ }, 100);
265
494
  timeoutId = setTimeout(() => {
266
- transport.removeEventListener('GLOBAL_timeline-event', listener);
495
+ cleanup();
267
496
  reject(new Error(`Timed out after ${timeout}ms waiting for attribute change event on '${attributeName}'`));
268
497
  }, timeout);
269
- transport.registerEventListener('GLOBAL_timeline-event', listener);
270
498
  });
271
- if (triggerAction) {
272
- await triggerAction();
273
- }
274
- matchEvent = await matchPromise;
275
499
  return {
276
500
  pass: !isNot,
277
501
  message: () => 'passed',
@@ -280,23 +504,38 @@ exports.gasExpect = test_1.expect.extend({
280
504
  };
281
505
  }
282
506
  catch (e) {
283
- if (!e.message.includes('Timed out')) {
507
+ if (!e.message?.includes('Timed out')) {
284
508
  throw e;
285
509
  }
286
510
  let failureDetails = `Last checked event: ${lastEvent ? JSON.stringify(lastEvent, null, 2) : 'None received'}`;
287
511
  if (lastFailedReasons.length > 0) {
288
512
  failureDetails += `\n\nFailed Criteria on last event:\n- ${lastFailedReasons.join('\n- ')}`;
289
513
  }
514
+ let diagStr = '';
515
+ try {
516
+ const diags = await locator.getDiagnostics({
517
+ instigator: expectedChange.instigator,
518
+ limit: 30
519
+ });
520
+ diagStr = formatAiDiagnostics(diags);
521
+ }
522
+ catch { }
290
523
  return {
291
524
  pass: isNot,
292
525
  message: () => `${this.utils.matcherHint(assertionName, locator.toString(), expectedParts.join(', '))}\n\n` +
293
526
  `Error: ${e.message}\n` +
294
527
  `Expected criteria: { ${expectedParts.join(', ')} }\n\n` +
295
- failureDetails,
528
+ failureDetails +
529
+ diagStr,
296
530
  actual: lastEvent,
297
531
  expected: expectedChange
298
532
  };
299
533
  }
534
+ finally {
535
+ if (transport && typeof transport.removeEventListener === 'function') {
536
+ transport.removeEventListener('GLOBAL_timeline-event', liveListener);
537
+ }
538
+ }
300
539
  });
301
540
  },
302
541
  async toHaveGameplayTag(locator, tag) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.108",
3
+ "version": "1.0.110",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",