@specter-automation/test 1.0.115 → 1.0.117

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.
@@ -1,7 +1,8 @@
1
1
  import { ComponentLocatorMap } from "../component-registry";
2
2
  import { SpecterLocator } from "../locators/specter-locator";
3
- import { Rotator, Transform, Vector3, RegisteredComponentClasses, RegisteredWidgetClasses, SpecterWorld } from "../specter-client";
3
+ import { Rotator, Transform, Vector3, RegisteredComponentClasses, RegisteredWidgetClasses, SpecterWorld, SpecterGrantedAbility, SpecterActiveEffect, RegisteredGameplayTags } from "../specter-client";
4
4
  import { WidgetLocator, WidgetRole, WidgetRoleOptions } from "./widget-locator";
5
+ import { AiControllerLocator } from "./ai-controller-locator";
5
6
  import { UnrealKey } from "../specter-keys";
6
7
  import { ActorEventMap, EventPredicate, WaitForEventOptions } from "../events";
7
8
  import { SpecterInputSequence } from "../specter-input-sequence";
@@ -154,11 +155,11 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
154
155
  */
155
156
  unpossess(): Promise<void>;
156
157
  getAttributeValue(attributeSet: string, attributeName: string): Promise<number>;
157
- hasGameplayTag(tag: string): Promise<boolean>;
158
+ hasGameplayTag(tag: RegisteredGameplayTags): Promise<boolean>;
158
159
  /**
159
160
  * Waits for a Gameplay Tag to be added or removed.
160
161
  */
161
- waitForGameplayTag(tag: string, expectedState: boolean, timeout?: number): Promise<boolean>;
162
+ waitForGameplayTag(tag: RegisteredGameplayTags, expectedState: boolean, timeout?: number): Promise<boolean>;
162
163
  /**
163
164
  * Waits for a Gameplay Attribute to reach a specific value, tracking its history.
164
165
  */
@@ -340,6 +341,50 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
340
341
  * Retrieves the Team Attitude of this Actor towards another Actor (requires IGenericTeamAgentInterface).
341
342
  */
342
343
  getTeamAttitudeTowards(other: ActorLocator): Promise<'Friendly' | 'Hostile' | 'Neutral'>;
344
+ /**
345
+ * Returns an AiControllerLocator for this Actor's AIController.
346
+ */
347
+ aiController(): AiControllerLocator;
348
+ /**
349
+ * Reads a Blackboard variable from this Actor's AIController.
350
+ */
351
+ getBlackboardValue(keyName: string): Promise<{
352
+ value: string;
353
+ objectName?: string;
354
+ objectClass?: string;
355
+ objectTags?: string[];
356
+ }>;
357
+ /**
358
+ * Checks if this AI Actor / Controller has Line of Sight to a target Actor.
359
+ */
360
+ hasLineOfSightTo(target: ActorLocator | string): Promise<boolean>;
361
+ /**
362
+ * Checks if this AI Actor / Controller is running a specific Behavior Tree asset.
363
+ */
364
+ isRunningBehaviorTree(treePath: string): Promise<boolean>;
365
+ /**
366
+ * Evaluates spatial movement vector, speed, and direction relative to a target actor or coordinates.
367
+ */
368
+ getMovementDirection(target: ActorLocator | {
369
+ x: number;
370
+ y: number;
371
+ z?: number;
372
+ } | string, options?: {
373
+ minSpeed?: number;
374
+ directionThreshold?: number;
375
+ }): Promise<{
376
+ distance: number;
377
+ distance2D: number;
378
+ speed: number;
379
+ speed2D: number;
380
+ velocityDot: number;
381
+ facingDot: number;
382
+ isMovingTowards: boolean;
383
+ isMovingAway: boolean;
384
+ isFacingTarget: boolean;
385
+ isNavigatingTowards: boolean;
386
+ targetActorName?: string;
387
+ }>;
343
388
  /**
344
389
  * Plays a high-resolution input sequence generated by SpecterInputSequence on this specific Actor.
345
390
  * @param sequence The input pattern to play.
@@ -357,7 +402,7 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
357
402
  * @param delayMs Optional delay between keystrokes in milliseconds.
358
403
  */
359
404
  type(text: string, delayMs?: number): Promise<void>;
360
- triggerAbilityByTag(inputTag: string): Promise<void>;
405
+ triggerAbilityByTag(inputTag: RegisteredGameplayTags): Promise<void>;
361
406
  /**
362
407
  * Simulates an ability input press or release on this actor's ASC.
363
408
  * Use this to interact with active abilities that use WaitInputPress/WaitInputRelease
@@ -366,24 +411,32 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
366
411
  * @param abilityTag - The gameplay tag of the ability (e.g. "Ability.Slot.D")
367
412
  * @param pressed - true to simulate press, false to simulate release. Defaults to true.
368
413
  */
369
- pressAbilityInput(abilityTag: string, pressed?: boolean): Promise<void>;
370
- triggerAbilityWithTarget(abilityTag: string, target: SpecterLocator | Vector3, options?: {
414
+ pressAbilityInput(abilityTag: RegisteredGameplayTags, pressed?: boolean): Promise<void>;
415
+ triggerAbilityWithTarget(abilityTag: RegisteredGameplayTags, target: SpecterLocator | Vector3, options?: {
371
416
  singleShot?: boolean;
372
417
  magnitude?: number;
373
418
  }): Promise<void>;
374
419
  applyGameplayEffect(effectClassPath: string, level?: number): Promise<void>;
375
420
  hasActiveGameplayEffect(effectClassPath: string): Promise<boolean>;
376
421
  hasGameplayEffect(effectClassPath: string): Promise<boolean>;
422
+ /**
423
+ * Retrieves all granted abilities on this actor's Ability System Component.
424
+ */
425
+ getGrantedAbilities(): Promise<SpecterGrantedAbility[]>;
426
+ /**
427
+ * Retrieves all active gameplay effects currently applied to this actor's Ability System Component.
428
+ */
429
+ getActiveEffects(): Promise<SpecterActiveEffect[]>;
377
430
  hasGameplayAbility(abilityClassPath: string): Promise<boolean>;
378
431
  getAbilityCooldown(abilityClassPath: string): Promise<number>;
379
432
  getGameplayEffectStackCount(effectClassPath: string): Promise<number>;
380
433
  getGameplayEffectLevel(effectClassPath: string): Promise<number>;
381
434
  getAttributeBaseValue(attributeSet: string, attributeName: string): Promise<number>;
382
435
  isAbilityExecuting(abilityOrClassPath: string): Promise<boolean>;
383
- cancelAbility(abilityOrTagOrClassPath: string): Promise<void>;
384
- getGameplayTagCount(tag: string): Promise<number>;
385
- hasAnyGameplayTags(tags: string[]): Promise<boolean>;
386
- hasAllGameplayTags(tags: string[]): Promise<boolean>;
436
+ cancelAbility(abilityOrTagOrClassPath: RegisteredGameplayTags): Promise<void>;
437
+ getGameplayTagCount(tag: RegisteredGameplayTags): Promise<number>;
438
+ hasAnyGameplayTags(tags: RegisteredGameplayTags[]): Promise<boolean>;
439
+ hasAllGameplayTags(tags: RegisteredGameplayTags[]): Promise<boolean>;
387
440
  getVelocitySize(): Promise<number>;
388
441
  isFalling(): Promise<boolean>;
389
442
  isCrouching(): Promise<boolean>;
@@ -40,6 +40,7 @@ exports.ActorLocator = void 0;
40
40
  const component_registry_1 = require("../component-registry");
41
41
  const specter_locator_1 = require("../locators/specter-locator");
42
42
  const widget_locator_1 = require("./widget-locator");
43
+ const ai_controller_locator_1 = require("./ai-controller-locator");
43
44
  const input_conditions_1 = require("../conditions/input-conditions");
44
45
  const test_1 = __importDefault(require("@playwright/test"));
45
46
  class ActorLocator extends specter_locator_1.SpecterLocator {
@@ -829,6 +830,78 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
829
830
  const response = await this.evaluate("GetTeamAttitudeTowards", { otherActorPath: other.resolvedPath });
830
831
  return response.data?.attitude ?? 'Neutral';
831
832
  }
833
+ /**
834
+ * Returns an AiControllerLocator for this Actor's AIController.
835
+ */
836
+ aiController() {
837
+ return new ai_controller_locator_1.AiControllerLocator(this.transport, [...this.pipeline]);
838
+ }
839
+ /**
840
+ * Reads a Blackboard variable from this Actor's AIController.
841
+ */
842
+ async getBlackboardValue(keyName) {
843
+ const response = await this.evaluate("GetBlackboardValue", { keyName });
844
+ return {
845
+ value: response.data?.value ?? "",
846
+ objectName: response.data?.objectName,
847
+ objectClass: response.data?.objectClass,
848
+ objectTags: response.data?.objectTags ?? []
849
+ };
850
+ }
851
+ /**
852
+ * Checks if this AI Actor / Controller has Line of Sight to a target Actor.
853
+ */
854
+ async hasLineOfSightTo(target) {
855
+ let payload = {};
856
+ if (typeof target === 'string') {
857
+ payload = { targetTag: target, targetName: target };
858
+ }
859
+ else if (target && target.pipeline) {
860
+ payload = { targetLocatorPipeline: target.pipeline };
861
+ }
862
+ const response = await this.evaluate("HasLineOfSightTo", payload);
863
+ return response.data?.hasLOS ?? false;
864
+ }
865
+ /**
866
+ * Checks if this AI Actor / Controller is running a specific Behavior Tree asset.
867
+ */
868
+ async isRunningBehaviorTree(treePath) {
869
+ const response = await this.evaluate("IsRunningBehaviorTree", { treePath });
870
+ return response.data?.isRunning ?? false;
871
+ }
872
+ /**
873
+ * Evaluates spatial movement vector, speed, and direction relative to a target actor or coordinates.
874
+ */
875
+ async getMovementDirection(target, options) {
876
+ let payload = {
877
+ minSpeed: options?.minSpeed,
878
+ directionThreshold: options?.directionThreshold
879
+ };
880
+ if (typeof target === 'string') {
881
+ payload.targetTag = target;
882
+ payload.targetName = target;
883
+ }
884
+ else if (target && typeof target === 'object' && 'pipeline' in target) {
885
+ payload.targetLocatorPipeline = target.pipeline;
886
+ }
887
+ else if (target && typeof target === 'object' && 'x' in target && 'y' in target) {
888
+ payload.targetLocation = target;
889
+ }
890
+ const response = await this.evaluate("GetMovementDirection", payload);
891
+ return {
892
+ distance: response.data?.distance ?? 0,
893
+ distance2D: response.data?.distance2D ?? 0,
894
+ speed: response.data?.speed ?? 0,
895
+ speed2D: response.data?.speed2D ?? 0,
896
+ velocityDot: response.data?.velocityDot ?? 0,
897
+ facingDot: response.data?.facingDot ?? 0,
898
+ isMovingTowards: response.data?.isMovingTowards ?? false,
899
+ isMovingAway: response.data?.isMovingAway ?? false,
900
+ isFacingTarget: response.data?.isFacingTarget ?? false,
901
+ isNavigatingTowards: response.data?.isNavigatingTowards ?? false,
902
+ targetActorName: response.data?.targetActorName
903
+ };
904
+ }
832
905
  /**
833
906
  * Plays a high-resolution input sequence generated by SpecterInputSequence on this specific Actor.
834
907
  * @param sequence The input pattern to play.
@@ -940,6 +1013,20 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
940
1013
  async hasGameplayEffect(effectClassPath) {
941
1014
  return this.hasActiveGameplayEffect(effectClassPath);
942
1015
  }
1016
+ /**
1017
+ * Retrieves all granted abilities on this actor's Ability System Component.
1018
+ */
1019
+ async getGrantedAbilities() {
1020
+ const response = await this.evaluate("GetGrantedAbilities", {});
1021
+ return response.data?.abilities ?? [];
1022
+ }
1023
+ /**
1024
+ * Retrieves all active gameplay effects currently applied to this actor's Ability System Component.
1025
+ */
1026
+ async getActiveEffects() {
1027
+ const response = await this.evaluate("GetActiveEffects", {});
1028
+ return response.data?.effects ?? [];
1029
+ }
943
1030
  async hasGameplayAbility(abilityClassPath) {
944
1031
  const response = await this.evaluate("HasGameplayAbility", { abilityClassPath });
945
1032
  return response.data.hasAbility;
@@ -1,6 +1,33 @@
1
1
  import { SpecterLocator } from "../locators/specter-locator";
2
2
  export declare class AiControllerLocator extends SpecterLocator {
3
3
  isRunningBehaviorTree(treePath: string): Promise<boolean>;
4
- getBlackboardValue(keyName: string): Promise<string>;
5
- hasLineOfSightTo(targetName: string): Promise<boolean>;
4
+ getBlackboardValue(keyName: string): Promise<{
5
+ value: string;
6
+ objectName?: string;
7
+ objectClass?: string;
8
+ objectTags?: string[];
9
+ }>;
10
+ hasLineOfSightTo(target: any): Promise<boolean>;
11
+ isAINavigating(): Promise<boolean>;
12
+ getAINavGoal(): Promise<{
13
+ x: number;
14
+ y: number;
15
+ z: number;
16
+ }>;
17
+ getMovementDirection(target: any, options?: {
18
+ minSpeed?: number;
19
+ directionThreshold?: number;
20
+ }): Promise<{
21
+ distance: number;
22
+ distance2D: number;
23
+ speed: number;
24
+ speed2D: number;
25
+ velocityDot: number;
26
+ facingDot: number;
27
+ isMovingTowards: boolean;
28
+ isMovingAway: boolean;
29
+ isFacingTarget: boolean;
30
+ isNavigatingTowards: boolean;
31
+ targetActorName?: string;
32
+ }>;
6
33
  }
@@ -5,15 +5,65 @@ const specter_locator_1 = require("../locators/specter-locator");
5
5
  class AiControllerLocator extends specter_locator_1.SpecterLocator {
6
6
  async isRunningBehaviorTree(treePath) {
7
7
  const response = await this.evaluate("IsRunningBehaviorTree", { treePath });
8
- return response.data.isRunning;
8
+ return response.data?.isRunning ?? false;
9
9
  }
10
10
  async getBlackboardValue(keyName) {
11
11
  const response = await this.evaluate("GetBlackboardValue", { keyName });
12
- return response.data.value;
12
+ return {
13
+ value: response.data?.value ?? "",
14
+ objectName: response.data?.objectName,
15
+ objectClass: response.data?.objectClass,
16
+ objectTags: response.data?.objectTags ?? []
17
+ };
13
18
  }
14
- async hasLineOfSightTo(targetName) {
15
- const response = await this.evaluate("HasLineOfSightTo", { targetName });
16
- return response.data.hasLOS;
19
+ async hasLineOfSightTo(target) {
20
+ let payload = {};
21
+ if (typeof target === 'string') {
22
+ payload = { targetTag: target, targetName: target };
23
+ }
24
+ else if (target && target.pipeline) {
25
+ payload = { targetLocatorPipeline: target.pipeline };
26
+ }
27
+ const response = await this.evaluate("HasLineOfSightTo", payload);
28
+ return response.data?.hasLOS ?? false;
29
+ }
30
+ async isAINavigating() {
31
+ const response = await this.evaluate("IsAINavigating", {});
32
+ return response.data?.isNavigating ?? false;
33
+ }
34
+ async getAINavGoal() {
35
+ const response = await this.evaluate("GetAINavGoal", {});
36
+ return response.data?.goalLocation ?? { x: 0, y: 0, z: 0 };
37
+ }
38
+ async getMovementDirection(target, options) {
39
+ let payload = {
40
+ minSpeed: options?.minSpeed,
41
+ directionThreshold: options?.directionThreshold
42
+ };
43
+ if (typeof target === 'string') {
44
+ payload.targetTag = target;
45
+ payload.targetName = target;
46
+ }
47
+ else if (target && typeof target === 'object' && 'pipeline' in target) {
48
+ payload.targetLocatorPipeline = target.pipeline;
49
+ }
50
+ else if (target && typeof target === 'object' && 'x' in target && 'y' in target) {
51
+ payload.targetLocation = target;
52
+ }
53
+ const response = await this.evaluate("GetMovementDirection", payload);
54
+ return {
55
+ distance: response.data?.distance ?? 0,
56
+ distance2D: response.data?.distance2D ?? 0,
57
+ speed: response.data?.speed ?? 0,
58
+ speed2D: response.data?.speed2D ?? 0,
59
+ velocityDot: response.data?.velocityDot ?? 0,
60
+ facingDot: response.data?.facingDot ?? 0,
61
+ isMovingTowards: response.data?.isMovingTowards ?? false,
62
+ isMovingAway: response.data?.isMovingAway ?? false,
63
+ isFacingTarget: response.data?.isFacingTarget ?? false,
64
+ isNavigatingTowards: response.data?.isNavigatingTowards ?? false,
65
+ targetActorName: response.data?.targetActorName
66
+ };
17
67
  }
18
68
  }
19
69
  exports.AiControllerLocator = AiControllerLocator;
@@ -18,6 +18,9 @@ export type RegisteredComponentClasses = SpecterRegistry extends {
18
18
  export type RegisteredWidgetClasses = SpecterRegistry extends {
19
19
  WidgetClasses: infer T;
20
20
  } ? T : string;
21
+ export type RegisteredGameplayTags = SpecterRegistry extends {
22
+ GameplayTags: infer T;
23
+ } ? (T | (string & {})) : string;
21
24
  export interface SpecterPayload {
22
25
  messageId?: string;
23
26
  command: string;
@@ -46,12 +49,34 @@ export interface SpecterTimelineEvent {
46
49
  ability?: string;
47
50
  target?: string;
48
51
  }
52
+ export interface SpecterGrantedAbility {
53
+ name: string;
54
+ className: string;
55
+ classPath: string;
56
+ handle: string;
57
+ level: number;
58
+ inputID: number;
59
+ isActive: boolean;
60
+ canActivate: boolean;
61
+ cooldownRemaining: number;
62
+ assetTags: string[];
63
+ sourceTags: string[];
64
+ allTags: string[];
65
+ failureTags: string[];
66
+ }
49
67
  export interface SpecterActiveEffect {
50
68
  name: string;
69
+ className?: string;
70
+ classPath?: string;
71
+ handle?: string;
51
72
  duration: number;
52
73
  remainingTime: number;
53
74
  stackCount: number;
75
+ level?: number;
76
+ period?: number;
54
77
  instigator?: string;
78
+ grantedTags?: string[];
79
+ assetTags?: string[];
55
80
  }
56
81
  export interface SpecterActorSnapshot {
57
82
  name: string;
@@ -67,6 +92,7 @@ export interface SpecterActorSnapshot {
67
92
  attributes?: Record<string, number>;
68
93
  gameplayTags?: string[];
69
94
  activeEffects?: SpecterActiveEffect[];
95
+ grantedAbilities?: SpecterGrantedAbility[];
70
96
  }
71
97
  export interface SpecterDiagnosticsReport {
72
98
  target?: SpecterActorSnapshot;
@@ -281,6 +281,16 @@ class SpecterReporter {
281
281
  .replace(/^(Error:\s*)+/i, '')
282
282
  .replace(/^(Specter C\+\+\s*Error:\s*)+/i, '')
283
283
  .trim();
284
+ // Strip extended diagnostics and causality timelines from the concise error message sent to Unreal UI
285
+ if (cleanMessage.includes('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')) {
286
+ cleanMessage = cleanMessage.split('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━')[0].trim();
287
+ }
288
+ if (cleanMessage.includes('🧠 SPECTER AI DIAGNOSTICS')) {
289
+ cleanMessage = cleanMessage.split('🧠 SPECTER AI DIAGNOSTICS')[0].trim();
290
+ }
291
+ if (cleanMessage.includes('📜 GAS EVENT CAUSALITY TIMELINE')) {
292
+ cleanMessage = cleanMessage.split('📜 GAS EVENT CAUSALITY TIMELINE')[0].trim();
293
+ }
284
294
  let header = 'ERROR';
285
295
  let message = cleanMessage;
286
296
  let source = '';
@@ -359,7 +369,18 @@ class SpecterReporter {
359
369
  message = message.replace(rawSnippet, '').trim();
360
370
  }
361
371
  }
362
- return `${header}|||${message}|||${source}|||${codeSnippet}`;
372
+ // 5. Truncate message and ensure total length is well within Unreal Engine FName limit (1023 chars)
373
+ if (message.length > 300) {
374
+ message = message.substring(0, 297) + '...';
375
+ }
376
+ if (codeSnippet.length > 100) {
377
+ codeSnippet = codeSnippet.substring(0, 97) + '...';
378
+ }
379
+ const formatted = `${header}|||${message}|||${source}|||${codeSnippet}`;
380
+ if (formatted.length > 500) {
381
+ return formatted.substring(0, 497) + '...';
382
+ }
383
+ return formatted;
363
384
  }
364
385
  onStdOut(chunk, test, result) {
365
386
  this.send({
@@ -5,7 +5,8 @@ import { ActorMatchers } from '../matchers/actor-matchers';
5
5
  import { LocatorMatchers } from '../matchers/locator-matchers';
6
6
  import { WidgetMatchers } from '../matchers/widget-matchers';
7
7
  import { MaterialMatchers } from '../matchers/material-matchers';
8
- export declare const expect: typeof baseExpect & GasMatchers & ActorMatchers & LocatorMatchers & WidgetMatchers & MaterialMatchers;
8
+ import { AiMatchers } from '../matchers/ai-matchers';
9
+ export declare const expect: typeof baseExpect & GasMatchers & ActorMatchers & LocatorMatchers & WidgetMatchers & MaterialMatchers & AiMatchers;
9
10
  type SpecterTestFixtures = {
10
11
  world: SpecterWorld;
11
12
  createWorld: (options: CreateWorldOptions) => Promise<SpecterWorld>;
@@ -41,7 +41,8 @@ const actor_matchers_1 = require("../matchers/actor-matchers");
41
41
  const locator_matchers_1 = require("../matchers/locator-matchers");
42
42
  const widget_matchers_1 = require("../matchers/widget-matchers");
43
43
  const material_matchers_1 = require("../matchers/material-matchers");
44
- exports.expect = (0, test_1.mergeExpects)(gas_matchers_1.gasExpect, actor_matchers_1.actorExpect, locator_matchers_1.locatorExpect, widget_matchers_1.widgetExpect, material_matchers_1.materialExpect);
44
+ const ai_matchers_1 = require("../matchers/ai-matchers");
45
+ exports.expect = (0, test_1.mergeExpects)(gas_matchers_1.gasExpect, actor_matchers_1.actorExpect, locator_matchers_1.locatorExpect, widget_matchers_1.widgetExpect, material_matchers_1.materialExpect, ai_matchers_1.aiExpect);
45
46
  // 2. Define the scopes in the extend block
46
47
  exports.test = test_1.test.extend({
47
48
  // WORKER FIXTURE: Boots once per Playwright worker process
package/dist/index.d.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  export { test, expect } from './core/test-wrapper';
2
2
  export { SpecterTransport, SpecterWorld, VectorUtils } from './core/specter-client';
3
- export type { SpecterPayload, SpawnOptions, Vector3, Rotator, LinearColor, Color, Vector2D, SpecterRegistry, SpecterFunctionRegistry, LoadMapOptions } from './core/specter-client';
3
+ export type { SpecterPayload, SpawnOptions, Vector3, Rotator, LinearColor, Color, Vector2D, SpecterRegistry, SpecterFunctionRegistry, LoadMapOptions, SpecterGrantedAbility, SpecterActiveEffect, SpecterActorSnapshot, RegisteredGameplayTags } from './core/specter-client';
4
4
  export { SpecterLocator, WidgetLocator, ActorLocator, AiControllerLocator, type WidgetGeometry } from './core/locators';
5
5
  export { default as SpecterReporter } from './core/specter-reporter';
6
6
  export type { UnrealKey } from './core/specter-keys';
@@ -11,3 +11,5 @@ export type { LocationCondition, DistanceCondition, PropertyCondition, Attribute
11
11
  export { evaluateCondition, runConditionalInputLoop } from './core/conditions/input-conditions';
12
12
  export type { MaterialOptions, MaterialScalarOptions, MaterialVectorOptions, ColorInput, MaterialMatchers } from './matchers/material-matchers';
13
13
  export { materialExpect } from './matchers/material-matchers';
14
+ export type { MovementDirectionInfo, AiMatchers } from './matchers/ai-matchers';
15
+ export { aiExpect } from './matchers/ai-matchers';
package/dist/index.js CHANGED
@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
3
3
  return (mod && mod.__esModule) ? mod : { "default": mod };
4
4
  };
5
5
  Object.defineProperty(exports, "__esModule", { value: true });
6
- exports.materialExpect = exports.runConditionalInputLoop = exports.evaluateCondition = exports.SpecterNetwork = exports.SpecterInputSequence = exports.SpecterReporter = exports.AiControllerLocator = exports.ActorLocator = exports.WidgetLocator = exports.SpecterLocator = exports.VectorUtils = exports.SpecterWorld = exports.SpecterTransport = exports.expect = exports.test = void 0;
6
+ exports.aiExpect = exports.materialExpect = exports.runConditionalInputLoop = exports.evaluateCondition = exports.SpecterNetwork = exports.SpecterInputSequence = exports.SpecterReporter = exports.AiControllerLocator = exports.ActorLocator = exports.WidgetLocator = exports.SpecterLocator = exports.VectorUtils = exports.SpecterWorld = exports.SpecterTransport = exports.expect = exports.test = void 0;
7
7
  var test_wrapper_1 = require("./core/test-wrapper");
8
8
  Object.defineProperty(exports, "test", { enumerable: true, get: function () { return test_wrapper_1.test; } });
9
9
  Object.defineProperty(exports, "expect", { enumerable: true, get: function () { return test_wrapper_1.expect; } });
@@ -27,3 +27,5 @@ Object.defineProperty(exports, "evaluateCondition", { enumerable: true, get: fun
27
27
  Object.defineProperty(exports, "runConditionalInputLoop", { enumerable: true, get: function () { return input_conditions_1.runConditionalInputLoop; } });
28
28
  var material_matchers_1 = require("./matchers/material-matchers");
29
29
  Object.defineProperty(exports, "materialExpect", { enumerable: true, get: function () { return material_matchers_1.materialExpect; } });
30
+ var ai_matchers_1 = require("./matchers/ai-matchers");
31
+ Object.defineProperty(exports, "aiExpect", { enumerable: true, get: function () { return ai_matchers_1.aiExpect; } });
@@ -0,0 +1,165 @@
1
+ import { ActorLocator, AiControllerLocator } from '../core/locators';
2
+ export interface MovementDirectionInfo {
3
+ distance: number;
4
+ distance2D: number;
5
+ speed: number;
6
+ speed2D: number;
7
+ velocityDot: number;
8
+ facingDot: number;
9
+ isMovingTowards: boolean;
10
+ isMovingAway: boolean;
11
+ isFacingTarget: boolean;
12
+ isNavigatingTowards: boolean;
13
+ targetActorName?: string;
14
+ }
15
+ declare global {
16
+ namespace PlaywrightTest {
17
+ interface Matchers<R, T> {
18
+ toHaveBlackboardValue(keyName: string, expectedValue: any, options?: {
19
+ timeout?: number;
20
+ }): T extends (ActorLocator | AiControllerLocator) ? Promise<R> : never;
21
+ toHaveAIState(expectedState: string, options?: {
22
+ timeout?: number;
23
+ keyName?: string;
24
+ }): T extends (ActorLocator | AiControllerLocator) ? Promise<R> : never;
25
+ toBeMovingTowards(target: ActorLocator | {
26
+ x: number;
27
+ y: number;
28
+ z?: number;
29
+ } | string, options?: {
30
+ timeout?: number;
31
+ minSpeed?: number;
32
+ threshold?: number;
33
+ }): T extends (ActorLocator | AiControllerLocator) ? Promise<R> : never;
34
+ toBeMovingAwayFrom(target: ActorLocator | {
35
+ x: number;
36
+ y: number;
37
+ z?: number;
38
+ } | string, options?: {
39
+ timeout?: number;
40
+ minSpeed?: number;
41
+ threshold?: number;
42
+ }): T extends (ActorLocator | AiControllerLocator) ? Promise<R> : never;
43
+ toBeWithinDistance(target: ActorLocator | {
44
+ x: number;
45
+ y: number;
46
+ z?: number;
47
+ } | string, distance: number, options?: {
48
+ timeout?: number;
49
+ planar?: boolean;
50
+ }): T extends (ActorLocator | AiControllerLocator) ? Promise<R> : never;
51
+ toBeFollowing(target: ActorLocator | string, options?: {
52
+ timeout?: number;
53
+ maxDistance?: number;
54
+ }): T extends (ActorLocator | AiControllerLocator) ? Promise<R> : never;
55
+ toHaveLineOfSightTo(target: ActorLocator | string, options?: {
56
+ timeout?: number;
57
+ }): T extends (ActorLocator | AiControllerLocator) ? Promise<R> : never;
58
+ toBeRunningBehaviorTree(treePath: string, options?: {
59
+ timeout?: number;
60
+ }): T extends (ActorLocator | AiControllerLocator) ? Promise<R> : never;
61
+ }
62
+ }
63
+ }
64
+ export interface AiMatchers {
65
+ toHaveBlackboardValue(keyName: string, expectedValue: any, options?: {
66
+ timeout?: number;
67
+ }): Promise<void>;
68
+ toHaveAIState(expectedState: string, options?: {
69
+ timeout?: number;
70
+ keyName?: string;
71
+ }): Promise<void>;
72
+ toBeMovingTowards(target: ActorLocator | {
73
+ x: number;
74
+ y: number;
75
+ z?: number;
76
+ } | string, options?: {
77
+ timeout?: number;
78
+ minSpeed?: number;
79
+ threshold?: number;
80
+ }): Promise<void>;
81
+ toBeMovingAwayFrom(target: ActorLocator | {
82
+ x: number;
83
+ y: number;
84
+ z?: number;
85
+ } | string, options?: {
86
+ timeout?: number;
87
+ minSpeed?: number;
88
+ threshold?: number;
89
+ }): Promise<void>;
90
+ toBeWithinDistance(target: ActorLocator | {
91
+ x: number;
92
+ y: number;
93
+ z?: number;
94
+ } | string, distance: number, options?: {
95
+ timeout?: number;
96
+ planar?: boolean;
97
+ }): Promise<void>;
98
+ toBeFollowing(target: ActorLocator | string, options?: {
99
+ timeout?: number;
100
+ maxDistance?: number;
101
+ }): Promise<void>;
102
+ toHaveLineOfSightTo(target: ActorLocator | string, options?: {
103
+ timeout?: number;
104
+ }): Promise<void>;
105
+ toBeRunningBehaviorTree(treePath: string, options?: {
106
+ timeout?: number;
107
+ }): Promise<void>;
108
+ }
109
+ export declare const aiExpect: import("playwright/test").Expect<{
110
+ toHaveBlackboardValue(this: import("playwright/test").ExpectMatcherState, locator: any, keyName: string, expectedValue: any, options?: {
111
+ timeout?: number;
112
+ }): Promise<{
113
+ pass: boolean;
114
+ message: () => string;
115
+ }>;
116
+ toHaveAIState(this: import("playwright/test").ExpectMatcherState, locator: any, expectedState: string, options?: {
117
+ timeout?: number;
118
+ keyName?: string;
119
+ }): Promise<{
120
+ pass: boolean;
121
+ message: () => string;
122
+ }>;
123
+ toBeMovingTowards(this: import("playwright/test").ExpectMatcherState, locator: any, target: any, options?: {
124
+ timeout?: number;
125
+ minSpeed?: number;
126
+ threshold?: number;
127
+ }): Promise<{
128
+ pass: boolean;
129
+ message: () => string;
130
+ }>;
131
+ toBeMovingAwayFrom(this: import("playwright/test").ExpectMatcherState, locator: any, target: any, options?: {
132
+ timeout?: number;
133
+ minSpeed?: number;
134
+ threshold?: number;
135
+ }): Promise<{
136
+ pass: boolean;
137
+ message: () => string;
138
+ }>;
139
+ toBeWithinDistance(this: import("playwright/test").ExpectMatcherState, locator: any, target: any, distance: number, options?: {
140
+ timeout?: number;
141
+ planar?: boolean;
142
+ }): Promise<{
143
+ pass: boolean;
144
+ message: () => string;
145
+ }>;
146
+ toBeFollowing(this: import("playwright/test").ExpectMatcherState, locator: any, target: any, options?: {
147
+ timeout?: number;
148
+ maxDistance?: number;
149
+ }): Promise<{
150
+ pass: boolean;
151
+ message: () => string;
152
+ }>;
153
+ toHaveLineOfSightTo(this: import("playwright/test").ExpectMatcherState, locator: any, target: any, options?: {
154
+ timeout?: number;
155
+ }): Promise<{
156
+ pass: boolean;
157
+ message: () => string;
158
+ }>;
159
+ toBeRunningBehaviorTree(this: import("playwright/test").ExpectMatcherState, locator: any, treePath: string, options?: {
160
+ timeout?: number;
161
+ }): Promise<{
162
+ pass: boolean;
163
+ message: () => string;
164
+ }>;
165
+ }>;
@@ -0,0 +1,318 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.aiExpect = void 0;
37
+ const test_1 = __importStar(require("@playwright/test"));
38
+ function formatTarget(target) {
39
+ if (typeof target === 'string')
40
+ return `'${target}'`;
41
+ if (target && typeof target.toString === 'function' && target.toString() !== '[object Object]') {
42
+ return target.toString();
43
+ }
44
+ if (target && typeof target === 'object' && 'x' in target && 'y' in target) {
45
+ return `(${target.x}, ${target.y}${target.z !== undefined ? `, ${target.z}` : ''})`;
46
+ }
47
+ return JSON.stringify(target);
48
+ }
49
+ exports.aiExpect = test_1.expect.extend({
50
+ async toHaveBlackboardValue(locator, keyName, expectedValue, options) {
51
+ const isNot = this.isNot;
52
+ const timeout = options?.timeout ?? 5000;
53
+ const startTime = Date.now();
54
+ const prefix = isNot ? 'not.toHaveBlackboardValue' : 'toHaveBlackboardValue';
55
+ const portStr = locator?.transport?.port ? `[Port ${locator.transport.port}] ` : '';
56
+ const stepName = `${portStr}expect(${locator.toString()}).${prefix}('${keyName}', ${formatTarget(expectedValue)})`;
57
+ return await test_1.default.step(stepName, async () => {
58
+ let lastValue = null;
59
+ let lastObjName = undefined;
60
+ let lastObjTags = [];
61
+ while (Date.now() - startTime < timeout) {
62
+ try {
63
+ const info = await locator.getBlackboardValue(keyName);
64
+ lastValue = info.value;
65
+ lastObjName = info.objectName;
66
+ lastObjTags = info.objectTags ?? [];
67
+ let matches = false;
68
+ if (expectedValue instanceof RegExp) {
69
+ matches = expectedValue.test(lastValue) || (lastObjName ? expectedValue.test(lastObjName) : false);
70
+ }
71
+ else if (typeof expectedValue === 'string') {
72
+ const expLower = expectedValue.toLowerCase();
73
+ matches = (lastValue ?? '').toLowerCase() === expLower ||
74
+ (lastObjName ?? '').toLowerCase() === expLower ||
75
+ lastObjTags.some((t) => t.toLowerCase() === expLower);
76
+ }
77
+ else if (typeof expectedValue === 'number') {
78
+ matches = Number(lastValue) === expectedValue;
79
+ }
80
+ else if (typeof expectedValue === 'boolean') {
81
+ const valLower = String(lastValue).toLowerCase();
82
+ const boolVal = valLower === 'true' || valLower === '1';
83
+ matches = boolVal === expectedValue;
84
+ }
85
+ else if (expectedValue && typeof expectedValue === 'object') {
86
+ const expStr = expectedValue.toString ? expectedValue.toString().toLowerCase() : '';
87
+ matches = (lastObjName ?? '').toLowerCase().includes(expStr) ||
88
+ lastObjTags.some((t) => expStr.includes(t.toLowerCase()));
89
+ }
90
+ else {
91
+ matches = lastValue === expectedValue;
92
+ }
93
+ if (isNot ? !matches : matches) {
94
+ return { pass: !isNot, message: () => 'passed' };
95
+ }
96
+ }
97
+ catch (e) { }
98
+ await new Promise(r => setTimeout(r, 100));
99
+ }
100
+ return {
101
+ pass: isNot,
102
+ message: () => `Expected Blackboard key '${keyName}' to ${isNot ? 'not ' : ''}match '${expectedValue}'.\n` +
103
+ `Received value: '${lastValue}'${lastObjName ? ` (Object: '${lastObjName}', Tags: [${lastObjTags.join(', ')}])` : ''}`
104
+ };
105
+ });
106
+ },
107
+ async toHaveAIState(locator, expectedState, options) {
108
+ const isNot = this.isNot;
109
+ const timeout = options?.timeout ?? 5000;
110
+ const keyName = options?.keyName ?? 'AIState';
111
+ const startTime = Date.now();
112
+ const prefix = isNot ? 'not.toHaveAIState' : 'toHaveAIState';
113
+ const portStr = locator?.transport?.port ? `[Port ${locator.transport.port}] ` : '';
114
+ const stepName = `${portStr}expect(${locator.toString()}).${prefix}('${expectedState}')`;
115
+ return await test_1.default.step(stepName, async () => {
116
+ let lastState = '';
117
+ while (Date.now() - startTime < timeout) {
118
+ try {
119
+ let info = await locator.getBlackboardValue(keyName);
120
+ lastState = info.value;
121
+ const expLower = expectedState.toLowerCase();
122
+ const matches = lastState.toLowerCase() === expLower || lastState.toLowerCase().includes(expLower);
123
+ if (isNot ? !matches : matches) {
124
+ return { pass: !isNot, message: () => 'passed' };
125
+ }
126
+ }
127
+ catch (e) { }
128
+ await new Promise(r => setTimeout(r, 100));
129
+ }
130
+ return {
131
+ pass: isNot,
132
+ message: () => `Expected AI state to ${isNot ? 'not ' : ''}be '${expectedState}'.\n` +
133
+ `Received state: '${lastState}' (Key: '${keyName}')`
134
+ };
135
+ });
136
+ },
137
+ async toBeMovingTowards(locator, target, options) {
138
+ const isNot = this.isNot;
139
+ const timeout = options?.timeout ?? 5000;
140
+ const minSpeed = options?.minSpeed ?? 10.0;
141
+ const startTime = Date.now();
142
+ const prefix = isNot ? 'not.toBeMovingTowards' : 'toBeMovingTowards';
143
+ const portStr = locator?.transport?.port ? `[Port ${locator.transport.port}] ` : '';
144
+ const stepName = `${portStr}expect(${locator.toString()}).${prefix}(${formatTarget(target)})`;
145
+ return await test_1.default.step(stepName, async () => {
146
+ let lastInfo = null;
147
+ while (Date.now() - startTime < timeout) {
148
+ try {
149
+ lastInfo = await locator.getMovementDirection(target, {
150
+ minSpeed,
151
+ directionThreshold: options?.threshold ?? 0.3
152
+ });
153
+ const matches = Boolean(lastInfo && lastInfo.isMovingTowards);
154
+ if (isNot ? !matches : matches) {
155
+ return { pass: !isNot, message: () => 'passed' };
156
+ }
157
+ }
158
+ catch (e) { }
159
+ await new Promise(r => setTimeout(r, 100));
160
+ }
161
+ return {
162
+ pass: isNot,
163
+ message: () => `Expected Actor to ${isNot ? 'not ' : ''}be moving towards target.\n` +
164
+ `Target: ${formatTarget(target)}${lastInfo?.targetActorName ? ` (${lastInfo.targetActorName})` : ''}\n` +
165
+ `Current Speed: ${lastInfo?.speed2D.toFixed(1) ?? 0} u/s (min: ${minSpeed})\n` +
166
+ `Velocity Dot: ${lastInfo?.velocityDot.toFixed(2) ?? 0}\n` +
167
+ `Facing Dot: ${lastInfo?.facingDot.toFixed(2) ?? 0} (facing: ${lastInfo?.isFacingTarget ? 'yes' : 'no'})\n` +
168
+ `Distance: ${lastInfo?.distance2D.toFixed(1) ?? 0} units`
169
+ };
170
+ });
171
+ },
172
+ async toBeMovingAwayFrom(locator, target, options) {
173
+ const isNot = this.isNot;
174
+ const timeout = options?.timeout ?? 5000;
175
+ const minSpeed = options?.minSpeed ?? 10.0;
176
+ const startTime = Date.now();
177
+ const prefix = isNot ? 'not.toBeMovingAwayFrom' : 'toBeMovingAwayFrom';
178
+ const portStr = locator?.transport?.port ? `[Port ${locator.transport.port}] ` : '';
179
+ const stepName = `${portStr}expect(${locator.toString()}).${prefix}(${formatTarget(target)})`;
180
+ return await test_1.default.step(stepName, async () => {
181
+ let lastInfo = null;
182
+ while (Date.now() - startTime < timeout) {
183
+ try {
184
+ lastInfo = await locator.getMovementDirection(target, {
185
+ minSpeed,
186
+ directionThreshold: options?.threshold ?? 0.3
187
+ });
188
+ const matches = Boolean(lastInfo && lastInfo.isMovingAway);
189
+ if (isNot ? !matches : matches) {
190
+ return { pass: !isNot, message: () => 'passed' };
191
+ }
192
+ }
193
+ catch (e) { }
194
+ await new Promise(r => setTimeout(r, 100));
195
+ }
196
+ return {
197
+ pass: isNot,
198
+ message: () => `Expected Actor to ${isNot ? 'not ' : ''}be moving away from target.\n` +
199
+ `Target: ${formatTarget(target)}${lastInfo?.targetActorName ? ` (${lastInfo.targetActorName})` : ''}\n` +
200
+ `Current Speed: ${lastInfo?.speed2D.toFixed(1) ?? 0} u/s (min: ${minSpeed})\n` +
201
+ `Velocity Dot: ${lastInfo?.velocityDot.toFixed(2) ?? 0}\n` +
202
+ `Distance: ${lastInfo?.distance2D.toFixed(1) ?? 0} units`
203
+ };
204
+ });
205
+ },
206
+ async toBeWithinDistance(locator, target, distance, options) {
207
+ const isNot = this.isNot;
208
+ const timeout = options?.timeout ?? 5000;
209
+ const planar = options?.planar ?? true;
210
+ const startTime = Date.now();
211
+ const prefix = isNot ? 'not.toBeWithinDistance' : 'toBeWithinDistance';
212
+ const portStr = locator?.transport?.port ? `[Port ${locator.transport.port}] ` : '';
213
+ const stepName = `${portStr}expect(${locator.toString()}).${prefix}(${formatTarget(target)}, ${distance})`;
214
+ return await test_1.default.step(stepName, async () => {
215
+ let lastDistance = Infinity;
216
+ while (Date.now() - startTime < timeout) {
217
+ try {
218
+ const info = await locator.getMovementDirection(target);
219
+ lastDistance = planar ? info.distance2D : info.distance;
220
+ const matches = lastDistance <= distance;
221
+ if (isNot ? !matches : matches) {
222
+ return { pass: !isNot, message: () => 'passed' };
223
+ }
224
+ }
225
+ catch (e) { }
226
+ await new Promise(r => setTimeout(r, 100));
227
+ }
228
+ return {
229
+ pass: isNot,
230
+ message: () => `Expected Actor to ${isNot ? 'not ' : ''}be within ${distance} units of target.\n` +
231
+ `Current distance: ${lastDistance.toFixed(1)} units (${planar ? '2D planar' : '3D'})`
232
+ };
233
+ });
234
+ },
235
+ async toBeFollowing(locator, target, options) {
236
+ const isNot = this.isNot;
237
+ const timeout = options?.timeout ?? 5000;
238
+ const startTime = Date.now();
239
+ const prefix = isNot ? 'not.toBeFollowing' : 'toBeFollowing';
240
+ const portStr = locator?.transport?.port ? `[Port ${locator.transport.port}] ` : '';
241
+ const stepName = `${portStr}expect(${locator.toString()}).${prefix}(${formatTarget(target)})`;
242
+ return await test_1.default.step(stepName, async () => {
243
+ let lastInfo = null;
244
+ while (Date.now() - startTime < timeout) {
245
+ try {
246
+ lastInfo = await locator.getMovementDirection(target);
247
+ let matches = Boolean(lastInfo && lastInfo.isMovingTowards && (lastInfo.isNavigatingTowards || lastInfo.speed2D > 10.0));
248
+ if (lastInfo && options?.maxDistance !== undefined && lastInfo.distance2D > options.maxDistance) {
249
+ matches = false;
250
+ }
251
+ if (isNot ? !matches : matches) {
252
+ return { pass: !isNot, message: () => 'passed' };
253
+ }
254
+ }
255
+ catch (e) { }
256
+ await new Promise(r => setTimeout(r, 100));
257
+ }
258
+ return {
259
+ pass: isNot,
260
+ message: () => `Expected Actor to ${isNot ? 'not ' : ''}be following target.\n` +
261
+ `Speed: ${lastInfo?.speed2D.toFixed(1) ?? 0} u/s\n` +
262
+ `Moving Towards: ${lastInfo?.isMovingTowards ? 'yes' : 'no'}\n` +
263
+ `Navigating Towards Destination: ${lastInfo?.isNavigatingTowards ? 'yes' : 'no'}\n` +
264
+ `Distance: ${lastInfo?.distance2D.toFixed(1) ?? 0} units${options?.maxDistance ? ` (max: ${options.maxDistance})` : ''}`
265
+ };
266
+ });
267
+ },
268
+ async toHaveLineOfSightTo(locator, target, options) {
269
+ const isNot = this.isNot;
270
+ const timeout = options?.timeout ?? 5000;
271
+ const startTime = Date.now();
272
+ const prefix = isNot ? 'not.toHaveLineOfSightTo' : 'toHaveLineOfSightTo';
273
+ const portStr = locator?.transport?.port ? `[Port ${locator.transport.port}] ` : '';
274
+ const stepName = `${portStr}expect(${locator.toString()}).${prefix}(${formatTarget(target)})`;
275
+ return await test_1.default.step(stepName, async () => {
276
+ let lastLOS = false;
277
+ while (Date.now() - startTime < timeout) {
278
+ try {
279
+ lastLOS = await locator.hasLineOfSightTo(target);
280
+ if (isNot ? !lastLOS : lastLOS) {
281
+ return { pass: !isNot, message: () => 'passed' };
282
+ }
283
+ }
284
+ catch (e) { }
285
+ await new Promise(r => setTimeout(r, 100));
286
+ }
287
+ return {
288
+ pass: isNot,
289
+ message: () => `Expected AI to ${isNot ? 'not ' : ''}have Line of Sight to target '${formatTarget(target)}', but hasLOS was ${lastLOS}.`
290
+ };
291
+ });
292
+ },
293
+ async toBeRunningBehaviorTree(locator, treePath, options) {
294
+ const isNot = this.isNot;
295
+ const timeout = options?.timeout ?? 5000;
296
+ const startTime = Date.now();
297
+ const prefix = isNot ? 'not.toBeRunningBehaviorTree' : 'toBeRunningBehaviorTree';
298
+ const portStr = locator?.transport?.port ? `[Port ${locator.transport.port}] ` : '';
299
+ const stepName = `${portStr}expect(${locator.toString()}).${prefix}('${treePath}')`;
300
+ return await test_1.default.step(stepName, async () => {
301
+ let lastRunning = false;
302
+ while (Date.now() - startTime < timeout) {
303
+ try {
304
+ lastRunning = await locator.isRunningBehaviorTree(treePath);
305
+ if (isNot ? !lastRunning : lastRunning) {
306
+ return { pass: !isNot, message: () => 'passed' };
307
+ }
308
+ }
309
+ catch (e) { }
310
+ await new Promise(r => setTimeout(r, 100));
311
+ }
312
+ return {
313
+ pass: isNot,
314
+ message: () => `Expected AI to ${isNot ? 'not ' : ''}be running BehaviorTree '${treePath}', but isRunning was ${lastRunning}.`
315
+ };
316
+ });
317
+ }
318
+ });
@@ -1,5 +1,5 @@
1
1
  import { SpecterLocator, ActorLocator } from '../core/locators';
2
- import { SpecterTimelineEvent } from '../core/specter-client';
2
+ import { SpecterTimelineEvent, RegisteredGameplayTags } from '../core/specter-client';
3
3
  declare global {
4
4
  namespace PlaywrightTest {
5
5
  interface Matchers<R, T> {
@@ -14,7 +14,7 @@ declare global {
14
14
  gameplayEffect?: string;
15
15
  ability?: string;
16
16
  }, triggerAction?: () => Promise<void>): T extends SpecterLocator ? Promise<R> : never;
17
- toHaveGameplayTag(tag: string): T extends SpecterLocator ? Promise<R> : never;
17
+ toHaveGameplayTag(tag: RegisteredGameplayTags): T extends SpecterLocator ? Promise<R> : never;
18
18
  toHaveGameplayEffect(effectClassPath: string): T extends SpecterLocator ? Promise<R> : never;
19
19
  toHaveAppliedGameplayEffect(effectNameOrClass: string, options?: {
20
20
  count?: number;
@@ -33,13 +33,13 @@ declare global {
33
33
  toHaveGameplayEffectLevel(effectClassPath: string, expectedLevel: number): T extends SpecterLocator ? Promise<R> : never;
34
34
  toHaveAttributeBaseValue(attributeSet: string, attributeName: string, expectedValue: number): T extends SpecterLocator ? Promise<R> : never;
35
35
  toBeExecutingAbility(abilityClassPath: string): T extends SpecterLocator ? Promise<R> : never;
36
- toHaveActivatedAbility(ability: string, optionsOrTrigger?: {
36
+ toHaveActivatedAbility(ability: RegisteredGameplayTags, optionsOrTrigger?: {
37
37
  timeout?: number;
38
38
  times?: number;
39
39
  } | (() => Promise<void>), triggerAction?: () => Promise<void>): T extends SpecterLocator ? Promise<R> : never;
40
- toHaveGameplayTagCount(tag: string, expectedCount: number): T extends SpecterLocator ? Promise<R> : never;
41
- toHaveAnyGameplayTags(tags: string[]): T extends SpecterLocator ? Promise<R> : never;
42
- toHaveAllGameplayTags(tags: string[]): T extends SpecterLocator ? Promise<R> : never;
40
+ toHaveGameplayTagCount(tag: RegisteredGameplayTags, expectedCount: number): T extends SpecterLocator ? Promise<R> : never;
41
+ toHaveAnyGameplayTags(tags: RegisteredGameplayTags[]): T extends SpecterLocator ? Promise<R> : never;
42
+ toHaveAllGameplayTags(tags: RegisteredGameplayTags[]): T extends SpecterLocator ? Promise<R> : never;
43
43
  }
44
44
  }
45
45
  }
@@ -57,7 +57,7 @@ export interface GasMatchers {
57
57
  timeout?: number;
58
58
  tolerance?: number;
59
59
  }, triggerAction?: () => Promise<void>): Promise<void>;
60
- toHaveGameplayTag(tag: string): Promise<void>;
60
+ toHaveGameplayTag(tag: RegisteredGameplayTags): Promise<void>;
61
61
  toHaveGameplayEffect(effectClassPath: string): Promise<void>;
62
62
  toHaveAppliedGameplayEffect(effectNameOrClass: string, options?: {
63
63
  count?: number;
@@ -76,13 +76,13 @@ export interface GasMatchers {
76
76
  toHaveGameplayEffectLevel(effectClassPath: string, expectedLevel: number): Promise<void>;
77
77
  toHaveAttributeBaseValue(attributeSet: string, attributeName: string, expectedValue: number): Promise<void>;
78
78
  toBeExecutingAbility(abilityClassPath: string): Promise<void>;
79
- toHaveActivatedAbility(ability: string, optionsOrTrigger?: {
79
+ toHaveActivatedAbility(ability: RegisteredGameplayTags, optionsOrTrigger?: {
80
80
  timeout?: number;
81
81
  times?: number;
82
82
  } | (() => Promise<void>), triggerAction?: () => Promise<void>): Promise<void>;
83
- toHaveGameplayTagCount(tag: string, expectedCount: number): Promise<void>;
84
- toHaveAnyGameplayTags(tags: string[]): Promise<void>;
85
- toHaveAllGameplayTags(tags: string[]): Promise<void>;
83
+ toHaveGameplayTagCount(tag: RegisteredGameplayTags, expectedCount: number): Promise<void>;
84
+ toHaveAnyGameplayTags(tags: RegisteredGameplayTags[]): Promise<void>;
85
+ toHaveAllGameplayTags(tags: RegisteredGameplayTags[]): Promise<void>;
86
86
  }
87
87
  export declare function formatAiDiagnostics(diagnostics: any): string;
88
88
  export declare function formatCausalityTimeline(events: SpecterTimelineEvent[]): string;
@@ -118,7 +118,7 @@ export declare const gasExpect: import("playwright/test").Expect<{
118
118
  tolerance?: number;
119
119
  };
120
120
  }>;
121
- toHaveGameplayTag(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, tag: string): Promise<{
121
+ toHaveGameplayTag(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, tag: RegisteredGameplayTags): Promise<{
122
122
  pass: boolean;
123
123
  message: () => string;
124
124
  actual: boolean;
@@ -207,7 +207,7 @@ export declare const gasExpect: import("playwright/test").Expect<{
207
207
  actual: boolean;
208
208
  expected: boolean;
209
209
  }>;
210
- toHaveActivatedAbility(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, ability: string, optionsOrTrigger?: {
210
+ toHaveActivatedAbility(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, ability: RegisteredGameplayTags, optionsOrTrigger?: {
211
211
  timeout?: number;
212
212
  times?: number;
213
213
  } | (() => Promise<void>), triggerAction?: () => Promise<void>): Promise<{
@@ -216,7 +216,7 @@ export declare const gasExpect: import("playwright/test").Expect<{
216
216
  actual: number | boolean;
217
217
  expected: number | boolean;
218
218
  }>;
219
- toHaveGameplayTagCount(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, tag: string, expectedCount: number): Promise<{
219
+ toHaveGameplayTagCount(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, tag: RegisteredGameplayTags, expectedCount: number): Promise<{
220
220
  pass: boolean;
221
221
  message: () => string;
222
222
  actual?: undefined;
@@ -227,7 +227,7 @@ export declare const gasExpect: import("playwright/test").Expect<{
227
227
  actual: number;
228
228
  expected: number;
229
229
  }>;
230
- toHaveAnyGameplayTags(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, tags: string[]): Promise<{
230
+ toHaveAnyGameplayTags(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, tags: RegisteredGameplayTags[]): Promise<{
231
231
  pass: boolean;
232
232
  message: () => string;
233
233
  actual?: undefined;
@@ -238,7 +238,7 @@ export declare const gasExpect: import("playwright/test").Expect<{
238
238
  actual: boolean;
239
239
  expected: boolean;
240
240
  }>;
241
- toHaveAllGameplayTags(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, tags: string[]): Promise<{
241
+ toHaveAllGameplayTags(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, tags: RegisteredGameplayTags[]): Promise<{
242
242
  pass: boolean;
243
243
  message: () => string;
244
244
  actual?: undefined;
@@ -729,6 +729,31 @@ exports.gasExpect = test_1.expect.extend({
729
729
  const transport = locator.transport;
730
730
  const capturedEvents = [];
731
731
  const matchingApplications = [];
732
+ const seenCapturedKeys = new Set();
733
+ const seenEffectKeys = new Set();
734
+ const recordCapturedEvent = (ev) => {
735
+ if (!ev)
736
+ return;
737
+ const key = `${ev.timestamp}_${ev.eventName}_${ev.oldValue}_${ev.newValue}_${ev.description}_${ev.networkRole}`;
738
+ if (!seenCapturedKeys.has(key)) {
739
+ seenCapturedKeys.add(key);
740
+ capturedEvents.push(ev);
741
+ }
742
+ };
743
+ const recordEffectApplication = (ev) => {
744
+ const time = Number(ev.timestamp) || 0;
745
+ // Quantize timestamp to 100ms window to group client prediction + server confirmation and avoid duplicate receipt
746
+ const timeBucket = (Math.round(time * 10) / 10).toFixed(1);
747
+ const target = (ev.target || '').trim();
748
+ const inst = (ev.instigator || '').trim();
749
+ const key = `${timeBucket}_${effectNameOrClass}_${target}_${inst}`;
750
+ if (!seenEffectKeys.has(key)) {
751
+ seenEffectKeys.add(key);
752
+ matchingApplications.push(ev);
753
+ return true;
754
+ }
755
+ return false;
756
+ };
732
757
  // Resolve instigator and target names
733
758
  const [expectedInstigatorName, targetName] = await Promise.all([
734
759
  options?.instigator
@@ -773,9 +798,9 @@ exports.gasExpect = test_1.expect.extend({
773
798
  const recent = transport.getRecentEvents('GLOBAL_timeline-event', startTime - 3000);
774
799
  for (const item of recent) {
775
800
  if (item?.data) {
776
- capturedEvents.push(item.data);
801
+ recordCapturedEvent(item.data);
777
802
  if (isMatchingEffect(item.data)) {
778
- matchingApplications.push(item.data);
803
+ recordEffectApplication(item.data);
779
804
  }
780
805
  }
781
806
  }
@@ -852,10 +877,11 @@ exports.gasExpect = test_1.expect.extend({
852
877
  const listener = (event) => {
853
878
  if (isResolved)
854
879
  return;
855
- capturedEvents.push(event);
880
+ recordCapturedEvent(event);
856
881
  if (isMatchingEffect(event)) {
857
- matchingApplications.push(event);
858
- checkCondition();
882
+ if (recordEffectApplication(event)) {
883
+ checkCondition();
884
+ }
859
885
  }
860
886
  };
861
887
  if (transport && typeof transport.registerEventListener === 'function') {
@@ -1126,41 +1152,76 @@ exports.gasExpect = test_1.expect.extend({
1126
1152
  const transport = locator.transport;
1127
1153
  const capturedEvents = [];
1128
1154
  const activations = [];
1155
+ const seenCapturedKeys = new Set();
1156
+ const seenActivationKeys = new Set();
1157
+ const recordCapturedEvent = (ev) => {
1158
+ if (!ev)
1159
+ return;
1160
+ const key = `${ev.timestamp}_${ev.eventName}_${ev.oldValue}_${ev.newValue}_${ev.description}_${ev.networkRole}`;
1161
+ if (!seenCapturedKeys.has(key)) {
1162
+ seenCapturedKeys.add(key);
1163
+ capturedEvents.push(ev);
1164
+ }
1165
+ };
1166
+ const recordActivation = (ev) => {
1167
+ const time = Number(ev.timestamp) || 0;
1168
+ // Quantize timestamp to 100ms window to group client prediction + server confirmation and avoid duplicate receipt
1169
+ const timeBucket = (Math.round(time * 10) / 10).toFixed(1);
1170
+ const inst = (ev.instigator || ev.target || '').trim();
1171
+ const key = `${timeBucket}_${ability}_${inst}`;
1172
+ if (!seenActivationKeys.has(key)) {
1173
+ seenActivationKeys.add(key);
1174
+ activations.push(ev);
1175
+ return true;
1176
+ }
1177
+ return false;
1178
+ };
1129
1179
  const startTime = Date.now();
1130
1180
  const targetName = await locator.getObjectName().catch(() => undefined);
1131
1181
  const isMatchingAbility = (data) => {
1132
1182
  if (!data)
1133
1183
  return false;
1134
- if (data.ability === ability || data.abilityName === ability || data.abilityClass === ability) {
1184
+ const evAbility = (data.ability || data.abilityName || data.abilityClass || '').trim();
1185
+ if (evAbility === ability || (evAbility && ability.includes(evAbility)) || (ability && evAbility.includes(ability))) {
1135
1186
  return true;
1136
1187
  }
1137
1188
  if (data.tags && Array.isArray(data.tags)) {
1138
- if (data.tags.some((t) => t === ability || t.includes(ability))) {
1189
+ if (data.tags.some((t) => t === ability || t.includes(ability) || ability.includes(t))) {
1139
1190
  return true;
1140
1191
  }
1141
1192
  }
1142
- if (data.abilityClass && data.abilityClass.includes(ability)) {
1193
+ if (data.abilityClass && (data.abilityClass.includes(ability) || ability.includes(data.abilityClass))) {
1143
1194
  return true;
1144
1195
  }
1145
- if (data.abilityPath && data.abilityPath.includes(ability)) {
1196
+ if (data.abilityPath && (data.abilityPath.includes(ability) || ability.includes(data.abilityPath))) {
1146
1197
  return true;
1147
1198
  }
1148
- if (data.eventName && data.eventName.includes(ability)) {
1199
+ if (data.eventName && (data.eventName.includes(ability) || (evAbility && data.eventName.includes(evAbility)))) {
1149
1200
  return true;
1150
1201
  }
1151
- if (data.description && data.description.includes(ability)) {
1202
+ if (data.description && (data.description.includes(ability) || (evAbility && data.description.includes(evAbility)))) {
1152
1203
  return true;
1153
1204
  }
1154
1205
  return false;
1155
1206
  };
1207
+ const isMatchingActor = (data) => {
1208
+ if (!targetName)
1209
+ return true;
1210
+ const inst = (data.instigator || data.target || '').trim();
1211
+ if (!inst)
1212
+ return true;
1213
+ const cleanTarget = targetName.trim();
1214
+ return inst.includes(cleanTarget) || cleanTarget.includes(inst) ||
1215
+ (inst.includes('PlayerState') && cleanTarget.includes('Hero') && inst.slice(-2) === cleanTarget.slice(-2));
1216
+ };
1156
1217
  // Seed from recent transport events if trigger action ran just prior
1157
1218
  if (transport && typeof transport.getRecentEvents === 'function') {
1158
1219
  const recent = transport.getRecentEvents('GLOBAL_timeline-event', startTime - 3000);
1159
1220
  for (const item of recent) {
1160
1221
  if (item?.data) {
1161
- capturedEvents.push(item.data);
1162
- if (isMatchingAbility(item.data)) {
1163
- activations.push(item.data);
1222
+ recordCapturedEvent(item.data);
1223
+ if (isMatchingAbility(item.data) && isMatchingActor(item.data)) {
1224
+ recordActivation(item.data);
1164
1225
  }
1165
1226
  }
1166
1227
  }
@@ -1246,23 +1307,16 @@ exports.gasExpect = test_1.expect.extend({
1246
1307
  const listener = (event) => {
1247
1308
  if (isResolved)
1248
1309
  return;
1249
- capturedEvents.push(event);
1310
+ recordCapturedEvent(event);
1250
1311
  const isAbilityEv = (event.eventName && event.eventName.includes('Ability Activated')) ||
1251
1312
  (event.description && event.description.includes('activated ability')) ||
1252
1313
  event.ability;
1253
1314
  if (isAbilityEv && isMatchingAbility(event)) {
1254
- if (targetName && event.instigator) {
1255
- const cleanTarget = targetName.trim();
1256
- const cleanInst = event.instigator.trim();
1257
- if (cleanInst.includes(cleanTarget) || cleanTarget.includes(cleanInst)) {
1258
- activations.push(event);
1315
+ if (isMatchingActor(event)) {
1316
+ if (recordActivation(event)) {
1259
1317
  checkCondition();
1260
1318
  }
1261
1319
  }
1262
- else {
1263
- activations.push(event);
1264
- checkCondition();
1265
- }
1266
1320
  }
1267
1321
  };
1268
1322
  if (transport && typeof transport.registerEventListener === 'function') {
@@ -1318,7 +1372,7 @@ exports.gasExpect = test_1.expect.extend({
1318
1372
  diagStr = formatAiDiagnostics(diags);
1319
1373
  if (diags?.flightRecorder && Array.isArray(diags.flightRecorder)) {
1320
1374
  for (const ev of diags.flightRecorder) {
1321
- capturedEvents.push(ev);
1375
+ recordCapturedEvent(ev);
1322
1376
  }
1323
1377
  }
1324
1378
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.115",
3
+ "version": "1.0.117",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",