@specter-automation/test 1.0.123 → 1.0.124

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.
@@ -155,7 +155,7 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
155
155
  */
156
156
  unpossess(): Promise<void>;
157
157
  getAttributeValue(attributeSet: string, attributeName: string): Promise<number>;
158
- hasGameplayTag(tag: RegisteredGameplayTags): Promise<boolean>;
158
+ hasGameplayTag(tag: RegisteredGameplayTags, bHideStep?: boolean): Promise<boolean>;
159
159
  /**
160
160
  * Waits for a Gameplay Tag to be added or removed.
161
161
  */
@@ -434,9 +434,9 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
434
434
  getAttributeBaseValue(attributeSet: string, attributeName: string): Promise<number>;
435
435
  isAbilityExecuting(abilityOrClassPath: string): Promise<boolean>;
436
436
  cancelAbility(abilityOrTagOrClassPath: RegisteredGameplayTags): Promise<void>;
437
- getGameplayTagCount(tag: RegisteredGameplayTags): Promise<number>;
438
- hasAnyGameplayTags(tags: RegisteredGameplayTags[]): Promise<boolean>;
439
- hasAllGameplayTags(tags: RegisteredGameplayTags[]): Promise<boolean>;
437
+ getGameplayTagCount(tag: RegisteredGameplayTags, bHideStep?: boolean): Promise<number>;
438
+ hasAnyGameplayTags(tags: RegisteredGameplayTags[], bHideStep?: boolean): Promise<boolean>;
439
+ hasAllGameplayTags(tags: RegisteredGameplayTags[], bHideStep?: boolean): Promise<boolean>;
440
440
  getVelocitySize(): Promise<number>;
441
441
  isFalling(): Promise<boolean>;
442
442
  isCrouching(): Promise<boolean>;
@@ -396,9 +396,9 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
396
396
  const response = await this.evaluate("GetAttributeValue", { attributeSet, attributeName }, attributeName);
397
397
  return parseFloat(response.data.value);
398
398
  }
399
- async hasGameplayTag(tag) {
400
- const response = await this.evaluate("HasGameplayTag", { tag });
401
- return response.data.hasTag;
399
+ async hasGameplayTag(tag, bHideStep = false) {
400
+ const response = await this.evaluate("HasGameplayTag", { tag }, tag, bHideStep);
401
+ return response.data?.hasTag ?? false;
402
402
  }
403
403
  /**
404
404
  * Waits for a Gameplay Tag to be added or removed.
@@ -408,30 +408,58 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
408
408
  const { SpecterEventType } = await Promise.resolve().then(() => __importStar(require('../specter-client')));
409
409
  return await test.step(`Specter: Wait For Tag [${tag} == ${expectedState}]`, async () => {
410
410
  const locatorId = this.resolvedPath;
411
- const response = await this.evaluate("TrackGameplayTag", { tag, locatorId });
412
- let hasTag = response.data.hasTag;
411
+ const targetName = await this.getObjectName().catch(() => undefined);
412
+ const response = await this.evaluate("TrackGameplayTag", { tag, locatorId }, undefined, true);
413
+ let hasTag = response.data?.hasTag;
413
414
  if (hasTag === expectedState) {
414
415
  return hasTag;
415
416
  }
416
417
  return await new Promise((resolve, reject) => {
417
418
  let timeoutId;
419
+ let isResolved = false;
420
+ const cleanup = () => {
421
+ if (isResolved)
422
+ return;
423
+ isResolved = true;
424
+ clearTimeout(timeoutId);
425
+ this.transport.removeEventListener('GLOBAL_timeline-event', listener);
426
+ };
418
427
  const listener = (event) => {
419
- if (event.eventType === SpecterEventType.GameplayTag &&
420
- event.eventName === tag &&
421
- event.description === locatorId) {
422
- const isTagPresent = event.newValue === 'true';
423
- if (isTagPresent === expectedState) {
424
- clearTimeout(timeoutId);
425
- this.transport.removeEventListener('GLOBAL_timeline-event', listener);
426
- resolve(isTagPresent);
428
+ if (isResolved)
429
+ return;
430
+ if (event.eventType !== SpecterEventType.GameplayTag && event.eventType !== 'GameplayTag') {
431
+ return;
432
+ }
433
+ const name = event.eventName || '';
434
+ const desc = event.description || '';
435
+ if (!name.includes(tag) && !desc.includes(tag)) {
436
+ return;
437
+ }
438
+ if (targetName) {
439
+ const evTarget = (event.target || '').trim();
440
+ if (evTarget && !evTarget.includes(targetName) && !targetName.includes(evTarget)) {
441
+ return;
427
442
  }
428
443
  }
444
+ const isAdded = name.startsWith('Added') || event.newValue === 'true' || parseInt(event.newValue || '0') > 0;
445
+ if (isAdded === expectedState) {
446
+ cleanup();
447
+ resolve(isAdded);
448
+ }
429
449
  };
430
- timeoutId = setTimeout(() => {
431
- this.transport.removeEventListener('GLOBAL_timeline-event', listener);
450
+ this.transport.registerEventListener('GLOBAL_timeline-event', listener);
451
+ timeoutId = setTimeout(async () => {
452
+ cleanup();
453
+ try {
454
+ const finalCheck = await this.hasGameplayTag(tag, true);
455
+ if (finalCheck === expectedState) {
456
+ resolve(finalCheck);
457
+ return;
458
+ }
459
+ }
460
+ catch { }
432
461
  reject(new Error(`Timed out after ${timeout}ms waiting for GAS Tag '${tag}' to be '${expectedState}'.`));
433
462
  }, timeout);
434
- this.transport.registerEventListener('GLOBAL_timeline-event', listener);
435
463
  });
436
464
  });
437
465
  }
@@ -1049,17 +1077,17 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
1049
1077
  abilityClassPath: abilityOrTagOrClassPath
1050
1078
  });
1051
1079
  }
1052
- async getGameplayTagCount(tag) {
1053
- const response = await this.evaluate("GetGameplayTagCount", { tag });
1054
- return response.data.count;
1080
+ async getGameplayTagCount(tag, bHideStep = false) {
1081
+ const response = await this.evaluate("GetGameplayTagCount", { tag }, tag, bHideStep);
1082
+ return response.data?.count ?? 0;
1055
1083
  }
1056
- async hasAnyGameplayTags(tags) {
1057
- const response = await this.evaluate("HasAnyGameplayTags", { tags });
1058
- return response.data.hasAny;
1084
+ async hasAnyGameplayTags(tags, bHideStep = false) {
1085
+ const response = await this.evaluate("HasAnyGameplayTags", { tags }, undefined, bHideStep);
1086
+ return response.data?.hasAny ?? false;
1059
1087
  }
1060
- async hasAllGameplayTags(tags) {
1061
- const response = await this.evaluate("HasAllGameplayTags", { tags });
1062
- return response.data.hasAll;
1088
+ async hasAllGameplayTags(tags, bHideStep = false) {
1089
+ const response = await this.evaluate("HasAllGameplayTags", { tags }, undefined, bHideStep);
1090
+ return response.data?.hasAll ?? false;
1063
1091
  }
1064
1092
  async getVelocitySize() {
1065
1093
  const response = await this.evaluate("GetVelocitySize", {});
@@ -76,7 +76,7 @@ export declare class SpecterLocator<T = any> {
76
76
  * Alias for `callFunction`. Calls a C++ UFUNCTION and returns the result.
77
77
  */
78
78
  callFunctionWithReturn(functionName: string, parameters?: Record<string, any>): Promise<any>;
79
- hasGameplayTag(tagToCheck: string): Promise<boolean>;
79
+ hasGameplayTag(tagToCheck: string, bHideStep?: boolean): Promise<boolean>;
80
80
  getObjectName(): Promise<string>;
81
81
  getPropertyValue(propertyName: string): Promise<any>;
82
82
  getMaterialScalarParameter(parameterName: string, options?: {
@@ -228,9 +228,9 @@ class SpecterLocator {
228
228
  async callFunctionWithReturn(functionName, parameters) {
229
229
  return this.callFunction(functionName, parameters);
230
230
  }
231
- async hasGameplayTag(tagToCheck) {
232
- const response = await this.evaluate("HasGameplayTag", { tag: tagToCheck }, tagToCheck);
233
- return response.data.hasTag === true;
231
+ async hasGameplayTag(tagToCheck, bHideStep = false) {
232
+ const response = await this.evaluate("HasGameplayTag", { tag: tagToCheck }, tagToCheck, bHideStep);
233
+ return response.data?.hasTag === true;
234
234
  }
235
235
  async getObjectName() {
236
236
  const response = await this.evaluate("GetObjectName", {}, undefined, true);
@@ -80,9 +80,6 @@ declare global {
80
80
  toBeAINavigating(options?: {
81
81
  timeout?: number;
82
82
  }): T extends ActorLocator ? Promise<R> : never;
83
- toHaveGameplayTag(expectedTag: string, options?: {
84
- timeout?: number;
85
- }): T extends ActorLocator ? Promise<R> : never;
86
83
  toHaveTeamId(expectedTeamId: number, options?: {
87
84
  timeout?: number;
88
85
  }): T extends ActorLocator ? Promise<R> : never;
@@ -167,9 +164,6 @@ export interface ActorMatchers {
167
164
  toBeAINavigating(options?: {
168
165
  timeout?: number;
169
166
  }): Promise<void>;
170
- toHaveGameplayTag(expectedTag: string, options?: {
171
- timeout?: number;
172
- }): Promise<void>;
173
167
  toHaveTeamId(expectedTeamId: number, options?: {
174
168
  timeout?: number;
175
169
  }): Promise<void>;
@@ -397,12 +391,6 @@ export declare const actorExpect: import("playwright/test").Expect<{
397
391
  pass: boolean;
398
392
  message: () => string;
399
393
  }>;
400
- toHaveGameplayTag(this: import("playwright/test").ExpectMatcherState, locator: any, expectedTag: string, options?: {
401
- timeout?: number;
402
- }): Promise<{
403
- pass: boolean;
404
- message: () => string;
405
- }>;
406
394
  toHaveTeamId(this: import("playwright/test").ExpectMatcherState, locator: any, expectedTeamId: number, options?: {
407
395
  timeout?: number;
408
396
  }): Promise<{
@@ -405,26 +405,6 @@ exports.actorExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)(
405
405
  message: () => `Expected AI to${isNot ? ' not' : ''} be actively navigating on NavMesh, but it was${lastState ? '' : ' not'}.`
406
406
  };
407
407
  },
408
- async toHaveGameplayTag(locator, expectedTag, options) {
409
- const isNot = this.isNot;
410
- const timeout = options?.timeout ?? 5000;
411
- const startTime = Date.now();
412
- let lastHas = false;
413
- while (Date.now() - startTime < timeout) {
414
- try {
415
- lastHas = await locator.hasGameplayTag(expectedTag);
416
- if (lastHas === !isNot) {
417
- return { pass: !isNot, message: () => 'passed' };
418
- }
419
- }
420
- catch (e) { }
421
- await new Promise(r => setTimeout(r, 100));
422
- }
423
- return {
424
- pass: isNot,
425
- message: () => `Expected Actor to${isNot ? ' not' : ''} have Gameplay Tag "${expectedTag}", but it did${lastHas ? '' : ' not'}.`
426
- };
427
- },
428
408
  async toHaveTeamId(locator, expectedTeamId, options) {
429
409
  const isNot = this.isNot;
430
410
  const timeout = options?.timeout ?? 5000;
@@ -14,7 +14,9 @@ declare global {
14
14
  gameplayEffect?: string;
15
15
  ability?: string;
16
16
  }, triggerAction?: () => Promise<void>): T extends SpecterLocator ? Promise<R> : never;
17
- toHaveGameplayTag(tag: RegisteredGameplayTags): T extends SpecterLocator ? Promise<R> : never;
17
+ toHaveGameplayTag(tag: RegisteredGameplayTags, options?: {
18
+ timeout?: number;
19
+ }): T extends SpecterLocator ? Promise<R> : never;
18
20
  toHaveGameplayEffect(effectClassPath: string): T extends SpecterLocator ? Promise<R> : never;
19
21
  toHaveAppliedGameplayEffect(effectNameOrClass: string, options?: {
20
22
  count?: number;
@@ -57,7 +59,9 @@ export interface GasMatchers {
57
59
  timeout?: number;
58
60
  tolerance?: number;
59
61
  }, triggerAction?: () => Promise<void>): Promise<void>;
60
- toHaveGameplayTag(tag: RegisteredGameplayTags): Promise<void>;
62
+ toHaveGameplayTag(tag: RegisteredGameplayTags, options?: {
63
+ timeout?: number;
64
+ }): Promise<void>;
61
65
  toHaveGameplayEffect(effectClassPath: string): Promise<void>;
62
66
  toHaveAppliedGameplayEffect(effectNameOrClass: string, options?: {
63
67
  count?: number;
@@ -118,7 +122,9 @@ export declare const gasExpect: import("playwright/test").Expect<{
118
122
  tolerance?: number;
119
123
  };
120
124
  }>;
121
- toHaveGameplayTag(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, tag: RegisteredGameplayTags): Promise<{
125
+ toHaveGameplayTag(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, tag: RegisteredGameplayTags, options?: {
126
+ timeout?: number;
127
+ }): Promise<{
122
128
  pass: boolean;
123
129
  message: () => string;
124
130
  actual: boolean;
@@ -612,36 +612,165 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
612
612
  }
613
613
  })();
614
614
  },
615
- async toHaveGameplayTag(locator, tag) {
615
+ async toHaveGameplayTag(locator, tag, options) {
616
616
  const assertionName = 'toHaveGameplayTag';
617
617
  const isNot = this.isNot;
618
+ const timeout = options?.timeout ?? 5000;
618
619
  return await (async () => {
619
- const timeout = 5000;
620
- let hasTag = false;
620
+ const transport = locator.transport;
621
+ const causalityEvents = [];
622
+ let lastEvent;
623
+ let targetName;
624
+ // 1. Immediately register live listener to catch push events
625
+ const capturedEvents = [];
626
+ let onLiveEvent = null;
627
+ const liveListener = (event) => {
628
+ capturedEvents.push(event);
629
+ causalityEvents.push(event);
630
+ if (onLiveEvent) {
631
+ onLiveEvent(event);
632
+ }
633
+ };
634
+ if (transport && typeof transport.registerEventListener === 'function') {
635
+ transport.registerEventListener('GLOBAL_timeline-event', liveListener);
636
+ }
621
637
  try {
622
- hasTag = await locator.waitForGameplayTag(tag, !isNot, timeout);
638
+ // In parallel: resolve target name, track tag in C++, and check initial state
639
+ const [resolvedTargetName, initialHasTag] = await Promise.all([
640
+ locator.getObjectName().catch(() => undefined),
641
+ locator.hasGameplayTag(tag, true).catch(() => undefined),
642
+ locator.evaluate("TrackGameplayTag", { tag }, undefined, true).catch(() => undefined),
643
+ ]);
644
+ targetName = resolvedTargetName;
645
+ const evaluateEvent = (event) => {
646
+ if (event.eventType !== specter_client_1.SpecterEventType.GameplayTag && event.eventType !== 'GameplayTag') {
647
+ return false;
648
+ }
649
+ const name = event.eventName || '';
650
+ const desc = event.description || '';
651
+ const matchesTag = name === tag || name.includes(`[${tag}]`) || name.includes(tag) || desc.includes(tag);
652
+ if (!matchesTag) {
653
+ return false;
654
+ }
655
+ if (targetName) {
656
+ const evTarget = (event.target || '').trim();
657
+ if (evTarget && !evTarget.includes(targetName) && !targetName.includes(evTarget)) {
658
+ return false;
659
+ }
660
+ }
661
+ lastEvent = event;
662
+ const isAdded = name.startsWith('Added') || event.newValue === 'true' || parseInt(event.newValue || '0') > 0;
663
+ const isRemoved = name.startsWith('Removed') || event.newValue === 'false' || parseInt(event.newValue || '0') === 0;
664
+ if (!isNot && isAdded)
665
+ return true;
666
+ if (isNot && isRemoved)
667
+ return true;
668
+ return false;
669
+ };
670
+ // Check initial state
671
+ if (initialHasTag !== undefined && (initialHasTag === !isNot)) {
672
+ return {
673
+ pass: !isNot,
674
+ message: () => 'passed',
675
+ actual: initialHasTag,
676
+ expected: !isNot
677
+ };
678
+ }
679
+ // Check any events received during initial read
680
+ for (const ev of capturedEvents) {
681
+ if (evaluateEvent(ev)) {
682
+ return {
683
+ pass: !isNot,
684
+ message: () => 'passed',
685
+ actual: !isNot,
686
+ expected: !isNot
687
+ };
688
+ }
689
+ }
690
+ // Wait for live event
691
+ await new Promise((resolve, reject) => {
692
+ let timeoutId;
693
+ let isResolved = false;
694
+ const cleanup = () => {
695
+ if (isResolved)
696
+ return;
697
+ isResolved = true;
698
+ clearTimeout(timeoutId);
699
+ };
700
+ onLiveEvent = (event) => {
701
+ if (isResolved)
702
+ return;
703
+ if (evaluateEvent(event)) {
704
+ cleanup();
705
+ resolve();
706
+ }
707
+ };
708
+ timeoutId = setTimeout(async () => {
709
+ cleanup();
710
+ // One final check before giving up in case an event was missed
711
+ try {
712
+ const finalHasTag = await locator.hasGameplayTag(tag, true);
713
+ if (finalHasTag !== undefined && (finalHasTag === !isNot)) {
714
+ resolve();
715
+ return;
716
+ }
717
+ }
718
+ catch { }
719
+ reject(new Error(`Timed out after ${timeout}ms waiting for Gameplay Tag '${tag}' to be ${isNot ? 'removed from' : 'present on'} '${locator.toString()}'.`));
720
+ }, timeout);
721
+ });
623
722
  return {
624
723
  pass: !isNot,
625
724
  message: () => 'passed',
626
- actual: hasTag,
725
+ actual: !isNot,
627
726
  expected: !isNot
628
727
  };
629
728
  }
630
729
  catch (e) {
631
- if (!e.message.includes('Timed out')) {
730
+ if (!e.message?.includes('Timed out')) {
632
731
  throw e;
633
732
  }
634
- hasTag = isNot;
733
+ let diagStr = '';
734
+ try {
735
+ const diags = await locator.getDiagnostics({ limit: 20 });
736
+ diagStr = formatAiDiagnostics(diags);
737
+ if (diags?.flightRecorder && Array.isArray(diags.flightRecorder)) {
738
+ for (const ev of diags.flightRecorder) {
739
+ causalityEvents.push(ev);
740
+ }
741
+ }
742
+ }
743
+ catch { }
744
+ const timelineStr = formatCausalityTimeline(causalityEvents);
745
+ try {
746
+ const testInfo = test_1.default.info();
747
+ if (testInfo && timelineStr) {
748
+ testInfo.attachments.push({
749
+ name: 'Specter Causality Timeline',
750
+ contentType: 'text/markdown',
751
+ body: Buffer.from(timelineStr)
752
+ });
753
+ }
754
+ }
755
+ catch { }
635
756
  return {
636
757
  pass: isNot,
637
758
  message: () => `${this.utils.matcherHint(assertionName, locator.toString(), tag)}\n\n` +
638
- `Timed out after ${timeout}ms waiting for tag on "${locator.toString()}".\n` +
759
+ `Timed out after ${timeout}ms waiting for Gameplay Tag on "${locator.toString()}".\n` +
639
760
  `Expected: ${isNot ? 'not to have tag' : 'to have tag'} ${tag}\n` +
640
- `Received: ${hasTag ? 'has tag' : 'does not have tag'}`,
641
- actual: hasTag,
761
+ `Received: ${isNot ? 'has tag' : 'does not have tag'}\n` +
762
+ `Last matched event: ${lastEvent ? JSON.stringify(lastEvent, null, 2) : 'None'}` +
763
+ timelineStr +
764
+ diagStr,
765
+ actual: isNot,
642
766
  expected: !isNot
643
767
  };
644
768
  }
769
+ finally {
770
+ if (transport && typeof transport.removeEventListener === 'function') {
771
+ transport.removeEventListener('GLOBAL_timeline-event', liveListener);
772
+ }
773
+ }
645
774
  })();
646
775
  },
647
776
  async toHaveGameplayEffect(locator, effectClassPath) {
@@ -1365,7 +1494,7 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
1365
1494
  let count = 0;
1366
1495
  while (Date.now() - startTime < timeout) {
1367
1496
  try {
1368
- count = await locator.getGameplayTagCount(tag);
1497
+ count = await locator.getGameplayTagCount(tag, true);
1369
1498
  if ((count === expectedCount) === !isNot)
1370
1499
  return { pass: !isNot, message: () => 'passed' };
1371
1500
  }
@@ -1383,7 +1512,7 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
1383
1512
  let has = false;
1384
1513
  while (Date.now() - startTime < timeout) {
1385
1514
  try {
1386
- has = await locator.hasAnyGameplayTags(tags);
1515
+ has = await locator.hasAnyGameplayTags(tags, true);
1387
1516
  if (has === !isNot)
1388
1517
  return { pass: !isNot, message: () => 'passed' };
1389
1518
  }
@@ -1401,7 +1530,7 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
1401
1530
  let has = false;
1402
1531
  while (Date.now() - startTime < timeout) {
1403
1532
  try {
1404
- has = await locator.hasAllGameplayTags(tags);
1533
+ has = await locator.hasAllGameplayTags(tags, true);
1405
1534
  if (has === !isNot)
1406
1535
  return { pass: !isNot, message: () => 'passed' };
1407
1536
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.123",
3
+ "version": "1.0.124",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",