@specter-automation/test 1.0.135 → 1.0.136

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.
@@ -7,6 +7,7 @@ import { UnrealKey } from "../specter-keys";
7
7
  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
+ import type { BehaviorTrail } from "../specter-ai-trail";
10
11
  export interface PossessAsPlayerOptions {
11
12
  world?: SpecterWorld | {
12
13
  world: SpecterWorld;
@@ -382,6 +383,14 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
382
383
  * Checks if this AI Actor / Controller is running a specific Behavior Tree asset.
383
384
  */
384
385
  isRunningBehaviorTree(treePath: string): Promise<boolean>;
386
+ /**
387
+ * What this AI did during the test: the node its behavior tree ran (or its StateTree's active states) and its
388
+ * blackboard, now and as recent changes.
389
+ * The AI matchers show it when they fail; `describeBehaviorTrail` turns it into lines.
390
+ */
391
+ getBehaviorTrail(options?: {
392
+ limit?: number;
393
+ }): Promise<BehaviorTrail>;
385
394
  /**
386
395
  * Evaluates spatial movement vector, speed, and direction relative to a target actor or coordinates.
387
396
  */
@@ -928,6 +928,18 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
928
928
  const response = await this.evaluate("IsRunningBehaviorTree", { treePath });
929
929
  return response.data?.isRunning ?? false;
930
930
  }
931
+ /**
932
+ * What this AI did during the test: the node its behavior tree ran (or its StateTree's active states) and its
933
+ * blackboard, now and as recent changes.
934
+ * The AI matchers show it when they fail; `describeBehaviorTrail` turns it into lines.
935
+ */
936
+ async getBehaviorTrail(options) {
937
+ const response = await this.evaluate("GetAITrail", { limit: options?.limit ?? 20 }, undefined, true);
938
+ if (response?.status === 'error' || !response?.data) {
939
+ throw new Error(response?.message || 'No AI trail: not an AI controller, a pawn one possesses, or an actor with a StateTree component.');
940
+ }
941
+ return response.data;
942
+ }
931
943
  /**
932
944
  * Evaluates spatial movement vector, speed, and direction relative to a target actor or coordinates.
933
945
  */
@@ -1,6 +1,15 @@
1
1
  import { SpecterLocator } from "../locators/specter-locator";
2
+ import type { BehaviorTrail } from "../specter-ai-trail";
2
3
  export declare class AiControllerLocator extends SpecterLocator {
3
4
  isRunningBehaviorTree(treePath: string): Promise<boolean>;
5
+ /**
6
+ * What this AI did during the test: the node its behavior tree ran (or its StateTree's active states) and its
7
+ * blackboard, now and as recent changes.
8
+ * The AI matchers show it when they fail; `describeBehaviorTrail` turns it into lines.
9
+ */
10
+ getBehaviorTrail(options?: {
11
+ limit?: number;
12
+ }): Promise<BehaviorTrail>;
4
13
  getBlackboardValue(keyName: string): Promise<{
5
14
  value: string;
6
15
  objectName?: string;
@@ -7,6 +7,18 @@ class AiControllerLocator extends specter_locator_1.SpecterLocator {
7
7
  const response = await this.evaluate("IsRunningBehaviorTree", { treePath });
8
8
  return response.data?.isRunning ?? false;
9
9
  }
10
+ /**
11
+ * What this AI did during the test: the node its behavior tree ran (or its StateTree's active states) and its
12
+ * blackboard, now and as recent changes.
13
+ * The AI matchers show it when they fail; `describeBehaviorTrail` turns it into lines.
14
+ */
15
+ async getBehaviorTrail(options) {
16
+ const response = await this.evaluate("GetAITrail", { limit: options?.limit ?? 20 }, undefined, true);
17
+ if (response?.status === 'error' || !response?.data) {
18
+ throw new Error(response?.message || 'No AI trail: not an AI controller, a pawn one possesses, or an actor with a StateTree component.');
19
+ }
20
+ return response.data;
21
+ }
10
22
  async getBlackboardValue(keyName) {
11
23
  const response = await this.evaluate("GetBlackboardValue", { keyName });
12
24
  return {
@@ -0,0 +1,85 @@
1
+ /**
2
+ * The AI trail: where an AI's logic was during the test (the node its behavior tree ran, or the states its StateTree
3
+ * had active) and how its blackboard changed. The plugin records it for every AI controller, and every actor with a
4
+ * StateTree component, from the test's start; the AI matchers show it when they fail, and
5
+ * `locator.getBehaviorTrail()` reads it.
6
+ */
7
+ /** One change in an AI's trail. Times are seconds since the test started. */
8
+ export type BehaviorTrailEvent =
9
+ /**
10
+ * The logic moved: a behavior tree to another node (`path` runs from the root to the running node), or a
11
+ * StateTree to other states (`path` lists the active states, root first). Empty: not running.
12
+ */
13
+ {
14
+ t: number;
15
+ kind: 'active';
16
+ path: string[];
17
+ from: string;
18
+ }
19
+ /** A blackboard key changed value */
20
+ | {
21
+ t: number;
22
+ kind: 'blackboard';
23
+ key: string;
24
+ from: string;
25
+ to: string;
26
+ }
27
+ /** The tree it runs changed (started, stopped, or swapped for another) */
28
+ | {
29
+ t: number;
30
+ kind: 'tree';
31
+ from: string;
32
+ to: string;
33
+ }
34
+ /** A StateTree's run status changed: Running, Succeeded, Failed, Stopped */
35
+ | {
36
+ t: number;
37
+ kind: 'status';
38
+ from: string;
39
+ to: string;
40
+ };
41
+ export interface BehaviorTrail {
42
+ /** The pawn's (or the StateTree actor's) name, and its AI controller's ('' for an actor running its own StateTree) */
43
+ actor: string;
44
+ controller: string;
45
+ /** What runs it */
46
+ logic: 'BehaviorTree' | 'StateTree' | '';
47
+ /** Seconds since the test started, when this was read */
48
+ now: number;
49
+ /** The behavior tree or StateTree asset ('' when none) */
50
+ tree: string;
51
+ running: boolean;
52
+ /** A StateTree's run status ('' for a behavior tree) */
53
+ status: string;
54
+ /** Root to the node running now, or the active states */
55
+ activePath: string[];
56
+ /** Every blackboard key's value now */
57
+ blackboard: Record<string, string>;
58
+ /** The most recent changes, oldest first */
59
+ events: BehaviorTrailEvent[];
60
+ /** Changes before `events` that weren't sent */
61
+ earlierEvents: number;
62
+ /** False when the plugin hadn't followed this AI (no test running): `events` is empty */
63
+ recorded: boolean;
64
+ }
65
+ export interface DescribeBehaviorTrailOptions {
66
+ /** Changes to show, the most recent. Default: 12. */
67
+ limit?: number;
68
+ /** Blackboard keys to show first; the rest follow while they fit. */
69
+ keys?: string[];
70
+ }
71
+ /** "Laning › Attack › Use Attack Ability", the last few named steps of a node path or a StateTree's active states */
72
+ export declare function describeNodePath(path: string[]): string;
73
+ /**
74
+ * The trail as lines for a failure message or a log:
75
+ *
76
+ * BP_Hero_Steel_C_0's behavior tree BT_Hero, its last 3 changes:
77
+ * 0.00s ▸ Laning › Find Next Waypoint
78
+ * 1.20s TargetActor: None → BP_Howitzer_C_1
79
+ * 1.21s ▸ Laning › Move To
80
+ * Now (4.80s): Laning › Move To
81
+ * Blackboard: AIState = Laning · TargetActor = BP_Howitzer_C_1
82
+ */
83
+ export declare function describeBehaviorTrail(trail: BehaviorTrail, options?: DescribeBehaviorTrailOptions): string;
84
+ /** The receiver's trail described, or '' when it has none (not an AI, gone, or the plugin predates trails) */
85
+ export declare function describeTrailOf(receiver: unknown, options?: DescribeBehaviorTrailOptions): Promise<string>;
@@ -0,0 +1,99 @@
1
+ "use strict";
2
+ /**
3
+ * The AI trail: where an AI's logic was during the test (the node its behavior tree ran, or the states its StateTree
4
+ * had active) and how its blackboard changed. The plugin records it for every AI controller, and every actor with a
5
+ * StateTree component, from the test's start; the AI matchers show it when they fail, and
6
+ * `locator.getBehaviorTrail()` reads it.
7
+ */
8
+ Object.defineProperty(exports, "__esModule", { value: true });
9
+ exports.describeNodePath = describeNodePath;
10
+ exports.describeBehaviorTrail = describeBehaviorTrail;
11
+ exports.describeTrailOf = describeTrailOf;
12
+ /** Composite nodes nobody named: they add nothing to "Laning › Move To" */
13
+ const UNNAMED_COMPOSITES = new Set(['Selector', 'Sequence', 'Simple Parallel', 'ROOT']);
14
+ const MAX_PATH_STEPS = 3;
15
+ const MAX_VALUE_LENGTH = 48;
16
+ const MAX_BLACKBOARD_KEYS = 8;
17
+ /** "Laning › Attack › Use Attack Ability", the last few named steps of a node path or a StateTree's active states */
18
+ function describeNodePath(path) {
19
+ if (!path || path.length === 0)
20
+ return '(not running)';
21
+ const named = path.filter((step, index) => index === path.length - 1 || !UNNAMED_COMPOSITES.has(step));
22
+ const shown = named.slice(-MAX_PATH_STEPS);
23
+ return (named.length > shown.length ? '… › ' : '') + shown.join(' › ');
24
+ }
25
+ function clip(value) {
26
+ const text = value === '' ? "''" : value;
27
+ return text.length > MAX_VALUE_LENGTH ? `${text.slice(0, MAX_VALUE_LENGTH - 1)}…` : text;
28
+ }
29
+ function time(seconds) {
30
+ return `${seconds.toFixed(2)}s`.padStart(8);
31
+ }
32
+ function describeEvent(event) {
33
+ switch (event.kind) {
34
+ case 'active':
35
+ return `▸ ${describeNodePath(event.path)}`;
36
+ case 'blackboard':
37
+ return `${event.key}: ${clip(event.from)} → ${clip(event.to)}`;
38
+ case 'tree':
39
+ if (!event.to)
40
+ return `Stopped running ${event.from}`;
41
+ if (!event.from)
42
+ return `Started running ${event.to}`;
43
+ return `Switched tree: ${event.from} → ${event.to}`;
44
+ case 'status':
45
+ return `StateTree ${event.from} → ${event.to}`;
46
+ }
47
+ }
48
+ /**
49
+ * The trail as lines for a failure message or a log:
50
+ *
51
+ * BP_Hero_Steel_C_0's behavior tree BT_Hero, its last 3 changes:
52
+ * 0.00s ▸ Laning › Find Next Waypoint
53
+ * 1.20s TargetActor: None → BP_Howitzer_C_1
54
+ * 1.21s ▸ Laning › Move To
55
+ * Now (4.80s): Laning › Move To
56
+ * Blackboard: AIState = Laning · TargetActor = BP_Howitzer_C_1
57
+ */
58
+ function describeBehaviorTrail(trail, options) {
59
+ const limit = options?.limit ?? 12;
60
+ const events = trail.events.slice(-limit);
61
+ const earlier = trail.earlierEvents + (trail.events.length - events.length);
62
+ const who = trail.actor || trail.controller;
63
+ const lines = [];
64
+ const logic = trail.logic === 'StateTree' ? 'StateTree' : trail.logic === 'BehaviorTree' ? 'behavior tree' : 'AI';
65
+ const changes = events.length ? `, its last ${events.length} change${events.length === 1 ? '' : 's'}:` : ':';
66
+ lines.push(`${who}'s ${logic}${trail.tree ? ` ${trail.tree}` : ''}${changes}`);
67
+ if (earlier > 0)
68
+ lines.push(` (${earlier} earlier change${earlier === 1 ? '' : 's'} not shown)`);
69
+ for (const event of events) {
70
+ lines.push(` ${time(event.t)} ${describeEvent(event)}`);
71
+ }
72
+ if (events.length === 0) {
73
+ lines.push(trail.recorded ? ' No changes since the test started.' : ' No changes recorded: the trail is recorded while a test runs.');
74
+ }
75
+ const stopped = trail.logic === 'StateTree' && trail.status && trail.status !== 'Running' ? `(StateTree ${trail.status.toLowerCase()})` : '(no tree running)';
76
+ lines.push(`Now (${trail.now.toFixed(2)}s): ${trail.running ? describeNodePath(trail.activePath) : stopped}`);
77
+ const keys = Object.keys(trail.blackboard ?? {}).filter(key => key !== 'SelfActor');
78
+ const first = (options?.keys ?? []).filter(key => keys.includes(key));
79
+ const ordered = [...first, ...keys.filter(key => !first.includes(key))];
80
+ if (ordered.length > 0) {
81
+ const shown = ordered.slice(0, Math.max(MAX_BLACKBOARD_KEYS, first.length));
82
+ const more = ordered.length - shown.length;
83
+ lines.push(`Blackboard: ${shown.map(key => `${key} = ${clip(trail.blackboard[key])}`).join(' · ')}${more > 0 ? ` · (${more} more)` : ''}`);
84
+ }
85
+ return lines.join('\n');
86
+ }
87
+ /** The receiver's trail described, or '' when it has none (not an AI, gone, or the plugin predates trails) */
88
+ async function describeTrailOf(receiver, options) {
89
+ const locator = receiver;
90
+ if (!locator || typeof locator.getBehaviorTrail !== 'function')
91
+ return '';
92
+ try {
93
+ const trail = await locator.getBehaviorTrail({ limit: options?.limit ?? 12 });
94
+ return trail ? describeBehaviorTrail(trail, options) : '';
95
+ }
96
+ catch {
97
+ return '';
98
+ }
99
+ }
@@ -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", "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", "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',
35
+ 'toBeWithinDistance', 'toBeFollowing', 'toHaveLineOfSightTo', 'toBeRunningBehaviorTree', 'toBeInState',
36
36
  // performance-matchers
37
37
  'toHaveFPS', 'toHaveMinFPS', 'toHaveFrameTimeBelow', 'toHaveMemoryBelow', 'toMaintainPerformanceBudget',
38
38
  'toHaveFrameTimeP95Below', 'toHaveFrameTimeP99Below', 'toHaveAverageFrameTimeBelow', 'toHaveAverageFPSAbove',
@@ -75,6 +75,32 @@ function extractLocatorFromExpectTitle(title) {
75
75
  * Pulls the locator out of a Specter matcher step title:
76
76
  * `[Server] toHaveGameplayTag('Status.Stunned') @ enemies[0] (getByTag('Spawned_c36e0554'))`
77
77
  */
78
+ /**
79
+ * A test's timeline preview frames: f_0001240.jpg = 1.240 s into the test. A multiplayer test keeps each game
80
+ * view's frames in a folder named after it (Server, Client 1, ...). Frames still being written have another
81
+ * extension. Returns [file, path inside the frames folder] pairs; none when the folder isn't on this machine.
82
+ */
83
+ function listFrames(frameDir) {
84
+ const isFrame = (name) => /^f_\d+\.jpg$/.test(name);
85
+ const frames = [];
86
+ try {
87
+ for (const item of fs.readdirSync(frameDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
88
+ if (item.isFile() && isFrame(item.name)) {
89
+ frames.push([path.join(frameDir, item.name), item.name]);
90
+ }
91
+ else if (item.isDirectory()) {
92
+ const viewDir = path.join(frameDir, item.name);
93
+ for (const name of fs.readdirSync(viewDir).filter(isFrame).sort()) {
94
+ frames.push([path.join(viewDir, name), `${item.name}/${name}`]);
95
+ }
96
+ }
97
+ }
98
+ }
99
+ catch {
100
+ // Not on this machine (the game runs elsewhere): the trace goes without preview frames
101
+ }
102
+ return frames;
103
+ }
78
104
  function extractLocatorFromMatcherTitle(title) {
79
105
  const afterArgs = title.indexOf(') @ ');
80
106
  if (afterArgs !== -1) {
@@ -733,6 +759,7 @@ class SpecterReporter {
733
759
  // tests/001_<name>/trace.json one test: the same content as a single-test trace
734
760
  // tests/001_<name>/screenshots/*.png its images
735
761
  // tests/001_<name>/frames/f_*.jpg small frames of the game view, for the timeline's hover preview
762
+ // (multiplayer: frames/Server/f_*.jpg, frames/Client 1/f_*.jpg, ...)
736
763
  // replay/<name>.replay the engine's replay of the run, when it recorded one
737
764
  //
738
765
  // Tests are staged on disk as they finish, so a long run doesn't sit in memory, and the archive is
@@ -878,21 +905,16 @@ class SpecterReporter {
878
905
  if (this.runFrameFolders.size > 0) {
879
906
  await sleep(250);
880
907
  }
908
+ // Each test's frames, as [file on disk, path inside the test's frames folder]
881
909
  const frameFiles = new Map();
882
910
  for (const entry of this.runTests.values()) {
883
911
  const frameDir = this.runFrameFolders.get(entry.testName) ?? this.runFrameFolders.get(entry.testName.replace(/\\/g, '/'));
884
912
  if (!frameDir) {
885
913
  continue;
886
914
  }
887
- try {
888
- // f_0001240.jpg = 1.240 s into the test. Frames still being written have another extension.
889
- const names = fs.readdirSync(frameDir).filter(name => /^f_\d+\.jpg$/.test(name)).sort();
890
- if (names.length > 0) {
891
- frameFiles.set(entry.testName, names.map(name => path.join(frameDir, name)));
892
- }
893
- }
894
- catch {
895
- // Not on this machine (the game runs elsewhere): the trace goes without preview frames
915
+ const frames = listFrames(frameDir);
916
+ if (frames.length > 0) {
917
+ frameFiles.set(entry.testName, frames);
896
918
  }
897
919
  }
898
920
  // A plain zip holds 65,535 files. A very large run keeps every Nth frame instead of failing.
@@ -943,9 +965,9 @@ class SpecterReporter {
943
965
  zip.addFile(`${entry.folder}/screenshots/${image}`, fs.readFileSync(path.join(imageDir, image)), { store: true });
944
966
  }
945
967
  }
946
- for (const frame of frameFiles.get(entry.testName) ?? []) {
968
+ for (const [frame, inFrames] of frameFiles.get(entry.testName) ?? []) {
947
969
  try {
948
- zip.addFile(`${entry.folder}/frames/${path.basename(frame)}`, fs.readFileSync(frame), { store: true });
970
+ zip.addFile(`${entry.folder}/frames/${inFrames}`, fs.readFileSync(frame), { store: true });
949
971
  }
950
972
  catch { }
951
973
  }
package/dist/index.d.ts CHANGED
@@ -8,6 +8,8 @@ export { SPECTER_MATCHER_ATTACHMENT } from './core/specter-matcher-report';
8
8
  export type { SpecterMatcherReport } from './core/specter-matcher-report';
9
9
  export { SPECTER_PERF_ATTACHMENT, describeHitch, describeHitches, summarizeCapture } from './core/specter-perf';
10
10
  export type { PerformanceCapture, PerformanceHitch, PerformanceStat, MeasurePerformanceOptions } from './core/specter-perf';
11
+ export { describeBehaviorTrail, describeNodePath } from './core/specter-ai-trail';
12
+ export type { BehaviorTrail, BehaviorTrailEvent, DescribeBehaviorTrailOptions } from './core/specter-ai-trail';
11
13
  export type { UnrealKey } from './core/specter-keys';
12
14
  export type { SpecterActorEvents, SpecterWidgetEvents, SpecterWorldEvents, CustomActorEvents, CustomWidgetEvents, CustomWorldEvents, ActorEventMap, WidgetEventMap, WorldEventMap, EventPredicate, WaitForEventOptions } from './core/events';
13
15
  export { SpecterInputSequence } from './core/specter-input-sequence';
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.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.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; } });
@@ -27,6 +27,9 @@ Object.defineProperty(exports, "SPECTER_PERF_ATTACHMENT", { enumerable: true, ge
27
27
  Object.defineProperty(exports, "describeHitch", { enumerable: true, get: function () { return specter_perf_1.describeHitch; } });
28
28
  Object.defineProperty(exports, "describeHitches", { enumerable: true, get: function () { return specter_perf_1.describeHitches; } });
29
29
  Object.defineProperty(exports, "summarizeCapture", { enumerable: true, get: function () { return specter_perf_1.summarizeCapture; } });
30
+ var specter_ai_trail_1 = require("./core/specter-ai-trail");
31
+ Object.defineProperty(exports, "describeBehaviorTrail", { enumerable: true, get: function () { return specter_ai_trail_1.describeBehaviorTrail; } });
32
+ Object.defineProperty(exports, "describeNodePath", { enumerable: true, get: function () { return specter_ai_trail_1.describeNodePath; } });
30
33
  var specter_input_sequence_1 = require("./core/specter-input-sequence");
31
34
  Object.defineProperty(exports, "SpecterInputSequence", { enumerable: true, get: function () { return specter_input_sequence_1.SpecterInputSequence; } });
32
35
  var specter_network_1 = require("./core/specter-network");
@@ -1,4 +1,5 @@
1
1
  import { ActorLocator, AiControllerLocator } from '../core/locators';
2
+ import type { ExpectMatcherState } from '@playwright/test';
2
3
  export interface MovementDirectionInfo {
3
4
  distance: number;
4
5
  distance2D: number;
@@ -58,6 +59,13 @@ declare global {
58
59
  toBeRunningBehaviorTree(treePath: string, options?: {
59
60
  timeout?: number;
60
61
  }): T extends (ActorLocator | AiControllerLocator) ? Promise<R> : never;
62
+ /**
63
+ * Its logic is in this state: a StateTree state that's active (any level, so a parent state counts too) or
64
+ * a behavior tree node on the path to the running node. Names match whole and ignore case.
65
+ */
66
+ toBeInState(stateName: string, options?: {
67
+ timeout?: number;
68
+ }): T extends (ActorLocator | AiControllerLocator) ? Promise<R> : never;
61
69
  }
62
70
  }
63
71
  }
@@ -105,22 +113,25 @@ export interface AiMatchers {
105
113
  toBeRunningBehaviorTree(treePath: string, options?: {
106
114
  timeout?: number;
107
115
  }): Promise<void>;
116
+ toBeInState(stateName: string, options?: {
117
+ timeout?: number;
118
+ }): Promise<void>;
108
119
  }
109
120
  export declare const aiExpect: import("playwright/test").Expect<{
110
- toHaveBlackboardValue(this: import("playwright/test").ExpectMatcherState, locator: any, keyName: string, expectedValue: any, options?: {
121
+ toHaveBlackboardValue(this: ExpectMatcherState, locator: any, keyName: string, expectedValue: any, options?: {
111
122
  timeout?: number;
112
123
  }): Promise<{
113
124
  pass: boolean;
114
125
  message: () => string;
115
126
  }>;
116
- toHaveAIState(this: import("playwright/test").ExpectMatcherState, locator: any, expectedState: string, options?: {
127
+ toHaveAIState(this: ExpectMatcherState, locator: any, expectedState: string, options?: {
117
128
  timeout?: number;
118
129
  keyName?: string;
119
130
  }): Promise<{
120
131
  pass: boolean;
121
132
  message: () => string;
122
133
  }>;
123
- toBeMovingTowards(this: import("playwright/test").ExpectMatcherState, locator: any, target: any, options?: {
134
+ toBeMovingTowards(this: ExpectMatcherState, locator: any, target: any, options?: {
124
135
  timeout?: number;
125
136
  minSpeed?: number;
126
137
  threshold?: number;
@@ -128,7 +139,7 @@ export declare const aiExpect: import("playwright/test").Expect<{
128
139
  pass: boolean;
129
140
  message: () => string;
130
141
  }>;
131
- toBeMovingAwayFrom(this: import("playwright/test").ExpectMatcherState, locator: any, target: any, options?: {
142
+ toBeMovingAwayFrom(this: ExpectMatcherState, locator: any, target: any, options?: {
132
143
  timeout?: number;
133
144
  minSpeed?: number;
134
145
  threshold?: number;
@@ -136,27 +147,33 @@ export declare const aiExpect: import("playwright/test").Expect<{
136
147
  pass: boolean;
137
148
  message: () => string;
138
149
  }>;
139
- toBeWithinDistance(this: import("playwright/test").ExpectMatcherState, locator: any, target: any, distance: number, options?: {
150
+ toBeWithinDistance(this: ExpectMatcherState, locator: any, target: any, distance: number, options?: {
140
151
  timeout?: number;
141
152
  planar?: boolean;
142
153
  }): Promise<{
143
154
  pass: boolean;
144
155
  message: () => string;
145
156
  }>;
146
- toBeFollowing(this: import("playwright/test").ExpectMatcherState, locator: any, target: any, options?: {
157
+ toBeFollowing(this: ExpectMatcherState, locator: any, target: any, options?: {
147
158
  timeout?: number;
148
159
  maxDistance?: number;
149
160
  }): Promise<{
150
161
  pass: boolean;
151
162
  message: () => string;
152
163
  }>;
153
- toHaveLineOfSightTo(this: import("playwright/test").ExpectMatcherState, locator: any, target: any, options?: {
164
+ toHaveLineOfSightTo(this: ExpectMatcherState, locator: any, target: any, options?: {
165
+ timeout?: number;
166
+ }): Promise<{
167
+ pass: boolean;
168
+ message: () => string;
169
+ }>;
170
+ toBeRunningBehaviorTree(this: ExpectMatcherState, locator: any, treePath: string, options?: {
154
171
  timeout?: number;
155
172
  }): Promise<{
156
173
  pass: boolean;
157
174
  message: () => string;
158
175
  }>;
159
- toBeRunningBehaviorTree(this: import("playwright/test").ExpectMatcherState, locator: any, treePath: string, options?: {
176
+ toBeInState(this: ExpectMatcherState, locator: any, stateName: string, options?: {
160
177
  timeout?: number;
161
178
  }): Promise<{
162
179
  pass: boolean;
@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.aiExpect = void 0;
4
4
  const test_1 = require("@playwright/test");
5
5
  const instrument_1 = require("./instrument");
6
+ const specter_ai_trail_1 = require("../core/specter-ai-trail");
6
7
  function formatTarget(target) {
7
8
  if (typeof target === 'string')
8
9
  return `'${target}'`;
@@ -14,7 +15,36 @@ function formatTarget(target) {
14
15
  }
15
16
  return JSON.stringify(target);
16
17
  }
17
- exports.aiExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
18
+ /** The blackboard keys a matcher is about, shown first in its trail */
19
+ function trailKeys(matcher, args) {
20
+ if (matcher === 'toHaveBlackboardValue' && typeof args[0] === 'string')
21
+ return [args[0]];
22
+ if (matcher === 'toHaveAIState')
23
+ return [args[1]?.keyName ?? 'AIState'];
24
+ return [];
25
+ }
26
+ /**
27
+ * A failing AI matcher says what the AI did instead: its behavior tree's recent nodes and blackboard changes (the
28
+ * AI trail the plugin records), after the matcher's own message.
29
+ */
30
+ function withAITrail(matchers) {
31
+ const wrapped = {};
32
+ for (const [name, matcher] of Object.entries(matchers)) {
33
+ wrapped[name] = async function (receiver, ...args) {
34
+ const result = await matcher.call(this, receiver, ...args);
35
+ const failed = this.isNot ? result.pass : !result.pass;
36
+ if (!failed)
37
+ return result;
38
+ const trail = await (0, specter_ai_trail_1.describeTrailOf)(receiver, { keys: trailKeys(name, args) });
39
+ if (!trail)
40
+ return result;
41
+ const message = result.message;
42
+ return { ...result, message: () => `${message()}\n\n${trail}` };
43
+ };
44
+ }
45
+ return wrapped;
46
+ }
47
+ exports.aiExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)(withAITrail({
18
48
  async toHaveBlackboardValue(locator, keyName, expectedValue, options) {
19
49
  const isNot = this.isNot;
20
50
  const timeout = options?.timeout ?? 5000;
@@ -258,5 +288,36 @@ exports.aiExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
258
288
  message: () => `Expected AI to ${isNot ? 'not ' : ''}be running BehaviorTree '${treePath}', but isRunning was ${lastRunning}.`
259
289
  };
260
290
  })();
291
+ },
292
+ async toBeInState(locator, stateName, options) {
293
+ const isNot = this.isNot;
294
+ const timeout = options?.timeout ?? 5000;
295
+ const startTime = Date.now();
296
+ const wanted = stateName.toLowerCase();
297
+ let lastPath = [];
298
+ let lastLogic = '';
299
+ let lastError = '';
300
+ while (Date.now() - startTime < timeout) {
301
+ try {
302
+ const trail = await locator.getBehaviorTrail({ limit: 1 });
303
+ lastPath = trail.running ? trail.activePath : [];
304
+ lastLogic = trail.logic;
305
+ lastError = '';
306
+ const matches = lastPath.some((step) => step.toLowerCase() === wanted);
307
+ if (isNot ? !matches : matches) {
308
+ return { pass: !isNot, message: () => 'passed' };
309
+ }
310
+ }
311
+ catch (e) {
312
+ lastError = e instanceof Error ? e.message : String(e);
313
+ }
314
+ await new Promise(r => setTimeout(r, 100));
315
+ }
316
+ const where = lastError ? lastError : lastPath.length ? lastPath.join(' › ') : '(no tree running)';
317
+ return {
318
+ pass: isNot,
319
+ message: () => `Expected AI to ${isNot ? 'not ' : ''}be in state '${stateName}'.\n` +
320
+ `${lastLogic === 'StateTree' ? 'Active states' : lastLogic === 'BehaviorTree' ? 'Running node path' : 'Logic'}: ${where}`
321
+ };
261
322
  }
262
- }));
323
+ })));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.135",
3
+ "version": "1.0.136",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",