@specter-automation/test 1.0.111 → 1.0.114

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.
@@ -87,18 +87,46 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
87
87
  /**
88
88
  * Filters the current set of Actors down to only those possessed by the local human player.
89
89
  * Perfect for filtering out AI Bots in Lyra!
90
+ * Pass false to get remote/non-local pawns.
90
91
  */
91
- isLocallyControlled(locallyControlled?: boolean): ActorLocator;
92
+ locallyControlled(locallyControlled?: boolean): ActorLocator<T>;
93
+ /**
94
+ * Alias for `locallyControlled()`.
95
+ */
96
+ filterLocallyControlled(locallyControlled?: boolean): ActorLocator<T>;
97
+ /**
98
+ * Checks if this actor is locally controlled by the local player controller.
99
+ * Returns true if locally controlled, false otherwise.
100
+ */
101
+ isLocallyControlled(): Promise<boolean>;
92
102
  /**
93
103
  * Filters the current set of Actors down to only those that are possessed by a controller.
94
104
  * Pass false to get unpossessed pawns.
95
105
  */
96
- isPossessed(possessed?: boolean): ActorLocator;
106
+ possessed(possessed?: boolean): ActorLocator<T>;
107
+ /**
108
+ * Alias for `possessed()`.
109
+ */
110
+ filterPossessed(possessed?: boolean): ActorLocator<T>;
111
+ /**
112
+ * Checks if this actor is currently possessed by a controller.
113
+ * Returns true if possessed, false otherwise.
114
+ */
115
+ isPossessed(): Promise<boolean>;
97
116
  /**
98
117
  * Filters the current set of Actors down to only those that are possessed by a human player.
99
118
  * Excludes AI controllers, bots, and dummy level actors.
100
119
  */
101
- isPlayerControlled(playerControlled?: boolean): ActorLocator;
120
+ playerControlled(playerControlled?: boolean): ActorLocator<T>;
121
+ /**
122
+ * Alias for `playerControlled()`.
123
+ */
124
+ filterPlayerControlled(playerControlled?: boolean): ActorLocator<T>;
125
+ /**
126
+ * Checks if this actor is possessed by a human player controller.
127
+ * Returns true if player controlled, false otherwise.
128
+ */
129
+ isPlayerControlled(): Promise<boolean>;
102
130
  getPlayerId(): Promise<number>;
103
131
  /**
104
132
  * Queries detailed controller possession state for this Pawn.
@@ -339,7 +367,10 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
339
367
  * @param pressed - true to simulate press, false to simulate release. Defaults to true.
340
368
  */
341
369
  pressAbilityInput(abilityTag: string, pressed?: boolean): Promise<void>;
342
- triggerAbilityWithTarget(abilityTag: string, target: SpecterLocator | Vector3): Promise<void>;
370
+ triggerAbilityWithTarget(abilityTag: string, target: SpecterLocator | Vector3, options?: {
371
+ singleShot?: boolean;
372
+ magnitude?: number;
373
+ }): Promise<void>;
343
374
  applyGameplayEffect(effectClassPath: string, level?: number): Promise<void>;
344
375
  hasActiveGameplayEffect(effectClassPath: string): Promise<boolean>;
345
376
  hasGameplayEffect(effectClassPath: string): Promise<boolean>;
@@ -349,7 +380,7 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
349
380
  getGameplayEffectLevel(effectClassPath: string): Promise<number>;
350
381
  getAttributeBaseValue(attributeSet: string, attributeName: string): Promise<number>;
351
382
  isAbilityExecuting(abilityOrClassPath: string): Promise<boolean>;
352
- cancelAbility(abilityClassPath: string): Promise<void>;
383
+ cancelAbility(abilityOrTagOrClassPath: string): Promise<void>;
353
384
  getGameplayTagCount(tag: string): Promise<number>;
354
385
  hasAnyGameplayTags(tags: string[]): Promise<boolean>;
355
386
  hasAllGameplayTags(tags: string[]): Promise<boolean>;
@@ -188,36 +188,79 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
188
188
  /**
189
189
  * Filters the current set of Actors down to only those possessed by the local human player.
190
190
  * Perfect for filtering out AI Bots in Lyra!
191
+ * Pass false to get remote/non-local pawns.
191
192
  */
192
- isLocallyControlled(locallyControlled = true) {
193
+ locallyControlled(locallyControlled = true) {
193
194
  const newPipeline = [
194
195
  ...this.pipeline,
195
196
  { action: 'filterLocallyControlled', value: locallyControlled ? '' : 'false' }
196
197
  ];
197
198
  return new ActorLocator(this.transport, newPipeline);
198
199
  }
200
+ /**
201
+ * Alias for `locallyControlled()`.
202
+ */
203
+ filterLocallyControlled(locallyControlled = true) {
204
+ return this.locallyControlled(locallyControlled);
205
+ }
206
+ /**
207
+ * Checks if this actor is locally controlled by the local player controller.
208
+ * Returns true if locally controlled, false otherwise.
209
+ */
210
+ async isLocallyControlled() {
211
+ const info = await this.getControllerInfo();
212
+ return info?.isLocallyControlled === true;
213
+ }
199
214
  /**
200
215
  * Filters the current set of Actors down to only those that are possessed by a controller.
201
216
  * Pass false to get unpossessed pawns.
202
217
  */
203
- isPossessed(possessed = true) {
218
+ possessed(possessed = true) {
204
219
  const newPipeline = [
205
220
  ...this.pipeline,
206
221
  { action: 'filterPossessed', value: possessed ? '' : 'false' }
207
222
  ];
208
223
  return new ActorLocator(this.transport, newPipeline);
209
224
  }
225
+ /**
226
+ * Alias for `possessed()`.
227
+ */
228
+ filterPossessed(possessed = true) {
229
+ return this.possessed(possessed);
230
+ }
231
+ /**
232
+ * Checks if this actor is currently possessed by a controller.
233
+ * Returns true if possessed, false otherwise.
234
+ */
235
+ async isPossessed() {
236
+ const info = await this.getControllerInfo();
237
+ return info?.isPossessed === true;
238
+ }
210
239
  /**
211
240
  * Filters the current set of Actors down to only those that are possessed by a human player.
212
241
  * Excludes AI controllers, bots, and dummy level actors.
213
242
  */
214
- isPlayerControlled(playerControlled = true) {
243
+ playerControlled(playerControlled = true) {
215
244
  const newPipeline = [
216
245
  ...this.pipeline,
217
246
  { action: 'filterPossessed', value: playerControlled ? '' : 'false' }
218
247
  ];
219
248
  return new ActorLocator(this.transport, newPipeline);
220
249
  }
250
+ /**
251
+ * Alias for `playerControlled()`.
252
+ */
253
+ filterPlayerControlled(playerControlled = true) {
254
+ return this.playerControlled(playerControlled);
255
+ }
256
+ /**
257
+ * Checks if this actor is possessed by a human player controller.
258
+ * Returns true if player controlled, false otherwise.
259
+ */
260
+ async isPlayerControlled() {
261
+ const info = await this.getControllerInfo();
262
+ return info?.isPlayerControlled === true;
263
+ }
221
264
  async getPlayerId() {
222
265
  const response = await this.evaluate("GetPlayerId");
223
266
  return response.data.playerId;
@@ -265,16 +308,27 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
265
308
  }
266
309
  }
267
310
  // If a client world is provided but neither playerId nor playerIndex is specified,
268
- // query the client world for its local PlayerId.
311
+ // query the client world silently for its local PlayerId.
269
312
  if (targetWorld && targetPlayerId === undefined && targetPlayerIndex === undefined) {
270
313
  try {
271
- const idResponse = await targetWorld.evaluate("GetPlayerId", {}, undefined);
272
- if (idResponse?.data?.playerId !== undefined) {
314
+ const idResponse = await targetWorld.evaluate("GetPlayerId", {}, undefined, undefined, true);
315
+ if (idResponse?.data?.playerId !== undefined && idResponse.data.playerId > 0) {
273
316
  targetPlayerId = idResponse.data.playerId;
274
317
  }
275
318
  }
276
319
  catch {
277
- // If GetPlayerId fails or isn't available yet, proceed without targetPlayerId
320
+ // If GetPlayerId fails or isn't available yet, proceed with fallback below
321
+ }
322
+ // Fallback: if playerId couldn't be resolved, infer playerIndex from client port (port 8081 -> index 1)
323
+ if (targetPlayerId === undefined) {
324
+ const transport = targetWorld.transport;
325
+ const portStr = transport?.port;
326
+ if (portStr) {
327
+ const portNum = parseInt(portStr, 10);
328
+ if (portNum > 8080 && portNum <= 8100) {
329
+ targetPlayerIndex = portNum - 8080;
330
+ }
331
+ }
278
332
  }
279
333
  }
280
334
  const payload = {};
@@ -858,8 +912,8 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
858
912
  async pressAbilityInput(abilityTag, pressed = true) {
859
913
  await this.evaluate("TriggerGasInput", { tag: abilityTag, isPressed: pressed });
860
914
  }
861
- async triggerAbilityWithTarget(abilityTag, target) {
862
- let payload = { abilityTag };
915
+ async triggerAbilityWithTarget(abilityTag, target, options) {
916
+ let payload = { abilityTag, ...options };
863
917
  if (target instanceof specter_locator_1.SpecterLocator) {
864
918
  payload.targetLocatorPipeline = target.pipeline;
865
919
  if (typeof target.getLocation === 'function') {
@@ -913,8 +967,12 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
913
967
  });
914
968
  return response.data?.isExecuting ?? response.data?.executing ?? false;
915
969
  }
916
- async cancelAbility(abilityClassPath) {
917
- await this.evaluate("CancelAbility", { abilityClassPath });
970
+ async cancelAbility(abilityOrTagOrClassPath) {
971
+ await this.evaluate("CancelAbility", {
972
+ ability: abilityOrTagOrClassPath,
973
+ abilityTag: abilityOrTagOrClassPath,
974
+ abilityClassPath: abilityOrTagOrClassPath
975
+ });
918
976
  }
919
977
  async getGameplayTagCount(tag) {
920
978
  const response = await this.evaluate("GetGameplayTagCount", { tag });
@@ -1085,7 +1143,8 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
1085
1143
  if (options?.instigator) {
1086
1144
  payload.instigatorLocatorPipeline = options.instigator.pipeline;
1087
1145
  }
1088
- return await this.transport.sendCommand("GetActorDiagnostics", this.pipeline, payload);
1146
+ const res = await this.transport.sendCommand("GetActorDiagnostics", this.pipeline, payload);
1147
+ return res?.data ?? res;
1089
1148
  }
1090
1149
  }
1091
1150
  exports.ActorLocator = ActorLocator;
@@ -16,6 +16,9 @@ export interface FilterOptions {
16
16
  value: string;
17
17
  operator?: '===' | '!=' | '>' | '<' | '>=' | '<=' | 'contains' | 'regex';
18
18
  };
19
+ locallyControlled?: boolean;
20
+ possessed?: boolean;
21
+ playerControlled?: boolean;
19
22
  }
20
23
  export declare class SpecterLocator<T = any> {
21
24
  pipeline: LocatorStep[];
@@ -140,6 +140,15 @@ class SpecterLocator {
140
140
  });
141
141
  newLocator.pipeline.push({ action: 'withinRadius', value: spatialPayload });
142
142
  }
143
+ if (options.locallyControlled !== undefined) {
144
+ newLocator.pipeline.push({ action: 'filterLocallyControlled', value: options.locallyControlled ? '' : 'false' });
145
+ }
146
+ if (options.possessed !== undefined) {
147
+ newLocator.pipeline.push({ action: 'filterPossessed', value: options.possessed ? '' : 'false' });
148
+ }
149
+ if (options.playerControlled !== undefined) {
150
+ newLocator.pipeline.push({ action: 'filterPossessed', value: options.playerControlled ? '' : 'false' });
151
+ }
143
152
  return newLocator;
144
153
  }
145
154
  /**
@@ -29,7 +29,8 @@ export declare enum SpecterEventType {
29
29
  GameplayAttribute = "GameplayAttribute",
30
30
  AssertionFailure = "AssertionFailure",
31
31
  GameEvent = "GameEvent",
32
- GameplayTag = "GameplayTag"
32
+ GameplayTag = "GameplayTag",
33
+ DiagnosticWarning = "DiagnosticWarning"
33
34
  }
34
35
  export interface SpecterTimelineEvent {
35
36
  timestamp: number;
@@ -38,6 +39,7 @@ export interface SpecterTimelineEvent {
38
39
  eventType: SpecterEventType;
39
40
  oldValue: string;
40
41
  newValue: string;
42
+ networkRole?: string;
41
43
  instigator?: string;
42
44
  effectCauser?: string;
43
45
  gameplayEffect?: string;
@@ -276,11 +278,16 @@ export declare class SpecterWorld {
276
278
  * @param payload The data payload to send
277
279
  * @param context Optional string to distinguish identical commands in the UI (e.g., "Attacker" or "Player 1")
278
280
  */
279
- evaluate(commandName: string, payload?: any, context?: string, targetLocator?: string): Promise<any>;
281
+ evaluate(commandName: string, payload?: any, context?: string, targetLocator?: string, bHideStep?: boolean): Promise<any>;
280
282
  setTimeDilation(speed: number): Promise<void>;
281
283
  spawnActor(assetPath: string, options?: SpawnOptions): Promise<ActorLocator>;
282
284
  actor<T extends RegisteredActorClasses | (string & {})>(selector: T): ActorLocator<T>;
283
285
  actorByTag(tagName: string): ActorLocator;
286
+ /**
287
+ * Locates the locally controlled actor for this world.
288
+ * Optionally filters by an actor class or selector.
289
+ */
290
+ localActor<T extends RegisteredActorClasses | (string & {}) = any>(className?: T): ActorLocator<T>;
284
291
  widget<T extends RegisteredWidgetClasses | (string & {})>(className: T): WidgetLocator<T>;
285
292
  getByWidget<T extends RegisteredWidgetClasses | (string & {})>(className: T): WidgetLocator<T>;
286
293
  getByRole(role: WidgetRole | string, options?: WidgetRoleOptions): WidgetLocator;
@@ -17,6 +17,7 @@ var SpecterEventType;
17
17
  SpecterEventType["AssertionFailure"] = "AssertionFailure";
18
18
  SpecterEventType["GameEvent"] = "GameEvent";
19
19
  SpecterEventType["GameplayTag"] = "GameplayTag";
20
+ SpecterEventType["DiagnosticWarning"] = "DiagnosticWarning";
20
21
  })(SpecterEventType || (exports.SpecterEventType = SpecterEventType = {}));
21
22
  exports.VectorUtils = {
22
23
  addOffset: (location, direction, offset) => {
@@ -466,7 +467,13 @@ class SpecterWorld {
466
467
  * @param payload The data payload to send
467
468
  * @param context Optional string to distinguish identical commands in the UI (e.g., "Attacker" or "Player 1")
468
469
  */
469
- async evaluate(commandName, payload = {}, context, targetLocator) {
470
+ async evaluate(commandName, payload = {}, context, targetLocator, bHideStep = false) {
471
+ if (bHideStep) {
472
+ return await this.transport.sendCommand({
473
+ command: commandName,
474
+ payload: payload
475
+ });
476
+ }
470
477
  const formattedCommand = commandName.charAt(0).toLowerCase() + commandName.slice(1);
471
478
  const portTag = this.transport.friendlyPortTag;
472
479
  // Format the title based on whether context was provided
@@ -514,6 +521,16 @@ class SpecterWorld {
514
521
  actorByTag(tagName) {
515
522
  return new locators_1.ActorLocator(this.transport, [{ action: 'getByTag', value: tagName }]);
516
523
  }
524
+ /**
525
+ * Locates the locally controlled actor for this world.
526
+ * Optionally filters by an actor class or selector.
527
+ */
528
+ localActor(className) {
529
+ if (className) {
530
+ return this.actor(className).locallyControlled();
531
+ }
532
+ return new locators_1.ActorLocator(this.transport, [{ action: 'filterLocallyControlled', value: '' }]);
533
+ }
517
534
  // ==========================================
518
535
  // THE WIDGET ENTRY POINTS
519
536
  // ==========================================
@@ -1,4 +1,5 @@
1
1
  import { SpecterLocator, ActorLocator } from '../core/locators';
2
+ import { SpecterTimelineEvent } from '../core/specter-client';
2
3
  declare global {
3
4
  namespace PlaywrightTest {
4
5
  interface Matchers<R, T> {
@@ -15,6 +16,11 @@ declare global {
15
16
  }, triggerAction?: () => Promise<void>): T extends SpecterLocator ? Promise<R> : never;
16
17
  toHaveGameplayTag(tag: string): T extends SpecterLocator ? Promise<R> : never;
17
18
  toHaveGameplayEffect(effectClassPath: string): T extends SpecterLocator ? Promise<R> : never;
19
+ toHaveAppliedGameplayEffect(effectNameOrClass: string, options?: {
20
+ count?: number;
21
+ instigator?: string | ActorLocator;
22
+ timeout?: number;
23
+ }): T extends SpecterLocator ? Promise<R> : never;
18
24
  toHaveGameplayAbility(abilityClassPath: string, options?: {
19
25
  timeout?: number;
20
26
  }): T extends SpecterLocator ? Promise<R> : never;
@@ -29,6 +35,7 @@ declare global {
29
35
  toBeExecutingAbility(abilityClassPath: string): T extends SpecterLocator ? Promise<R> : never;
30
36
  toHaveActivatedAbility(ability: string, optionsOrTrigger?: {
31
37
  timeout?: number;
38
+ times?: number;
32
39
  } | (() => Promise<void>), triggerAction?: () => Promise<void>): T extends SpecterLocator ? Promise<R> : never;
33
40
  toHaveGameplayTagCount(tag: string, expectedCount: number): T extends SpecterLocator ? Promise<R> : never;
34
41
  toHaveAnyGameplayTags(tags: string[]): T extends SpecterLocator ? Promise<R> : never;
@@ -52,6 +59,11 @@ export interface GasMatchers {
52
59
  }, triggerAction?: () => Promise<void>): Promise<void>;
53
60
  toHaveGameplayTag(tag: string): Promise<void>;
54
61
  toHaveGameplayEffect(effectClassPath: string): Promise<void>;
62
+ toHaveAppliedGameplayEffect(effectNameOrClass: string, options?: {
63
+ count?: number;
64
+ instigator?: string | ActorLocator;
65
+ timeout?: number;
66
+ }): Promise<void>;
55
67
  toHaveGameplayAbility(abilityClassPath: string, options?: {
56
68
  timeout?: number;
57
69
  }): Promise<void>;
@@ -66,12 +78,14 @@ export interface GasMatchers {
66
78
  toBeExecutingAbility(abilityClassPath: string): Promise<void>;
67
79
  toHaveActivatedAbility(ability: string, optionsOrTrigger?: {
68
80
  timeout?: number;
81
+ times?: number;
69
82
  } | (() => Promise<void>), triggerAction?: () => Promise<void>): Promise<void>;
70
83
  toHaveGameplayTagCount(tag: string, expectedCount: number): Promise<void>;
71
84
  toHaveAnyGameplayTags(tags: string[]): Promise<void>;
72
85
  toHaveAllGameplayTags(tags: string[]): Promise<void>;
73
86
  }
74
87
  export declare function formatAiDiagnostics(diagnostics: any): string;
88
+ export declare function formatCausalityTimeline(events: SpecterTimelineEvent[]): string;
75
89
  export declare const gasExpect: import("playwright/test").Expect<{
76
90
  toHaveAttributeValue(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, attributeSet: string, attributeName: string, expectedValue: number, options?: {
77
91
  timeout?: number;
@@ -116,6 +130,21 @@ export declare const gasExpect: import("playwright/test").Expect<{
116
130
  actual: boolean;
117
131
  expected: boolean;
118
132
  }>;
133
+ toHaveAppliedGameplayEffect(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, effectNameOrClass: string, options?: {
134
+ count?: number;
135
+ instigator?: string | ActorLocator;
136
+ timeout?: number;
137
+ }): Promise<{
138
+ pass: true;
139
+ message: () => string;
140
+ actual: boolean | SpecterTimelineEvent;
141
+ expected: string;
142
+ } | {
143
+ pass: boolean;
144
+ message: () => string;
145
+ actual: number;
146
+ expected: number;
147
+ }>;
119
148
  toHaveGameplayAbility(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, abilityClassPath: string, options?: {
120
149
  timeout?: number;
121
150
  }): Promise<{
@@ -180,11 +209,12 @@ export declare const gasExpect: import("playwright/test").Expect<{
180
209
  }>;
181
210
  toHaveActivatedAbility(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, ability: string, optionsOrTrigger?: {
182
211
  timeout?: number;
212
+ times?: number;
183
213
  } | (() => Promise<void>), triggerAction?: () => Promise<void>): Promise<{
184
214
  pass: boolean;
185
215
  message: () => string;
186
- actual: boolean;
187
- expected: boolean;
216
+ actual: number | boolean;
217
+ expected: number | boolean;
188
218
  }>;
189
219
  toHaveGameplayTagCount(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, tag: string, expectedCount: number): Promise<{
190
220
  pass: boolean;
@@ -35,11 +35,13 @@ var __importStar = (this && this.__importStar) || (function () {
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.gasExpect = void 0;
37
37
  exports.formatAiDiagnostics = formatAiDiagnostics;
38
+ exports.formatCausalityTimeline = formatCausalityTimeline;
38
39
  const test_1 = __importStar(require("@playwright/test"));
39
40
  const specter_client_1 = require("../core/specter-client");
40
41
  function formatAiDiagnostics(diagnostics) {
41
42
  if (!diagnostics)
42
43
  return '';
44
+ diagnostics = diagnostics?.data || diagnostics;
43
45
  const lines = [];
44
46
  lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
45
47
  lines.push('🧠 SPECTER AI DIAGNOSTICS REPORT');
@@ -94,9 +96,10 @@ function formatAiDiagnostics(diagnostics) {
94
96
  // 5. Recent Flight Recorder Events
95
97
  if (diagnostics.flightRecorder && diagnostics.flightRecorder.length > 0) {
96
98
  lines.push('⏱️ Recent Flight Recorder Events (most recent last):');
97
- const recentSlice = diagnostics.flightRecorder.slice(-12);
99
+ const recentSlice = diagnostics.flightRecorder.slice(-15);
98
100
  for (const ev of recentSlice) {
99
- lines.push(` [${Number(ev.timestamp).toFixed(2)}s] ${ev.eventName} - ${ev.description || ''}`);
101
+ const roleStr = ev.networkRole ? `${ev.networkRole} ` : '';
102
+ lines.push(` [${Number(ev.timestamp).toFixed(2)}s] ${roleStr}${ev.eventName} - ${ev.description || ''}`);
100
103
  }
101
104
  lines.push('');
102
105
  }
@@ -119,6 +122,61 @@ function formatAiDiagnostics(diagnostics) {
119
122
  catch { }
120
123
  return '\n\n' + lines.join('\n');
121
124
  }
125
+ function formatCausalityTimeline(events) {
126
+ if (!events || events.length === 0)
127
+ return '';
128
+ const lines = [];
129
+ lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
130
+ lines.push('📜 GAS EVENT CAUSALITY TIMELINE');
131
+ lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
132
+ // Deduplicate identical consecutive / redundant events
133
+ const seen = new Set();
134
+ const uniqueEvents = [];
135
+ for (const ev of events) {
136
+ const key = `${ev.timestamp}_${ev.eventName}_${ev.oldValue}_${ev.newValue}_${ev.description}_${ev.networkRole}`;
137
+ if (!seen.has(key)) {
138
+ seen.add(key);
139
+ uniqueEvents.push(ev);
140
+ }
141
+ }
142
+ // Sort chronologically
143
+ uniqueEvents.sort((a, b) => (Number(a.timestamp) || 0) - (Number(b.timestamp) || 0));
144
+ for (const ev of uniqueEvents) {
145
+ const timeVal = Number(ev.timestamp);
146
+ const timeStr = !isNaN(timeVal) ? `[${timeVal.toFixed(2)}s]` : `[${ev.timestamp || '0.00s'}]`;
147
+ const roleStr = ev.networkRole ? `${ev.networkRole} ` : '';
148
+ if (ev.eventType === specter_client_1.SpecterEventType.DiagnosticWarning || ev.eventType === 'DiagnosticWarning' || ev.eventName?.includes('DiagnosticWarning') || ev.eventName?.includes('Watchdog Warning')) {
149
+ lines.push(` • ⚠️ ${roleStr}${timeStr} [DIAGNOSTIC WARNING] ${ev.description || ev.eventName}`);
150
+ }
151
+ else if (ev.eventType === specter_client_1.SpecterEventType.GameplayAttribute || ev.eventType === 'GameplayAttribute') {
152
+ const oldNum = parseFloat(ev.oldValue);
153
+ const newNum = parseFloat(ev.newValue);
154
+ const delta = (!isNaN(oldNum) && !isNaN(newNum)) ? (newNum - oldNum) : undefined;
155
+ const deltaStr = delta !== undefined ? ` (Delta: ${delta > 0 ? '+' : ''}${delta.toFixed(1)})` : '';
156
+ const targetStr = ev.target ? ` on [${ev.target}]` : '';
157
+ const effectStr = ev.gameplayEffect ? ` | Effect: ${ev.gameplayEffect}` : '';
158
+ const instigatorStr = ev.instigator ? ` | Instigator: ${ev.instigator}` : '';
159
+ lines.push(` • 📊 ${roleStr}${timeStr} Attribute '${ev.eventName}'${targetStr}: ${ev.oldValue ?? '?'} -> ${ev.newValue ?? '?'}${deltaStr}${effectStr}${instigatorStr}`);
160
+ }
161
+ else if (ev.eventName?.startsWith('GameplayEffectApplied:') || ev.eventName?.startsWith('GE Applied') || ev.gameplayEffect) {
162
+ const effectName = ev.gameplayEffect || ev.eventName?.replace('GameplayEffectApplied: ', '').replace('GE Applied [', '').replace(']', '');
163
+ const targetStr = ev.target ? ` -> Target: [${ev.target}]` : '';
164
+ const instigatorStr = ev.instigator ? ` | Instigator: ${ev.instigator}` : '';
165
+ const abilityStr = ev.ability ? ` | Ability: ${ev.ability}` : '';
166
+ lines.push(` • ⚡ ${roleStr}${timeStr} Effect Applied: ${effectName}${targetStr}${instigatorStr}${abilityStr}`);
167
+ }
168
+ else if (ev.eventName?.startsWith('GameplayAbilityActivated:') || ev.eventName?.startsWith('Ability Activated') || ev.ability) {
169
+ const abilityName = ev.ability || ev.eventName?.replace('GameplayAbilityActivated: ', '').replace('Ability Activated [', '').replace(']', '');
170
+ const instigatorStr = ev.instigator ? ` | Instigator: ${ev.instigator}` : '';
171
+ lines.push(` • 🎯 ${roleStr}${timeStr} Ability Activated: ${abilityName}${instigatorStr}`);
172
+ }
173
+ else {
174
+ lines.push(` • ℹ️ ${roleStr}${timeStr} ${ev.eventName} - ${ev.description || ''}`);
175
+ }
176
+ }
177
+ lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
178
+ return '\n\n' + lines.join('\n');
179
+ }
122
180
  exports.gasExpect = test_1.expect.extend({
123
181
  async toHaveAttributeValue(locator, attributeSet, attributeName, expectedValue, options) {
124
182
  const assertionName = 'toHaveAttributeValue';
@@ -135,6 +193,18 @@ exports.gasExpect = test_1.expect.extend({
135
193
  return await test_1.default.step(stepName, async () => {
136
194
  let lastValue;
137
195
  let valueHistory = [];
196
+ const startTime = Date.now();
197
+ const transport = locator.transport;
198
+ const causalityEvents = [];
199
+ // Seed causality events from recent transport buffer
200
+ if (transport && typeof transport.getRecentEvents === 'function') {
201
+ const recent = transport.getRecentEvents('GLOBAL_timeline-event', startTime - 3000);
202
+ for (const item of recent) {
203
+ if (item?.data) {
204
+ causalityEvents.push(item.data);
205
+ }
206
+ }
207
+ }
138
208
  try {
139
209
  // 1. Check the current value immediately (try once)
140
210
  try {
@@ -155,7 +225,6 @@ exports.gasExpect = test_1.expect.extend({
155
225
  // Suppress initial read error if transient, but proceed to listen
156
226
  }
157
227
  // 2. If it does not match immediately, listen for the live attribute change event
158
- const transport = locator.transport;
159
228
  const finalValue = await new Promise((resolve, reject) => {
160
229
  let timeoutId;
161
230
  let pollIntervalId;
@@ -173,6 +242,7 @@ exports.gasExpect = test_1.expect.extend({
173
242
  const listener = (event) => {
174
243
  if (isResolved)
175
244
  return;
245
+ causalityEvents.push(event);
176
246
  if (event.eventType === specter_client_1.SpecterEventType.GameplayAttribute &&
177
247
  (event.eventName === attributeName || event.eventName.includes(attributeName))) {
178
248
  const val = parseFloat(event.newValue);
@@ -233,6 +303,23 @@ exports.gasExpect = test_1.expect.extend({
233
303
  try {
234
304
  const diags = await locator.getDiagnostics({ limit: 20 });
235
305
  diagStr = formatAiDiagnostics(diags);
306
+ if (diags?.flightRecorder && Array.isArray(diags.flightRecorder)) {
307
+ for (const ev of diags.flightRecorder) {
308
+ causalityEvents.push(ev);
309
+ }
310
+ }
311
+ }
312
+ catch { }
313
+ const timelineStr = formatCausalityTimeline(causalityEvents);
314
+ try {
315
+ const testInfo = test_1.default.info();
316
+ if (testInfo && timelineStr) {
317
+ testInfo.attachments.push({
318
+ name: 'Specter Causality Timeline',
319
+ contentType: 'text/markdown',
320
+ body: Buffer.from(timelineStr)
321
+ });
322
+ }
236
323
  }
237
324
  catch { }
238
325
  return {
@@ -241,6 +328,7 @@ exports.gasExpect = test_1.expect.extend({
241
328
  `Expected: ${this.utils.printExpected(expectedValue)}\n` +
242
329
  `Received: ${lastValue !== undefined ? this.utils.printReceived(lastValue) : 'Timeout'}\n` +
243
330
  `History: [${valueHistory.join(', ')}]` +
331
+ timelineStr +
244
332
  diagStr,
245
333
  actual: lastValue,
246
334
  expected: expectedValue
@@ -518,6 +606,23 @@ exports.gasExpect = test_1.expect.extend({
518
606
  limit: 30
519
607
  });
520
608
  diagStr = formatAiDiagnostics(diags);
609
+ if (diags?.flightRecorder && Array.isArray(diags.flightRecorder)) {
610
+ for (const ev of diags.flightRecorder) {
611
+ capturedEvents.push(ev);
612
+ }
613
+ }
614
+ }
615
+ catch { }
616
+ const timelineStr = formatCausalityTimeline(capturedEvents);
617
+ try {
618
+ const testInfo = test_1.default.info();
619
+ if (testInfo && timelineStr) {
620
+ testInfo.attachments.push({
621
+ name: 'Specter Causality Timeline',
622
+ contentType: 'text/markdown',
623
+ body: Buffer.from(timelineStr)
624
+ });
625
+ }
521
626
  }
522
627
  catch { }
523
628
  return {
@@ -526,6 +631,7 @@ exports.gasExpect = test_1.expect.extend({
526
631
  `Error: ${e.message}\n` +
527
632
  `Expected criteria: { ${expectedParts.join(', ')} }\n\n` +
528
633
  failureDetails +
634
+ timelineStr +
529
635
  diagStr,
530
636
  actual: lastEvent,
531
637
  expected: expectedChange
@@ -604,6 +710,236 @@ exports.gasExpect = test_1.expect.extend({
604
710
  };
605
711
  });
606
712
  },
713
+ async toHaveAppliedGameplayEffect(locator, effectNameOrClass, options) {
714
+ const assertionName = 'toHaveAppliedGameplayEffect';
715
+ const isNot = this.isNot;
716
+ const prefix = isNot ? 'not.toHaveAppliedGameplayEffect' : 'toHaveAppliedGameplayEffect';
717
+ const timeout = options?.timeout ?? 5000;
718
+ const expectedCount = options?.count;
719
+ const startTime = Date.now();
720
+ const expectedParts = [effectNameOrClass];
721
+ if (expectedCount !== undefined)
722
+ expectedParts.push(`count: ${expectedCount}`);
723
+ if (options?.instigator !== undefined) {
724
+ const instName = typeof options.instigator === 'string' ? options.instigator : options.instigator.toString();
725
+ expectedParts.push(`instigator: ${instName}`);
726
+ }
727
+ const stepName = `${prefix}('${effectNameOrClass}'${expectedCount !== undefined ? `, { count: ${expectedCount} }` : ''}) @ ${locator.toString()}`;
728
+ return await test_1.default.step(stepName, async () => {
729
+ const transport = locator.transport;
730
+ const capturedEvents = [];
731
+ const matchingApplications = [];
732
+ // Resolve instigator and target names
733
+ const [expectedInstigatorName, targetName] = await Promise.all([
734
+ options?.instigator
735
+ ? (typeof options.instigator === 'string' ? Promise.resolve(options.instigator) : options.instigator.getObjectName().catch(() => undefined))
736
+ : Promise.resolve(undefined),
737
+ locator.getObjectName().catch(() => undefined),
738
+ ]);
739
+ const isMatchingEffect = (ev) => {
740
+ const isEffectEvent = (ev.eventName && ev.eventName.includes('GameplayEffectApplied')) ||
741
+ (ev.eventName && ev.eventName.includes('GE Applied')) ||
742
+ (ev.gameplayEffect && ev.gameplayEffect.length > 0) ||
743
+ (ev.description && ev.description.includes('GameplayEffectApplied')) ||
744
+ (ev.description && ev.description.includes('Applied'));
745
+ if (!isEffectEvent)
746
+ return false;
747
+ // Match effect name
748
+ const evEffect = ev.gameplayEffect || (ev.eventName ? ev.eventName.replace('GameplayEffectApplied: ', '').replace('GE Applied [', '').replace(']', '') : '');
749
+ const effectMatches = evEffect.includes(effectNameOrClass) || effectNameOrClass.includes(evEffect) ||
750
+ (ev.description && ev.description.includes(effectNameOrClass));
751
+ if (!effectMatches)
752
+ return false;
753
+ // Target match (if target is present in event and targetName is known)
754
+ if (targetName && ev.target) {
755
+ const cleanTarget = targetName.trim();
756
+ const evTarget = ev.target.trim();
757
+ if (!evTarget.includes(cleanTarget) && !cleanTarget.includes(evTarget)) {
758
+ return false;
759
+ }
760
+ }
761
+ // Instigator match
762
+ if (expectedInstigatorName && ev.instigator) {
763
+ const cleanInst = expectedInstigatorName.trim();
764
+ const evInst = ev.instigator.trim();
765
+ if (!evInst.includes(cleanInst) && !cleanInst.includes(evInst)) {
766
+ return false;
767
+ }
768
+ }
769
+ return true;
770
+ };
771
+ // Seed from recent events in transport
772
+ if (transport && typeof transport.getRecentEvents === 'function') {
773
+ const recent = transport.getRecentEvents('GLOBAL_timeline-event', startTime - 3000);
774
+ for (const item of recent) {
775
+ if (item?.data) {
776
+ capturedEvents.push(item.data);
777
+ if (isMatchingEffect(item.data)) {
778
+ matchingApplications.push(item.data);
779
+ }
780
+ }
781
+ }
782
+ }
783
+ // Also check current active gameplay effects if count is not strictly demanded
784
+ let isActiveOnTarget = false;
785
+ try {
786
+ isActiveOnTarget = await locator.hasActiveGameplayEffect(effectNameOrClass);
787
+ }
788
+ catch { }
789
+ // If we are not demanding exact count and it's already active or already matched
790
+ if (expectedCount === undefined && !isNot) {
791
+ if (matchingApplications.length > 0 || isActiveOnTarget) {
792
+ return {
793
+ pass: true,
794
+ message: () => 'passed',
795
+ actual: matchingApplications.length > 0 ? matchingApplications[0] : true,
796
+ expected: effectNameOrClass
797
+ };
798
+ }
799
+ }
800
+ // Listen for events
801
+ const result = await new Promise((resolve) => {
802
+ let timeoutId;
803
+ let isResolved = false;
804
+ const cleanup = () => {
805
+ if (isResolved)
806
+ return;
807
+ isResolved = true;
808
+ clearTimeout(timeoutId);
809
+ if (transport && typeof transport.removeEventListener === 'function') {
810
+ transport.removeEventListener('GLOBAL_timeline-event', listener);
811
+ }
812
+ };
813
+ const checkCondition = () => {
814
+ if (isResolved)
815
+ return;
816
+ if (expectedCount !== undefined) {
817
+ if (matchingApplications.length === expectedCount) {
818
+ setTimeout(() => {
819
+ if (isResolved)
820
+ return;
821
+ if (matchingApplications.length === expectedCount) {
822
+ cleanup();
823
+ resolve({ pass: true });
824
+ }
825
+ else {
826
+ cleanup();
827
+ resolve({
828
+ pass: false,
829
+ error: `Expected ${expectedCount} application(s) of '${effectNameOrClass}', but detected ${matchingApplications.length} applications!`
830
+ });
831
+ }
832
+ }, 150);
833
+ return;
834
+ }
835
+ else if (matchingApplications.length > expectedCount) {
836
+ cleanup();
837
+ resolve({
838
+ pass: false,
839
+ error: `Expected ${expectedCount} application(s) of '${effectNameOrClass}', but detected ${matchingApplications.length} applications!`
840
+ });
841
+ return;
842
+ }
843
+ }
844
+ else {
845
+ if (matchingApplications.length > 0) {
846
+ cleanup();
847
+ resolve({ pass: true });
848
+ return;
849
+ }
850
+ }
851
+ };
852
+ const listener = (event) => {
853
+ if (isResolved)
854
+ return;
855
+ capturedEvents.push(event);
856
+ if (isMatchingEffect(event)) {
857
+ matchingApplications.push(event);
858
+ checkCondition();
859
+ }
860
+ };
861
+ if (transport && typeof transport.registerEventListener === 'function') {
862
+ transport.registerEventListener('GLOBAL_timeline-event', listener);
863
+ }
864
+ // Immediate check after listener registered
865
+ checkCondition();
866
+ timeoutId = setTimeout(async () => {
867
+ cleanup();
868
+ // Final check on timeout
869
+ if (expectedCount !== undefined) {
870
+ if (matchingApplications.length === expectedCount) {
871
+ resolve({ pass: true });
872
+ }
873
+ else {
874
+ resolve({
875
+ pass: false,
876
+ error: `Timed out after ${timeout}ms: Expected ${expectedCount} application(s) of '${effectNameOrClass}', but received ${matchingApplications.length}.`
877
+ });
878
+ }
879
+ }
880
+ else {
881
+ try {
882
+ const active = await locator.hasActiveGameplayEffect(effectNameOrClass);
883
+ if (active) {
884
+ resolve({ pass: true });
885
+ return;
886
+ }
887
+ }
888
+ catch { }
889
+ resolve({
890
+ pass: false,
891
+ error: `Timed out after ${timeout}ms waiting for gameplay effect '${effectNameOrClass}' to be applied to ${locator.toString()}`
892
+ });
893
+ }
894
+ }, timeout);
895
+ });
896
+ if (result.pass === !isNot) {
897
+ return {
898
+ pass: !isNot,
899
+ message: () => 'passed',
900
+ actual: matchingApplications.length,
901
+ expected: expectedCount ?? 1
902
+ };
903
+ }
904
+ // Failure handling with diagnostics and timeline
905
+ let diagStr = '';
906
+ try {
907
+ const diags = await locator.getDiagnostics({
908
+ instigator: options?.instigator,
909
+ limit: 30
910
+ });
911
+ diagStr = formatAiDiagnostics(diags);
912
+ if (diags?.flightRecorder && Array.isArray(diags.flightRecorder)) {
913
+ for (const ev of diags.flightRecorder) {
914
+ capturedEvents.push(ev);
915
+ }
916
+ }
917
+ }
918
+ catch { }
919
+ const timelineStr = formatCausalityTimeline(capturedEvents);
920
+ try {
921
+ const testInfo = test_1.default.info();
922
+ if (testInfo && timelineStr) {
923
+ testInfo.attachments.push({
924
+ name: 'Specter Causality Timeline',
925
+ contentType: 'text/markdown',
926
+ body: Buffer.from(timelineStr)
927
+ });
928
+ }
929
+ }
930
+ catch { }
931
+ return {
932
+ pass: isNot,
933
+ message: () => `${this.utils.matcherHint(assertionName, locator.toString(), expectedParts.join(', '))}\n\n` +
934
+ `Error: ${result.error || 'Assertion failed'}\n` +
935
+ `Applications Recorded: ${matchingApplications.length} (Expected: ${expectedCount ?? '>= 1'})\n\n` +
936
+ timelineStr +
937
+ diagStr,
938
+ actual: matchingApplications.length,
939
+ expected: expectedCount ?? 1
940
+ };
941
+ });
942
+ },
607
943
  async toHaveGameplayAbility(locator, abilityClassPath, options) {
608
944
  const assertionName = 'toHaveGameplayAbility';
609
945
  const isNot = this.isNot;
@@ -772,103 +1108,242 @@ exports.gasExpect = test_1.expect.extend({
772
1108
  const assertionName = 'toHaveActivatedAbility';
773
1109
  const isNot = this.isNot;
774
1110
  const prefix = isNot ? 'not.toHaveActivatedAbility' : 'toHaveActivatedAbility';
775
- const stepName = `${prefix}('${ability}') @ ${locator.toString()}`;
776
1111
  let timeout = 5000;
777
1112
  let action;
1113
+ let expectedTimes;
778
1114
  if (typeof optionsOrTrigger === 'function') {
779
1115
  action = optionsOrTrigger;
780
1116
  }
781
1117
  else if (optionsOrTrigger && typeof optionsOrTrigger === 'object') {
782
1118
  timeout = optionsOrTrigger.timeout ?? 5000;
1119
+ expectedTimes = optionsOrTrigger.times;
783
1120
  }
784
1121
  if (triggerAction && typeof triggerAction === 'function') {
785
1122
  action = triggerAction;
786
1123
  }
1124
+ const stepName = `${prefix}('${ability}'${expectedTimes !== undefined ? `, { times: ${expectedTimes} }` : ''}) @ ${locator.toString()}`;
787
1125
  return await test_1.default.step(stepName, async () => {
788
- // 1. Check initially if it's already active
789
- let isAlreadyActive = false;
790
- try {
791
- isAlreadyActive = await locator.isAbilityExecuting(ability);
792
- }
793
- catch (err) {
794
- // Ignore initial check errors
1126
+ const transport = locator.transport;
1127
+ const capturedEvents = [];
1128
+ const activations = [];
1129
+ const startTime = Date.now();
1130
+ const targetName = await locator.getObjectName().catch(() => undefined);
1131
+ const isMatchingAbility = (data) => {
1132
+ if (!data)
1133
+ return false;
1134
+ if (data.ability === ability || data.abilityName === ability || data.abilityClass === ability) {
1135
+ return true;
1136
+ }
1137
+ if (data.tags && Array.isArray(data.tags)) {
1138
+ if (data.tags.some((t) => t === ability || t.includes(ability))) {
1139
+ return true;
1140
+ }
1141
+ }
1142
+ if (data.abilityClass && data.abilityClass.includes(ability)) {
1143
+ return true;
1144
+ }
1145
+ if (data.abilityPath && data.abilityPath.includes(ability)) {
1146
+ return true;
1147
+ }
1148
+ if (data.eventName && data.eventName.includes(ability)) {
1149
+ return true;
1150
+ }
1151
+ if (data.description && data.description.includes(ability)) {
1152
+ return true;
1153
+ }
1154
+ return false;
1155
+ };
1156
+ // Seed from recent transport events if trigger action ran just prior
1157
+ if (transport && typeof transport.getRecentEvents === 'function') {
1158
+ const recent = transport.getRecentEvents('GLOBAL_timeline-event', startTime - 3000);
1159
+ for (const item of recent) {
1160
+ if (item?.data) {
1161
+ capturedEvents.push(item.data);
1162
+ if (isMatchingAbility(item.data)) {
1163
+ activations.push(item.data);
1164
+ }
1165
+ }
1166
+ }
795
1167
  }
796
- if (isAlreadyActive) {
797
- if (isNot) {
1168
+ // If no exact count is required, check initially if already active
1169
+ if (expectedTimes === undefined) {
1170
+ let isAlreadyActive = false;
1171
+ try {
1172
+ isAlreadyActive = await locator.isAbilityExecuting(ability);
1173
+ }
1174
+ catch { }
1175
+ if (isAlreadyActive) {
1176
+ if (isNot) {
1177
+ return {
1178
+ pass: isNot,
1179
+ message: () => `Expected ability '${ability}' not to be active on ${locator.toString()}, but it was already executing.`,
1180
+ actual: true,
1181
+ expected: !isNot
1182
+ };
1183
+ }
798
1184
  return {
799
- pass: isNot,
800
- message: () => `Expected ability '${ability}' not to be active on ${locator.toString()}, but it was already executing.`,
1185
+ pass: !isNot,
1186
+ message: () => 'passed',
801
1187
  actual: true,
802
1188
  expected: !isNot
803
1189
  };
804
1190
  }
805
- return {
806
- pass: !isNot,
807
- message: () => 'passed',
808
- actual: true,
809
- expected: !isNot
810
- };
811
1191
  }
812
- // 2. Set up event listener for OnAbilityActivated
813
- const eventPromise = locator.waitForEvent('OnAbilityActivated', {
814
- timeout,
815
- predicate: (data) => {
816
- if (!data)
817
- return false;
818
- if (data.ability === ability || data.abilityName === ability || data.abilityClass === ability) {
819
- return true;
1192
+ // Set up listener for timeline events
1193
+ let checkConditionFn = () => { };
1194
+ const result = await new Promise(async (resolve) => {
1195
+ let timeoutId;
1196
+ let isResolved = false;
1197
+ const cleanup = () => {
1198
+ if (isResolved)
1199
+ return;
1200
+ isResolved = true;
1201
+ clearTimeout(timeoutId);
1202
+ if (transport && typeof transport.removeEventListener === 'function') {
1203
+ transport.removeEventListener('GLOBAL_timeline-event', listener);
820
1204
  }
821
- if (data.tags && Array.isArray(data.tags)) {
822
- if (data.tags.some(t => t === ability || t.includes(ability))) {
823
- return true;
1205
+ };
1206
+ const checkCondition = () => {
1207
+ if (isResolved)
1208
+ return;
1209
+ if (expectedTimes !== undefined) {
1210
+ if (activations.length === expectedTimes) {
1211
+ setTimeout(() => {
1212
+ if (isResolved)
1213
+ return;
1214
+ if (activations.length === expectedTimes) {
1215
+ cleanup();
1216
+ resolve({ pass: true });
1217
+ }
1218
+ else {
1219
+ cleanup();
1220
+ resolve({
1221
+ pass: false,
1222
+ error: `Expected ability '${ability}' to activate ${expectedTimes} time(s), but detected ${activations.length} activations!`
1223
+ });
1224
+ }
1225
+ }, 150);
1226
+ return;
1227
+ }
1228
+ else if (activations.length > expectedTimes) {
1229
+ cleanup();
1230
+ resolve({
1231
+ pass: false,
1232
+ error: `Expected ability '${ability}' to activate ${expectedTimes} time(s), but detected ${activations.length} activations!`
1233
+ });
1234
+ return;
824
1235
  }
825
1236
  }
826
- if (data.abilityClass && data.abilityClass.includes(ability)) {
827
- return true;
1237
+ else {
1238
+ if (activations.length > 0) {
1239
+ cleanup();
1240
+ resolve({ pass: true });
1241
+ return;
1242
+ }
828
1243
  }
829
- if (data.abilityPath && data.abilityPath.includes(ability)) {
830
- return true;
1244
+ };
1245
+ checkConditionFn = checkCondition;
1246
+ const listener = (event) => {
1247
+ if (isResolved)
1248
+ return;
1249
+ capturedEvents.push(event);
1250
+ const isAbilityEv = (event.eventName && event.eventName.includes('Ability Activated')) ||
1251
+ (event.description && event.description.includes('activated ability')) ||
1252
+ event.ability;
1253
+ if (isAbilityEv && isMatchingAbility(event)) {
1254
+ if (targetName && event.instigator) {
1255
+ const cleanTarget = targetName.trim();
1256
+ const cleanInst = event.instigator.trim();
1257
+ if (cleanInst.includes(cleanTarget) || cleanTarget.includes(cleanInst)) {
1258
+ activations.push(event);
1259
+ checkCondition();
1260
+ }
1261
+ }
1262
+ else {
1263
+ activations.push(event);
1264
+ checkCondition();
1265
+ }
831
1266
  }
832
- return false;
1267
+ };
1268
+ if (transport && typeof transport.registerEventListener === 'function') {
1269
+ transport.registerEventListener('GLOBAL_timeline-event', listener);
833
1270
  }
834
- }).then(() => true).catch(() => false);
835
- // 3. If a trigger action was provided, run it while the listener is active
836
- if (action) {
837
- await action();
838
- }
839
- // 4. Await event with polling fallback
840
- let didActivate = await eventPromise;
841
- // If event did not catch it (e.g. slight timing difference), check executing state
842
- if (!didActivate && !isNot) {
843
- try {
844
- didActivate = await locator.isAbilityExecuting(ability);
1271
+ // If a trigger action was provided, run it now while listening
1272
+ if (action) {
1273
+ await action();
845
1274
  }
846
- catch { }
847
- }
848
- if (didActivate === !isNot) {
1275
+ checkCondition();
1276
+ timeoutId = setTimeout(async () => {
1277
+ cleanup();
1278
+ if (expectedTimes !== undefined) {
1279
+ if (activations.length === expectedTimes) {
1280
+ resolve({ pass: true });
1281
+ }
1282
+ else {
1283
+ resolve({
1284
+ pass: false,
1285
+ error: `Timed out after ${timeout}ms: Expected ability '${ability}' to activate ${expectedTimes} time(s), but received ${activations.length}.`
1286
+ });
1287
+ }
1288
+ }
1289
+ else {
1290
+ // Polling fallback: check executing state one last time
1291
+ try {
1292
+ const executing = await locator.isAbilityExecuting(ability);
1293
+ if (executing) {
1294
+ resolve({ pass: true });
1295
+ return;
1296
+ }
1297
+ }
1298
+ catch { }
1299
+ resolve({
1300
+ pass: false,
1301
+ error: `Timed out after ${timeout}ms waiting for ability activation on '${ability}'.`
1302
+ });
1303
+ }
1304
+ }, timeout);
1305
+ });
1306
+ if (result.pass === !isNot) {
849
1307
  return {
850
1308
  pass: !isNot,
851
1309
  message: () => 'passed',
852
- actual: didActivate,
853
- expected: !isNot
1310
+ actual: activations.length > 0 ? activations.length : false,
1311
+ expected: expectedTimes ?? !isNot
854
1312
  };
855
1313
  }
856
- // Failure: Fetch rich AI diagnostics
1314
+ // Failure handling: Fetch rich AI diagnostics and build Causality Timeline
857
1315
  let diagStr = '';
858
1316
  try {
859
1317
  const diags = await locator.getDiagnostics({ limit: 20 });
860
1318
  diagStr = formatAiDiagnostics(diags);
1319
+ if (diags?.flightRecorder && Array.isArray(diags.flightRecorder)) {
1320
+ for (const ev of diags.flightRecorder) {
1321
+ capturedEvents.push(ev);
1322
+ }
1323
+ }
1324
+ }
1325
+ catch { }
1326
+ const timelineStr = formatCausalityTimeline(capturedEvents);
1327
+ try {
1328
+ const testInfo = test_1.default.info();
1329
+ if (testInfo && timelineStr) {
1330
+ testInfo.attachments.push({
1331
+ name: 'Specter Causality Timeline',
1332
+ contentType: 'text/markdown',
1333
+ body: Buffer.from(timelineStr)
1334
+ });
1335
+ }
861
1336
  }
862
1337
  catch { }
863
1338
  return {
864
1339
  pass: isNot,
865
1340
  message: () => `${this.utils.matcherHint(assertionName, locator.toString(), ability)}\n\n` +
866
- `Timed out after ${timeout}ms waiting for ability activation on '${ability}'.\n` +
867
- `Expected: ${isNot ? 'not to activate ability' : 'to activate ability'} ${ability}\n` +
868
- `Received: ${didActivate ? 'activated' : 'not activated'}` +
1341
+ `Error: ${result.error || 'Assertion failed'}\n` +
1342
+ `Activations Recorded: ${activations.length} (Expected: ${expectedTimes ?? (isNot ? 0 : '>= 1')})\n\n` +
1343
+ timelineStr +
869
1344
  diagStr,
870
- actual: didActivate,
871
- expected: !isNot
1345
+ actual: activations.length,
1346
+ expected: expectedTimes ?? !isNot
872
1347
  };
873
1348
  });
874
1349
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.111",
3
+ "version": "1.0.114",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",