@specter-automation/test 1.0.149 → 1.0.151

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.
@@ -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.SpecterWorld = exports.SpecterTransport = exports.VectorUtils = exports.SpecterEventType = void 0;
6
+ exports.SpecterWorld = exports.SpecterTransport = exports.deltaRotator = exports.normalizeRotator = exports.calculateDistance2D = exports.calculateDistance = exports.getRotationBetween = exports.findLookAtRotation = exports.normalizeAxis = exports.resolveRotator = exports.resolveVector3 = exports.RotatorUtils = exports.VectorUtils = exports.SpecterEventType = void 0;
7
7
  const ws_1 = __importDefault(require("ws"));
8
8
  const crypto_1 = __importDefault(require("crypto"));
9
9
  const locators_1 = require("./locators");
@@ -23,44 +23,18 @@ var SpecterEventType;
23
23
  /** An AI's logic moved, a blackboard key changed, or its tree started or finished (the AI trail) */
24
24
  SpecterEventType["AIState"] = "AIState";
25
25
  })(SpecterEventType || (exports.SpecterEventType = SpecterEventType = {}));
26
- /**
27
- * Vector maths for the plain `{ x, y, z }` objects Specter returns (TypeScript has no operator overloading,
28
- * so `a + b` on two vectors won't work). Every function returns a new vector and leaves its inputs alone.
29
- *
30
- * @example
31
- * const { add, distance2D } = VectorUtils;
32
- * await boss.setLocation(add(home, { x: 2100, y: 0, z: 0 }));
33
- * expect(distance2D(await hero.getLocation(), start)).toBeLessThan(40);
34
- */
35
- exports.VectorUtils = {
36
- /** `a + b` */
37
- add: (a, b) => ({ x: a.x + b.x, y: a.y + b.y, z: a.z + b.z }),
38
- /** `a - b`: the vector from `b` to `a` */
39
- sub: (a, b) => ({ x: a.x - b.x, y: a.y - b.y, z: a.z - b.z }),
40
- /** `v * scalar` */
41
- scale: (v, scalar) => ({ x: v.x * scalar, y: v.y * scalar, z: v.z * scalar }),
42
- /** Length of `v` */
43
- length: (v) => Math.hypot(v.x, v.y, v.z),
44
- /** `v` scaled to length 1; a zero vector stays zero */
45
- normalize: (v) => {
46
- const len = Math.hypot(v.x, v.y, v.z);
47
- return len === 0 ? { x: 0, y: 0, z: 0 } : { x: v.x / len, y: v.y / len, z: v.z / len };
48
- },
49
- /** Dot product of `a` and `b` */
50
- dot: (a, b) => a.x * b.x + a.y * b.y + a.z * b.z,
51
- /** Distance between `a` and `b` */
52
- distance: (a, b) => Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z),
53
- /** Distance between `a` and `b` on the ground (x and y only), so height doesn't count */
54
- distance2D: (a, b) => Math.hypot(a.x - b.x, a.y - b.y),
55
- /** `location + direction * offset`: a point `offset` units along `direction` from `location` */
56
- addOffset: (location, direction, offset) => {
57
- return {
58
- x: location.x + (direction.x * offset),
59
- y: location.y + (direction.y * offset),
60
- z: location.z + (direction.z * offset)
61
- };
62
- }
63
- };
26
+ var specter_math_1 = require("./specter-math");
27
+ Object.defineProperty(exports, "VectorUtils", { enumerable: true, get: function () { return specter_math_1.VectorUtils; } });
28
+ Object.defineProperty(exports, "RotatorUtils", { enumerable: true, get: function () { return specter_math_1.RotatorUtils; } });
29
+ Object.defineProperty(exports, "resolveVector3", { enumerable: true, get: function () { return specter_math_1.resolveVector3; } });
30
+ Object.defineProperty(exports, "resolveRotator", { enumerable: true, get: function () { return specter_math_1.resolveRotator; } });
31
+ Object.defineProperty(exports, "normalizeAxis", { enumerable: true, get: function () { return specter_math_1.normalizeAxis; } });
32
+ Object.defineProperty(exports, "findLookAtRotation", { enumerable: true, get: function () { return specter_math_1.findLookAtRotation; } });
33
+ Object.defineProperty(exports, "getRotationBetween", { enumerable: true, get: function () { return specter_math_1.getRotationBetween; } });
34
+ Object.defineProperty(exports, "calculateDistance", { enumerable: true, get: function () { return specter_math_1.calculateDistance; } });
35
+ Object.defineProperty(exports, "calculateDistance2D", { enumerable: true, get: function () { return specter_math_1.calculateDistance2D; } });
36
+ Object.defineProperty(exports, "normalizeRotator", { enumerable: true, get: function () { return specter_math_1.normalizeRotator; } });
37
+ Object.defineProperty(exports, "deltaRotator", { enumerable: true, get: function () { return specter_math_1.deltaRotator; } });
64
38
  // ==========================================
65
39
  // THE TRANSPORT LAYER (Hidden from End-User)
66
40
  // ==========================================
@@ -458,6 +432,30 @@ class SpecterWorld {
458
432
  // Inject the connected transport into the new world
459
433
  return new SpecterWorld(transport);
460
434
  }
435
+ /**
436
+ * The engine's warnings and errors (the output log's yellow and red lines) since the last test's cleanup:
437
+ * spawn failures, navigation, Blueprint and ability system complaints. Specter's own are left out; a line logged
438
+ * again is counted (`count`). A failing test's diagnostics report shows them too.
439
+ */
440
+ async getEngineLog(options) {
441
+ const res = await this.evaluate("GetEngineLog", { max: options?.max ?? 100 });
442
+ return (res?.data ?? { entries: [], dropped: 0 });
443
+ }
444
+ /**
445
+ * Where the test's actors (what it spawned, and the pawns spawned while it ran) were and how they were doing, four
446
+ * times a second: location, yaw, speed, health, their AI's path following. Times are seconds since the test
447
+ * started, the timeline's clock. `at`: just the sample nearest that time. `actor`: only actors whose name has it.
448
+ * The history is also written next to the test's timeline preview frames when it ends (state.json).
449
+ */
450
+ async getStateHistory(options) {
451
+ const res = await this.evaluate("GetStateHistory", {
452
+ from: options?.from ?? -1,
453
+ to: options?.to ?? -1,
454
+ at: options?.at ?? -1,
455
+ actor: options?.actor ?? '',
456
+ });
457
+ return (res?.data ?? { interval: 0.25, classes: {} });
458
+ }
461
459
  /**
462
460
  * Queries comprehensive runtime diagnostics from the engine, including
463
461
  * actor identity mapping, attribute/tag snapshots, spatial relations, and recent Flight Recorder events.
@@ -580,7 +578,15 @@ class SpecterWorld {
580
578
  this.transport.sendCommand({
581
579
  command: 'ListenForGlobalEvent',
582
580
  payload: { eventName: String(eventName) }
583
- }).catch(() => { });
581
+ }).catch((error) => {
582
+ // A plugin from before ListenForGlobalEvent still broadcasts MapLoaded and timeline events: keep waiting
583
+ const message = error instanceof Error ? error.message : String(error);
584
+ if (/Unknown command/i.test(message))
585
+ return;
586
+ clearTimeout(timer);
587
+ this.transport.removeEventListener(eventKey, listener);
588
+ reject(new Error(`Specter: can't wait for world event [${String(eventName)}]: ${message}`));
589
+ });
584
590
  });
585
591
  }
586
592
  async joinHost(ipAddress, expectedMap) {
@@ -717,8 +723,16 @@ class SpecterWorld {
717
723
  // Generate a unique tag if the user didn't provide one
718
724
  const uniqueId = crypto_1.default.randomBytes(4).toString('hex');
719
725
  const tag = options?.tag || `Spawned_${uniqueId}`;
720
- const location = options?.location || { x: 0, y: 0, z: 0 };
721
- const rotation = options?.rotation || { pitch: 0, yaw: 0, roll: 0 };
726
+ const location = {
727
+ x: options?.location?.x ?? 0,
728
+ y: options?.location?.y ?? 0,
729
+ z: options?.location?.z ?? 0
730
+ };
731
+ const rotation = {
732
+ pitch: options?.rotation?.pitch ?? 0,
733
+ yaw: options?.rotation?.yaw ?? 0,
734
+ roll: options?.rotation?.roll ?? 0
735
+ };
722
736
  const assetPath = String(classNameOrAssetPath);
723
737
  const assetName = assetPath.split('/').pop()?.split('.')[0];
724
738
  const properties = options?.properties;
@@ -1024,11 +1038,12 @@ class SpecterWorld {
1024
1038
  });
1025
1039
  }
1026
1040
  /**
1027
- * Opens a level (absolute travel) via UGameplayStatics::OpenLevel
1041
+ * Opens a level via UGameplayStatics::OpenLevel (relative travel in Play-In-Editor, so the editor world is safe).
1042
+ * @param options URL options, e.g. "?game=/Game/Modes/BP_Arena.BP_Arena_C"
1028
1043
  */
1029
1044
  async loadLevel(levelName, options = "") {
1030
1045
  await test_1.default.step(`Specter: Load Level [${levelName}]`, async () => {
1031
- await this.evaluate("OpenLevel", { levelName, options });
1046
+ await this.evaluate("LoadLevel", { levelName, options });
1032
1047
  });
1033
1048
  }
1034
1049
  /**
@@ -0,0 +1,145 @@
1
+ /**
2
+ * Results of Specter's debugging commands: what's in the way of a line, why an AI doesn't see something, the navmesh
3
+ * path to a place, what overlaps what, collision settings, the engine's warnings during a test, and the state history
4
+ * of the test's actors.
5
+ */
6
+ /** "Block", "Overlap" or "Ignore" */
7
+ export type CollisionResponse = 'Block' | 'Overlap' | 'Ignore';
8
+ /** A collision component's settings */
9
+ export interface CollisionDescription {
10
+ component: string;
11
+ componentClass: string;
12
+ actor?: string;
13
+ /** The collision profile ("Custom" when set by hand) */
14
+ profile: string;
15
+ collisionEnabled: 'NoCollision' | 'QueryOnly' | 'PhysicsOnly' | 'QueryAndPhysics' | 'Other';
16
+ /** The channel it is as an object ("Pawn", "WorldDynamic", a project channel) */
17
+ objectType: string;
18
+ generatesOverlapEvents: boolean;
19
+ canEverAffectNavigation: boolean;
20
+ /** Its response to each channel the project names (or only the channel asked about) */
21
+ responses: Record<string, CollisionResponse>;
22
+ }
23
+ /** A line traced on a collision channel */
24
+ export interface TraceResult {
25
+ channel: string;
26
+ /** Nothing in the way (or the first thing in the way is the target) */
27
+ clear: boolean;
28
+ from: [number, number, number];
29
+ to: [number, number, number];
30
+ distance: number;
31
+ /** One line: "Clear on Visibility." or what blocked it and its collision settings */
32
+ summary: string;
33
+ /** The first thing in the way, when not clear */
34
+ blockedBy?: CollisionDescription & {
35
+ actorClass?: string;
36
+ location: [number, number, number];
37
+ distance: number;
38
+ };
39
+ }
40
+ /** Whether an AI sees another actor, and why not */
41
+ export interface PerceptionResult {
42
+ ai: string;
43
+ target: string;
44
+ perceived: boolean;
45
+ /** "Perceived by sight.", "Out of range: ...", "Outside its view: ...", "Something's in the way: ...", ... */
46
+ reason: string;
47
+ distance: number;
48
+ /** Degrees between where it faces and the target */
49
+ angle: number;
50
+ attitude: 'Friendly' | 'Neutral' | 'Hostile' | '?';
51
+ sightRadius?: number;
52
+ loseSightRadius?: number;
53
+ peripheralVisionAngle?: number;
54
+ /** The last time sight sensed the target */
55
+ lastSight?: {
56
+ ageSeconds: number;
57
+ sensed: boolean;
58
+ };
59
+ /** The line AI sight traces (on the AI System's sight channel) */
60
+ trace: TraceResult;
61
+ }
62
+ /** The navmesh path to a goal */
63
+ export interface NavPathResult {
64
+ start: [number, number, number];
65
+ goal: [number, number, number];
66
+ startOnNavMesh: boolean;
67
+ goalOnNavMesh: boolean;
68
+ found: boolean;
69
+ /** The path stops short of the goal */
70
+ partial?: boolean;
71
+ length?: number;
72
+ end?: [number, number, number];
73
+ endToGoal?: number;
74
+ points?: [number, number, number][];
75
+ /** Its AI's path following now */
76
+ aiMove?: {
77
+ status: 'Idle' | 'Waiting' | 'Paused' | 'Moving';
78
+ destination?: [number, number, number];
79
+ speed: number;
80
+ };
81
+ summary: string;
82
+ }
83
+ export interface OverlapResult {
84
+ /** The actors overlapping */
85
+ actors: string[];
86
+ overlaps: {
87
+ component: string;
88
+ actor: string;
89
+ actorClass: string;
90
+ otherComponent: string;
91
+ }[];
92
+ }
93
+ /** One line of the engine's warnings and errors */
94
+ export interface EngineLogEntry {
95
+ /** Seconds after the last test's cleanup (real time) */
96
+ seconds: number;
97
+ verbosity: 'Warning' | 'Error';
98
+ category: string;
99
+ message: string;
100
+ /** Times it was logged */
101
+ count: number;
102
+ }
103
+ export interface EngineLog {
104
+ entries: EngineLogEntry[];
105
+ /** Different lines not kept, the buffer being full */
106
+ dropped: number;
107
+ }
108
+ /** One actor in a state sample */
109
+ export interface ActorStateSample {
110
+ at: [number, number, number];
111
+ yaw: number;
112
+ speed: number;
113
+ health?: number;
114
+ maxHealth?: number;
115
+ /** Its AI's path following: Idle, Waiting, Paused, Moving */
116
+ move?: string;
117
+ moveGoal?: [number, number];
118
+ gone?: boolean;
119
+ }
120
+ export interface StateSample {
121
+ /** Seconds since the test started (the timeline's clock) */
122
+ t: number;
123
+ actors: Record<string, ActorStateSample>;
124
+ }
125
+ /** Where the test's actors were and how they were doing, a few times a second */
126
+ export interface StateHistory {
127
+ /** Seconds between samples */
128
+ interval: number;
129
+ /** Each actor's class */
130
+ classes: Record<string, string>;
131
+ samples?: StateSample[];
132
+ /** With `at`: the sample nearest that time */
133
+ sample?: StateSample;
134
+ }
135
+ /** An AI that stood still while its path following said it was moving */
136
+ export interface StuckAI {
137
+ actor: string;
138
+ since: number;
139
+ seconds: number;
140
+ location: [number, number];
141
+ goal: [number, number];
142
+ stillStuck: boolean;
143
+ }
144
+ /** The diagnostics report's lines about the engine's warnings and stuck AIs */
145
+ export declare function formatDebugDiagnostics(diagnostics: any): string[];
@@ -0,0 +1,35 @@
1
+ "use strict";
2
+ /**
3
+ * Results of Specter's debugging commands: what's in the way of a line, why an AI doesn't see something, the navmesh
4
+ * path to a place, what overlaps what, collision settings, the engine's warnings during a test, and the state history
5
+ * of the test's actors.
6
+ */
7
+ Object.defineProperty(exports, "__esModule", { value: true });
8
+ exports.formatDebugDiagnostics = formatDebugDiagnostics;
9
+ /** The diagnostics report's lines about the engine's warnings and stuck AIs */
10
+ function formatDebugDiagnostics(diagnostics) {
11
+ const lines = [];
12
+ const stuck = diagnostics?.stuckAI ?? [];
13
+ if (stuck.length > 0) {
14
+ lines.push('🚧 AI that stood still while moving:');
15
+ for (const entry of stuck) {
16
+ lines.push(` • ${entry.actor}: moving to (${entry.goal[0]}, ${entry.goal[1]}) but at (${entry.location[0]}, ${entry.location[1]}) for ${Number(entry.seconds).toFixed(1)}s from ${Number(entry.since).toFixed(1)}s${entry.stillStuck ? ', still' : ''}`);
17
+ }
18
+ lines.push('');
19
+ }
20
+ const log = diagnostics?.engineLog ?? [];
21
+ if (log.length > 0) {
22
+ lines.push('⚠️ Engine warnings and errors since the last test (most recent last):');
23
+ for (const entry of log.slice(-15)) {
24
+ lines.push(` [${Number(entry.seconds).toFixed(1)}s] ${entry.verbosity} ${entry.category}: ${entry.message}${entry.count > 1 ? ` (×${entry.count})` : ''}`);
25
+ }
26
+ if (log.length > 15) {
27
+ lines.push(` … ${log.length - 15} earlier`);
28
+ }
29
+ if (diagnostics?.engineLogDropped) {
30
+ lines.push(` … ${diagnostics.engineLogDropped} more not kept`);
31
+ }
32
+ lines.push('');
33
+ }
34
+ return lines;
35
+ }
@@ -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", "toHaveBlackboardChange", "toHaveVisitedState", "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", "toHaveRotation", "toBeFacing", "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"`.
@@ -17,7 +17,7 @@ exports.SPECTER_MATCHER_NAMES = [
17
17
  'toBeExecutingAbility', 'toHaveActivatedAbility', 'toHaveGameplayTagCount',
18
18
  'toHaveAnyGameplayTags', 'toHaveAllGameplayTags',
19
19
  // actor-matchers
20
- 'toHaveMovedFurtherThan', 'toHaveLocation', 'toHaveInputMappingContext', 'toHaveInputActionValue',
20
+ 'toHaveMovedFurtherThan', 'toHaveLocation', 'toHaveRotation', 'toBeFacing', 'toHaveInputMappingContext', 'toHaveInputActionValue',
21
21
  'toHavePlayerScore', 'toBeNiagaraActive', 'toHaveNiagaraAsset', 'toBeAudioPlaying', 'toHaveSoundAsset',
22
22
  'toBePhysicsSimulating', 'toBePhysicsAsleep', 'toHaveVelocity', 'toHaveCameraFOV', 'toBeCameraShaking',
23
23
  'toHaveCameraViewTarget', 'toBeAINavigating', 'toHaveTeamId', 'toBeHostileTowards', 'toBePossessed',