@specter-automation/test 1.0.141 → 1.0.143

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,6 +1,6 @@
1
1
  import { ComponentLocatorMap } from "../component-registry";
2
2
  import { SpecterLocator } from "../locators/specter-locator";
3
- import { Rotator, Transform, Vector3, RegisteredComponentClasses, RegisteredWidgetClasses, SpecterWorld, SpecterGrantedAbility, SpecterActiveEffect, RegisteredGameplayTags } from "../specter-client";
3
+ import { Rotator, Transform, Vector3, RegisteredActorClasses, RegisteredComponentClasses, RegisteredWidgetClasses, SpecterWorld, SpecterGrantedAbility, SpecterActiveEffect, RegisteredGameplayTags } from "../specter-client";
4
4
  import { WidgetLocator, WidgetRole, WidgetRoleOptions } from "./widget-locator";
5
5
  import { AiControllerLocator } from "./ai-controller-locator";
6
6
  import { UnrealKey } from "../specter-keys";
@@ -8,6 +8,17 @@ import { ActorEventMap, EventPredicate, WaitForEventOptions } from "../events";
8
8
  import { SpecterInputSequence } from "../specter-input-sequence";
9
9
  import { InputConditionalOptions, SpecterCondition, ConditionFunction } from '../conditions/input-conditions';
10
10
  import type { BehaviorTrail } from "../specter-ai-trail";
11
+ export interface BlackboardValueResult {
12
+ value: string;
13
+ objectName?: string;
14
+ objectClass?: string;
15
+ objectTags?: string[];
16
+ /**
17
+ * Converts this blackboard value into an ActorLocator if it represents an Actor.
18
+ * Returns null if no Actor is stored (e.g. value is 'None' or empty).
19
+ */
20
+ toActor<A extends RegisteredActorClasses | (string & {}) = any>(): ActorLocator<A> | null;
21
+ }
11
22
  export interface PossessAsPlayerOptions {
12
23
  world?: SpecterWorld | {
13
24
  world: SpecterWorld;
@@ -369,12 +380,12 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
369
380
  /**
370
381
  * Reads a Blackboard variable from this Actor's AIController.
371
382
  */
372
- getBlackboardValue(keyName: string): Promise<{
373
- value: string;
374
- objectName?: string;
375
- objectClass?: string;
376
- objectTags?: string[];
377
- }>;
383
+ getBlackboardValue(keyName: string): Promise<BlackboardValueResult>;
384
+ /**
385
+ * Convenience method to directly get an ActorLocator for an Actor stored in an AI Blackboard key.
386
+ * Returns null if the Blackboard key does not contain an Actor or is set to None.
387
+ */
388
+ getBlackboardActor<A extends RegisteredActorClasses | (string & {}) = any>(keyName: string): Promise<ActorLocator<A> | null>;
378
389
  /**
379
390
  * Checks if this AI Actor / Controller has Line of Sight to a target Actor.
380
391
  */
@@ -900,13 +900,36 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
900
900
  */
901
901
  async getBlackboardValue(keyName) {
902
902
  const response = await this.evaluate("GetBlackboardValue", { keyName });
903
+ const value = response.data?.value ?? "";
904
+ const objectName = response.data?.objectName;
905
+ const objectClass = response.data?.objectClass;
906
+ const objectTags = response.data?.objectTags ?? [];
903
907
  return {
904
- value: response.data?.value ?? "",
905
- objectName: response.data?.objectName,
906
- objectClass: response.data?.objectClass,
907
- objectTags: response.data?.objectTags ?? []
908
+ value,
909
+ objectName,
910
+ objectClass,
911
+ objectTags,
912
+ toActor: () => {
913
+ if (!objectName || value.toLowerCase() === 'none')
914
+ return null;
915
+ if (objectClass) {
916
+ return new ActorLocator(this.transport, [
917
+ { action: 'getByClass', value: objectClass },
918
+ { action: 'filterByProperty', value: JSON.stringify({ name: 'Name', value: objectName }) }
919
+ ]);
920
+ }
921
+ return new ActorLocator(this.transport, [{ action: 'getByTag', value: objectName }]);
922
+ }
908
923
  };
909
924
  }
925
+ /**
926
+ * Convenience method to directly get an ActorLocator for an Actor stored in an AI Blackboard key.
927
+ * Returns null if the Blackboard key does not contain an Actor or is set to None.
928
+ */
929
+ async getBlackboardActor(keyName) {
930
+ const result = await this.getBlackboardValue(keyName);
931
+ return result.toActor();
932
+ }
910
933
  /**
911
934
  * Checks if this AI Actor / Controller has Line of Sight to a target Actor.
912
935
  */
@@ -1,5 +1,7 @@
1
1
  import { SpecterLocator } from "../locators/specter-locator";
2
2
  import type { BehaviorTrail } from "../specter-ai-trail";
3
+ import { ActorLocator, type BlackboardValueResult } from "./actor-locator";
4
+ import type { RegisteredActorClasses } from "../specter-client";
3
5
  export declare class AiControllerLocator extends SpecterLocator {
4
6
  isRunningBehaviorTree(treePath: string): Promise<boolean>;
5
7
  /**
@@ -10,12 +12,8 @@ export declare class AiControllerLocator extends SpecterLocator {
10
12
  getBehaviorTrail(options?: {
11
13
  limit?: number;
12
14
  }): Promise<BehaviorTrail>;
13
- getBlackboardValue(keyName: string): Promise<{
14
- value: string;
15
- objectName?: string;
16
- objectClass?: string;
17
- objectTags?: string[];
18
- }>;
15
+ getBlackboardValue(keyName: string): Promise<BlackboardValueResult>;
16
+ getBlackboardActor<A extends RegisteredActorClasses | (string & {}) = any>(keyName: string): Promise<ActorLocator<A> | null>;
19
17
  hasLineOfSightTo(target: any): Promise<boolean>;
20
18
  isAINavigating(): Promise<boolean>;
21
19
  getAINavGoal(): Promise<{
@@ -2,6 +2,7 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.AiControllerLocator = void 0;
4
4
  const specter_locator_1 = require("../locators/specter-locator");
5
+ const actor_locator_1 = require("./actor-locator");
5
6
  class AiControllerLocator extends specter_locator_1.SpecterLocator {
6
7
  async isRunningBehaviorTree(treePath) {
7
8
  const response = await this.evaluate("IsRunningBehaviorTree", { treePath });
@@ -21,13 +22,32 @@ class AiControllerLocator extends specter_locator_1.SpecterLocator {
21
22
  }
22
23
  async getBlackboardValue(keyName) {
23
24
  const response = await this.evaluate("GetBlackboardValue", { keyName });
25
+ const value = response.data?.value ?? "";
26
+ const objectName = response.data?.objectName;
27
+ const objectClass = response.data?.objectClass;
28
+ const objectTags = response.data?.objectTags ?? [];
24
29
  return {
25
- value: response.data?.value ?? "",
26
- objectName: response.data?.objectName,
27
- objectClass: response.data?.objectClass,
28
- objectTags: response.data?.objectTags ?? []
30
+ value,
31
+ objectName,
32
+ objectClass,
33
+ objectTags,
34
+ toActor: () => {
35
+ if (!objectName || value.toLowerCase() === 'none')
36
+ return null;
37
+ if (objectClass) {
38
+ return new actor_locator_1.ActorLocator(this.transport, [
39
+ { action: 'getByClass', value: objectClass },
40
+ { action: 'filterByProperty', value: JSON.stringify({ name: 'Name', value: objectName }) }
41
+ ]);
42
+ }
43
+ return new actor_locator_1.ActorLocator(this.transport, [{ action: 'getByTag', value: objectName }]);
44
+ }
29
45
  };
30
46
  }
47
+ async getBlackboardActor(keyName) {
48
+ const result = await this.getBlackboardValue(keyName);
49
+ return result.toActor();
50
+ }
31
51
  async hasLineOfSightTo(target) {
32
52
  let payload = {};
33
53
  if (typeof target === 'string') {
@@ -196,6 +196,8 @@ export interface SpawnOptions {
196
196
  location?: Vector3;
197
197
  rotation?: Rotator;
198
198
  properties?: Record<string, any>;
199
+ /** Pawns only. Default true: the pawn gets its controller (its AI). False spawns it with none, even when its class
200
+ * would possess it with AI on spawn: it stands where it's put, e.g. a target dummy. Needs the Specter plugin from 2026-10-15. */
199
201
  spawnController?: boolean;
200
202
  name?: string;
201
203
  /** If true, the actor will not be destroyed by ClearAllSpawned between tests. */
@@ -394,6 +396,10 @@ export declare class SpecterWorld {
394
396
  spawnActor<T extends RegisteredActorClasses | (string & {})>(classNameOrAssetPath: T, options?: SpawnOptions): Promise<ActorLocator<T>>;
395
397
  actor<T extends RegisteredActorClasses | (string & {})>(selector: T): ActorLocator<T>;
396
398
  actorByTag(tagName: string): ActorLocator;
399
+ /**
400
+ * Locates an Actor by its engine Object Name (e.g. 'BP_Minion_C_1' or custom name).
401
+ */
402
+ actorByName<T extends RegisteredActorClasses | (string & {}) = any>(actorName: string): ActorLocator<T>;
397
403
  /**
398
404
  * Locates the locally controlled actor for this world.
399
405
  * Optionally filters by an actor class or selector.
@@ -704,17 +704,27 @@ class SpecterWorld {
704
704
  // ==========================================
705
705
  // THE ACTOR ENTRY POINTS
706
706
  // ==========================================
707
- // Replaces 'getByClass'. Defaults to finding an Actor by class, or supports selector prefixes like 'Tag:Tagname' or 'tag=Tagname'.
707
+ // Replaces 'getByClass'. Defaults to finding an Actor by class, or supports selector prefixes like 'Tag:Tagname', 'tag=Tagname', 'name:ActorName', or 'name=ActorName'.
708
708
  actor(selector) {
709
709
  if (typeof selector === 'string' && /^(tag[:=]|Tag[:=])/i.test(selector)) {
710
710
  const tagName = selector.replace(/^(tag[:=]|Tag[:=])/i, '');
711
711
  return this.actorByTag(tagName);
712
712
  }
713
+ if (typeof selector === 'string' && /^(name[:=]|Name[:=])/i.test(selector)) {
714
+ const name = selector.replace(/^(name[:=]|Name[:=])/i, '');
715
+ return this.actorByName(name);
716
+ }
713
717
  return new locators_1.ActorLocator(this.transport, [{ action: 'getByClass', value: selector }]);
714
718
  }
715
719
  actorByTag(tagName) {
716
720
  return new locators_1.ActorLocator(this.transport, [{ action: 'getByTag', value: tagName }]);
717
721
  }
722
+ /**
723
+ * Locates an Actor by its engine Object Name (e.g. 'BP_Minion_C_1' or custom name).
724
+ */
725
+ actorByName(actorName) {
726
+ return new locators_1.ActorLocator(this.transport, [{ action: 'getByTag', value: actorName }]);
727
+ }
718
728
  /**
719
729
  * Locates the locally controlled actor for this world.
720
730
  * Optionally filters by an actor class or selector.
@@ -17,6 +17,9 @@ function formatTarget(target) {
17
17
  }
18
18
  /** What a blackboard value is expected to be, ready to compare with the trail's text: an actor locator becomes its name */
19
19
  async function resolveExpectedValue(expected) {
20
+ if (Array.isArray(expected)) {
21
+ return Promise.all(expected.map(e => resolveExpectedValue(e)));
22
+ }
20
23
  if (expected && typeof expected === 'object' && !(expected instanceof RegExp) && typeof expected.getObjectName === 'function') {
21
24
  try {
22
25
  return await expected.getObjectName();
@@ -29,6 +32,9 @@ async function resolveExpectedValue(expected) {
29
32
  }
30
33
  /** A value from the trail (DescribeKeyValue text) against what the test expects */
31
34
  function trailValueMatches(value, expected) {
35
+ if (Array.isArray(expected)) {
36
+ return expected.some(singleExp => trailValueMatches(value, singleExp));
37
+ }
32
38
  if (expected instanceof RegExp)
33
39
  return expected.test(value);
34
40
  if (typeof expected === 'number')
@@ -38,6 +44,9 @@ function trailValueMatches(value, expected) {
38
44
  return value.toLowerCase() === String(expected).toLowerCase();
39
45
  }
40
46
  function describeExpected(expected) {
47
+ if (Array.isArray(expected)) {
48
+ return `[${expected.map(describeExpected).join(', ')}]`;
49
+ }
41
50
  return expected instanceof RegExp ? String(expected) : `'${expected}'`;
42
51
  }
43
52
  /** The blackboard keys a matcher is about, shown first in its trail */
@@ -76,42 +85,48 @@ exports.aiExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)(wit
76
85
  const isNot = this.isNot;
77
86
  const timeout = options?.timeout ?? 5000;
78
87
  const startTime = Date.now();
88
+ const resolvedExpected = await resolveExpectedValue(expectedValue);
79
89
  return await (async () => {
80
90
  let lastValue = null;
81
91
  let lastObjName = undefined;
82
92
  let lastObjTags = [];
93
+ const checkMatch = (exp) => {
94
+ if (Array.isArray(exp)) {
95
+ return exp.some(singleExp => checkMatch(singleExp));
96
+ }
97
+ if (exp instanceof RegExp) {
98
+ return exp.test(lastValue) || (lastObjName ? exp.test(lastObjName) : false);
99
+ }
100
+ else if (typeof exp === 'string') {
101
+ const expLower = exp.toLowerCase();
102
+ return (lastValue ?? '').toLowerCase() === expLower ||
103
+ (lastObjName ?? '').toLowerCase() === expLower ||
104
+ lastObjTags.some((t) => t.toLowerCase() === expLower);
105
+ }
106
+ else if (typeof exp === 'number') {
107
+ return Number(lastValue) === exp;
108
+ }
109
+ else if (typeof exp === 'boolean') {
110
+ const valLower = String(lastValue).toLowerCase();
111
+ const boolVal = valLower === 'true' || valLower === '1';
112
+ return boolVal === exp;
113
+ }
114
+ else if (exp && typeof exp === 'object') {
115
+ const expStr = exp.toString ? exp.toString().toLowerCase() : '';
116
+ return (lastObjName ?? '').toLowerCase().includes(expStr) ||
117
+ lastObjTags.some((t) => expStr.includes(t.toLowerCase()));
118
+ }
119
+ else {
120
+ return lastValue === exp;
121
+ }
122
+ };
83
123
  while (Date.now() - startTime < timeout) {
84
124
  try {
85
125
  const info = await locator.getBlackboardValue(keyName);
86
126
  lastValue = info.value;
87
127
  lastObjName = info.objectName;
88
128
  lastObjTags = info.objectTags ?? [];
89
- let matches = false;
90
- if (expectedValue instanceof RegExp) {
91
- matches = expectedValue.test(lastValue) || (lastObjName ? expectedValue.test(lastObjName) : false);
92
- }
93
- else if (typeof expectedValue === 'string') {
94
- const expLower = expectedValue.toLowerCase();
95
- matches = (lastValue ?? '').toLowerCase() === expLower ||
96
- (lastObjName ?? '').toLowerCase() === expLower ||
97
- lastObjTags.some((t) => t.toLowerCase() === expLower);
98
- }
99
- else if (typeof expectedValue === 'number') {
100
- matches = Number(lastValue) === expectedValue;
101
- }
102
- else if (typeof expectedValue === 'boolean') {
103
- const valLower = String(lastValue).toLowerCase();
104
- const boolVal = valLower === 'true' || valLower === '1';
105
- matches = boolVal === expectedValue;
106
- }
107
- else if (expectedValue && typeof expectedValue === 'object') {
108
- const expStr = expectedValue.toString ? expectedValue.toString().toLowerCase() : '';
109
- matches = (lastObjName ?? '').toLowerCase().includes(expStr) ||
110
- lastObjTags.some((t) => expStr.includes(t.toLowerCase()));
111
- }
112
- else {
113
- matches = lastValue === expectedValue;
114
- }
129
+ const matches = checkMatch(resolvedExpected);
115
130
  if (isNot ? !matches : matches) {
116
131
  return { pass: !isNot, message: () => 'passed' };
117
132
  }
@@ -121,7 +136,7 @@ exports.aiExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)(wit
121
136
  }
122
137
  return {
123
138
  pass: isNot,
124
- message: () => `Expected Blackboard key '${keyName}' to ${isNot ? 'not ' : ''}match '${expectedValue}'.\n` +
139
+ message: () => `Expected Blackboard key '${keyName}' to ${isNot ? 'not ' : ''}match ${describeExpected(resolvedExpected)}.\n` +
125
140
  `Received value: '${lastValue}'${lastObjName ? ` (Object: '${lastObjName}', Tags: [${lastObjTags.join(', ')}])` : ''}`
126
141
  };
127
142
  })();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.141",
3
+ "version": "1.0.143",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",