@specter-automation/test 1.0.153 → 1.0.155

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.
@@ -473,6 +473,8 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
473
473
  */
474
474
  getBehaviorTrail(options?: {
475
475
  limit?: number;
476
+ /** The state or task the caller is looking for: gameplay coverage counts it as tested (the AI matchers set it) */
477
+ checking?: string;
476
478
  }): Promise<BehaviorTrail>;
477
479
  /**
478
480
  * Evaluates spatial movement vector, speed, and direction relative to a target actor or coordinates.
@@ -1103,7 +1103,10 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
1103
1103
  * The AI matchers show it when they fail; `describeBehaviorTrail` turns it into lines.
1104
1104
  */
1105
1105
  async getBehaviorTrail(options) {
1106
- const response = await this.evaluate("GetAITrail", { limit: options?.limit ?? 20 }, undefined, true);
1106
+ const payload = { limit: options?.limit ?? 20 };
1107
+ if (options?.checking)
1108
+ payload.checking = options.checking;
1109
+ const response = await this.evaluate("GetAITrail", payload, undefined, true);
1107
1110
  if (response?.status === 'error' || !response?.data) {
1108
1111
  throw new Error(response?.message || 'No AI trail: not an AI controller, a pawn one possesses, or an actor with a StateTree component.');
1109
1112
  }
@@ -349,7 +349,7 @@ exports.aiExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)(wit
349
349
  let lastError = '';
350
350
  while (Date.now() - startTime < timeout) {
351
351
  try {
352
- const trail = await locator.getBehaviorTrail({ limit: 1 });
352
+ const trail = await locator.getBehaviorTrail({ limit: 1, checking: stateName });
353
353
  lastPath = trail.running ? trail.activePath : [];
354
354
  lastLogic = trail.logic;
355
355
  lastError = '';
@@ -415,7 +415,7 @@ exports.aiExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)(wit
415
415
  let lastError = '';
416
416
  while (true) {
417
417
  try {
418
- const trail = await locator.getBehaviorTrail({ limit: 400 });
418
+ const trail = await locator.getBehaviorTrail({ limit: 400, checking: stateName });
419
419
  const paths = trail.events.flatMap((event) => (event.kind === 'active' ? [event.path] : []));
420
420
  if (trail.running)
421
421
  paths.push(trail.activePath);
@@ -414,6 +414,9 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
414
414
  const transport = locator.transport;
415
415
  let lastEvent;
416
416
  let lastFailedReasons = [];
417
+ // Each change to this actor's attribute that didn't match, and why (events are checked more than once)
418
+ const nearMisses = new Map();
419
+ let subjectName;
417
420
  let initialValue;
418
421
  // Synchronously register live listener immediately to capture all events during setup & action
419
422
  const capturedEvents = [];
@@ -441,6 +444,7 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
441
444
  locator.getObjectName().catch(() => undefined),
442
445
  ]);
443
446
  initialValue = resolvedInitialVal;
447
+ subjectName = targetName;
444
448
  // Evaluates whether an event matches all expected criteria
445
449
  const evaluateEvent = (event) => {
446
450
  if (event.eventType !== specter_client_1.SpecterEventType.GameplayAttribute && event.eventType !== 'GameplayAttribute') {
@@ -468,15 +472,16 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
468
472
  Math.abs(Math.abs(actualDelta) - Math.abs(expDelta)) <= tolerance;
469
473
  if (!deltaMatch) {
470
474
  isMatch = false;
471
- lastFailedReasons.push(`delta (expected: ${expDelta}, actual: ${actualDelta})`);
475
+ lastFailedReasons.push(`delta: expected ${expDelta}, but it was ${actualDelta}`);
472
476
  }
473
477
  }
474
478
  // 2. Instigator check
479
+ // The instigator is the ability system's owner, which is often the PlayerState rather than the
480
+ // hero: the hero is then the effect causer, and either one names who caused the change
475
481
  if (expectedInstigatorName !== undefined) {
476
- const inst = (event.instigator || '').trim();
477
- if (!inst || (!inst.includes(expectedInstigatorName) && !expectedInstigatorName.includes(inst))) {
482
+ if (!namesSource(expectedInstigatorName, event.instigator, event.effectCauser)) {
478
483
  isMatch = false;
479
- lastFailedReasons.push(`instigator (expected to include: '${expectedInstigatorName}', actual: '${event.instigator}')`);
484
+ lastFailedReasons.push(`instigator: expected ${expectedInstigatorName}, but it came from ${describeSource(event)}`);
480
485
  }
481
486
  }
482
487
  // 3. Effect Causer check
@@ -484,23 +489,27 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
484
489
  const causer = (event.effectCauser || '').trim();
485
490
  if (!causer || (!causer.includes(expectedEffectCauserName) && !expectedEffectCauserName.includes(causer))) {
486
491
  isMatch = false;
487
- lastFailedReasons.push(`effectCauser (expected to include: '${expectedEffectCauserName}', actual: '${event.effectCauser}')`);
492
+ lastFailedReasons.push(`effectCauser: expected ${expectedEffectCauserName}, but it was ${event.effectCauser || 'not recorded'}`);
488
493
  }
489
494
  }
490
495
  // 4. Gameplay Effect check
491
496
  if (expectedChange.gameplayEffect !== undefined) {
492
497
  if (!event.gameplayEffect || (!event.gameplayEffect.includes(expectedChange.gameplayEffect) && !expectedChange.gameplayEffect.includes(event.gameplayEffect))) {
493
498
  isMatch = false;
494
- lastFailedReasons.push(`gameplayEffect (expected to include: '${expectedChange.gameplayEffect}', actual: '${event.gameplayEffect}')`);
499
+ lastFailedReasons.push(`gameplayEffect: expected ${expectedChange.gameplayEffect}, but it was ${event.gameplayEffect || 'not recorded'}`);
495
500
  }
496
501
  }
497
502
  // 5. Ability check
498
503
  if (expectedChange.ability !== undefined) {
499
504
  if (!event.ability || (!event.ability.includes(expectedChange.ability) && !expectedChange.ability.includes(event.ability))) {
500
505
  isMatch = false;
501
- lastFailedReasons.push(`ability (expected to include: '${expectedChange.ability}', actual: '${event.ability}')`);
506
+ lastFailedReasons.push(`ability: expected ${expectedChange.ability}, but it was ${event.ability || 'not recorded'}`);
502
507
  }
503
508
  }
509
+ if (!isMatch) {
510
+ const key = `${event.timestamp}_${event.oldValue}_${event.newValue}_${event.instigator}_${event.gameplayEffect}_${event.networkRole}`;
511
+ nearMisses.set(key, { event, reasons: [...lastFailedReasons] });
512
+ }
504
513
  return isMatch;
505
514
  };
506
515
  // --- 1. TRY ONCE IMMEDIATELY ---
@@ -610,10 +619,19 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
610
619
  if (!e.message?.includes('Timed out')) {
611
620
  throw e;
612
621
  }
613
- let failureDetails = `Last checked event: ${lastEvent ? JSON.stringify(lastEvent, null, 2) : 'None received'}`;
614
- if (lastFailedReasons.length > 0) {
615
- failureDetails += `\n\nFailed Criteria on last event:\n- ${lastFailedReasons.join('\n- ')}`;
622
+ const subject = `${attributeName} on ${subjectName ?? locator.toString()}`;
623
+ const misses = [...nearMisses.values()];
624
+ let headline;
625
+ if (misses.length === 0) {
626
+ headline = `${subject} didn't change within ${timeout}ms.`;
627
+ }
628
+ else {
629
+ const shown = misses.slice(-5);
630
+ headline = `${subject} changed ${misses.length === 1 ? 'once' : `${misses.length} times`} within ${timeout}ms, but no change matched:\n` +
631
+ shown.map(m => ` - ${describeChangeValues(m.event)}: ${m.reasons.join('; ')}`).join('\n') +
632
+ (misses.length > shown.length ? `\n - and ${misses.length - shown.length} earlier change(s)` : '');
616
633
  }
634
+ const failureDetails = lastEvent ? `\n\nLast checked event: ${JSON.stringify(lastEvent, null, 2)}` : '';
617
635
  let diagStr = '';
618
636
  try {
619
637
  const diags = await locator.getDiagnostics({
@@ -644,8 +662,8 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
644
662
  return {
645
663
  pass: false,
646
664
  message: () => `${this.utils.matcherHint(assertionName, locator.toString(), expectedParts.join(', '))}\n\n` +
647
- `Error: ${e.message}\n` +
648
- `Expected criteria: { ${expectedParts.join(', ')} }\n\n` +
665
+ `${headline}\n\n` +
666
+ `Expected: { ${expectedParts.join(', ')} }` +
649
667
  failureDetails +
650
668
  timelineStr +
651
669
  diagStr,
@@ -926,10 +944,9 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
926
944
  return false;
927
945
  }
928
946
  // Instigator match
929
- if (expectedInstigatorName && ev.instigator) {
930
- const cleanInst = expectedInstigatorName.trim();
931
- const evInst = ev.instigator.trim();
932
- if (!evInst.includes(cleanInst) && !cleanInst.includes(evInst)) {
947
+ // (the instigator or the effect causer: the instigator is often the PlayerState that owns the ability system)
948
+ if (expectedInstigatorName && (ev.instigator || ev.effectCauser)) {
949
+ if (!namesSource(expectedInstigatorName, ev.instigator, ev.effectCauser)) {
933
950
  return false;
934
951
  }
935
952
  }
@@ -1629,6 +1646,38 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
1629
1646
  })();
1630
1647
  },
1631
1648
  }));
1649
+ /** Whether any of an event's source names (instigator, effect causer) names the expected actor */
1650
+ function namesSource(expected, ...names) {
1651
+ const want = expected.trim();
1652
+ if (!want)
1653
+ return false;
1654
+ return names.some(name => {
1655
+ const got = (name || '').trim();
1656
+ return !!got && (got.includes(want) || want.includes(got));
1657
+ });
1658
+ }
1659
+ /** Who an event came from: its instigator, and its effect causer when that's a different actor */
1660
+ function describeSource(event) {
1661
+ const inst = (event?.instigator || '').trim();
1662
+ const causer = (event?.effectCauser || '').trim();
1663
+ if (!inst && !causer)
1664
+ return 'no recorded instigator';
1665
+ if (!causer || causer === inst)
1666
+ return inst;
1667
+ if (!inst)
1668
+ return `effect causer ${causer}`;
1669
+ return `${inst} (effect causer ${causer})`;
1670
+ }
1671
+ /** "2500 -> 2150 (-350) at 12.40s" */
1672
+ function describeChangeValues(event) {
1673
+ const oldValue = parseFloat(event?.oldValue);
1674
+ const newValue = parseFloat(event?.newValue);
1675
+ const delta = newValue - oldValue;
1676
+ let text = `${oldValue} -> ${newValue} (${delta >= 0 ? '+' : ''}${delta})`;
1677
+ if (typeof event?.timestamp === 'number')
1678
+ text += ` at ${event.timestamp.toFixed(2)}s`;
1679
+ return text;
1680
+ }
1632
1681
  /** One line for an attribute change event: what changed, on whom, and from what (the raw event was cut short in reports) */
1633
1682
  function describeAttributeChange(event) {
1634
1683
  if (!event || event.oldValue === undefined) {
@@ -1646,6 +1695,8 @@ function describeAttributeChange(event) {
1646
1695
  parts.push(`effect ${event.gameplayEffect}`);
1647
1696
  if (event.instigator)
1648
1697
  parts.push(`instigator ${event.instigator}`);
1698
+ if (event.effectCauser && event.effectCauser !== event.instigator)
1699
+ parts.push(`effect causer ${event.effectCauser}`);
1649
1700
  if (event.ability)
1650
1701
  parts.push(`ability ${event.ability}`);
1651
1702
  return parts.join(', ');
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.153",
3
+ "version": "1.0.155",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",