@specter-automation/test 1.0.139 → 1.0.141

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.
@@ -5,6 +5,7 @@ import { SpecterKeyboard } from './specter-keyboard';
5
5
  import { UnrealKey } from './specter-keys';
6
6
  import { SpecterInputSequence } from './specter-input-sequence';
7
7
  import { SpecterNetwork } from './specter-network';
8
+ import { SpecterPreview } from './specter-preview';
8
9
  import { type MeasurePerformanceOptions, type PerformanceCapture } from './specter-perf';
9
10
  export interface SpecterRegistry {
10
11
  }
@@ -279,6 +280,8 @@ export declare class SpecterWorld {
279
280
  private transport;
280
281
  readonly keyboard: SpecterKeyboard;
281
282
  readonly network: SpecterNetwork;
283
+ /** What the runner's timeline preview shows while this test runs (follow actors, a place, the player's view) */
284
+ readonly preview: SpecterPreview;
282
285
  timeDilation: number;
283
286
  constructor(transport: SpecterTransport);
284
287
  toString(): string;
@@ -10,6 +10,7 @@ const locators_1 = require("./locators");
10
10
  const test_1 = __importDefault(require("@playwright/test"));
11
11
  const specter_keyboard_1 = require("./specter-keyboard");
12
12
  const specter_network_1 = require("./specter-network");
13
+ const specter_preview_1 = require("./specter-preview");
13
14
  const specter_perf_1 = require("./specter-perf");
14
15
  var SpecterEventType;
15
16
  (function (SpecterEventType) {
@@ -403,11 +404,14 @@ class SpecterWorld {
403
404
  transport;
404
405
  keyboard;
405
406
  network;
407
+ /** What the runner's timeline preview shows while this test runs (follow actors, a place, the player's view) */
408
+ preview;
406
409
  timeDilation = 1.0;
407
410
  constructor(transport) {
408
411
  this.transport = transport;
409
412
  this.keyboard = new specter_keyboard_1.SpecterKeyboard(this);
410
413
  this.network = new specter_network_1.SpecterNetwork(this);
414
+ this.preview = new specter_preview_1.SpecterPreview(this);
411
415
  }
412
416
  toString() {
413
417
  return 'world';
@@ -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',
@@ -0,0 +1,55 @@
1
+ import type { SpecterWorld, Vector3 } from './specter-client';
2
+ import type { SpecterLocator } from './locators';
3
+ /** What the timeline preview shows after a `world.preview` call */
4
+ export interface TimelinePreviewState {
5
+ /** False when the preview isn't recording here (off in the Specter settings, or no game view): the call changed nothing */
6
+ recording: boolean;
7
+ /** "auto", "follow: BP_Boss_C_0, BP_Hero_C_1", "at (0, 2800, 90), radius 1500" or "player" */
8
+ mode: string;
9
+ note?: string;
10
+ }
11
+ /**
12
+ * What the runner's timeline preview shows while this test runs: the little pictures you scrub along the timeline.
13
+ *
14
+ * By default it follows the action: cameras of its own look at what the test spawns, aims commands at, and the AIs
15
+ * whose behavior changes, with a view for each place the action is (up to four, side by side or in a 2x2 grid).
16
+ * A test that knows better can say what matters. The choice lasts until the test ends; every test starts on `auto()`.
17
+ *
18
+ * ```ts
19
+ * // A boss fight: keep the boss and the hero in view, wherever they go
20
+ * await world.preview.follow([boss, hero]);
21
+ *
22
+ * // Watch a doorway, whoever comes through it
23
+ * await world.preview.at({ x: 1200, y: -300, z: 0 }, { radius: 800 });
24
+ *
25
+ * // What the player sees (a first-person test, a menu)
26
+ * await world.preview.player();
27
+ * ```
28
+ *
29
+ * Steering the preview never fails a test because previews are off: it then returns `{ recording: false }`.
30
+ */
31
+ export declare class SpecterPreview {
32
+ private world;
33
+ constructor(world: SpecterWorld);
34
+ /**
35
+ * Shows only these actors (a pawn, its AI controller or one of its components all mean the actor). Those close
36
+ * together share a view; far apart, each gets its own. An actor that's destroyed drops out; when none are left,
37
+ * the preview goes back to `auto()`.
38
+ *
39
+ * @param options.add Adds to the actors already followed instead of replacing them.
40
+ */
41
+ follow(actors: SpecterLocator | SpecterLocator[], options?: {
42
+ add?: boolean;
43
+ }): Promise<TimelinePreviewState>;
44
+ /**
45
+ * Shows a fixed place: a sphere of `radius` (default 1500) around `location`, from above at an angle.
46
+ */
47
+ at(location: Vector3, options?: {
48
+ radius?: number;
49
+ }): Promise<TimelinePreviewState>;
50
+ /** Shows the player's view, as the game draws it. */
51
+ player(): Promise<TimelinePreviewState>;
52
+ /** Back to following the action (or the player's view, when that's off in the Specter settings). */
53
+ auto(): Promise<TimelinePreviewState>;
54
+ private send;
55
+ }
@@ -0,0 +1,63 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.SpecterPreview = void 0;
4
+ /**
5
+ * What the runner's timeline preview shows while this test runs: the little pictures you scrub along the timeline.
6
+ *
7
+ * By default it follows the action: cameras of its own look at what the test spawns, aims commands at, and the AIs
8
+ * whose behavior changes, with a view for each place the action is (up to four, side by side or in a 2x2 grid).
9
+ * A test that knows better can say what matters. The choice lasts until the test ends; every test starts on `auto()`.
10
+ *
11
+ * ```ts
12
+ * // A boss fight: keep the boss and the hero in view, wherever they go
13
+ * await world.preview.follow([boss, hero]);
14
+ *
15
+ * // Watch a doorway, whoever comes through it
16
+ * await world.preview.at({ x: 1200, y: -300, z: 0 }, { radius: 800 });
17
+ *
18
+ * // What the player sees (a first-person test, a menu)
19
+ * await world.preview.player();
20
+ * ```
21
+ *
22
+ * Steering the preview never fails a test because previews are off: it then returns `{ recording: false }`.
23
+ */
24
+ class SpecterPreview {
25
+ world;
26
+ constructor(world) {
27
+ this.world = world;
28
+ }
29
+ /**
30
+ * Shows only these actors (a pawn, its AI controller or one of its components all mean the actor). Those close
31
+ * together share a view; far apart, each gets its own. An actor that's destroyed drops out; when none are left,
32
+ * the preview goes back to `auto()`.
33
+ *
34
+ * @param options.add Adds to the actors already followed instead of replacing them.
35
+ */
36
+ async follow(actors, options) {
37
+ const list = Array.isArray(actors) ? actors : [actors];
38
+ if (list.length === 0) {
39
+ throw new Error('world.preview.follow needs at least one actor. To go back to following the action, use world.preview.auto().');
40
+ }
41
+ const names = list.map(actor => actor.toString()).join(', ');
42
+ return this.send({ mode: 'follow', targets: list.map(actor => actor.pipeline), add: options?.add ?? false }, `${options?.add ? 'also follow' : 'follow'} ${names}`);
43
+ }
44
+ /**
45
+ * Shows a fixed place: a sphere of `radius` (default 1500) around `location`, from above at an angle.
46
+ */
47
+ async at(location, options) {
48
+ return this.send({ mode: 'at', location, radius: options?.radius ?? 0 }, `at (${Math.round(location.x)}, ${Math.round(location.y)}, ${Math.round(location.z)})`);
49
+ }
50
+ /** Shows the player's view, as the game draws it. */
51
+ async player() {
52
+ return this.send({ mode: 'player' }, 'player view');
53
+ }
54
+ /** Back to following the action (or the player's view, when that's off in the Specter settings). */
55
+ async auto() {
56
+ return this.send({ mode: 'auto' }, 'auto');
57
+ }
58
+ async send(payload, context) {
59
+ const response = await this.world.evaluate('SetTimelinePreview', payload, context);
60
+ return (response?.data ?? { recording: false, mode: String(payload.mode) });
61
+ }
62
+ }
63
+ exports.SpecterPreview = SpecterPreview;
package/dist/index.d.ts CHANGED
@@ -14,6 +14,8 @@ export type { UnrealKey } from './core/specter-keys';
14
14
  export type { SpecterActorEvents, SpecterWidgetEvents, SpecterWorldEvents, CustomActorEvents, CustomWidgetEvents, CustomWorldEvents, ActorEventMap, WidgetEventMap, WorldEventMap, EventPredicate, WaitForEventOptions } from './core/events';
15
15
  export { SpecterInputSequence } from './core/specter-input-sequence';
16
16
  export { SpecterNetwork } from './core/specter-network';
17
+ export { SpecterPreview } from './core/specter-preview';
18
+ export type { TimelinePreviewState } from './core/specter-preview';
17
19
  export type { LocationCondition, DistanceCondition, PropertyCondition, AttributeCondition, SpecterCondition, ConditionFunction, InputConditionalOptions } from './core/conditions/input-conditions';
18
20
  export { evaluateCondition, runConditionalInputLoop } from './core/conditions/input-conditions';
19
21
  export type { MaterialOptions, MaterialScalarOptions, MaterialVectorOptions, ColorInput, MaterialMatchers } from './matchers/material-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.visualExpect = exports.performanceExpect = exports.aiExpect = exports.materialExpect = exports.runConditionalInputLoop = exports.evaluateCondition = exports.SpecterNetwork = exports.SpecterInputSequence = exports.describeNodePath = exports.describeBehaviorTrail = exports.summarizeCapture = exports.describeHitches = exports.describeHitch = exports.SPECTER_PERF_ATTACHMENT = exports.SPECTER_MATCHER_ATTACHMENT = exports.expectAll = exports.SpecterReporter = exports.AiControllerLocator = exports.ActorLocator = exports.WidgetLocator = exports.SpecterLocator = exports.VectorUtils = exports.SpecterWorld = exports.SpecterTransport = exports.expect = exports.test = void 0;
6
+ exports.visualExpect = exports.performanceExpect = exports.aiExpect = exports.materialExpect = exports.runConditionalInputLoop = exports.evaluateCondition = exports.SpecterPreview = exports.SpecterNetwork = exports.SpecterInputSequence = exports.describeNodePath = exports.describeBehaviorTrail = exports.summarizeCapture = exports.describeHitches = exports.describeHitch = exports.SPECTER_PERF_ATTACHMENT = exports.SPECTER_MATCHER_ATTACHMENT = exports.expectAll = 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; } });
@@ -34,6 +34,8 @@ var specter_input_sequence_1 = require("./core/specter-input-sequence");
34
34
  Object.defineProperty(exports, "SpecterInputSequence", { enumerable: true, get: function () { return specter_input_sequence_1.SpecterInputSequence; } });
35
35
  var specter_network_1 = require("./core/specter-network");
36
36
  Object.defineProperty(exports, "SpecterNetwork", { enumerable: true, get: function () { return specter_network_1.SpecterNetwork; } });
37
+ var specter_preview_1 = require("./core/specter-preview");
38
+ Object.defineProperty(exports, "SpecterPreview", { enumerable: true, get: function () { return specter_preview_1.SpecterPreview; } });
37
39
  var input_conditions_1 = require("./core/conditions/input-conditions");
38
40
  Object.defineProperty(exports, "evaluateCondition", { enumerable: true, get: function () { return input_conditions_1.evaluateCondition; } });
39
41
  Object.defineProperty(exports, "runConditionalInputLoop", { enumerable: true, get: function () { return input_conditions_1.runConditionalInputLoop; } });
@@ -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.139",
3
+ "version": "1.0.141",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",