@specter-automation/test 1.0.135 → 1.0.137
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/locators/actor-locator.d.ts +9 -0
- package/dist/core/locators/actor-locator.js +12 -0
- package/dist/core/locators/ai-controller-locator.d.ts +9 -0
- package/dist/core/locators/ai-controller-locator.js +12 -0
- package/dist/core/specter-ai-trail.d.ts +85 -0
- package/dist/core/specter-ai-trail.js +99 -0
- package/dist/core/specter-client.js +1 -1
- package/dist/core/specter-matcher-report.d.ts +1 -1
- package/dist/core/specter-matcher-report.js +1 -1
- package/dist/core/specter-perf.d.ts +3 -2
- package/dist/core/specter-reporter.js +33 -11
- package/dist/index.d.ts +2 -0
- package/dist/index.js +4 -1
- package/dist/matchers/ai-matchers.d.ts +25 -8
- package/dist/matchers/ai-matchers.js +63 -2
- package/package.json +1 -1
|
@@ -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
|
+
}
|
|
@@ -1202,7 +1202,7 @@ class SpecterWorld {
|
|
|
1202
1202
|
const portTag = this.transport.friendlyPortTag;
|
|
1203
1203
|
const stepTitle = `${portTag}Measure performance: ${name}`;
|
|
1204
1204
|
return await test_1.default.step(stepTitle, async () => {
|
|
1205
|
-
await this.transport.sendCommand({ command: 'StartPerfCapture', payload: { name, hitchMs, timelinePreview: options.timelinePreview ??
|
|
1205
|
+
await this.transport.sendCommand({ command: 'StartPerfCapture', payload: { name, hitchMs, timelinePreview: options.timelinePreview ?? true } });
|
|
1206
1206
|
let failed = false;
|
|
1207
1207
|
let failure;
|
|
1208
1208
|
try {
|
|
@@ -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',
|
|
@@ -110,8 +110,9 @@ export interface MeasurePerformanceOptions {
|
|
|
110
110
|
/** Frames slower than this many milliseconds count as hitches. Default: 50. */
|
|
111
111
|
hitchMs?: number;
|
|
112
112
|
/**
|
|
113
|
-
* Keep recording the runner's timeline preview frames while measuring
|
|
114
|
-
*
|
|
113
|
+
* Keep recording the runner's timeline preview frames while measuring, so the timeline shows what happened during
|
|
114
|
+
* the measurement. Default: true (each preview frame costs a GPU readback and a small JPEG encode).
|
|
115
|
+
* Turn it off for the strictest numbers: the timeline then holds the last frame from before the measurement.
|
|
115
116
|
*/
|
|
116
117
|
timelinePreview?: boolean;
|
|
117
118
|
}
|
|
@@ -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
|
-
|
|
888
|
-
|
|
889
|
-
|
|
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/${
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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:
|
|
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
|
-
|
|
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
|
-
|
|
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
|
+
})));
|