@specter-automation/test 1.0.112 → 1.0.115

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;
@@ -869,8 +912,8 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
869
912
  async pressAbilityInput(abilityTag, pressed = true) {
870
913
  await this.evaluate("TriggerGasInput", { tag: abilityTag, isPressed: pressed });
871
914
  }
872
- async triggerAbilityWithTarget(abilityTag, target) {
873
- let payload = { abilityTag };
915
+ async triggerAbilityWithTarget(abilityTag, target, options) {
916
+ let payload = { abilityTag, ...options };
874
917
  if (target instanceof specter_locator_1.SpecterLocator) {
875
918
  payload.targetLocatorPipeline = target.pipeline;
876
919
  if (typeof target.getLocation === 'function') {
@@ -924,8 +967,12 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
924
967
  });
925
968
  return response.data?.isExecuting ?? response.data?.executing ?? false;
926
969
  }
927
- async cancelAbility(abilityClassPath) {
928
- await this.evaluate("CancelAbility", { abilityClassPath });
970
+ async cancelAbility(abilityOrTagOrClassPath) {
971
+ await this.evaluate("CancelAbility", {
972
+ ability: abilityOrTagOrClassPath,
973
+ abilityTag: abilityOrTagOrClassPath,
974
+ abilityClassPath: abilityOrTagOrClassPath
975
+ });
929
976
  }
930
977
  async getGameplayTagCount(tag) {
931
978
  const response = await this.evaluate("GetGameplayTagCount", { tag });
@@ -1096,7 +1143,8 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
1096
1143
  if (options?.instigator) {
1097
1144
  payload.instigatorLocatorPipeline = options.instigator.pipeline;
1098
1145
  }
1099
- 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;
1100
1148
  }
1101
1149
  }
1102
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[];
@@ -55,6 +58,10 @@ export declare class SpecterLocator<T = any> {
55
58
  } ? (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 {
56
59
  returnType: infer R;
57
60
  } ? R : any) : any) : any>;
61
+ /**
62
+ * Alias for `callFunction`. Calls a C++ UFUNCTION and returns the result.
63
+ */
64
+ callFunctionWithReturn(functionName: string, parameters?: Record<string, any>): Promise<any>;
58
65
  hasGameplayTag(tagToCheck: string): Promise<boolean>;
59
66
  getObjectName(): Promise<string>;
60
67
  getPropertyValue(propertyName: string): Promise<any>;
@@ -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
  /**
@@ -192,6 +201,12 @@ class SpecterLocator {
192
201
  }, functionName);
193
202
  return response.data?.ReturnValue || response.data?.returnValue || response.data;
194
203
  }
204
+ /**
205
+ * Alias for `callFunction`. Calls a C++ UFUNCTION and returns the result.
206
+ */
207
+ async callFunctionWithReturn(functionName, parameters) {
208
+ return this.callFunction(functionName, parameters);
209
+ }
195
210
  async hasGameplayTag(tagToCheck) {
196
211
  const response = await this.evaluate("HasGameplayTag", { tag: tagToCheck }, tagToCheck);
197
212
  return response.data.hasTag === true;
@@ -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;
@@ -281,6 +283,11 @@ export declare class SpecterWorld {
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) => {
@@ -520,6 +521,16 @@ class SpecterWorld {
520
521
  actorByTag(tagName) {
521
522
  return new locators_1.ActorLocator(this.transport, [{ action: 'getByTag', value: tagName }]);
522
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
+ }
523
534
  // ==========================================
524
535
  // THE WIDGET ENTRY POINTS
525
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.112",
3
+ "version": "1.0.115",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",