@specter-automation/test 1.0.109 → 1.0.110
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 +8 -0
- package/dist/core/locators/actor-locator.js +22 -0
- package/dist/core/specter-client.d.ts +71 -0
- package/dist/core/specter-client.js +27 -1
- package/dist/core/test-wrapper.js +23 -0
- package/dist/matchers/gas-matchers.d.ts +1 -0
- package/dist/matchers/gas-matchers.js +102 -2
- package/package.json +1 -1
|
@@ -425,4 +425,12 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
|
|
|
425
425
|
* and optional accessible name.
|
|
426
426
|
*/
|
|
427
427
|
getByRole(role: WidgetRole | string, options?: WidgetRoleOptions): WidgetLocator;
|
|
428
|
+
/**
|
|
429
|
+
* Fetches comprehensive AI diagnostics for this actor (and an optional instigator),
|
|
430
|
+
* including attribute snapshot, active gameplay tags, effects, identity, and flight recorder events.
|
|
431
|
+
*/
|
|
432
|
+
getDiagnostics(options?: {
|
|
433
|
+
instigator?: ActorLocator | SpecterLocator;
|
|
434
|
+
limit?: number;
|
|
435
|
+
}): Promise<any>;
|
|
428
436
|
}
|
|
@@ -851,6 +851,14 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
|
|
|
851
851
|
let payload = { abilityTag };
|
|
852
852
|
if (target instanceof specter_locator_1.SpecterLocator) {
|
|
853
853
|
payload.targetLocatorPipeline = target.pipeline;
|
|
854
|
+
if (typeof target.getLocation === 'function') {
|
|
855
|
+
try {
|
|
856
|
+
payload.targetLocation = await target.getLocation();
|
|
857
|
+
}
|
|
858
|
+
catch {
|
|
859
|
+
// Fallback to server-side pipeline resolution if getLocation fails
|
|
860
|
+
}
|
|
861
|
+
}
|
|
854
862
|
}
|
|
855
863
|
else {
|
|
856
864
|
payload.targetLocation = target;
|
|
@@ -1051,5 +1059,19 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
|
|
|
1051
1059
|
{ action: 'getWidgetByRole', value: rolePayload, exact: options?.exact }
|
|
1052
1060
|
]);
|
|
1053
1061
|
}
|
|
1062
|
+
/**
|
|
1063
|
+
* Fetches comprehensive AI diagnostics for this actor (and an optional instigator),
|
|
1064
|
+
* including attribute snapshot, active gameplay tags, effects, identity, and flight recorder events.
|
|
1065
|
+
*/
|
|
1066
|
+
async getDiagnostics(options) {
|
|
1067
|
+
const payload = {
|
|
1068
|
+
limit: options?.limit ?? 30,
|
|
1069
|
+
targetLocatorPipeline: this.pipeline
|
|
1070
|
+
};
|
|
1071
|
+
if (options?.instigator) {
|
|
1072
|
+
payload.instigatorLocatorPipeline = options.instigator.pipeline;
|
|
1073
|
+
}
|
|
1074
|
+
return await this.transport.sendCommand("GetActorDiagnostics", this.pipeline, payload);
|
|
1075
|
+
}
|
|
1054
1076
|
}
|
|
1055
1077
|
exports.ActorLocator = ActorLocator;
|
|
@@ -42,6 +42,60 @@ export interface SpecterTimelineEvent {
|
|
|
42
42
|
effectCauser?: string;
|
|
43
43
|
gameplayEffect?: string;
|
|
44
44
|
ability?: string;
|
|
45
|
+
target?: string;
|
|
46
|
+
}
|
|
47
|
+
export interface SpecterActiveEffect {
|
|
48
|
+
name: string;
|
|
49
|
+
duration: number;
|
|
50
|
+
remainingTime: number;
|
|
51
|
+
stackCount: number;
|
|
52
|
+
instigator?: string;
|
|
53
|
+
}
|
|
54
|
+
export interface SpecterActorSnapshot {
|
|
55
|
+
name: string;
|
|
56
|
+
class: string;
|
|
57
|
+
tags: string[];
|
|
58
|
+
location: Vector3;
|
|
59
|
+
rotation: Rotator;
|
|
60
|
+
forward: Vector3;
|
|
61
|
+
velocity: Vector3;
|
|
62
|
+
teamId?: number;
|
|
63
|
+
asc?: string;
|
|
64
|
+
ascOwner?: string;
|
|
65
|
+
attributes?: Record<string, number>;
|
|
66
|
+
gameplayTags?: string[];
|
|
67
|
+
activeEffects?: SpecterActiveEffect[];
|
|
68
|
+
}
|
|
69
|
+
export interface SpecterDiagnosticsReport {
|
|
70
|
+
target?: SpecterActorSnapshot;
|
|
71
|
+
instigator?: SpecterActorSnapshot;
|
|
72
|
+
distance?: number;
|
|
73
|
+
relativeDirection?: string;
|
|
74
|
+
facingDotProduct?: number;
|
|
75
|
+
actorMap?: Record<string, {
|
|
76
|
+
name: string;
|
|
77
|
+
class: string;
|
|
78
|
+
asc?: string;
|
|
79
|
+
ascOwner?: string;
|
|
80
|
+
}>;
|
|
81
|
+
flightRecorder?: Array<{
|
|
82
|
+
timestamp: number;
|
|
83
|
+
eventName: string;
|
|
84
|
+
description: string;
|
|
85
|
+
eventType: string;
|
|
86
|
+
oldValue?: string;
|
|
87
|
+
newValue?: string;
|
|
88
|
+
instigator?: string;
|
|
89
|
+
effectCauser?: string;
|
|
90
|
+
gameplayEffect?: string;
|
|
91
|
+
ability?: string;
|
|
92
|
+
target?: string;
|
|
93
|
+
}>;
|
|
94
|
+
engine?: {
|
|
95
|
+
map: string;
|
|
96
|
+
worldTime: number;
|
|
97
|
+
deltaSeconds: number;
|
|
98
|
+
};
|
|
45
99
|
}
|
|
46
100
|
export interface Vector3 {
|
|
47
101
|
x: number;
|
|
@@ -146,6 +200,23 @@ export declare class SpecterWorld {
|
|
|
146
200
|
readonly network: SpecterNetwork;
|
|
147
201
|
constructor(transport: SpecterTransport);
|
|
148
202
|
static connect(url?: string): Promise<SpecterWorld>;
|
|
203
|
+
/**
|
|
204
|
+
* Queries comprehensive runtime diagnostics from the engine, including
|
|
205
|
+
* actor identity mapping, attribute/tag snapshots, spatial relations, and recent Flight Recorder events.
|
|
206
|
+
*/
|
|
207
|
+
getDiagnostics(options?: {
|
|
208
|
+
target?: SpecterLocator | ActorLocator;
|
|
209
|
+
instigator?: SpecterLocator | ActorLocator;
|
|
210
|
+
limit?: number;
|
|
211
|
+
}): Promise<SpecterDiagnosticsReport>;
|
|
212
|
+
/**
|
|
213
|
+
* Commands Unreal Engine to safely reload or load a game module (e.g. "Hots") using FModuleManager.
|
|
214
|
+
*/
|
|
215
|
+
reloadModule(moduleName: string): Promise<{
|
|
216
|
+
success: boolean;
|
|
217
|
+
message: string;
|
|
218
|
+
wasLoaded: boolean;
|
|
219
|
+
}>;
|
|
149
220
|
/**
|
|
150
221
|
* Waits for the given `timeout` in milliseconds.
|
|
151
222
|
* Matches Playwright's `page.waitForTimeout()` method.
|
|
@@ -284,6 +284,30 @@ class SpecterWorld {
|
|
|
284
284
|
// Inject the connected transport into the new world
|
|
285
285
|
return new SpecterWorld(transport);
|
|
286
286
|
}
|
|
287
|
+
/**
|
|
288
|
+
* Queries comprehensive runtime diagnostics from the engine, including
|
|
289
|
+
* actor identity mapping, attribute/tag snapshots, spatial relations, and recent Flight Recorder events.
|
|
290
|
+
*/
|
|
291
|
+
async getDiagnostics(options) {
|
|
292
|
+
const payload = {
|
|
293
|
+
limit: options?.limit ?? 30
|
|
294
|
+
};
|
|
295
|
+
if (options?.target) {
|
|
296
|
+
payload.targetLocatorPipeline = options.target.pipeline;
|
|
297
|
+
}
|
|
298
|
+
if (options?.instigator) {
|
|
299
|
+
payload.instigatorLocatorPipeline = options.instigator.pipeline;
|
|
300
|
+
}
|
|
301
|
+
const res = await this.evaluate("GetActorDiagnostics", payload);
|
|
302
|
+
return res;
|
|
303
|
+
}
|
|
304
|
+
/**
|
|
305
|
+
* Commands Unreal Engine to safely reload or load a game module (e.g. "Hots") using FModuleManager.
|
|
306
|
+
*/
|
|
307
|
+
async reloadModule(moduleName) {
|
|
308
|
+
const res = await this.evaluate("ReloadModule", { module: moduleName });
|
|
309
|
+
return res;
|
|
310
|
+
}
|
|
287
311
|
/**
|
|
288
312
|
* Waits for the given `timeout` in milliseconds.
|
|
289
313
|
* Matches Playwright's `page.waitForTimeout()` method.
|
|
@@ -471,7 +495,9 @@ class SpecterWorld {
|
|
|
471
495
|
const location = options?.location || { x: 0, y: 0, z: 0 };
|
|
472
496
|
const rotation = options?.rotation || { pitch: 0, yaw: 0, roll: 0 };
|
|
473
497
|
const assetName = assetPath.split('/').pop()?.split('.')[0];
|
|
474
|
-
|
|
498
|
+
const properties = options?.properties;
|
|
499
|
+
const spawnController = options?.spawnController;
|
|
500
|
+
await this.evaluate("SpawnActor", { assetPath, tag, location, rotation, properties, spawnController }, assetName, tag);
|
|
475
501
|
return this.actorByTag(tag);
|
|
476
502
|
}
|
|
477
503
|
// ==========================================
|
|
@@ -195,6 +195,29 @@ exports.test = test_1.test.extend({
|
|
|
195
195
|
catch (e) {
|
|
196
196
|
console.error("[Specter] Failed to capture error screenshot:", e);
|
|
197
197
|
}
|
|
198
|
+
try {
|
|
199
|
+
const diagnostics = await world.getDiagnostics({ limit: 35 });
|
|
200
|
+
if (diagnostics) {
|
|
201
|
+
const formattedSummary = (0, gas_matchers_1.formatAiDiagnostics)(diagnostics);
|
|
202
|
+
console.log('\n' + formattedSummary + '\n');
|
|
203
|
+
const alreadyAttached = testInfo.attachments.some(a => a.name.includes('Specter AI Diagnostics'));
|
|
204
|
+
if (!alreadyAttached) {
|
|
205
|
+
testInfo.attachments.push({
|
|
206
|
+
name: 'Specter AI Diagnostics (JSON)',
|
|
207
|
+
contentType: 'application/json',
|
|
208
|
+
body: Buffer.from(JSON.stringify(diagnostics, null, 2))
|
|
209
|
+
});
|
|
210
|
+
testInfo.attachments.push({
|
|
211
|
+
name: 'Specter AI Diagnostics (Markdown)',
|
|
212
|
+
contentType: 'text/markdown',
|
|
213
|
+
body: Buffer.from(formattedSummary)
|
|
214
|
+
});
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
}
|
|
218
|
+
catch (e) {
|
|
219
|
+
console.error("[Specter] Failed to capture AI diagnostics on test failure:", e);
|
|
220
|
+
}
|
|
198
221
|
}
|
|
199
222
|
}, { auto: true }]
|
|
200
223
|
});
|
|
@@ -65,6 +65,7 @@ export interface GasMatchers {
|
|
|
65
65
|
toHaveAnyGameplayTags(tags: string[]): Promise<void>;
|
|
66
66
|
toHaveAllGameplayTags(tags: string[]): Promise<void>;
|
|
67
67
|
}
|
|
68
|
+
export declare function formatAiDiagnostics(diagnostics: any): string;
|
|
68
69
|
export declare const gasExpect: import("playwright/test").Expect<{
|
|
69
70
|
toHaveAttributeValue(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, attributeSet: string, attributeName: string, expectedValue: number, options?: {
|
|
70
71
|
timeout?: number;
|
|
@@ -34,8 +34,91 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
36
|
exports.gasExpect = void 0;
|
|
37
|
+
exports.formatAiDiagnostics = formatAiDiagnostics;
|
|
37
38
|
const test_1 = __importStar(require("@playwright/test"));
|
|
38
39
|
const specter_client_1 = require("../core/specter-client");
|
|
40
|
+
function formatAiDiagnostics(diagnostics) {
|
|
41
|
+
if (!diagnostics)
|
|
42
|
+
return '';
|
|
43
|
+
const lines = [];
|
|
44
|
+
lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
|
|
45
|
+
lines.push('🧠 SPECTER AI DIAGNOSTICS REPORT');
|
|
46
|
+
lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
|
|
47
|
+
// 1. Actor Identity Mapping
|
|
48
|
+
if (diagnostics.actorMap && Object.keys(diagnostics.actorMap).length > 0) {
|
|
49
|
+
lines.push('📍 Actor Identity Mapping:');
|
|
50
|
+
for (const [tag, info] of Object.entries(diagnostics.actorMap)) {
|
|
51
|
+
lines.push(` • [${tag}] -> ${info.name} (${info.class}) | ASC: ${info.asc || 'N/A'}${info.ascOwner ? ` (Owner: ${info.ascOwner})` : ''}`);
|
|
52
|
+
}
|
|
53
|
+
lines.push('');
|
|
54
|
+
}
|
|
55
|
+
// 2. Target Actor Current State
|
|
56
|
+
if (diagnostics.target) {
|
|
57
|
+
lines.push(`🎯 Target Actor: ${diagnostics.target.name} (${diagnostics.target.class})`);
|
|
58
|
+
if (diagnostics.target.attributes) {
|
|
59
|
+
const attrEntries = Object.entries(diagnostics.target.attributes)
|
|
60
|
+
.slice(0, 12)
|
|
61
|
+
.map(([k, v]) => `${k}: ${v}`)
|
|
62
|
+
.join(', ');
|
|
63
|
+
lines.push(` • Attributes: { ${attrEntries} }`);
|
|
64
|
+
}
|
|
65
|
+
if (diagnostics.target.gameplayTags && diagnostics.target.gameplayTags.length > 0) {
|
|
66
|
+
lines.push(` • Active Tags: [ ${diagnostics.target.gameplayTags.join(', ')} ]`);
|
|
67
|
+
}
|
|
68
|
+
if (diagnostics.target.activeEffects && diagnostics.target.activeEffects.length > 0) {
|
|
69
|
+
const effectStrs = diagnostics.target.activeEffects.map((e) => `${e.name} (stacks: ${e.stackCount}, remaining: ${Number(e.remainingTime).toFixed(1)}s)`);
|
|
70
|
+
lines.push(` • Active Effects: [ ${effectStrs.join(', ')} ]`);
|
|
71
|
+
}
|
|
72
|
+
lines.push('');
|
|
73
|
+
}
|
|
74
|
+
// 3. Instigator Actor Current State
|
|
75
|
+
if (diagnostics.instigator) {
|
|
76
|
+
lines.push(`⚔️ Instigator Actor: ${diagnostics.instigator.name} (${diagnostics.instigator.class})`);
|
|
77
|
+
if (diagnostics.instigator.attributes) {
|
|
78
|
+
const attrEntries = Object.entries(diagnostics.instigator.attributes)
|
|
79
|
+
.slice(0, 8)
|
|
80
|
+
.map(([k, v]) => `${k}: ${v}`)
|
|
81
|
+
.join(', ');
|
|
82
|
+
lines.push(` • Attributes: { ${attrEntries} }`);
|
|
83
|
+
}
|
|
84
|
+
if (diagnostics.instigator.gameplayTags && diagnostics.instigator.gameplayTags.length > 0) {
|
|
85
|
+
lines.push(` • Active Tags: [ ${diagnostics.instigator.gameplayTags.join(', ')} ]`);
|
|
86
|
+
}
|
|
87
|
+
lines.push('');
|
|
88
|
+
}
|
|
89
|
+
// 4. Spatial Analysis
|
|
90
|
+
if (diagnostics.distance !== undefined) {
|
|
91
|
+
lines.push(`📐 Spatial Context: Distance = ${Number(diagnostics.distance).toFixed(1)} units | Facing Zone = ${diagnostics.relativeDirection || 'N/A'} (Dot: ${Number(diagnostics.facingDotProduct || 0).toFixed(2)})`);
|
|
92
|
+
lines.push('');
|
|
93
|
+
}
|
|
94
|
+
// 5. Recent Flight Recorder Events
|
|
95
|
+
if (diagnostics.flightRecorder && diagnostics.flightRecorder.length > 0) {
|
|
96
|
+
lines.push('⏱️ Recent Flight Recorder Events (most recent last):');
|
|
97
|
+
const recentSlice = diagnostics.flightRecorder.slice(-12);
|
|
98
|
+
for (const ev of recentSlice) {
|
|
99
|
+
lines.push(` [${Number(ev.timestamp).toFixed(2)}s] ${ev.eventName} - ${ev.description || ''}`);
|
|
100
|
+
}
|
|
101
|
+
lines.push('');
|
|
102
|
+
}
|
|
103
|
+
lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
|
|
104
|
+
try {
|
|
105
|
+
const testInfo = test_1.default.info();
|
|
106
|
+
if (testInfo) {
|
|
107
|
+
testInfo.attachments.push({
|
|
108
|
+
name: 'Specter AI Diagnostics (JSON)',
|
|
109
|
+
contentType: 'application/json',
|
|
110
|
+
body: Buffer.from(JSON.stringify(diagnostics, null, 2))
|
|
111
|
+
});
|
|
112
|
+
testInfo.attachments.push({
|
|
113
|
+
name: 'Specter AI Diagnostics (Summary)',
|
|
114
|
+
contentType: 'text/markdown',
|
|
115
|
+
body: Buffer.from(lines.join('\n'))
|
|
116
|
+
});
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
catch { }
|
|
120
|
+
return '\n\n' + lines.join('\n');
|
|
121
|
+
}
|
|
39
122
|
exports.gasExpect = test_1.expect.extend({
|
|
40
123
|
async toHaveAttributeValue(locator, attributeSet, attributeName, expectedValue, options) {
|
|
41
124
|
const assertionName = 'toHaveAttributeValue';
|
|
@@ -146,12 +229,19 @@ exports.gasExpect = test_1.expect.extend({
|
|
|
146
229
|
if (!e.message?.includes('Timed out')) {
|
|
147
230
|
throw e;
|
|
148
231
|
}
|
|
232
|
+
let diagStr = '';
|
|
233
|
+
try {
|
|
234
|
+
const diags = await locator.getDiagnostics({ limit: 20 });
|
|
235
|
+
diagStr = formatAiDiagnostics(diags);
|
|
236
|
+
}
|
|
237
|
+
catch { }
|
|
149
238
|
return {
|
|
150
239
|
pass: isNot,
|
|
151
240
|
message: () => `${this.utils.matcherHint(assertionName, locator.toString(), expectedValue.toString())}\n\n` +
|
|
152
241
|
`Expected: ${this.utils.printExpected(expectedValue)}\n` +
|
|
153
242
|
`Received: ${lastValue !== undefined ? this.utils.printReceived(lastValue) : 'Timeout'}\n` +
|
|
154
|
-
`History: [${valueHistory.join(', ')}]
|
|
243
|
+
`History: [${valueHistory.join(', ')}]` +
|
|
244
|
+
diagStr,
|
|
155
245
|
actual: lastValue,
|
|
156
246
|
expected: expectedValue
|
|
157
247
|
};
|
|
@@ -421,12 +511,22 @@ exports.gasExpect = test_1.expect.extend({
|
|
|
421
511
|
if (lastFailedReasons.length > 0) {
|
|
422
512
|
failureDetails += `\n\nFailed Criteria on last event:\n- ${lastFailedReasons.join('\n- ')}`;
|
|
423
513
|
}
|
|
514
|
+
let diagStr = '';
|
|
515
|
+
try {
|
|
516
|
+
const diags = await locator.getDiagnostics({
|
|
517
|
+
instigator: expectedChange.instigator,
|
|
518
|
+
limit: 30
|
|
519
|
+
});
|
|
520
|
+
diagStr = formatAiDiagnostics(diags);
|
|
521
|
+
}
|
|
522
|
+
catch { }
|
|
424
523
|
return {
|
|
425
524
|
pass: isNot,
|
|
426
525
|
message: () => `${this.utils.matcherHint(assertionName, locator.toString(), expectedParts.join(', '))}\n\n` +
|
|
427
526
|
`Error: ${e.message}\n` +
|
|
428
527
|
`Expected criteria: { ${expectedParts.join(', ')} }\n\n` +
|
|
429
|
-
failureDetails
|
|
528
|
+
failureDetails +
|
|
529
|
+
diagStr,
|
|
430
530
|
actual: lastEvent,
|
|
431
531
|
expected: expectedChange
|
|
432
532
|
};
|