@specter-automation/test 1.0.145 → 1.0.147

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.
@@ -6,6 +6,9 @@ export interface LocatorStep {
6
6
  exact?: boolean;
7
7
  regex?: boolean;
8
8
  invert?: boolean;
9
+ /** GetComponent steps */
10
+ componentClass?: string;
11
+ componentName?: string;
9
12
  }
10
13
  export interface FilterOptions {
11
14
  hasComponent?: string;
@@ -201,7 +201,11 @@ class SpecterLocator {
201
201
  }
202
202
  /** The locator pipeline only, without the friendly name. */
203
203
  toSelectorString() {
204
- return this.pipeline.map(step => `${step.action}('${step.value}')`).join(' -> ');
204
+ // A GetComponent step keeps its class in componentClass (and its name in componentName), not in value
205
+ return this.pipeline.map(step => {
206
+ const value = step.value ?? (step.componentName ? `${step.componentClass}:${step.componentName}` : step.componentClass);
207
+ return `${step.action}('${value ?? ''}')`;
208
+ }).join(' -> ');
205
209
  }
206
210
  toString() {
207
211
  const selector = this.toSelectorString();
@@ -299,6 +303,9 @@ class SpecterLocator {
299
303
  slotIndex: options?.slotIndex ?? 0,
300
304
  componentName: options?.componentName
301
305
  }, parameterName);
306
+ // Empty when the material has no such parameter (the engine still names a texture, 'None')
307
+ if (response.data && response.data.found === false)
308
+ return '';
302
309
  return response.data?.value?.textureName || '';
303
310
  }
304
311
  async getMaterialName(options) {
@@ -315,19 +315,27 @@ exports.aiExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)(wit
315
315
  const startTime = Date.now();
316
316
  return await (async () => {
317
317
  let lastRunning = false;
318
+ let lastError = '';
318
319
  while (Date.now() - startTime < timeout) {
319
320
  try {
320
321
  lastRunning = await locator.isRunningBehaviorTree(treePath);
322
+ lastError = '';
321
323
  if (isNot ? !lastRunning : lastRunning) {
322
324
  return { pass: !isNot, message: () => 'passed' };
323
325
  }
324
326
  }
325
- catch (e) { }
327
+ catch (e) {
328
+ // A tree that doesn't exist, or an actor with no AI: neither proves the assertion either way
329
+ lastError = e?.message ?? String(e);
330
+ }
326
331
  await new Promise(r => setTimeout(r, 100));
327
332
  }
328
333
  return {
334
+ // An error fails .not too (pass is inverted for .not)
329
335
  pass: isNot,
330
- message: () => `Expected AI to ${isNot ? 'not ' : ''}be running BehaviorTree '${treePath}', but isRunning was ${lastRunning}.`
336
+ message: () => lastError
337
+ ? `Couldn't check whether the AI ${isNot ? 'is not' : 'is'} running BehaviorTree '${treePath}': ${lastError}`
338
+ : `Expected AI to ${isNot ? 'not ' : ''}be running BehaviorTree '${treePath}', but isRunning was ${lastRunning}.`
331
339
  };
332
340
  })();
333
341
  },
@@ -40,8 +40,12 @@ declare global {
40
40
  times?: number;
41
41
  } | (() => Promise<void>), triggerAction?: () => Promise<void>): T extends SpecterLocator ? Promise<R> : never;
42
42
  toHaveGameplayTagCount(tag: RegisteredGameplayTags, expectedCount: number): T extends SpecterLocator ? Promise<R> : never;
43
- toHaveAnyGameplayTags(tags: RegisteredGameplayTags[]): T extends SpecterLocator ? Promise<R> : never;
44
- toHaveAllGameplayTags(tags: RegisteredGameplayTags[]): T extends SpecterLocator ? Promise<R> : never;
43
+ toHaveAnyGameplayTags(tags: RegisteredGameplayTags[], options?: {
44
+ timeout?: number;
45
+ }): T extends SpecterLocator ? Promise<R> : never;
46
+ toHaveAllGameplayTags(tags: RegisteredGameplayTags[], options?: {
47
+ timeout?: number;
48
+ }): T extends SpecterLocator ? Promise<R> : never;
45
49
  }
46
50
  }
47
51
  }
@@ -85,8 +89,12 @@ export interface GasMatchers {
85
89
  times?: number;
86
90
  } | (() => Promise<void>), triggerAction?: () => Promise<void>): Promise<void>;
87
91
  toHaveGameplayTagCount(tag: RegisteredGameplayTags, expectedCount: number): Promise<void>;
88
- toHaveAnyGameplayTags(tags: RegisteredGameplayTags[]): Promise<void>;
89
- toHaveAllGameplayTags(tags: RegisteredGameplayTags[]): Promise<void>;
92
+ toHaveAnyGameplayTags(tags: RegisteredGameplayTags[], options?: {
93
+ timeout?: number;
94
+ }): Promise<void>;
95
+ toHaveAllGameplayTags(tags: RegisteredGameplayTags[], options?: {
96
+ timeout?: number;
97
+ }): Promise<void>;
90
98
  }
91
99
  export declare function formatAiDiagnostics(diagnostics: any): string;
92
100
  export declare function formatCausalityTimeline(events: SpecterTimelineEvent[]): string;
@@ -95,7 +103,12 @@ export declare const gasExpect: import("playwright/test").Expect<{
95
103
  timeout?: number;
96
104
  tolerance?: number;
97
105
  }): Promise<{
98
- pass: boolean;
106
+ pass: true;
107
+ message: () => string;
108
+ actual: any;
109
+ expected: number;
110
+ } | {
111
+ pass: false;
99
112
  message: () => string;
100
113
  actual: any;
101
114
  expected: number;
@@ -233,7 +246,9 @@ export declare const gasExpect: import("playwright/test").Expect<{
233
246
  actual: number;
234
247
  expected: number;
235
248
  }>;
236
- toHaveAnyGameplayTags(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, tags: RegisteredGameplayTags[]): Promise<{
249
+ toHaveAnyGameplayTags(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, tags: RegisteredGameplayTags[], options?: {
250
+ timeout?: number;
251
+ }): Promise<{
237
252
  pass: boolean;
238
253
  message: () => string;
239
254
  actual?: undefined;
@@ -244,7 +259,9 @@ export declare const gasExpect: import("playwright/test").Expect<{
244
259
  actual: boolean;
245
260
  expected: boolean;
246
261
  }>;
247
- toHaveAllGameplayTags(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, tags: RegisteredGameplayTags[]): Promise<{
262
+ toHaveAllGameplayTags(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, tags: RegisteredGameplayTags[], options?: {
263
+ timeout?: number;
264
+ }): Promise<{
248
265
  pass: boolean;
249
266
  message: () => string;
250
267
  actual?: undefined;
@@ -39,6 +39,27 @@ exports.formatCausalityTimeline = formatCausalityTimeline;
39
39
  const test_1 = __importStar(require("@playwright/test"));
40
40
  const instrument_1 = require("./instrument");
41
41
  const specter_client_1 = require("../core/specter-client");
42
+ /**
43
+ * An asset or class reference reduced to its class name, for comparing effect and ability names however they're
44
+ * written: '/Game/FX/GE_Burn.GE_Burn_C', 'GE_Burn_C', 'Default__GE_Burn_C' and 'GE_Burn' are all 'GE_Burn'.
45
+ */
46
+ function canonicalAssetName(name) {
47
+ let n = (name || '').trim();
48
+ if (!n)
49
+ return '';
50
+ const quoted = n.match(/'([^']+)'/);
51
+ if (quoted)
52
+ n = quoted[1];
53
+ n = n.split('/').pop() || n;
54
+ if (n.includes('.'))
55
+ n = n.split('.').pop() || n;
56
+ n = n.replace(/^Default__/, '').replace(/_C$/, '');
57
+ return n;
58
+ }
59
+ /** True when an ability reference looks like a gameplay tag ('Ability.Steel.Q') rather than a class or asset path */
60
+ function looksLikeGameplayTag(name) {
61
+ return !name.includes('/') && name.includes('.') && !/_C$/.test(name) && !/^(GA|GE)_/.test(name.split('.')[0]);
62
+ }
42
63
  function formatAiDiagnostics(diagnostics) {
43
64
  if (!diagnostics)
44
65
  return '';
@@ -189,6 +210,43 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
189
210
  return true;
190
211
  return Math.abs(val - expectedValue) <= tolerance;
191
212
  };
213
+ // .not waits for the attribute to hold anything but the value. pass is whether it holds the value: Playwright
214
+ // inverts it for .not
215
+ if (isNot) {
216
+ const notStart = Date.now();
217
+ let lastRead;
218
+ let lastError = '';
219
+ const history = [];
220
+ while (true) {
221
+ try {
222
+ lastRead = await locator.getAttributeValue(attributeSet, attributeName);
223
+ lastError = '';
224
+ if (lastRead !== undefined && !isNaN(lastRead)) {
225
+ if (history[history.length - 1] !== lastRead)
226
+ history.push(lastRead);
227
+ if (!isMatch(lastRead)) {
228
+ return { pass: false, message: () => 'passed', actual: lastRead, expected: expectedValue };
229
+ }
230
+ }
231
+ }
232
+ catch (e) {
233
+ lastError = e?.message ?? String(e);
234
+ }
235
+ if (Date.now() - notStart >= timeout)
236
+ break;
237
+ await new Promise(r => setTimeout(r, 100));
238
+ }
239
+ return {
240
+ pass: true,
241
+ message: () => `${this.utils.matcherHint(assertionName, locator.toString(), expectedValue.toString(), { isNot })}\n\n` +
242
+ `Expected: not ${this.utils.printExpected(expectedValue)}\n` +
243
+ (lastError
244
+ ? `Couldn't read ${attributeSet}.${attributeName}: ${lastError}`
245
+ : `Received: ${this.utils.printReceived(lastRead)}\nHistory: [${history.join(', ')}]`),
246
+ actual: lastRead,
247
+ expected: expectedValue
248
+ };
249
+ }
192
250
  return await (async () => {
193
251
  let lastValue;
194
252
  let valueHistory = [];
@@ -341,6 +399,14 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
341
399
  expectedParts.push(`gameplayEffect: ${expectedChange.gameplayEffect}`);
342
400
  if (expectedChange.ability !== undefined)
343
401
  expectedParts.push(`ability: ${expectedChange.ability}`);
402
+ // pass is whether the change happened (Playwright inverts it for .not): a match fails .not with this message
403
+ const matched = (actual) => ({
404
+ pass: true,
405
+ message: () => `${this.utils.matcherHint(assertionName, locator.toString(), expectedParts.join(', '), { isNot })}\n\n` +
406
+ `Expected no change matching { ${expectedParts.join(', ')} }, but got: ${describeAttributeChange(actual)}`,
407
+ actual,
408
+ expected: expectedChange
409
+ });
344
410
  return await (async () => {
345
411
  const transport = locator.transport;
346
412
  let lastEvent;
@@ -360,7 +426,7 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
360
426
  }
361
427
  try {
362
428
  // In parallel: resolve initial value and locator names
363
- const [resolvedInitialVal, expectedInstigatorName, expectedEffectCauserName] = await Promise.all([
429
+ const [resolvedInitialVal, expectedInstigatorName, expectedEffectCauserName, targetName] = await Promise.all([
364
430
  locator.getAttributeValue(attributeSet, attributeName).catch(() => undefined),
365
431
  expectedChange.instigator
366
432
  ? (typeof expectedChange.instigator === 'string' ? Promise.resolve(expectedChange.instigator) : expectedChange.instigator.getObjectName().catch(() => undefined))
@@ -368,6 +434,8 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
368
434
  expectedChange.effectCauser
369
435
  ? (typeof expectedChange.effectCauser === 'string' ? Promise.resolve(expectedChange.effectCauser) : expectedChange.effectCauser.getObjectName().catch(() => undefined))
370
436
  : Promise.resolve(undefined),
437
+ // The actor this checks: events come from every actor in the game
438
+ locator.getObjectName().catch(() => undefined),
371
439
  ]);
372
440
  initialValue = resolvedInitialVal;
373
441
  // Evaluates whether an event matches all expected criteria
@@ -378,6 +446,10 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
378
446
  if (event.eventName !== attributeName && !event.eventName?.includes(attributeName)) {
379
447
  return false;
380
448
  }
449
+ // Only changes to this actor's attributes count (the event's target is the avatar, a hero rather than its PlayerState)
450
+ if (targetName && (event.target || '').trim() !== targetName.trim()) {
451
+ return false;
452
+ }
381
453
  lastEvent = event;
382
454
  lastFailedReasons = [];
383
455
  let isMatch = true;
@@ -431,12 +503,7 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
431
503
  // A. Check events captured in real-time during setup
432
504
  for (const ev of capturedEvents) {
433
505
  if (evaluateEvent(ev)) {
434
- return {
435
- pass: !isNot,
436
- message: () => 'passed',
437
- actual: ev,
438
- expected: expectedChange
439
- };
506
+ return matched(ev);
440
507
  }
441
508
  }
442
509
  // B. Check transport recent events ring buffer (events from just before or during call)
@@ -444,12 +511,7 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
444
511
  const recent = transport.getRecentEvents('GLOBAL_timeline-event', startTime - 3000);
445
512
  for (const item of recent) {
446
513
  if (evaluateEvent(item.data)) {
447
- return {
448
- pass: !isNot,
449
- message: () => 'passed',
450
- actual: item.data,
451
- expected: expectedChange
452
- };
514
+ return matched(item.data);
453
515
  }
454
516
  }
455
517
  }
@@ -459,12 +521,7 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
459
521
  // Re-check captured events immediately after trigger action completes
460
522
  for (const ev of capturedEvents) {
461
523
  if (evaluateEvent(ev)) {
462
- return {
463
- pass: !isNot,
464
- message: () => 'passed',
465
- actual: ev,
466
- expected: expectedChange
467
- };
524
+ return matched(ev);
468
525
  }
469
526
  }
470
527
  }
@@ -475,27 +532,18 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
475
532
  // Verify whether any conflicting attribute change events arrived
476
533
  const conflictingEvent = capturedEvents.find(ev => (ev.eventType === specter_client_1.SpecterEventType.GameplayAttribute || ev.eventType === 'GameplayAttribute') &&
477
534
  (ev.eventName === attributeName || ev.eventName?.includes(attributeName)) &&
535
+ (!targetName || (ev.target || '').trim() === targetName.trim()) &&
478
536
  parseFloat(ev.oldValue) !== parseFloat(ev.newValue));
479
537
  if (!conflictingEvent) {
480
538
  const currentVal = await locator.getAttributeValue(attributeSet, attributeName).catch(() => initialValue);
481
539
  if (initialValue !== undefined && currentVal !== undefined) {
482
540
  const delta = currentVal - initialValue;
483
541
  if (Math.abs(delta) <= tolerance) {
484
- return {
485
- pass: !isNot,
486
- message: () => 'passed',
487
- actual: { delta, value: currentVal },
488
- expected: expectedChange
489
- };
542
+ return matched({ delta, value: currentVal });
490
543
  }
491
544
  }
492
545
  else if (currentVal !== undefined) {
493
- return {
494
- pass: !isNot,
495
- message: () => 'passed',
496
- actual: { delta: 0, value: currentVal },
497
- expected: expectedChange
498
- };
546
+ return matched({ delta: 0, value: currentVal });
499
547
  }
500
548
  }
501
549
  }
@@ -552,12 +600,7 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
552
600
  reject(new Error(`Timed out after ${timeout}ms waiting for attribute change event on '${attributeName}'`));
553
601
  }, timeout);
554
602
  });
555
- return {
556
- pass: !isNot,
557
- message: () => 'passed',
558
- actual: matchEvent,
559
- expected: expectedChange
560
- };
603
+ return matched(matchEvent);
561
604
  }
562
605
  catch (e) {
563
606
  if (!e.message?.includes('Timed out')) {
@@ -593,8 +636,9 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
593
636
  }
594
637
  }
595
638
  catch { }
639
+ // pass is whether the change happened: Playwright inverts it for .not, which passes here
596
640
  return {
597
- pass: isNot,
641
+ pass: false,
598
642
  message: () => `${this.utils.matcherHint(assertionName, locator.toString(), expectedParts.join(', '))}\n\n` +
599
643
  `Error: ${e.message}\n` +
600
644
  `Expected criteria: { ${expectedParts.join(', ')} }\n\n` +
@@ -642,35 +686,19 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
642
686
  locator.evaluate("TrackGameplayTag", { tag }, undefined, true).catch(() => undefined),
643
687
  ]);
644
688
  targetName = resolvedTargetName;
645
- const evaluateEvent = (event) => {
689
+ // A tag event is only a cue to ask the actor again: events can come from another actor's ASC (heroes
690
+ // keep theirs on the PlayerState), so only the actor's own answer counts
691
+ const isTagEvent = (event) => {
646
692
  if (event.eventType !== specter_client_1.SpecterEventType.GameplayTag && event.eventType !== 'GameplayTag') {
647
693
  return false;
648
694
  }
649
695
  const name = event.eventName || '';
650
696
  const desc = event.description || '';
651
697
  const matchesTag = name === tag || name.includes(`[${tag}]`) || name.includes(tag) || desc.includes(tag);
652
- if (!matchesTag) {
653
- return false;
698
+ if (matchesTag && targetName && (event.target || '').trim() === targetName) {
699
+ lastEvent = event;
654
700
  }
655
- if (targetName) {
656
- const evTarget = (event.target || '').trim();
657
- const locatorTag = (locator.tag || '').trim();
658
- const isTargetMatch = !evTarget ||
659
- evTarget.includes(targetName) || targetName.includes(evTarget) ||
660
- (locatorTag && (evTarget.includes(locatorTag) || locatorTag.includes(evTarget))) ||
661
- (evTarget.includes('PlayerState') && (targetName.includes('Hero') || targetName.includes('BP_') || targetName.includes('Character') || targetName.includes('Spawned')));
662
- if (!isTargetMatch) {
663
- return false;
664
- }
665
- }
666
- lastEvent = event;
667
- const isAdded = name.startsWith('Added') || event.newValue === 'true' || parseInt(event.newValue || '0') > 0;
668
- const isRemoved = name.startsWith('Removed') || event.newValue === 'false' || parseInt(event.newValue || '0') === 0;
669
- if (!isNot && isAdded)
670
- return true;
671
- if (isNot && isRemoved)
672
- return true;
673
- return false;
701
+ return matchesTag;
674
702
  };
675
703
  // Check initial state
676
704
  if (initialHasTag !== undefined && (initialHasTag === !isNot)) {
@@ -681,38 +709,55 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
681
709
  expected: !isNot
682
710
  };
683
711
  }
684
- // Check any events received during initial read
685
- for (const ev of capturedEvents) {
686
- if (evaluateEvent(ev)) {
687
- return {
688
- pass: !isNot,
689
- message: () => 'passed',
690
- actual: !isNot,
691
- expected: !isNot
692
- };
693
- }
694
- }
695
- // Wait for live event
712
+ // Wait for the actor to gain (or lose) the tag
696
713
  await new Promise((resolve, reject) => {
697
714
  let timeoutId;
715
+ let pollId;
698
716
  let isResolved = false;
717
+ let checking = false;
718
+ let checkAgain = false;
699
719
  const cleanup = () => {
700
720
  if (isResolved)
701
721
  return;
702
722
  isResolved = true;
703
723
  clearTimeout(timeoutId);
724
+ clearInterval(pollId);
704
725
  };
705
- onLiveEvent = (event) => {
726
+ const recheck = async () => {
706
727
  if (isResolved)
707
728
  return;
708
- if (evaluateEvent(event)) {
709
- cleanup();
710
- resolve();
729
+ if (checking) {
730
+ checkAgain = true;
731
+ return;
711
732
  }
733
+ checking = true;
734
+ try {
735
+ const hasTag = await locator.hasGameplayTag(tag, true);
736
+ if (!isResolved && hasTag === !isNot) {
737
+ cleanup();
738
+ resolve();
739
+ }
740
+ }
741
+ catch { }
742
+ finally {
743
+ checking = false;
744
+ if (checkAgain && !isResolved) {
745
+ checkAgain = false;
746
+ void recheck();
747
+ }
748
+ }
749
+ };
750
+ onLiveEvent = (event) => {
751
+ if (!isResolved && isTagEvent(event))
752
+ void recheck();
712
753
  };
754
+ // Events that arrived during the first read, then a slow poll in case an event is missed
755
+ if (capturedEvents.some(isTagEvent))
756
+ void recheck();
757
+ pollId = setInterval(() => void recheck(), 250);
713
758
  timeoutId = setTimeout(async () => {
714
759
  cleanup();
715
- // One final check before giving up in case an event was missed
760
+ // One final check before giving up
716
761
  try {
717
762
  const finalHasTag = await locator.hasGameplayTag(tag, true);
718
763
  if (finalHasTag !== undefined && (finalHasTag === !isNot)) {
@@ -865,24 +910,16 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
865
910
  (ev.description && ev.description.includes('Applied'));
866
911
  if (!isEffectEvent)
867
912
  return false;
868
- // Match effect name
869
- const evEffect = ev.gameplayEffect || (ev.eventName ? ev.eventName.replace('GameplayEffectApplied: ', '').replace('GE Applied [', '').replace(']', '') : '');
870
- const effectMatches = evEffect.includes(effectNameOrClass) || effectNameOrClass.includes(evEffect) ||
871
- (ev.description && ev.description.includes(effectNameOrClass));
872
- if (!effectMatches)
913
+ // Match effect name: the same class, however either side writes it
914
+ const wanted = canonicalAssetName(effectNameOrClass);
915
+ const evEffect = canonicalAssetName(ev.gameplayEffect || (ev.eventName ? ev.eventName.replace('GameplayEffectApplied: ', '').replace('GE Applied [', '').replace(']', '') : ''));
916
+ if (!wanted || evEffect !== wanted)
873
917
  return false;
874
- // Target match (if target is present in event and targetName is known)
875
- if (targetName && ev.target) {
876
- const cleanTarget = targetName.trim();
877
- const evTarget = ev.target.trim();
878
- const locatorTag = (locator.tag || '').trim();
879
- const isTargetMatch = !evTarget ||
880
- evTarget.includes(cleanTarget) || cleanTarget.includes(evTarget) ||
881
- (locatorTag && (evTarget.includes(locatorTag) || locatorTag.includes(evTarget))) ||
882
- (evTarget.includes('PlayerState') && (cleanTarget.includes('Hero') || cleanTarget.includes('BP_') || cleanTarget.includes('Character') || cleanTarget.includes('Spawned')));
883
- if (!isTargetMatch) {
918
+ // Target match: the event must name this actor (events from other actors never count)
919
+ if (targetName) {
920
+ const evTarget = (ev.target || '').trim();
921
+ if (evTarget !== targetName.trim())
884
922
  return false;
885
- }
886
923
  }
887
924
  // Instigator match
888
925
  if (expectedInstigatorName && ev.instigator) {
@@ -912,6 +949,16 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
912
949
  isActiveOnTarget = await locator.hasActiveGameplayEffect(effectNameOrClass);
913
950
  }
914
951
  catch { }
952
+ // An effect applied while that check ran (expect and apply often start together)
953
+ if (transport && typeof transport.getRecentEvents === 'function') {
954
+ for (const item of transport.getRecentEvents('GLOBAL_timeline-event', startTime - 3000)) {
955
+ if (item?.data) {
956
+ recordCapturedEvent(item.data);
957
+ if (isMatchingEffect(item.data))
958
+ recordEffectApplication(item.data);
959
+ }
960
+ }
961
+ }
915
962
  // If we are not demanding exact count and it's already active or already matched
916
963
  if (expectedCount === undefined && !isNot) {
917
964
  if (matchingApplications.length > 0 || isActiveOnTarget) {
@@ -926,12 +973,15 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
926
973
  // Listen for events
927
974
  const result = await new Promise((resolve) => {
928
975
  let timeoutId;
976
+ let pollId;
929
977
  let isResolved = false;
930
978
  const cleanup = () => {
931
979
  if (isResolved)
932
980
  return;
933
981
  isResolved = true;
934
982
  clearTimeout(timeoutId);
983
+ if (pollId)
984
+ clearInterval(pollId);
935
985
  if (transport && typeof transport.removeEventListener === 'function') {
936
986
  transport.removeEventListener('GLOBAL_timeline-event', listener);
937
987
  }
@@ -990,6 +1040,20 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
990
1040
  }
991
1041
  // Immediate check after listener registered
992
1042
  checkCondition();
1043
+ // A lasting effect also shows up as active, should its event be missed
1044
+ if (expectedCount === undefined && !isNot) {
1045
+ pollId = setInterval(async () => {
1046
+ if (isResolved)
1047
+ return;
1048
+ try {
1049
+ if (await locator.hasActiveGameplayEffect(effectNameOrClass)) {
1050
+ cleanup();
1051
+ resolve({ pass: true });
1052
+ }
1053
+ }
1054
+ catch { }
1055
+ }, 250);
1056
+ }
993
1057
  timeoutId = setTimeout(async () => {
994
1058
  cleanup();
995
1059
  // Final check on timeout
@@ -1273,41 +1337,25 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
1273
1337
  };
1274
1338
  const startTime = Date.now();
1275
1339
  const targetName = await locator.getObjectName().catch(() => undefined);
1340
+ // The same ability class (however either side writes it), or for a gameplay tag the ability's tag
1341
+ const wantedClass = canonicalAssetName(ability);
1342
+ const wantsTag = looksLikeGameplayTag(ability);
1276
1343
  const isMatchingAbility = (data) => {
1277
1344
  if (!data)
1278
1345
  return false;
1279
- const evAbility = (data.ability || data.abilityName || data.abilityClass || '').trim();
1280
- if (evAbility === ability || (evAbility && ability.includes(evAbility)) || (ability && evAbility.includes(ability))) {
1281
- return true;
1282
- }
1283
- if (data.tags && Array.isArray(data.tags)) {
1284
- if (data.tags.some((t) => t === ability || t.includes(ability) || ability.includes(t))) {
1285
- return true;
1286
- }
1287
- }
1288
- if (data.abilityClass && (data.abilityClass.includes(ability) || ability.includes(data.abilityClass))) {
1289
- return true;
1290
- }
1291
- if (data.abilityPath && (data.abilityPath.includes(ability) || ability.includes(data.abilityPath))) {
1292
- return true;
1293
- }
1294
- if (data.eventName && (data.eventName.includes(ability) || (evAbility && data.eventName.includes(evAbility)))) {
1295
- return true;
1296
- }
1297
- if (data.description && (data.description.includes(ability) || (evAbility && data.description.includes(evAbility)))) {
1298
- return true;
1346
+ const evTags = [data.ability, ...(Array.isArray(data.tags) ? data.tags : [])].filter(Boolean);
1347
+ if (wantsTag) {
1348
+ return evTags.some((t) => t === ability || t.startsWith(`${ability}.`));
1299
1349
  }
1300
- return false;
1350
+ const evClasses = [data.abilityClass, data.abilityName, data.abilityPath, data.ability].filter(Boolean);
1351
+ return evClasses.some((c) => canonicalAssetName(c) === wantedClass);
1301
1352
  };
1353
+ // The event must name this actor: activations on other actors never count
1302
1354
  const isMatchingActor = (data) => {
1303
1355
  if (!targetName)
1304
1356
  return true;
1305
1357
  const inst = (data.instigator || data.target || '').trim();
1306
- if (!inst)
1307
- return true;
1308
- const cleanTarget = targetName.trim();
1309
- return inst.includes(cleanTarget) || cleanTarget.includes(inst) ||
1310
- (inst.includes('PlayerState') && cleanTarget.includes('Hero') && inst.slice(-2) === cleanTarget.slice(-2));
1358
+ return inst === targetName.trim();
1311
1359
  };
1312
1360
  // Seed from recent transport events if trigger action ran just prior
1313
1361
  if (transport && typeof transport.getRecentEvents === 'function') {
@@ -1514,40 +1562,87 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
1514
1562
  return { pass: isNot, message: () => `Expected count: ${expectedCount}. Got: ${count}`, actual: count, expected: expectedCount };
1515
1563
  })();
1516
1564
  },
1517
- async toHaveAnyGameplayTags(locator, tags) {
1565
+ async toHaveAnyGameplayTags(locator, tags, options) {
1518
1566
  const isNot = this.isNot;
1519
1567
  return await (async () => {
1520
- const timeout = 5000;
1568
+ const timeout = options?.timeout ?? 5000;
1521
1569
  const startTime = Date.now();
1522
1570
  let has = false;
1571
+ let lastError = '';
1523
1572
  while (Date.now() - startTime < timeout) {
1524
1573
  try {
1525
1574
  has = await locator.hasAnyGameplayTags(tags, true);
1575
+ lastError = '';
1526
1576
  if (has === !isNot)
1527
1577
  return { pass: !isNot, message: () => 'passed' };
1528
1578
  }
1529
- catch (e) { }
1579
+ catch (e) {
1580
+ // An unknown tag or an actor with no ability system: report it rather than read it as "no"
1581
+ lastError = e?.message ?? String(e);
1582
+ }
1530
1583
  await new Promise(r => setTimeout(r, 100));
1531
1584
  }
1532
- return { pass: isNot, message: () => `Expected any tags: ${!isNot}. Got: ${has}`, actual: has, expected: !isNot };
1585
+ const list = tags.join(', ');
1586
+ return {
1587
+ pass: isNot,
1588
+ message: () => lastError
1589
+ ? `Couldn't read the gameplay tags of ${locator.toString()}: ${lastError}`
1590
+ : `Expected ${locator.toString()} ${isNot ? 'not ' : ''}to have any of [${list}], but it ${has ? 'does' : "doesn't"}.`,
1591
+ actual: has,
1592
+ expected: !isNot
1593
+ };
1533
1594
  })();
1534
1595
  },
1535
- async toHaveAllGameplayTags(locator, tags) {
1596
+ async toHaveAllGameplayTags(locator, tags, options) {
1536
1597
  const isNot = this.isNot;
1537
1598
  return await (async () => {
1538
- const timeout = 5000;
1599
+ const timeout = options?.timeout ?? 5000;
1539
1600
  const startTime = Date.now();
1540
1601
  let has = false;
1602
+ let lastError = '';
1541
1603
  while (Date.now() - startTime < timeout) {
1542
1604
  try {
1543
1605
  has = await locator.hasAllGameplayTags(tags, true);
1606
+ lastError = '';
1544
1607
  if (has === !isNot)
1545
1608
  return { pass: !isNot, message: () => 'passed' };
1546
1609
  }
1547
- catch (e) { }
1610
+ catch (e) {
1611
+ // An unknown tag or an actor with no ability system: report it rather than read it as "no"
1612
+ lastError = e?.message ?? String(e);
1613
+ }
1548
1614
  await new Promise(r => setTimeout(r, 100));
1549
1615
  }
1550
- return { pass: isNot, message: () => `Expected all tags: ${!isNot}. Got: ${has}`, actual: has, expected: !isNot };
1616
+ const list = tags.join(', ');
1617
+ return {
1618
+ pass: isNot,
1619
+ message: () => lastError
1620
+ ? `Couldn't read the gameplay tags of ${locator.toString()}: ${lastError}`
1621
+ : `Expected ${locator.toString()} ${isNot ? 'not ' : ''}to have all of [${list}], but it ${has ? 'does' : "doesn't"}.`,
1622
+ actual: has,
1623
+ expected: !isNot
1624
+ };
1551
1625
  })();
1552
1626
  },
1553
1627
  }));
1628
+ /** One line for an attribute change event: what changed, on whom, and from what (the raw event was cut short in reports) */
1629
+ function describeAttributeChange(event) {
1630
+ if (!event || event.oldValue === undefined) {
1631
+ return JSON.stringify(event);
1632
+ }
1633
+ const oldValue = parseFloat(event.oldValue);
1634
+ const newValue = parseFloat(event.newValue);
1635
+ const delta = newValue - oldValue;
1636
+ const parts = [`${event.eventName} ${oldValue} -> ${newValue} (${delta >= 0 ? '+' : ''}${delta})`];
1637
+ if (event.target)
1638
+ parts.push(`on ${event.target}`);
1639
+ if (typeof event.timestamp === 'number')
1640
+ parts.push(`at ${event.timestamp.toFixed(2)}s`);
1641
+ if (event.gameplayEffect)
1642
+ parts.push(`effect ${event.gameplayEffect}`);
1643
+ if (event.instigator)
1644
+ parts.push(`instigator ${event.instigator}`);
1645
+ if (event.ability)
1646
+ parts.push(`ability ${event.ability}`);
1647
+ return parts.join(', ');
1648
+ }
@@ -64,12 +64,15 @@ export declare const locatorExpect: import("playwright/test").Expect<{
64
64
  onScreen?: boolean;
65
65
  timeout?: number;
66
66
  }): Promise<{
67
- pass: boolean;
67
+ pass: any;
68
68
  message: () => string;
69
69
  }>;
70
70
  toBeInViewport(this: import("playwright/test").ExpectMatcherState, locator: any, options?: {
71
71
  timeout?: number;
72
- }): Promise<any>;
72
+ }): Promise<{
73
+ pass: any;
74
+ message: () => string;
75
+ }>;
73
76
  toBeDestroyed(this: import("playwright/test").ExpectMatcherState, locator: any, options?: {
74
77
  timeout?: number;
75
78
  }): Promise<{
@@ -46,6 +46,69 @@ function deepEqual(a, b) {
46
46
  const keysA = Object.keys(a), keysB = Object.keys(b);
47
47
  return keysA.length === keysB.length && keysA.every(k => Object.prototype.hasOwnProperty.call(b, k) && deepEqual(a[k], b[k]));
48
48
  }
49
+ /** toBeVisible, and toBeInViewport (visible and on screen) */
50
+ async function checkVisible(assertionName, locator, options) {
51
+ // 1. THE BOUNCER: Enforce type safety at runtime
52
+ const isActor = locator instanceof locators_1.ActorLocator;
53
+ const isWidget = locator instanceof locators_1.WidgetLocator;
54
+ if (!isActor && !isWidget) {
55
+ return {
56
+ pass: false,
57
+ message: () => `${this.utils.matcherHint(assertionName, 'locator', '')}\n\n` +
58
+ `Type Error: .toBeVisible() requires an ActorLocator or WidgetLocator.\n` +
59
+ `Did you forget to call .asActor() or .asWidget()?`,
60
+ };
61
+ }
62
+ const pollTimeout = options?.timeout ?? 5000;
63
+ const checkOnScreen = isActor ? (options?.onScreen ?? false) : false; // UMG ignores spatial onScreen bounds
64
+ const isNot = this.isNot;
65
+ return await (async () => {
66
+ let isVis = false;
67
+ try {
68
+ await test_1.expect.poll(async () => {
69
+ try {
70
+ isVis = await locator.checkVisibility(checkOnScreen);
71
+ return isVis;
72
+ }
73
+ catch (err) {
74
+ const msg = err instanceof Error ? err.message : String(err);
75
+ // Several matches is an error either way; no match at all just isn't visible
76
+ if (msg.toLowerCase().includes('strict mode') && !/resolved to 0 /.test(msg)) {
77
+ throw err;
78
+ }
79
+ isVis = false;
80
+ return false;
81
+ }
82
+ }, { timeout: pollTimeout, intervals: [100, 200, 250] }).toBe(!isNot);
83
+ return { pass: !isNot, message: () => 'passed' };
84
+ }
85
+ catch (e) {
86
+ // Extract the actual message whether it's an Error object or a raw string
87
+ const errorMessage = e instanceof Error ? e.message : String(e);
88
+ // 1. Intercept Strict Mode Violations
89
+ if (errorMessage.toLowerCase().includes('strict mode violation') && !/resolved to 0 /.test(errorMessage)) {
90
+ // Fails .not as well (pass is inverted for .not): an ambiguous locator proves nothing
91
+ return {
92
+ pass: isNot,
93
+ message: () => `${this.utils.matcherHint(assertionName, locator.toString(), '')}\n\n` +
94
+ `🚨 STRICT MODE ERROR:\n` +
95
+ `${errorMessage}\n\n` +
96
+ `Fix: You must narrow your locator pipeline. Use .first(), .nth(), or .filter().`
97
+ };
98
+ }
99
+ // 2. Standard Visibility Timeout
100
+ return {
101
+ pass: isNot,
102
+ message: () => `${this.utils.matcherHint(assertionName, locator.toString(), '')}\n\n` +
103
+ `Timed out after ${pollTimeout}ms waiting for element to be ${isNot ? 'not visible' : 'visible'}.\n` +
104
+ `Expected: ${this.utils.printExpected(isNot ? 'Not Visible' : 'Visible')}\n` +
105
+ `Received: ${this.utils.printReceived(isNot ? 'Visible' : 'Not Visible')}\n` +
106
+ // Optional: If it failed for a reason OTHER than "0 objects", print it here
107
+ (errorMessage.includes('0 objects') ? '' : `\nUnderlying Engine Error: ${errorMessage}`)
108
+ };
109
+ }
110
+ })();
111
+ }
49
112
  exports.locatorExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
50
113
  async toHavePropertyValue(locator, propertyName, expectedValue, options) {
51
114
  const operator = options?.operator ?? '===';
@@ -119,68 +182,10 @@ exports.locatorExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers
119
182
  },
120
183
  async toBeVisible(locator, // Accept any to bypass generic strictness
121
184
  options) {
122
- const assertionName = 'toBeVisible';
123
- // 1. THE BOUNCER: Enforce type safety at runtime
124
- const isActor = locator instanceof locators_1.ActorLocator;
125
- const isWidget = locator instanceof locators_1.WidgetLocator;
126
- if (!isActor && !isWidget) {
127
- return {
128
- pass: false,
129
- message: () => `${this.utils.matcherHint(assertionName, 'locator', '')}\n\n` +
130
- `Type Error: .toBeVisible() requires an ActorLocator or WidgetLocator.\n` +
131
- `Did you forget to call .asActor() or .asWidget()?`,
132
- };
133
- }
134
- const pollTimeout = options?.timeout ?? 5000;
135
- const checkOnScreen = isActor ? (options?.onScreen ?? false) : false; // UMG ignores spatial onScreen bounds
136
- const isNot = this.isNot;
137
- return await (async () => {
138
- let isVis = false;
139
- try {
140
- await test_1.expect.poll(async () => {
141
- try {
142
- isVis = await locator.checkVisibility(checkOnScreen);
143
- return isVis;
144
- }
145
- catch (err) {
146
- const msg = err instanceof Error ? err.message : String(err);
147
- if (msg.toLowerCase().includes('strict mode')) {
148
- throw err;
149
- }
150
- isVis = false;
151
- return false;
152
- }
153
- }, { timeout: pollTimeout, intervals: [100, 200, 250] }).toBe(!isNot);
154
- return { pass: !isNot, message: () => 'passed' };
155
- }
156
- catch (e) {
157
- // Extract the actual message whether it's an Error object or a raw string
158
- const errorMessage = e instanceof Error ? e.message : String(e);
159
- // 1. Intercept Strict Mode Violations
160
- if (errorMessage.toLowerCase().includes('strict mode violation')) {
161
- return {
162
- pass: false,
163
- message: () => `${this.utils.matcherHint(assertionName, locator.toString(), '')}\n\n` +
164
- `🚨 STRICT MODE ERROR:\n` +
165
- `${errorMessage}\n\n` +
166
- `Fix: You must narrow your locator pipeline. Use .first(), .nth(), or .filter().`
167
- };
168
- }
169
- // 2. Standard Visibility Timeout
170
- return {
171
- pass: isNot,
172
- message: () => `${this.utils.matcherHint(assertionName, locator.toString(), '')}\n\n` +
173
- `Timed out after ${pollTimeout}ms waiting for element to be ${isNot ? 'not visible' : 'visible'}.\n` +
174
- `Expected: ${this.utils.printExpected(isNot ? 'Not Visible' : 'Visible')}\n` +
175
- `Received: ${this.utils.printReceived(isNot ? 'Visible' : 'Not Visible')}\n` +
176
- // Optional: If it failed for a reason OTHER than "0 objects", print it here
177
- (errorMessage.includes('0 objects') ? '' : `\nUnderlying Engine Error: ${errorMessage}`)
178
- };
179
- }
180
- })();
185
+ return checkVisible.call(this, 'toBeVisible', locator, options);
181
186
  },
182
187
  async toBeInViewport(locator, options) {
183
- return this.toBeVisible(locator, { onScreen: true, timeout: options?.timeout });
188
+ return checkVisible.call(this, 'toBeInViewport', locator, { onScreen: true, timeout: options?.timeout });
184
189
  },
185
190
  async toBeDestroyed(locator, options) {
186
191
  const assertionName = 'toBeDestroyed';
@@ -118,7 +118,10 @@ exports.visualExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)
118
118
  }
119
119
  catch { }
120
120
  }
121
- const failureMessage = lastError?.message || `Screenshot did not match baseline '${normalizedName}'`;
121
+ // .not fails when the view matched the baseline (lastError is a capture problem, if any)
122
+ const failureMessage = isNot
123
+ ? (lastError?.message || `Screenshot matched baseline '${normalizedName}', but it must not`)
124
+ : (lastError?.message || `Screenshot did not match baseline '${normalizedName}'`);
122
125
  return {
123
126
  pass: isNot,
124
127
  message: () => failureMessage,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.145",
3
+ "version": "1.0.147",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",