@specter-automation/test 1.0.140 → 1.0.142

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
  }
@@ -195,6 +196,8 @@ export interface SpawnOptions {
195
196
  location?: Vector3;
196
197
  rotation?: Rotator;
197
198
  properties?: Record<string, any>;
199
+ /** Pawns only. Default true: the pawn gets its controller (its AI). False spawns it with none, even when its class
200
+ * would possess it with AI on spawn: it stands where it's put, e.g. a target dummy. Needs the Specter plugin from 2026-10-15. */
198
201
  spawnController?: boolean;
199
202
  name?: string;
200
203
  /** If true, the actor will not be destroyed by ClearAllSpawned between tests. */
@@ -279,6 +282,8 @@ export declare class SpecterWorld {
279
282
  private transport;
280
283
  readonly keyboard: SpecterKeyboard;
281
284
  readonly network: SpecterNetwork;
285
+ /** What the runner's timeline preview shows while this test runs (follow actors, a place, the player's view) */
286
+ readonly preview: SpecterPreview;
282
287
  timeDilation: number;
283
288
  constructor(transport: SpecterTransport);
284
289
  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';
@@ -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; } });
@@ -17,6 +17,9 @@ function formatTarget(target) {
17
17
  }
18
18
  /** What a blackboard value is expected to be, ready to compare with the trail's text: an actor locator becomes its name */
19
19
  async function resolveExpectedValue(expected) {
20
+ if (Array.isArray(expected)) {
21
+ return Promise.all(expected.map(e => resolveExpectedValue(e)));
22
+ }
20
23
  if (expected && typeof expected === 'object' && !(expected instanceof RegExp) && typeof expected.getObjectName === 'function') {
21
24
  try {
22
25
  return await expected.getObjectName();
@@ -29,6 +32,9 @@ async function resolveExpectedValue(expected) {
29
32
  }
30
33
  /** A value from the trail (DescribeKeyValue text) against what the test expects */
31
34
  function trailValueMatches(value, expected) {
35
+ if (Array.isArray(expected)) {
36
+ return expected.some(singleExp => trailValueMatches(value, singleExp));
37
+ }
32
38
  if (expected instanceof RegExp)
33
39
  return expected.test(value);
34
40
  if (typeof expected === 'number')
@@ -38,6 +44,9 @@ function trailValueMatches(value, expected) {
38
44
  return value.toLowerCase() === String(expected).toLowerCase();
39
45
  }
40
46
  function describeExpected(expected) {
47
+ if (Array.isArray(expected)) {
48
+ return `[${expected.map(describeExpected).join(', ')}]`;
49
+ }
41
50
  return expected instanceof RegExp ? String(expected) : `'${expected}'`;
42
51
  }
43
52
  /** The blackboard keys a matcher is about, shown first in its trail */
@@ -76,42 +85,48 @@ exports.aiExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)(wit
76
85
  const isNot = this.isNot;
77
86
  const timeout = options?.timeout ?? 5000;
78
87
  const startTime = Date.now();
88
+ const resolvedExpected = await resolveExpectedValue(expectedValue);
79
89
  return await (async () => {
80
90
  let lastValue = null;
81
91
  let lastObjName = undefined;
82
92
  let lastObjTags = [];
93
+ const checkMatch = (exp) => {
94
+ if (Array.isArray(exp)) {
95
+ return exp.some(singleExp => checkMatch(singleExp));
96
+ }
97
+ if (exp instanceof RegExp) {
98
+ return exp.test(lastValue) || (lastObjName ? exp.test(lastObjName) : false);
99
+ }
100
+ else if (typeof exp === 'string') {
101
+ const expLower = exp.toLowerCase();
102
+ return (lastValue ?? '').toLowerCase() === expLower ||
103
+ (lastObjName ?? '').toLowerCase() === expLower ||
104
+ lastObjTags.some((t) => t.toLowerCase() === expLower);
105
+ }
106
+ else if (typeof exp === 'number') {
107
+ return Number(lastValue) === exp;
108
+ }
109
+ else if (typeof exp === 'boolean') {
110
+ const valLower = String(lastValue).toLowerCase();
111
+ const boolVal = valLower === 'true' || valLower === '1';
112
+ return boolVal === exp;
113
+ }
114
+ else if (exp && typeof exp === 'object') {
115
+ const expStr = exp.toString ? exp.toString().toLowerCase() : '';
116
+ return (lastObjName ?? '').toLowerCase().includes(expStr) ||
117
+ lastObjTags.some((t) => expStr.includes(t.toLowerCase()));
118
+ }
119
+ else {
120
+ return lastValue === exp;
121
+ }
122
+ };
83
123
  while (Date.now() - startTime < timeout) {
84
124
  try {
85
125
  const info = await locator.getBlackboardValue(keyName);
86
126
  lastValue = info.value;
87
127
  lastObjName = info.objectName;
88
128
  lastObjTags = info.objectTags ?? [];
89
- let matches = false;
90
- if (expectedValue instanceof RegExp) {
91
- matches = expectedValue.test(lastValue) || (lastObjName ? expectedValue.test(lastObjName) : false);
92
- }
93
- else if (typeof expectedValue === 'string') {
94
- const expLower = expectedValue.toLowerCase();
95
- matches = (lastValue ?? '').toLowerCase() === expLower ||
96
- (lastObjName ?? '').toLowerCase() === expLower ||
97
- lastObjTags.some((t) => t.toLowerCase() === expLower);
98
- }
99
- else if (typeof expectedValue === 'number') {
100
- matches = Number(lastValue) === expectedValue;
101
- }
102
- else if (typeof expectedValue === 'boolean') {
103
- const valLower = String(lastValue).toLowerCase();
104
- const boolVal = valLower === 'true' || valLower === '1';
105
- matches = boolVal === expectedValue;
106
- }
107
- else if (expectedValue && typeof expectedValue === 'object') {
108
- const expStr = expectedValue.toString ? expectedValue.toString().toLowerCase() : '';
109
- matches = (lastObjName ?? '').toLowerCase().includes(expStr) ||
110
- lastObjTags.some((t) => expStr.includes(t.toLowerCase()));
111
- }
112
- else {
113
- matches = lastValue === expectedValue;
114
- }
129
+ const matches = checkMatch(resolvedExpected);
115
130
  if (isNot ? !matches : matches) {
116
131
  return { pass: !isNot, message: () => 'passed' };
117
132
  }
@@ -121,7 +136,7 @@ exports.aiExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)(wit
121
136
  }
122
137
  return {
123
138
  pass: isNot,
124
- message: () => `Expected Blackboard key '${keyName}' to ${isNot ? 'not ' : ''}match '${expectedValue}'.\n` +
139
+ message: () => `Expected Blackboard key '${keyName}' to ${isNot ? 'not ' : ''}match ${describeExpected(resolvedExpected)}.\n` +
125
140
  `Received value: '${lastValue}'${lastObjName ? ` (Object: '${lastObjName}', Tags: [${lastObjTags.join(', ')}])` : ''}`
126
141
  };
127
142
  })();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.140",
3
+ "version": "1.0.142",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",