@specter-automation/test 1.0.109 → 1.0.111

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.
@@ -63,6 +63,13 @@ export interface SpecterActorEvents {
63
63
  z: number;
64
64
  };
65
65
  };
66
+ OnAbilityActivated: {
67
+ ability: string;
68
+ abilityName: string;
69
+ abilityClass: string;
70
+ abilityPath?: string;
71
+ tags: string[];
72
+ };
66
73
  }
67
74
  export interface SpecterWidgetEvents {
68
75
  OnClicked: void;
@@ -330,6 +330,15 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
330
330
  */
331
331
  type(text: string, delayMs?: number): Promise<void>;
332
332
  triggerAbilityByTag(inputTag: string): Promise<void>;
333
+ /**
334
+ * Simulates an ability input press or release on this actor's ASC.
335
+ * Use this to interact with active abilities that use WaitInputPress/WaitInputRelease
336
+ * (e.g. toggle abilities like Steel's Shield Block).
337
+ *
338
+ * @param abilityTag - The gameplay tag of the ability (e.g. "Ability.Slot.D")
339
+ * @param pressed - true to simulate press, false to simulate release. Defaults to true.
340
+ */
341
+ pressAbilityInput(abilityTag: string, pressed?: boolean): Promise<void>;
333
342
  triggerAbilityWithTarget(abilityTag: string, target: SpecterLocator | Vector3): Promise<void>;
334
343
  applyGameplayEffect(effectClassPath: string, level?: number): Promise<void>;
335
344
  hasActiveGameplayEffect(effectClassPath: string): Promise<boolean>;
@@ -339,7 +348,7 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
339
348
  getGameplayEffectStackCount(effectClassPath: string): Promise<number>;
340
349
  getGameplayEffectLevel(effectClassPath: string): Promise<number>;
341
350
  getAttributeBaseValue(attributeSet: string, attributeName: string): Promise<number>;
342
- isAbilityExecuting(abilityClassPath: string): Promise<boolean>;
351
+ isAbilityExecuting(abilityOrClassPath: string): Promise<boolean>;
343
352
  cancelAbility(abilityClassPath: string): Promise<void>;
344
353
  getGameplayTagCount(tag: string): Promise<number>;
345
354
  hasAnyGameplayTags(tags: string[]): Promise<boolean>;
@@ -425,4 +434,12 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
425
434
  * and optional accessible name.
426
435
  */
427
436
  getByRole(role: WidgetRole | string, options?: WidgetRoleOptions): WidgetLocator;
437
+ /**
438
+ * Fetches comprehensive AI diagnostics for this actor (and an optional instigator),
439
+ * including attribute snapshot, active gameplay tags, effects, identity, and flight recorder events.
440
+ */
441
+ getDiagnostics(options?: {
442
+ instigator?: ActorLocator | SpecterLocator;
443
+ limit?: number;
444
+ }): Promise<any>;
428
445
  }
@@ -847,10 +847,29 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
847
847
  async triggerAbilityByTag(inputTag) {
848
848
  await this.evaluate("TriggerAbilityByTag", { inputTag });
849
849
  }
850
+ /**
851
+ * Simulates an ability input press or release on this actor's ASC.
852
+ * Use this to interact with active abilities that use WaitInputPress/WaitInputRelease
853
+ * (e.g. toggle abilities like Steel's Shield Block).
854
+ *
855
+ * @param abilityTag - The gameplay tag of the ability (e.g. "Ability.Slot.D")
856
+ * @param pressed - true to simulate press, false to simulate release. Defaults to true.
857
+ */
858
+ async pressAbilityInput(abilityTag, pressed = true) {
859
+ await this.evaluate("TriggerGasInput", { tag: abilityTag, isPressed: pressed });
860
+ }
850
861
  async triggerAbilityWithTarget(abilityTag, target) {
851
862
  let payload = { abilityTag };
852
863
  if (target instanceof specter_locator_1.SpecterLocator) {
853
864
  payload.targetLocatorPipeline = target.pipeline;
865
+ if (typeof target.getLocation === 'function') {
866
+ try {
867
+ payload.targetLocation = await target.getLocation();
868
+ }
869
+ catch {
870
+ // Fallback to server-side pipeline resolution if getLocation fails
871
+ }
872
+ }
854
873
  }
855
874
  else {
856
875
  payload.targetLocation = target;
@@ -887,9 +906,12 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
887
906
  const response = await this.evaluate("GetAttributeBaseValue", { attributeSet, attributeName });
888
907
  return response.data.baseValue;
889
908
  }
890
- async isAbilityExecuting(abilityClassPath) {
891
- const response = await this.evaluate("IsAbilityExecuting", { abilityClassPath });
892
- return response.data.executing;
909
+ async isAbilityExecuting(abilityOrClassPath) {
910
+ const response = await this.evaluate("IsAbilityExecuting", {
911
+ ability: abilityOrClassPath,
912
+ abilityClassPath: abilityOrClassPath
913
+ });
914
+ return response.data?.isExecuting ?? response.data?.executing ?? false;
893
915
  }
894
916
  async cancelAbility(abilityClassPath) {
895
917
  await this.evaluate("CancelAbility", { abilityClassPath });
@@ -1051,5 +1073,19 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
1051
1073
  { action: 'getWidgetByRole', value: rolePayload, exact: options?.exact }
1052
1074
  ]);
1053
1075
  }
1076
+ /**
1077
+ * Fetches comprehensive AI diagnostics for this actor (and an optional instigator),
1078
+ * including attribute snapshot, active gameplay tags, effects, identity, and flight recorder events.
1079
+ */
1080
+ async getDiagnostics(options) {
1081
+ const payload = {
1082
+ limit: options?.limit ?? 30,
1083
+ targetLocatorPipeline: this.pipeline
1084
+ };
1085
+ if (options?.instigator) {
1086
+ payload.instigatorLocatorPipeline = options.instigator.pipeline;
1087
+ }
1088
+ return await this.transport.sendCommand("GetActorDiagnostics", this.pipeline, payload);
1089
+ }
1054
1090
  }
1055
1091
  exports.ActorLocator = ActorLocator;
@@ -42,6 +42,60 @@ export interface SpecterTimelineEvent {
42
42
  effectCauser?: string;
43
43
  gameplayEffect?: string;
44
44
  ability?: string;
45
+ target?: string;
46
+ }
47
+ export interface SpecterActiveEffect {
48
+ name: string;
49
+ duration: number;
50
+ remainingTime: number;
51
+ stackCount: number;
52
+ instigator?: string;
53
+ }
54
+ export interface SpecterActorSnapshot {
55
+ name: string;
56
+ class: string;
57
+ tags: string[];
58
+ location: Vector3;
59
+ rotation: Rotator;
60
+ forward: Vector3;
61
+ velocity: Vector3;
62
+ teamId?: number;
63
+ asc?: string;
64
+ ascOwner?: string;
65
+ attributes?: Record<string, number>;
66
+ gameplayTags?: string[];
67
+ activeEffects?: SpecterActiveEffect[];
68
+ }
69
+ export interface SpecterDiagnosticsReport {
70
+ target?: SpecterActorSnapshot;
71
+ instigator?: SpecterActorSnapshot;
72
+ distance?: number;
73
+ relativeDirection?: string;
74
+ facingDotProduct?: number;
75
+ actorMap?: Record<string, {
76
+ name: string;
77
+ class: string;
78
+ asc?: string;
79
+ ascOwner?: string;
80
+ }>;
81
+ flightRecorder?: Array<{
82
+ timestamp: number;
83
+ eventName: string;
84
+ description: string;
85
+ eventType: string;
86
+ oldValue?: string;
87
+ newValue?: string;
88
+ instigator?: string;
89
+ effectCauser?: string;
90
+ gameplayEffect?: string;
91
+ ability?: string;
92
+ target?: string;
93
+ }>;
94
+ engine?: {
95
+ map: string;
96
+ worldTime: number;
97
+ deltaSeconds: number;
98
+ };
45
99
  }
46
100
  export interface Vector3 {
47
101
  x: number;
@@ -146,6 +200,23 @@ export declare class SpecterWorld {
146
200
  readonly network: SpecterNetwork;
147
201
  constructor(transport: SpecterTransport);
148
202
  static connect(url?: string): Promise<SpecterWorld>;
203
+ /**
204
+ * Queries comprehensive runtime diagnostics from the engine, including
205
+ * actor identity mapping, attribute/tag snapshots, spatial relations, and recent Flight Recorder events.
206
+ */
207
+ getDiagnostics(options?: {
208
+ target?: SpecterLocator | ActorLocator;
209
+ instigator?: SpecterLocator | ActorLocator;
210
+ limit?: number;
211
+ }): Promise<SpecterDiagnosticsReport>;
212
+ /**
213
+ * Commands Unreal Engine to safely reload or load a game module (e.g. "Hots") using FModuleManager.
214
+ */
215
+ reloadModule(moduleName: string): Promise<{
216
+ success: boolean;
217
+ message: string;
218
+ wasLoaded: boolean;
219
+ }>;
149
220
  /**
150
221
  * Waits for the given `timeout` in milliseconds.
151
222
  * Matches Playwright's `page.waitForTimeout()` method.
@@ -284,6 +284,30 @@ class SpecterWorld {
284
284
  // Inject the connected transport into the new world
285
285
  return new SpecterWorld(transport);
286
286
  }
287
+ /**
288
+ * Queries comprehensive runtime diagnostics from the engine, including
289
+ * actor identity mapping, attribute/tag snapshots, spatial relations, and recent Flight Recorder events.
290
+ */
291
+ async getDiagnostics(options) {
292
+ const payload = {
293
+ limit: options?.limit ?? 30
294
+ };
295
+ if (options?.target) {
296
+ payload.targetLocatorPipeline = options.target.pipeline;
297
+ }
298
+ if (options?.instigator) {
299
+ payload.instigatorLocatorPipeline = options.instigator.pipeline;
300
+ }
301
+ const res = await this.evaluate("GetActorDiagnostics", payload);
302
+ return res;
303
+ }
304
+ /**
305
+ * Commands Unreal Engine to safely reload or load a game module (e.g. "Hots") using FModuleManager.
306
+ */
307
+ async reloadModule(moduleName) {
308
+ const res = await this.evaluate("ReloadModule", { module: moduleName });
309
+ return res;
310
+ }
287
311
  /**
288
312
  * Waits for the given `timeout` in milliseconds.
289
313
  * Matches Playwright's `page.waitForTimeout()` method.
@@ -471,7 +495,9 @@ class SpecterWorld {
471
495
  const location = options?.location || { x: 0, y: 0, z: 0 };
472
496
  const rotation = options?.rotation || { pitch: 0, yaw: 0, roll: 0 };
473
497
  const assetName = assetPath.split('/').pop()?.split('.')[0];
474
- await this.evaluate("SpawnActor", { assetPath, tag, location, rotation }, assetName, tag);
498
+ const properties = options?.properties;
499
+ const spawnController = options?.spawnController;
500
+ await this.evaluate("SpawnActor", { assetPath, tag, location, rotation, properties, spawnController }, assetName, tag);
475
501
  return this.actorByTag(tag);
476
502
  }
477
503
  // ==========================================
@@ -195,6 +195,29 @@ exports.test = test_1.test.extend({
195
195
  catch (e) {
196
196
  console.error("[Specter] Failed to capture error screenshot:", e);
197
197
  }
198
+ try {
199
+ const diagnostics = await world.getDiagnostics({ limit: 35 });
200
+ if (diagnostics) {
201
+ const formattedSummary = (0, gas_matchers_1.formatAiDiagnostics)(diagnostics);
202
+ console.log('\n' + formattedSummary + '\n');
203
+ const alreadyAttached = testInfo.attachments.some(a => a.name.includes('Specter AI Diagnostics'));
204
+ if (!alreadyAttached) {
205
+ testInfo.attachments.push({
206
+ name: 'Specter AI Diagnostics (JSON)',
207
+ contentType: 'application/json',
208
+ body: Buffer.from(JSON.stringify(diagnostics, null, 2))
209
+ });
210
+ testInfo.attachments.push({
211
+ name: 'Specter AI Diagnostics (Markdown)',
212
+ contentType: 'text/markdown',
213
+ body: Buffer.from(formattedSummary)
214
+ });
215
+ }
216
+ }
217
+ }
218
+ catch (e) {
219
+ console.error("[Specter] Failed to capture AI diagnostics on test failure:", e);
220
+ }
198
221
  }
199
222
  }, { auto: true }]
200
223
  });
@@ -27,6 +27,9 @@ declare global {
27
27
  toHaveGameplayEffectLevel(effectClassPath: string, expectedLevel: number): T extends SpecterLocator ? Promise<R> : never;
28
28
  toHaveAttributeBaseValue(attributeSet: string, attributeName: string, expectedValue: number): T extends SpecterLocator ? Promise<R> : never;
29
29
  toBeExecutingAbility(abilityClassPath: string): T extends SpecterLocator ? Promise<R> : never;
30
+ toHaveActivatedAbility(ability: string, optionsOrTrigger?: {
31
+ timeout?: number;
32
+ } | (() => Promise<void>), triggerAction?: () => Promise<void>): T extends SpecterLocator ? Promise<R> : never;
30
33
  toHaveGameplayTagCount(tag: string, expectedCount: number): T extends SpecterLocator ? Promise<R> : never;
31
34
  toHaveAnyGameplayTags(tags: string[]): T extends SpecterLocator ? Promise<R> : never;
32
35
  toHaveAllGameplayTags(tags: string[]): T extends SpecterLocator ? Promise<R> : never;
@@ -61,10 +64,14 @@ export interface GasMatchers {
61
64
  toHaveGameplayEffectLevel(effectClassPath: string, expectedLevel: number): Promise<void>;
62
65
  toHaveAttributeBaseValue(attributeSet: string, attributeName: string, expectedValue: number): Promise<void>;
63
66
  toBeExecutingAbility(abilityClassPath: string): Promise<void>;
67
+ toHaveActivatedAbility(ability: string, optionsOrTrigger?: {
68
+ timeout?: number;
69
+ } | (() => Promise<void>), triggerAction?: () => Promise<void>): Promise<void>;
64
70
  toHaveGameplayTagCount(tag: string, expectedCount: number): Promise<void>;
65
71
  toHaveAnyGameplayTags(tags: string[]): Promise<void>;
66
72
  toHaveAllGameplayTags(tags: string[]): Promise<void>;
67
73
  }
74
+ export declare function formatAiDiagnostics(diagnostics: any): string;
68
75
  export declare const gasExpect: import("playwright/test").Expect<{
69
76
  toHaveAttributeValue(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, attributeSet: string, attributeName: string, expectedValue: number, options?: {
70
77
  timeout?: number;
@@ -171,6 +178,14 @@ export declare const gasExpect: import("playwright/test").Expect<{
171
178
  actual: boolean;
172
179
  expected: boolean;
173
180
  }>;
181
+ toHaveActivatedAbility(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, ability: string, optionsOrTrigger?: {
182
+ timeout?: number;
183
+ } | (() => Promise<void>), triggerAction?: () => Promise<void>): Promise<{
184
+ pass: boolean;
185
+ message: () => string;
186
+ actual: boolean;
187
+ expected: boolean;
188
+ }>;
174
189
  toHaveGameplayTagCount(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, tag: string, expectedCount: number): Promise<{
175
190
  pass: boolean;
176
191
  message: () => string;
@@ -34,8 +34,91 @@ var __importStar = (this && this.__importStar) || (function () {
34
34
  })();
35
35
  Object.defineProperty(exports, "__esModule", { value: true });
36
36
  exports.gasExpect = void 0;
37
+ exports.formatAiDiagnostics = formatAiDiagnostics;
37
38
  const test_1 = __importStar(require("@playwright/test"));
38
39
  const specter_client_1 = require("../core/specter-client");
40
+ function formatAiDiagnostics(diagnostics) {
41
+ if (!diagnostics)
42
+ return '';
43
+ const lines = [];
44
+ lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
45
+ lines.push('🧠 SPECTER AI DIAGNOSTICS REPORT');
46
+ lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
47
+ // 1. Actor Identity Mapping
48
+ if (diagnostics.actorMap && Object.keys(diagnostics.actorMap).length > 0) {
49
+ lines.push('📍 Actor Identity Mapping:');
50
+ for (const [tag, info] of Object.entries(diagnostics.actorMap)) {
51
+ lines.push(` • [${tag}] -> ${info.name} (${info.class}) | ASC: ${info.asc || 'N/A'}${info.ascOwner ? ` (Owner: ${info.ascOwner})` : ''}`);
52
+ }
53
+ lines.push('');
54
+ }
55
+ // 2. Target Actor Current State
56
+ if (diagnostics.target) {
57
+ lines.push(`🎯 Target Actor: ${diagnostics.target.name} (${diagnostics.target.class})`);
58
+ if (diagnostics.target.attributes) {
59
+ const attrEntries = Object.entries(diagnostics.target.attributes)
60
+ .slice(0, 12)
61
+ .map(([k, v]) => `${k}: ${v}`)
62
+ .join(', ');
63
+ lines.push(` • Attributes: { ${attrEntries} }`);
64
+ }
65
+ if (diagnostics.target.gameplayTags && diagnostics.target.gameplayTags.length > 0) {
66
+ lines.push(` • Active Tags: [ ${diagnostics.target.gameplayTags.join(', ')} ]`);
67
+ }
68
+ if (diagnostics.target.activeEffects && diagnostics.target.activeEffects.length > 0) {
69
+ const effectStrs = diagnostics.target.activeEffects.map((e) => `${e.name} (stacks: ${e.stackCount}, remaining: ${Number(e.remainingTime).toFixed(1)}s)`);
70
+ lines.push(` • Active Effects: [ ${effectStrs.join(', ')} ]`);
71
+ }
72
+ lines.push('');
73
+ }
74
+ // 3. Instigator Actor Current State
75
+ if (diagnostics.instigator) {
76
+ lines.push(`⚔️ Instigator Actor: ${diagnostics.instigator.name} (${diagnostics.instigator.class})`);
77
+ if (diagnostics.instigator.attributes) {
78
+ const attrEntries = Object.entries(diagnostics.instigator.attributes)
79
+ .slice(0, 8)
80
+ .map(([k, v]) => `${k}: ${v}`)
81
+ .join(', ');
82
+ lines.push(` • Attributes: { ${attrEntries} }`);
83
+ }
84
+ if (diagnostics.instigator.gameplayTags && diagnostics.instigator.gameplayTags.length > 0) {
85
+ lines.push(` • Active Tags: [ ${diagnostics.instigator.gameplayTags.join(', ')} ]`);
86
+ }
87
+ lines.push('');
88
+ }
89
+ // 4. Spatial Analysis
90
+ if (diagnostics.distance !== undefined) {
91
+ lines.push(`📐 Spatial Context: Distance = ${Number(diagnostics.distance).toFixed(1)} units | Facing Zone = ${diagnostics.relativeDirection || 'N/A'} (Dot: ${Number(diagnostics.facingDotProduct || 0).toFixed(2)})`);
92
+ lines.push('');
93
+ }
94
+ // 5. Recent Flight Recorder Events
95
+ if (diagnostics.flightRecorder && diagnostics.flightRecorder.length > 0) {
96
+ lines.push('⏱️ Recent Flight Recorder Events (most recent last):');
97
+ const recentSlice = diagnostics.flightRecorder.slice(-12);
98
+ for (const ev of recentSlice) {
99
+ lines.push(` [${Number(ev.timestamp).toFixed(2)}s] ${ev.eventName} - ${ev.description || ''}`);
100
+ }
101
+ lines.push('');
102
+ }
103
+ lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
104
+ try {
105
+ const testInfo = test_1.default.info();
106
+ if (testInfo) {
107
+ testInfo.attachments.push({
108
+ name: 'Specter AI Diagnostics (JSON)',
109
+ contentType: 'application/json',
110
+ body: Buffer.from(JSON.stringify(diagnostics, null, 2))
111
+ });
112
+ testInfo.attachments.push({
113
+ name: 'Specter AI Diagnostics (Summary)',
114
+ contentType: 'text/markdown',
115
+ body: Buffer.from(lines.join('\n'))
116
+ });
117
+ }
118
+ }
119
+ catch { }
120
+ return '\n\n' + lines.join('\n');
121
+ }
39
122
  exports.gasExpect = test_1.expect.extend({
40
123
  async toHaveAttributeValue(locator, attributeSet, attributeName, expectedValue, options) {
41
124
  const assertionName = 'toHaveAttributeValue';
@@ -146,12 +229,19 @@ exports.gasExpect = test_1.expect.extend({
146
229
  if (!e.message?.includes('Timed out')) {
147
230
  throw e;
148
231
  }
232
+ let diagStr = '';
233
+ try {
234
+ const diags = await locator.getDiagnostics({ limit: 20 });
235
+ diagStr = formatAiDiagnostics(diags);
236
+ }
237
+ catch { }
149
238
  return {
150
239
  pass: isNot,
151
240
  message: () => `${this.utils.matcherHint(assertionName, locator.toString(), expectedValue.toString())}\n\n` +
152
241
  `Expected: ${this.utils.printExpected(expectedValue)}\n` +
153
242
  `Received: ${lastValue !== undefined ? this.utils.printReceived(lastValue) : 'Timeout'}\n` +
154
- `History: [${valueHistory.join(', ')}]`,
243
+ `History: [${valueHistory.join(', ')}]` +
244
+ diagStr,
155
245
  actual: lastValue,
156
246
  expected: expectedValue
157
247
  };
@@ -421,12 +511,22 @@ exports.gasExpect = test_1.expect.extend({
421
511
  if (lastFailedReasons.length > 0) {
422
512
  failureDetails += `\n\nFailed Criteria on last event:\n- ${lastFailedReasons.join('\n- ')}`;
423
513
  }
514
+ let diagStr = '';
515
+ try {
516
+ const diags = await locator.getDiagnostics({
517
+ instigator: expectedChange.instigator,
518
+ limit: 30
519
+ });
520
+ diagStr = formatAiDiagnostics(diags);
521
+ }
522
+ catch { }
424
523
  return {
425
524
  pass: isNot,
426
525
  message: () => `${this.utils.matcherHint(assertionName, locator.toString(), expectedParts.join(', '))}\n\n` +
427
526
  `Error: ${e.message}\n` +
428
527
  `Expected criteria: { ${expectedParts.join(', ')} }\n\n` +
429
- failureDetails,
528
+ failureDetails +
529
+ diagStr,
430
530
  actual: lastEvent,
431
531
  expected: expectedChange
432
532
  };
@@ -668,6 +768,110 @@ exports.gasExpect = test_1.expect.extend({
668
768
  return { pass: isNot, message: () => `Expected executing: ${!isNot}. Got: ${exec}`, actual: exec, expected: !isNot };
669
769
  });
670
770
  },
771
+ async toHaveActivatedAbility(locator, ability, optionsOrTrigger, triggerAction) {
772
+ const assertionName = 'toHaveActivatedAbility';
773
+ const isNot = this.isNot;
774
+ const prefix = isNot ? 'not.toHaveActivatedAbility' : 'toHaveActivatedAbility';
775
+ const stepName = `${prefix}('${ability}') @ ${locator.toString()}`;
776
+ let timeout = 5000;
777
+ let action;
778
+ if (typeof optionsOrTrigger === 'function') {
779
+ action = optionsOrTrigger;
780
+ }
781
+ else if (optionsOrTrigger && typeof optionsOrTrigger === 'object') {
782
+ timeout = optionsOrTrigger.timeout ?? 5000;
783
+ }
784
+ if (triggerAction && typeof triggerAction === 'function') {
785
+ action = triggerAction;
786
+ }
787
+ 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
795
+ }
796
+ if (isAlreadyActive) {
797
+ if (isNot) {
798
+ return {
799
+ pass: isNot,
800
+ message: () => `Expected ability '${ability}' not to be active on ${locator.toString()}, but it was already executing.`,
801
+ actual: true,
802
+ expected: !isNot
803
+ };
804
+ }
805
+ return {
806
+ pass: !isNot,
807
+ message: () => 'passed',
808
+ actual: true,
809
+ expected: !isNot
810
+ };
811
+ }
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;
820
+ }
821
+ if (data.tags && Array.isArray(data.tags)) {
822
+ if (data.tags.some(t => t === ability || t.includes(ability))) {
823
+ return true;
824
+ }
825
+ }
826
+ if (data.abilityClass && data.abilityClass.includes(ability)) {
827
+ return true;
828
+ }
829
+ if (data.abilityPath && data.abilityPath.includes(ability)) {
830
+ return true;
831
+ }
832
+ return false;
833
+ }
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);
845
+ }
846
+ catch { }
847
+ }
848
+ if (didActivate === !isNot) {
849
+ return {
850
+ pass: !isNot,
851
+ message: () => 'passed',
852
+ actual: didActivate,
853
+ expected: !isNot
854
+ };
855
+ }
856
+ // Failure: Fetch rich AI diagnostics
857
+ let diagStr = '';
858
+ try {
859
+ const diags = await locator.getDiagnostics({ limit: 20 });
860
+ diagStr = formatAiDiagnostics(diags);
861
+ }
862
+ catch { }
863
+ return {
864
+ pass: isNot,
865
+ 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'}` +
869
+ diagStr,
870
+ actual: didActivate,
871
+ expected: !isNot
872
+ };
873
+ });
874
+ },
671
875
  async toHaveGameplayTagCount(locator, tag, expectedCount) {
672
876
  const isNot = this.isNot;
673
877
  return await test_1.default.step(`${isNot ? 'not.' : ''}toHaveGameplayTagCount('${tag}', ${expectedCount})`, async () => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.109",
3
+ "version": "1.0.111",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",