@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.
- package/dist/core/specter-client.d.ts +5 -0
- package/dist/core/specter-client.js +4 -0
- package/dist/core/specter-preview.d.ts +55 -0
- package/dist/core/specter-preview.js +63 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +3 -1
- package/dist/matchers/ai-matchers.js +42 -27
- package/package.json +1 -1
|
@@ -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
|
-
|
|
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
|
|
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
|
})();
|