@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.
@@ -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
- await this.evaluate("SpawnActor", { assetPath, tag, location, rotation }, assetName, tag);
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
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.109",
3
+ "version": "1.0.110",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",