@specter-automation/test 1.0.138 → 1.0.140

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.
@@ -34,7 +34,9 @@ export declare enum SpecterEventType {
34
34
  AssertionFailure = "AssertionFailure",
35
35
  GameEvent = "GameEvent",
36
36
  GameplayTag = "GameplayTag",
37
- DiagnosticWarning = "DiagnosticWarning"
37
+ DiagnosticWarning = "DiagnosticWarning",
38
+ /** An AI's logic moved, a blackboard key changed, or its tree started or finished (the AI trail) */
39
+ AIState = "AIState"
38
40
  }
39
41
  export interface SpecterTimelineEvent {
40
42
  timestamp: number;
@@ -19,6 +19,8 @@ var SpecterEventType;
19
19
  SpecterEventType["GameEvent"] = "GameEvent";
20
20
  SpecterEventType["GameplayTag"] = "GameplayTag";
21
21
  SpecterEventType["DiagnosticWarning"] = "DiagnosticWarning";
22
+ /** An AI's logic moved, a blackboard key changed, or its tree started or finished (the AI trail) */
23
+ SpecterEventType["AIState"] = "AIState";
22
24
  })(SpecterEventType || (exports.SpecterEventType = SpecterEventType = {}));
23
25
  exports.VectorUtils = {
24
26
  addOffset: (location, direction, offset) => {
@@ -31,7 +31,7 @@ export type SpecterMatcherName = keyof GasMatchers | keyof ActorMatchers | keyof
31
31
  * Every Specter matcher. The compile-time check below fails the build if a
32
32
  * matcher is added to one of the matcher interfaces but not to this list.
33
33
  */
34
- export declare const SPECTER_MATCHER_NAMES: readonly ["toHaveAttributeValue", "toHaveAttributeChange", "toHaveGameplayTag", "toHaveGameplayEffect", "toHaveAppliedGameplayEffect", "toHaveGameplayAbility", "toHaveAbilityCooldown", "toHaveGameplayEffectStackCount", "toHaveGameplayEffectLevel", "toHaveAttributeBaseValue", "toBeExecutingAbility", "toHaveActivatedAbility", "toHaveGameplayTagCount", "toHaveAnyGameplayTags", "toHaveAllGameplayTags", "toHaveMovedFurtherThan", "toHaveLocation", "toHaveInputMappingContext", "toHaveInputActionValue", "toHavePlayerScore", "toBeNiagaraActive", "toHaveNiagaraAsset", "toBeAudioPlaying", "toHaveSoundAsset", "toBePhysicsSimulating", "toBePhysicsAsleep", "toHaveVelocity", "toHaveCameraFOV", "toBeCameraShaking", "toHaveCameraViewTarget", "toBeAINavigating", "toHaveTeamId", "toBeHostileTowards", "toBePossessed", "toBePlayerControlled", "toBeLocallyControlled", "toHaveController", "toBeFalling", "toBeSwimming", "toBeFlying", "toBeCrouching", "toBeMovingOnGround", "toHaveMovementMode", "toBeVisible", "toHavePropertyValue", "toBeInViewport", "toBeDestroyed", "toHaveCount", "toHaveText", "toHaveValue", "toContainText", "toBeEnabled", "toHaveMaterialScalarParameter", "toHaveMaterialVectorParameter", "toHaveMaterial", "toBeDynamicMaterial", "toHaveMaterialTextureParameter", "toHaveBlackboardValue", "toHaveAIState", "toBeMovingTowards", "toBeMovingAwayFrom", "toBeWithinDistance", "toBeFollowing", "toHaveLineOfSightTo", "toBeRunningBehaviorTree", "toBeInState", "toHaveFPS", "toHaveMinFPS", "toHaveFrameTimeBelow", "toHaveMemoryBelow", "toMaintainPerformanceBudget", "toHaveFrameTimeP95Below", "toHaveFrameTimeP99Below", "toHaveAverageFrameTimeBelow", "toHaveAverageFPSAbove", "toHaveOnePercentLowFPSAbove", "toHaveNoHitchesOver", "toHavePeakMemoryBelow", "toHaveMemoryGrowthBelow", "toHaveDrawCallsBelow"];
34
+ export declare const SPECTER_MATCHER_NAMES: readonly ["toHaveAttributeValue", "toHaveAttributeChange", "toHaveGameplayTag", "toHaveGameplayEffect", "toHaveAppliedGameplayEffect", "toHaveGameplayAbility", "toHaveAbilityCooldown", "toHaveGameplayEffectStackCount", "toHaveGameplayEffectLevel", "toHaveAttributeBaseValue", "toBeExecutingAbility", "toHaveActivatedAbility", "toHaveGameplayTagCount", "toHaveAnyGameplayTags", "toHaveAllGameplayTags", "toHaveMovedFurtherThan", "toHaveLocation", "toHaveInputMappingContext", "toHaveInputActionValue", "toHavePlayerScore", "toBeNiagaraActive", "toHaveNiagaraAsset", "toBeAudioPlaying", "toHaveSoundAsset", "toBePhysicsSimulating", "toBePhysicsAsleep", "toHaveVelocity", "toHaveCameraFOV", "toBeCameraShaking", "toHaveCameraViewTarget", "toBeAINavigating", "toHaveTeamId", "toBeHostileTowards", "toBePossessed", "toBePlayerControlled", "toBeLocallyControlled", "toHaveController", "toBeFalling", "toBeSwimming", "toBeFlying", "toBeCrouching", "toBeMovingOnGround", "toHaveMovementMode", "toBeVisible", "toHavePropertyValue", "toBeInViewport", "toBeDestroyed", "toHaveCount", "toHaveText", "toHaveValue", "toContainText", "toBeEnabled", "toHaveMaterialScalarParameter", "toHaveMaterialVectorParameter", "toHaveMaterial", "toBeDynamicMaterial", "toHaveMaterialTextureParameter", "toHaveBlackboardValue", "toHaveAIState", "toBeMovingTowards", "toBeMovingAwayFrom", "toBeWithinDistance", "toBeFollowing", "toHaveLineOfSightTo", "toBeRunningBehaviorTree", "toBeInState", "toHaveBlackboardChange", "toHaveVisitedState", "toHaveFPS", "toHaveMinFPS", "toHaveFrameTimeBelow", "toHaveMemoryBelow", "toMaintainPerformanceBudget", "toHaveFrameTimeP95Below", "toHaveFrameTimeP99Below", "toHaveAverageFrameTimeBelow", "toHaveAverageFPSAbove", "toHaveOnePercentLowFPSAbove", "toHaveNoHitchesOver", "toHavePeakMemoryBelow", "toHaveMemoryGrowthBelow", "toHaveDrawCallsBelow"];
35
35
  export declare function isSpecterMatcher(name: string): boolean;
36
36
  /**
37
37
  * Parses Playwright's expect step title, e.g. `Expect "soft not toHaveGameplayTag"`.
@@ -32,7 +32,7 @@ exports.SPECTER_MATCHER_NAMES = [
32
32
  'toBeDynamicMaterial', 'toHaveMaterialTextureParameter',
33
33
  // ai-matchers
34
34
  'toHaveBlackboardValue', 'toHaveAIState', 'toBeMovingTowards', 'toBeMovingAwayFrom',
35
- 'toBeWithinDistance', 'toBeFollowing', 'toHaveLineOfSightTo', 'toBeRunningBehaviorTree', 'toBeInState',
35
+ 'toBeWithinDistance', 'toBeFollowing', 'toHaveLineOfSightTo', 'toBeRunningBehaviorTree', 'toBeInState', 'toHaveBlackboardChange', 'toHaveVisitedState',
36
36
  // performance-matchers
37
37
  'toHaveFPS', 'toHaveMinFPS', 'toHaveFrameTimeBelow', 'toHaveMemoryBelow', 'toMaintainPerformanceBudget',
38
38
  'toHaveFrameTimeP95Below', 'toHaveFrameTimeP99Below', 'toHaveAverageFrameTimeBelow', 'toHaveAverageFPSAbove',
@@ -66,6 +66,23 @@ declare global {
66
66
  toBeInState(stateName: string, options?: {
67
67
  timeout?: number;
68
68
  }): T extends (ActorLocator | AiControllerLocator) ? Promise<R> : never;
69
+ /**
70
+ * A blackboard key changed during the test (from the AI trail, so a change that's already over still
71
+ * counts). `to` / `from`: the value it changed to or from: text (ignoring case), a RegExp, a number, a
72
+ * boolean, or an actor locator (its name).
73
+ */
74
+ toHaveBlackboardChange(keyName: string, options?: {
75
+ to?: any;
76
+ from?: any;
77
+ timeout?: number;
78
+ }): T extends (ActorLocator | AiControllerLocator) ? Promise<R> : never;
79
+ /**
80
+ * Its logic was in this state at some point of the test (from the AI trail): a StateTree state at any
81
+ * level, or a behavior tree node on the path to the running node. Names match whole and ignore case.
82
+ */
83
+ toHaveVisitedState(stateName: string, options?: {
84
+ timeout?: number;
85
+ }): T extends (ActorLocator | AiControllerLocator) ? Promise<R> : never;
69
86
  }
70
87
  }
71
88
  }
@@ -116,6 +133,14 @@ export interface AiMatchers {
116
133
  toBeInState(stateName: string, options?: {
117
134
  timeout?: number;
118
135
  }): Promise<void>;
136
+ toHaveBlackboardChange(keyName: string, options?: {
137
+ to?: any;
138
+ from?: any;
139
+ timeout?: number;
140
+ }): Promise<void>;
141
+ toHaveVisitedState(stateName: string, options?: {
142
+ timeout?: number;
143
+ }): Promise<void>;
119
144
  }
120
145
  export declare const aiExpect: import("playwright/test").Expect<{
121
146
  toHaveBlackboardValue(this: ExpectMatcherState, locator: any, keyName: string, expectedValue: any, options?: {
@@ -179,4 +204,18 @@ export declare const aiExpect: import("playwright/test").Expect<{
179
204
  pass: boolean;
180
205
  message: () => string;
181
206
  }>;
207
+ toHaveBlackboardChange(this: ExpectMatcherState, locator: any, keyName: string, options?: {
208
+ to?: any;
209
+ from?: any;
210
+ timeout?: number;
211
+ }): Promise<{
212
+ pass: boolean;
213
+ message: () => string;
214
+ }>;
215
+ toHaveVisitedState(this: ExpectMatcherState, locator: any, stateName: string, options?: {
216
+ timeout?: number;
217
+ }): Promise<{
218
+ pass: boolean;
219
+ message: () => string;
220
+ }>;
182
221
  }>;
@@ -15,12 +15,39 @@ function formatTarget(target) {
15
15
  }
16
16
  return JSON.stringify(target);
17
17
  }
18
+ /** What a blackboard value is expected to be, ready to compare with the trail's text: an actor locator becomes its name */
19
+ async function resolveExpectedValue(expected) {
20
+ if (expected && typeof expected === 'object' && !(expected instanceof RegExp) && typeof expected.getObjectName === 'function') {
21
+ try {
22
+ return await expected.getObjectName();
23
+ }
24
+ catch {
25
+ return String(expected);
26
+ }
27
+ }
28
+ return expected;
29
+ }
30
+ /** A value from the trail (DescribeKeyValue text) against what the test expects */
31
+ function trailValueMatches(value, expected) {
32
+ if (expected instanceof RegExp)
33
+ return expected.test(value);
34
+ if (typeof expected === 'number')
35
+ return Number(value) === expected;
36
+ if (typeof expected === 'boolean')
37
+ return (value.toLowerCase() === 'true' || value === '1') === expected;
38
+ return value.toLowerCase() === String(expected).toLowerCase();
39
+ }
40
+ function describeExpected(expected) {
41
+ return expected instanceof RegExp ? String(expected) : `'${expected}'`;
42
+ }
18
43
  /** The blackboard keys a matcher is about, shown first in its trail */
19
44
  function trailKeys(matcher, args) {
20
45
  if (matcher === 'toHaveBlackboardValue' && typeof args[0] === 'string')
21
46
  return [args[0]];
22
47
  if (matcher === 'toHaveAIState')
23
48
  return [args[1]?.keyName ?? 'AIState'];
49
+ if (matcher === 'toHaveBlackboardChange' && typeof args[0] === 'string')
50
+ return [args[0]];
24
51
  return [];
25
52
  }
26
53
  /**
@@ -319,5 +346,74 @@ exports.aiExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)(wit
319
346
  message: () => `Expected AI to ${isNot ? 'not ' : ''}be in state '${stateName}'.\n` +
320
347
  `${lastLogic === 'StateTree' ? 'Active states' : lastLogic === 'BehaviorTree' ? 'Running node path' : 'Logic'}: ${where}`
321
348
  };
349
+ },
350
+ async toHaveBlackboardChange(locator, keyName, options) {
351
+ const isNot = this.isNot;
352
+ const timeout = options?.timeout ?? 5000;
353
+ const startTime = Date.now();
354
+ const key = keyName.toLowerCase();
355
+ const to = options && 'to' in options ? await resolveExpectedValue(options.to) : undefined;
356
+ const from = options && 'from' in options ? await resolveExpectedValue(options.from) : undefined;
357
+ let seen = [];
358
+ let lastError = '';
359
+ while (true) {
360
+ try {
361
+ const trail = await locator.getBehaviorTrail({ limit: 400 });
362
+ seen = trail.events.flatMap((event) => event.kind === 'blackboard' && String(event.key).toLowerCase() === key ? [{ t: event.t, from: event.from, to: event.to }] : []);
363
+ lastError = '';
364
+ const matches = seen.some(change => (to === undefined || trailValueMatches(change.to, to)) && (from === undefined || trailValueMatches(change.from, from)));
365
+ if (isNot ? !matches : matches) {
366
+ return { pass: !isNot, message: () => 'passed' };
367
+ }
368
+ }
369
+ catch (e) {
370
+ lastError = e instanceof Error ? e.message : String(e);
371
+ }
372
+ if (Date.now() - startTime >= timeout)
373
+ break;
374
+ await new Promise(r => setTimeout(r, 100));
375
+ }
376
+ const wanted = `${from !== undefined ? ` from ${describeExpected(from)}` : ''}${to !== undefined ? ` to ${describeExpected(to)}` : ''}`;
377
+ const changes = seen.length
378
+ ? seen.map(change => `${change.t.toFixed(2)}s ${change.from} → ${change.to}`).join(', ')
379
+ : 'none';
380
+ return {
381
+ pass: isNot,
382
+ message: () => `Expected blackboard key '${keyName}' to ${isNot ? 'not ' : ''}change${wanted}.\n` +
383
+ (lastError ? lastError : `Its changes: ${changes}`)
384
+ };
385
+ },
386
+ async toHaveVisitedState(locator, stateName, options) {
387
+ const isNot = this.isNot;
388
+ const timeout = options?.timeout ?? 5000;
389
+ const startTime = Date.now();
390
+ const wanted = stateName.toLowerCase();
391
+ let visited = [];
392
+ let lastError = '';
393
+ while (true) {
394
+ try {
395
+ const trail = await locator.getBehaviorTrail({ limit: 400 });
396
+ const paths = trail.events.flatMap((event) => (event.kind === 'active' ? [event.path] : []));
397
+ if (trail.running)
398
+ paths.push(trail.activePath);
399
+ visited = [...new Set(paths.map(path => path.join(' › ')).filter(Boolean))];
400
+ lastError = '';
401
+ const matches = paths.some(path => path.some(step => step.toLowerCase() === wanted));
402
+ if (isNot ? !matches : matches) {
403
+ return { pass: !isNot, message: () => 'passed' };
404
+ }
405
+ }
406
+ catch (e) {
407
+ lastError = e instanceof Error ? e.message : String(e);
408
+ }
409
+ if (Date.now() - startTime >= timeout)
410
+ break;
411
+ await new Promise(r => setTimeout(r, 100));
412
+ }
413
+ return {
414
+ pass: isNot,
415
+ message: () => `Expected AI to ${isNot ? 'not ' : ''}have been in state '${stateName}' during the test.\n` +
416
+ (lastError ? lastError : `It was in: ${visited.length ? visited.join('; ') : 'nothing recorded'}`)
417
+ };
322
418
  }
323
419
  })));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.138",
3
+ "version": "1.0.140",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",