@specter-automation/test 1.0.126 → 1.0.128

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.
@@ -4,6 +4,8 @@ export interface LocatorStep {
4
4
  action: string;
5
5
  value: string;
6
6
  exact?: boolean;
7
+ regex?: boolean;
8
+ invert?: boolean;
7
9
  }
8
10
  export interface FilterOptions {
9
11
  hasComponent?: string;
@@ -1,4 +1,4 @@
1
- import { SpecterLocator } from "../locators/specter-locator";
1
+ import { SpecterLocator, FilterOptions } from "../locators/specter-locator";
2
2
  import { ClickOptions } from "../specter-client";
3
3
  import { WidgetEventMap, EventPredicate, WaitForEventOptions } from "../events";
4
4
  export type WidgetRole = 'button' | 'textbox' | 'checkbox' | 'slider' | 'text' | 'heading' | 'label' | 'image' | 'combobox' | 'dropdown' | 'progressbar';
@@ -6,6 +6,45 @@ export interface WidgetRoleOptions {
6
6
  name?: string | RegExp;
7
7
  exact?: boolean;
8
8
  }
9
+ export interface WidgetFilterOptions extends Partial<FilterOptions> {
10
+ /**
11
+ * Matches widgets containing the specified text string or regular expression anywhere inside them.
12
+ */
13
+ hasText?: string | RegExp;
14
+ /**
15
+ * Matches widgets that do NOT contain the specified text string or regular expression anywhere inside them.
16
+ */
17
+ hasNotText?: string | RegExp;
18
+ /**
19
+ * Matches widgets that contain a child or descendant matching the given sub-locator.
20
+ */
21
+ has?: WidgetLocator | SpecterLocator;
22
+ /**
23
+ * Matches widgets that do NOT contain any child or descendant matching the given sub-locator.
24
+ */
25
+ hasNot?: WidgetLocator | SpecterLocator;
26
+ /**
27
+ * Matches widgets that have a child with the specified designer name.
28
+ */
29
+ hasChild?: string;
30
+ /**
31
+ * Matches widgets that do not have a child with the specified designer name.
32
+ */
33
+ hasNotChild?: string;
34
+ /**
35
+ * Filter by whether the widget is visually visible / rendered.
36
+ */
37
+ visible?: boolean;
38
+ /**
39
+ * Filter by whether the widget is enabled (`bIsEnabled`).
40
+ */
41
+ enabled?: boolean;
42
+ /**
43
+ * When using string `hasText` or `hasNotText`, whether the match must be exact.
44
+ * Default is false (substring match) for string, or exact if specified.
45
+ */
46
+ exact?: boolean;
47
+ }
9
48
  export interface WidgetGeometry {
10
49
  isRendered: boolean;
11
50
  isVisible: boolean;
@@ -23,6 +62,10 @@ export interface WidgetGeometry {
23
62
  };
24
63
  }
25
64
  export declare class WidgetLocator<T = any> extends SpecterLocator<T> {
65
+ /**
66
+ * Filters the currently located widgets by text, child widgets, visibility, enabled state, or properties.
67
+ */
68
+ filter(options: WidgetFilterOptions): this;
26
69
  waitForEvent<K extends keyof WidgetEventMap>(eventName: K | (string & {}), optionsOrPredicate?: number | EventPredicate<K extends keyof WidgetEventMap ? WidgetEventMap[K] : any> | WaitForEventOptions<K extends keyof WidgetEventMap ? WidgetEventMap[K] : any>): Promise<K extends keyof WidgetEventMap ? WidgetEventMap[K] : any>;
27
70
  /**
28
71
  * Finds a child widget by its semantic role (button, textbox, checkbox, slider, text, image, combobox)
@@ -37,6 +37,119 @@ exports.WidgetLocator = void 0;
37
37
  const specter_locator_1 = require("../locators/specter-locator");
38
38
  const test_1 = __importStar(require("@playwright/test"));
39
39
  class WidgetLocator extends specter_locator_1.SpecterLocator {
40
+ /**
41
+ * Filters the currently located widgets by text, child widgets, visibility, enabled state, or properties.
42
+ */
43
+ filter(options) {
44
+ const newLocator = this.clone();
45
+ if (options.hasText !== undefined) {
46
+ const isRegex = options.hasText instanceof RegExp;
47
+ const textStr = isRegex ? options.hasText.source : options.hasText;
48
+ newLocator.pipeline.push({
49
+ action: 'filterWidgetByText',
50
+ value: textStr,
51
+ exact: options.exact ?? false,
52
+ regex: isRegex,
53
+ invert: false,
54
+ });
55
+ }
56
+ if (options.hasNotText !== undefined) {
57
+ const isRegex = options.hasNotText instanceof RegExp;
58
+ const textStr = isRegex ? options.hasNotText.source : options.hasNotText;
59
+ newLocator.pipeline.push({
60
+ action: 'filterWidgetByText',
61
+ value: textStr,
62
+ exact: options.exact ?? false,
63
+ regex: isRegex,
64
+ invert: true,
65
+ });
66
+ }
67
+ if (options.hasChild !== undefined) {
68
+ newLocator.pipeline.push({
69
+ action: 'filterWidgetByChild',
70
+ value: options.hasChild,
71
+ exact: options.exact ?? false,
72
+ invert: false,
73
+ });
74
+ }
75
+ if (options.hasNotChild !== undefined) {
76
+ newLocator.pipeline.push({
77
+ action: 'filterWidgetByChild',
78
+ value: options.hasNotChild,
79
+ exact: options.exact ?? false,
80
+ invert: true,
81
+ });
82
+ }
83
+ if (options.has !== undefined) {
84
+ newLocator.pipeline.push({
85
+ action: 'filterWidgetHas',
86
+ value: JSON.stringify(options.has.pipeline),
87
+ invert: false,
88
+ });
89
+ }
90
+ if (options.hasNot !== undefined) {
91
+ newLocator.pipeline.push({
92
+ action: 'filterWidgetHas',
93
+ value: JSON.stringify(options.hasNot.pipeline),
94
+ invert: true,
95
+ });
96
+ }
97
+ if (options.visible !== undefined) {
98
+ newLocator.pipeline.push({
99
+ action: 'filterWidgetVisibility',
100
+ value: options.visible ? 'true' : 'false',
101
+ });
102
+ }
103
+ if (options.enabled !== undefined) {
104
+ newLocator.pipeline.push({
105
+ action: 'filterWidgetEnabled',
106
+ value: options.enabled ? 'true' : 'false',
107
+ });
108
+ }
109
+ if (options.property) {
110
+ newLocator.pipeline.push({
111
+ action: 'filterByProperty',
112
+ value: JSON.stringify(options.property),
113
+ });
114
+ }
115
+ if (options.hasComponent) {
116
+ newLocator.pipeline.push({
117
+ action: 'filterByComponent',
118
+ value: options.hasComponent,
119
+ });
120
+ }
121
+ if (options.withinRadius !== undefined) {
122
+ const spatialPayload = JSON.stringify({
123
+ x: options.x ?? 0,
124
+ y: options.y ?? 0,
125
+ z: options.z ?? 0,
126
+ radius: options.withinRadius,
127
+ });
128
+ newLocator.pipeline.push({
129
+ action: 'withinRadius',
130
+ value: spatialPayload,
131
+ });
132
+ }
133
+ if (options.locallyControlled !== undefined) {
134
+ newLocator.pipeline.push({
135
+ action: 'filterLocallyControlled',
136
+ value: options.locallyControlled ? '' : 'false',
137
+ });
138
+ }
139
+ if (options.possessed !== undefined) {
140
+ newLocator.pipeline.push({
141
+ action: 'filterPossessed',
142
+ value: options.possessed ? '' : 'false',
143
+ });
144
+ }
145
+ if (options.playerControlled !== undefined) {
146
+ newLocator.pipeline.push({
147
+ action: 'filterPossessed',
148
+ value: options.playerControlled ? '' : 'false',
149
+ });
150
+ }
151
+ return newLocator;
152
+ }
40
153
  async waitForEvent(eventName, optionsOrPredicate) {
41
154
  return super.waitForEvent(eventName, optionsOrPredicate);
42
155
  }
@@ -263,7 +263,10 @@ export declare class SpecterWorld {
263
263
  private transport;
264
264
  readonly keyboard: SpecterKeyboard;
265
265
  readonly network: SpecterNetwork;
266
+ timeDilation: number;
266
267
  constructor(transport: SpecterTransport);
268
+ toString(): string;
269
+ toSelectorString(): string;
267
270
  static connect(url?: string): Promise<SpecterWorld>;
268
271
  /**
269
272
  * Queries comprehensive runtime diagnostics from the engine, including
@@ -343,6 +346,27 @@ export declare class SpecterWorld {
343
346
  */
344
347
  evaluate(commandName: string, payload?: any, context?: string, targetLocator?: string, bHideStep?: boolean): Promise<any>;
345
348
  setTimeDilation(speed: number): Promise<void>;
349
+ /**
350
+ * Advances the engine's game clock faster than real-time by a specific number of seconds.
351
+ * Useful for bypassing long ability cooldowns, buff durations, or cutscenes deterministically
352
+ * without waiting real wall-clock seconds.
353
+ *
354
+ * E.g. `await world.advanceTime(10.0)` fast-forwards 10 seconds of simulation time in ~500ms.
355
+ *
356
+ * @param seconds Total in-game simulation seconds to advance.
357
+ * @param options.speedMultiplier Simulation acceleration rate (defaults to 20x, or 4x active dilation).
358
+ */
359
+ advanceTime(seconds: number, options?: {
360
+ speedMultiplier?: number;
361
+ }): Promise<void>;
362
+ /**
363
+ * Waits for the specified amount of in-game simulation time.
364
+ * If faster-than-real-time time dilation is active (e.g. configured via `use: { timeDilation: 5 }`),
365
+ * the real wall-clock wait is scaled down automatically (e.g. 5 game seconds elapses in 1 wall-clock second).
366
+ *
367
+ * @param seconds In-game simulation seconds to wait.
368
+ */
369
+ waitForGameSeconds(seconds: number): Promise<void>;
346
370
  spawnActor(assetPath: string, options?: SpawnOptions): Promise<ActorLocator>;
347
371
  actor<T extends RegisteredActorClasses | (string & {})>(selector: T): ActorLocator<T>;
348
372
  actorByTag(tagName: string): ActorLocator;
@@ -515,4 +539,10 @@ export declare class SpecterWorld {
515
539
  * Scrubs a Level Sequence cutscene to a specific playback position in seconds.
516
540
  */
517
541
  scrubSequence(sequenceName: string, positionSeconds: number): Promise<void>;
542
+ /**
543
+ * Imports a saved portable .specter-trace file into the running engine,
544
+ * replaying all its recorded steps, telemetry events, and matcher results
545
+ * into the Unreal Editor in-engine test runner.
546
+ */
547
+ importTrace(traceFilePath: string): Promise<void>;
518
548
  }
@@ -400,11 +400,18 @@ class SpecterWorld {
400
400
  transport;
401
401
  keyboard;
402
402
  network;
403
+ timeDilation = 1.0;
403
404
  constructor(transport) {
404
405
  this.transport = transport;
405
406
  this.keyboard = new specter_keyboard_1.SpecterKeyboard(this);
406
407
  this.network = new specter_network_1.SpecterNetwork(this);
407
408
  }
409
+ toString() {
410
+ return 'world';
411
+ }
412
+ toSelectorString() {
413
+ return 'world';
414
+ }
408
415
  // Factory method matches the Playwright style: await SpecterPage.connect()
409
416
  static async connect(url) {
410
417
  const transport = new SpecterTransport(url);
@@ -623,6 +630,46 @@ class SpecterWorld {
623
630
  async setTimeDilation(speed) {
624
631
  return this.setTimeScale(speed);
625
632
  }
633
+ /**
634
+ * Advances the engine's game clock faster than real-time by a specific number of seconds.
635
+ * Useful for bypassing long ability cooldowns, buff durations, or cutscenes deterministically
636
+ * without waiting real wall-clock seconds.
637
+ *
638
+ * E.g. `await world.advanceTime(10.0)` fast-forwards 10 seconds of simulation time in ~500ms.
639
+ *
640
+ * @param seconds Total in-game simulation seconds to advance.
641
+ * @param options.speedMultiplier Simulation acceleration rate (defaults to 20x, or 4x active dilation).
642
+ */
643
+ async advanceTime(seconds, options) {
644
+ if (seconds <= 0)
645
+ return;
646
+ const defaultSpeed = this.timeDilation > 1 ? Math.max(20, this.timeDilation * 4) : 20;
647
+ const speed = options?.speedMultiplier ?? defaultSpeed;
648
+ const durationWallClockMs = Math.max(16, (seconds / speed) * 1000);
649
+ await test_1.default.step(`Specter: Advance Time [${seconds}s at ${speed}x speed]`, async () => {
650
+ await this.console(`slomo ${speed}`);
651
+ await this.waitForTimeout(durationWallClockMs);
652
+ await this.console(`slomo ${this.timeDilation}`);
653
+ });
654
+ }
655
+ /**
656
+ * Waits for the specified amount of in-game simulation time.
657
+ * If faster-than-real-time time dilation is active (e.g. configured via `use: { timeDilation: 5 }`),
658
+ * the real wall-clock wait is scaled down automatically (e.g. 5 game seconds elapses in 1 wall-clock second).
659
+ *
660
+ * @param seconds In-game simulation seconds to wait.
661
+ */
662
+ async waitForGameSeconds(seconds) {
663
+ if (seconds <= 0)
664
+ return;
665
+ const dilation = this.timeDilation > 0 ? this.timeDilation : 1.0;
666
+ const wallClockMs = Math.max(16, (seconds / dilation) * 1000);
667
+ const portTag = this.transport.friendlyPortTag;
668
+ const stepTitle = `${portTag}waitForGameSeconds (${seconds}s game time at ${dilation}x -> ~${Math.round(wallClockMs)}ms wall clock)`;
669
+ return await test_1.default.step(stepTitle, async () => {
670
+ await new Promise(resolve => setTimeout(resolve, wallClockMs));
671
+ });
672
+ }
626
673
  async spawnActor(assetPath, options) {
627
674
  // Generate a unique tag if the user didn't provide one
628
675
  const uniqueId = crypto_1.default.randomBytes(4).toString('hex');
@@ -719,6 +766,7 @@ class SpecterWorld {
719
766
  if (multiplier <= 0) {
720
767
  throw new Error(`[Specter Error] setTimeScale multiplier must be greater than 0. Received: ${multiplier}`);
721
768
  }
769
+ this.timeDilation = multiplier;
722
770
  await test_1.default.step(`Specter: Set Global Time Scale [${multiplier}x]`, async () => {
723
771
  // Under the hood, this simply routes through our new console bridge
724
772
  await this.console(`slomo ${multiplier}`);
@@ -1026,6 +1074,13 @@ class SpecterWorld {
1026
1074
  catch (e) {
1027
1075
  // Ignore cleanup timeouts during test teardown if connection is closing/closed
1028
1076
  }
1077
+ if (this.timeDilation !== 1.0) {
1078
+ try {
1079
+ await this.console("slomo 1");
1080
+ this.timeDilation = 1.0;
1081
+ }
1082
+ catch (e) { }
1083
+ }
1029
1084
  }
1030
1085
  /**
1031
1086
  * Restores the primary PlayerController to its pre-possession state
@@ -1094,5 +1149,15 @@ class SpecterWorld {
1094
1149
  await this.evaluate("ScrubSequence", { name: sequenceName, positionSeconds });
1095
1150
  });
1096
1151
  }
1152
+ /**
1153
+ * Imports a saved portable .specter-trace file into the running engine,
1154
+ * replaying all its recorded steps, telemetry events, and matcher results
1155
+ * into the Unreal Editor in-engine test runner.
1156
+ */
1157
+ async importTrace(traceFilePath) {
1158
+ await test_1.default.step(`Specter: Import Trace [${traceFilePath}]`, async () => {
1159
+ await this.evaluate("ImportTrace", { traceFilePath });
1160
+ });
1161
+ }
1097
1162
  }
1098
1163
  exports.SpecterWorld = SpecterWorld;
@@ -13,6 +13,7 @@ export default class SpecterReporter implements Reporter {
13
13
  private failedSteps;
14
14
  constructor();
15
15
  private connect;
16
+ private recordedEvents;
16
17
  private send;
17
18
  onBegin(config: FullConfig, suite: Suite): void;
18
19
  onTestBegin(test: TestCase): void;
@@ -38,5 +39,6 @@ export default class SpecterReporter implements Reporter {
38
39
  onStdOut(chunk: string | Buffer, test: void | TestCase, result: void | TestResult): void;
39
40
  onStdErr(chunk: string | Buffer, test: void | TestCase, result: void | TestResult): void;
40
41
  onTestEnd(test: TestCase, result: TestResult): void;
42
+ private saveTraceFile;
41
43
  onEnd(result: FullResult): void;
42
44
  }
@@ -126,9 +126,23 @@ class SpecterReporter {
126
126
  this.isConnected = false;
127
127
  });
128
128
  }
129
+ recordedEvents = new Map();
129
130
  send(payload) {
130
131
  const msg = JSON.stringify(payload);
131
132
  console.log(`[REPORTER WEBSOCKET SEND]: ${msg}`);
133
+ const testName = payload.payload?.testName;
134
+ if (testName) {
135
+ let events = this.recordedEvents.get(testName);
136
+ if (!events) {
137
+ events = [];
138
+ this.recordedEvents.set(testName, events);
139
+ }
140
+ events.push({
141
+ event: payload.event,
142
+ payload: payload.payload,
143
+ timestamp: Date.now()
144
+ });
145
+ }
132
146
  if (this.isConnected && this.ws && this.ws.readyState === ws_1.default.OPEN) {
133
147
  this.ws.send(msg);
134
148
  }
@@ -550,6 +564,63 @@ class SpecterReporter {
550
564
  status: result.status
551
565
  }
552
566
  });
567
+ // Determine if portable trace should be saved:
568
+ // Default: save on failure, on CI, or when SPECTER_TRACE !== 'off'
569
+ const isFailure = result.status !== 'passed';
570
+ const traceEnv = process.env.SPECTER_TRACE;
571
+ const shouldSaveTrace = traceEnv === 'on' || traceEnv === 'always' || (traceEnv !== 'off' && (isFailure || process.env.CI !== undefined));
572
+ if (shouldSaveTrace) {
573
+ this.saveTraceFile(uniqueTestKey, test, result);
574
+ }
575
+ else {
576
+ this.recordedEvents.delete(uniqueTestKey);
577
+ }
578
+ }
579
+ saveTraceFile(testKey, test, result) {
580
+ const events = this.recordedEvents.get(testKey) || [];
581
+ const sanitizedName = testKey.replace(/[^a-zA-Z0-9_-]/g, '_');
582
+ const traceDir = path.resolve(process.cwd(), 'specter-traces');
583
+ try {
584
+ fs.mkdirSync(traceDir, { recursive: true });
585
+ const traceFilePath = path.join(traceDir, `${sanitizedName}.specter-trace.json`);
586
+ // Collect any image attachments as base64 for complete portability
587
+ const screenshots = {};
588
+ for (const att of result.attachments) {
589
+ if (att.contentType.startsWith('image/') && att.path && fs.existsSync(att.path)) {
590
+ try {
591
+ const imgBuf = fs.readFileSync(att.path);
592
+ screenshots[att.name || path.basename(att.path)] = `data:image/png;base64,${imgBuf.toString('base64')}`;
593
+ }
594
+ catch { }
595
+ }
596
+ }
597
+ const tracePayload = {
598
+ specterTraceVersion: '1.0',
599
+ testName: testKey,
600
+ file: test.location?.file,
601
+ line: test.location?.line,
602
+ status: result.status,
603
+ durationMs: result.duration,
604
+ error: result.error ? this.formatError(result.error, result) : undefined,
605
+ recordedAt: new Date().toISOString(),
606
+ events,
607
+ screenshots
608
+ };
609
+ fs.writeFileSync(traceFilePath, JSON.stringify(tracePayload, null, 2), 'utf-8');
610
+ console.log(`[Specter Trace] Saved portable trace to: ${traceFilePath}`);
611
+ // Attach to Playwright result so CI uploads it with test artifacts
612
+ result.attachments.push({
613
+ name: 'specter-trace',
614
+ path: traceFilePath,
615
+ contentType: 'application/json'
616
+ });
617
+ }
618
+ catch (e) {
619
+ console.error(`[Specter Trace] Failed to write trace for ${testKey}:`, e);
620
+ }
621
+ finally {
622
+ this.recordedEvents.delete(testKey);
623
+ }
553
624
  }
554
625
  onEnd(result) {
555
626
  this.send({
@@ -6,7 +6,25 @@ import { LocatorMatchers } from '../matchers/locator-matchers';
6
6
  import { WidgetMatchers } from '../matchers/widget-matchers';
7
7
  import { MaterialMatchers } from '../matchers/material-matchers';
8
8
  import { AiMatchers } from '../matchers/ai-matchers';
9
- export declare const expect: typeof baseExpect & GasMatchers & ActorMatchers & LocatorMatchers & WidgetMatchers & MaterialMatchers & AiMatchers;
9
+ import { PerformanceMatchers } from '../matchers/performance-matchers';
10
+ import { VisualMatchers } from '../matchers/visual-matchers';
11
+ export declare const expect: typeof baseExpect & GasMatchers & ActorMatchers & LocatorMatchers & WidgetMatchers & MaterialMatchers & AiMatchers & PerformanceMatchers & VisualMatchers;
12
+ export type SpecterTestOptions = {
13
+ /**
14
+ * Global simulation speed multiplier (time dilation / slomo) for tests.
15
+ * Default is 1.0 (normal real-time).
16
+ * Set to e.g. 5 or 10 in `playwright.config.ts` (`use: { timeDilation: 5 }`)
17
+ * or per test block (`test.use({ timeDilation: 10 })`) to run tests faster than real-time.
18
+ * Can also be overridden via the `SPECTER_TIME_DILATION` environment variable.
19
+ */
20
+ timeDilation: number;
21
+ /**
22
+ * Optional fixed delta time in seconds (e.g. 1/60 = 0.0166667) for deterministic frame ticks.
23
+ * Enforces fixed timestep simulation so physics, timers, and cooldowns produce identical
24
+ * results regardless of host machine performance. Default is 0 (unconstrained / real delta time).
25
+ */
26
+ fixedDeltaSeconds: number;
27
+ };
10
28
  type SpecterTestFixtures = {
11
29
  world: SpecterWorld;
12
30
  createWorld: (options: CreateWorldOptions) => Promise<SpecterWorld>;
@@ -22,5 +40,5 @@ type CreateWorldOptions = {
22
40
  autoJoinHost?: boolean;
23
41
  launchClient?: boolean;
24
42
  };
25
- export declare const test: import("playwright/test").TestType<import("playwright/test").PlaywrightTestArgs & import("playwright/test").PlaywrightTestOptions & SpecterTestFixtures, import("playwright/test").PlaywrightWorkerArgs & import("playwright/test").PlaywrightWorkerOptions & SpecterWorkerFixtures>;
43
+ export declare const test: import("playwright/test").TestType<import("playwright/test").PlaywrightTestArgs & import("playwright/test").PlaywrightTestOptions & SpecterTestFixtures & SpecterTestOptions, import("playwright/test").PlaywrightWorkerArgs & import("playwright/test").PlaywrightWorkerOptions & SpecterWorkerFixtures>;
26
44
  export {};
@@ -42,9 +42,14 @@ const locator_matchers_1 = require("../matchers/locator-matchers");
42
42
  const widget_matchers_1 = require("../matchers/widget-matchers");
43
43
  const material_matchers_1 = require("../matchers/material-matchers");
44
44
  const ai_matchers_1 = require("../matchers/ai-matchers");
45
- exports.expect = (0, test_1.mergeExpects)(gas_matchers_1.gasExpect, actor_matchers_1.actorExpect, locator_matchers_1.locatorExpect, widget_matchers_1.widgetExpect, material_matchers_1.materialExpect, ai_matchers_1.aiExpect);
45
+ const performance_matchers_1 = require("../matchers/performance-matchers");
46
+ const visual_matchers_1 = require("../matchers/visual-matchers");
47
+ exports.expect = (0, test_1.mergeExpects)(gas_matchers_1.gasExpect, actor_matchers_1.actorExpect, locator_matchers_1.locatorExpect, widget_matchers_1.widgetExpect, material_matchers_1.materialExpect, ai_matchers_1.aiExpect, performance_matchers_1.performanceExpect, visual_matchers_1.visualExpect);
46
48
  // 2. Define the scopes in the extend block
47
49
  exports.test = test_1.test.extend({
50
+ // OPTIONS FIXTURES: Configurable via playwright.config.ts `use: { ... }` or `test.use({ ... })`
51
+ timeDilation: [1.0, { option: true }],
52
+ fixedDeltaSeconds: [0, { option: true }],
48
53
  // WORKER FIXTURE: Boots once per Playwright worker process
49
54
  specter: [async ({}, use) => {
50
55
  const socket = new specter_client_1.SpecterTransport();
@@ -60,14 +65,30 @@ exports.test = test_1.test.extend({
60
65
  }
61
66
  }, { scope: 'worker' }], // <-- This is the magic flag
62
67
  // TEST FIXTURE: Runs before/after every single test block
63
- world: async ({ specter }, use, testInfo) => {
68
+ world: async ({ specter, timeDilation, fixedDeltaSeconds }, use, testInfo) => {
69
+ const envDilation = process.env.SPECTER_TIME_DILATION ? parseFloat(process.env.SPECTER_TIME_DILATION) : undefined;
70
+ const activeDilation = (envDilation !== undefined && !isNaN(envDilation) && envDilation > 0) ? envDilation : (timeDilation || 1.0);
64
71
  const world = new specter_client_1.SpecterWorld(specter);
72
+ world.timeDilation = activeDilation;
73
+ if (activeDilation !== 1.0) {
74
+ await world.setTimeScale(activeDilation);
75
+ }
76
+ if (fixedDeltaSeconds && fixedDeltaSeconds > 0) {
77
+ await world.console(`r.FixedDeltaTime ${fixedDeltaSeconds}`);
78
+ }
65
79
  await use(world);
66
- // Wipe the level clean for the next test in the queue
80
+ // Teardown: Reset fixed delta time if configured
81
+ if (fixedDeltaSeconds && fixedDeltaSeconds > 0) {
82
+ try {
83
+ await world.console(`r.FixedDeltaTime 0`);
84
+ }
85
+ catch (e) { }
86
+ }
87
+ // Wipe the level clean for the next test in the queue (also restores slomo 1.0 if dilated)
67
88
  await world.cleanup();
68
89
  },
69
90
  // THE MULTIPLAYER FACTORY FIXTURE
70
- createWorld: async ({}, use) => {
91
+ createWorld: async ({ timeDilation }, use) => {
71
92
  const activeWorlds = [];
72
93
  const activeProcesses = [];
73
94
  const factory = async (options) => {
@@ -149,6 +170,8 @@ exports.test = test_1.test.extend({
149
170
  }
150
171
  await transport.connect();
151
172
  const newWorld = new specter_client_1.SpecterWorld(transport);
173
+ const envDilation = process.env.SPECTER_TIME_DILATION ? parseFloat(process.env.SPECTER_TIME_DILATION) : undefined;
174
+ newWorld.timeDilation = (envDilation !== undefined && !isNaN(envDilation) && envDilation > 0) ? envDilation : (timeDilation || 1.0);
152
175
  activeWorlds.push(newWorld);
153
176
  // 2. Automatically command the engine to travel if requested
154
177
  if (options.autoJoinHost && options.hostAddress) {
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
- export { test, expect } from './core/test-wrapper';
1
+ export { test, expect, type SpecterTestOptions } from './core/test-wrapper';
2
2
  export { SpecterTransport, SpecterWorld, VectorUtils } from './core/specter-client';
3
3
  export type { SpecterPayload, SpawnOptions, Vector3, Rotator, Transform, HitResult, LinearColor, Color, Vector2D, SpecterRegistry, SpecterFunctionRegistry, LoadMapOptions, SpecterGrantedAbility, SpecterActiveEffect, SpecterActorSnapshot, RegisteredGameplayTags } from './core/specter-client';
4
- export { SpecterLocator, WidgetLocator, ActorLocator, AiControllerLocator, type WidgetGeometry } from './core/locators';
4
+ export { SpecterLocator, WidgetLocator, ActorLocator, AiControllerLocator, type WidgetGeometry, type WidgetFilterOptions } from './core/locators';
5
5
  export { default as SpecterReporter } from './core/specter-reporter';
6
6
  export { expectAll } from './core/expect-all';
7
7
  export { SPECTER_MATCHER_ATTACHMENT } from './core/specter-matcher-report';
@@ -16,3 +16,7 @@ export type { MaterialOptions, MaterialScalarOptions, MaterialVectorOptions, Col
16
16
  export { materialExpect } from './matchers/material-matchers';
17
17
  export type { MovementDirectionInfo, AiMatchers } from './matchers/ai-matchers';
18
18
  export { aiExpect } from './matchers/ai-matchers';
19
+ export type { PerformanceBudgetOptions, PerformanceMatchers } from './matchers/performance-matchers';
20
+ export { performanceExpect } from './matchers/performance-matchers';
21
+ export type { MatchScreenshotOptions, VisualMatchers } from './matchers/visual-matchers';
22
+ export { visualExpect } from './matchers/visual-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.aiExpect = exports.materialExpect = exports.runConditionalInputLoop = exports.evaluateCondition = exports.SpecterNetwork = exports.SpecterInputSequence = 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.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; } });
@@ -33,3 +33,7 @@ var material_matchers_1 = require("./matchers/material-matchers");
33
33
  Object.defineProperty(exports, "materialExpect", { enumerable: true, get: function () { return material_matchers_1.materialExpect; } });
34
34
  var ai_matchers_1 = require("./matchers/ai-matchers");
35
35
  Object.defineProperty(exports, "aiExpect", { enumerable: true, get: function () { return ai_matchers_1.aiExpect; } });
36
+ var performance_matchers_1 = require("./matchers/performance-matchers");
37
+ Object.defineProperty(exports, "performanceExpect", { enumerable: true, get: function () { return performance_matchers_1.performanceExpect; } });
38
+ var visual_matchers_1 = require("./matchers/visual-matchers");
39
+ Object.defineProperty(exports, "visualExpect", { enumerable: true, get: function () { return visual_matchers_1.visualExpect; } });
@@ -654,7 +654,12 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
654
654
  }
655
655
  if (targetName) {
656
656
  const evTarget = (event.target || '').trim();
657
- if (evTarget && !evTarget.includes(targetName) && !targetName.includes(evTarget)) {
657
+ const locatorTag = (locator.tag || '').trim();
658
+ const isTargetMatch = !evTarget ||
659
+ evTarget.includes(targetName) || targetName.includes(evTarget) ||
660
+ (locatorTag && (evTarget.includes(locatorTag) || locatorTag.includes(evTarget))) ||
661
+ (evTarget.includes('PlayerState') && (targetName.includes('Hero') || targetName.includes('BP_') || targetName.includes('Character') || targetName.includes('Spawned')));
662
+ if (!isTargetMatch) {
658
663
  return false;
659
664
  }
660
665
  }
@@ -870,7 +875,12 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
870
875
  if (targetName && ev.target) {
871
876
  const cleanTarget = targetName.trim();
872
877
  const evTarget = ev.target.trim();
873
- if (!evTarget.includes(cleanTarget) && !cleanTarget.includes(evTarget)) {
878
+ const locatorTag = (locator.tag || '').trim();
879
+ const isTargetMatch = !evTarget ||
880
+ evTarget.includes(cleanTarget) || cleanTarget.includes(evTarget) ||
881
+ (locatorTag && (evTarget.includes(locatorTag) || locatorTag.includes(evTarget))) ||
882
+ (evTarget.includes('PlayerState') && (cleanTarget.includes('Hero') || cleanTarget.includes('BP_') || cleanTarget.includes('Character') || cleanTarget.includes('Spawned')));
883
+ if (!isTargetMatch) {
874
884
  return false;
875
885
  }
876
886
  }
@@ -65,20 +65,31 @@ function recordResult(report) {
65
65
  function isLocatorLike(value) {
66
66
  return !!value && typeof value === 'object' && Array.isArray(value.pipeline);
67
67
  }
68
+ function isWorldLike(value) {
69
+ return !!value && typeof value === 'object' && typeof value.getPerformanceMetrics === 'function';
70
+ }
68
71
  function describe(receiver) {
69
72
  if (isLocatorLike(receiver))
70
73
  return receiver.toString();
74
+ if (isWorldLike(receiver))
75
+ return 'world';
71
76
  return formatArg(receiver);
72
77
  }
73
78
  function selectorOf(receiver) {
74
79
  if (isLocatorLike(receiver)) {
75
80
  return typeof receiver.toSelectorString === 'function' ? receiver.toSelectorString() : receiver.toString();
76
81
  }
82
+ if (isWorldLike(receiver))
83
+ return 'world';
77
84
  return formatArg(receiver);
78
85
  }
79
86
  function clientTagOf(receiver) {
80
87
  try {
81
- return isLocatorLike(receiver) && typeof receiver.portTag === 'string' ? receiver.portTag : '';
88
+ if (isLocatorLike(receiver) && typeof receiver.portTag === 'string')
89
+ return receiver.portTag;
90
+ if (isWorldLike(receiver) && typeof receiver.transport?.friendlyPortTag === 'string')
91
+ return receiver.transport.friendlyPortTag;
92
+ return '';
82
93
  }
83
94
  catch {
84
95
  return '';
@@ -0,0 +1,118 @@
1
+ import { SpecterWorld } from '../core/specter-client';
2
+ import { SpecterLocator } from '../core/locators';
3
+ export interface PerformanceBudgetOptions {
4
+ /** Minimum FPS allowed across all samples (no frame drops below this threshold). */
5
+ minFps?: number;
6
+ /** Average FPS required across the entire sampling duration. */
7
+ avgFps?: number;
8
+ /** Maximum allowed frame time in milliseconds (spike threshold, e.g. 16.67ms for 60fps). */
9
+ maxFrameTimeMs?: number;
10
+ /** Maximum allowed physical memory in megabytes. */
11
+ maxMemoryMb?: number;
12
+ /** Total duration to collect performance samples in milliseconds (default: 1000ms). */
13
+ sampleDurationMs?: number;
14
+ /** Interval between performance samples in milliseconds (default: 100ms). */
15
+ sampleIntervalMs?: number;
16
+ }
17
+ declare global {
18
+ namespace PlaywrightTest {
19
+ interface Matchers<R, T> {
20
+ toHaveFPS(this: Matchers<R, SpecterWorld | SpecterLocator>, expectedFps: number, options?: {
21
+ operator?: '>=' | '<=' | '>' | '<' | '===';
22
+ timeout?: number;
23
+ }): Promise<R>;
24
+ toHaveMinFPS(this: Matchers<R, SpecterWorld | SpecterLocator>, expectedMinFps: number, options?: {
25
+ timeout?: number;
26
+ }): Promise<R>;
27
+ toHaveFrameTimeBelow(this: Matchers<R, SpecterWorld | SpecterLocator>, maxFrameTimeMs: number, options?: {
28
+ timeout?: number;
29
+ }): Promise<R>;
30
+ toHaveMemoryBelow(this: Matchers<R, SpecterWorld | SpecterLocator>, maxMemoryMb: number, options?: {
31
+ timeout?: number;
32
+ }): Promise<R>;
33
+ toMaintainPerformanceBudget(this: Matchers<R, SpecterWorld | SpecterLocator>, budget: PerformanceBudgetOptions): Promise<R>;
34
+ }
35
+ }
36
+ }
37
+ export interface PerformanceMatchers {
38
+ toHaveFPS(expectedFps: number, options?: {
39
+ operator?: '>=' | '<=' | '>' | '<' | '===';
40
+ timeout?: number;
41
+ }): Promise<void>;
42
+ toHaveMinFPS(expectedMinFps: number, options?: {
43
+ timeout?: number;
44
+ }): Promise<void>;
45
+ toHaveFrameTimeBelow(maxFrameTimeMs: number, options?: {
46
+ timeout?: number;
47
+ }): Promise<void>;
48
+ toHaveMemoryBelow(maxMemoryMb: number, options?: {
49
+ timeout?: number;
50
+ }): Promise<void>;
51
+ toMaintainPerformanceBudget(budget: PerformanceBudgetOptions): Promise<void>;
52
+ }
53
+ export declare const performanceExpect: import("playwright/test").Expect<{
54
+ toHaveFPS(this: import("playwright/test").ExpectMatcherState, receiver: any, expectedFps: number, options?: {
55
+ operator?: ">=" | "<=" | ">" | "<" | "===";
56
+ timeout?: number;
57
+ }): Promise<{
58
+ pass: boolean;
59
+ message: () => string;
60
+ actual?: undefined;
61
+ expected?: undefined;
62
+ } | {
63
+ pass: boolean;
64
+ message: () => string;
65
+ actual: number;
66
+ expected: number;
67
+ }>;
68
+ toHaveMinFPS(this: import("playwright/test").ExpectMatcherState, receiver: any, expectedMinFps: number, options?: {
69
+ timeout?: number;
70
+ }): Promise<{
71
+ pass: boolean;
72
+ message: () => string;
73
+ actual?: undefined;
74
+ expected?: undefined;
75
+ } | {
76
+ pass: boolean;
77
+ message: () => string;
78
+ actual: number;
79
+ expected: number;
80
+ }>;
81
+ toHaveFrameTimeBelow(this: import("playwright/test").ExpectMatcherState, receiver: any, maxFrameTimeMs: number, options?: {
82
+ timeout?: number;
83
+ }): Promise<{
84
+ pass: boolean;
85
+ message: () => string;
86
+ actual?: undefined;
87
+ expected?: undefined;
88
+ } | {
89
+ pass: boolean;
90
+ message: () => string;
91
+ actual: number;
92
+ expected: number;
93
+ }>;
94
+ toHaveMemoryBelow(this: import("playwright/test").ExpectMatcherState, receiver: any, maxMemoryMb: number, options?: {
95
+ timeout?: number;
96
+ }): Promise<{
97
+ pass: boolean;
98
+ message: () => string;
99
+ actual?: undefined;
100
+ expected?: undefined;
101
+ } | {
102
+ pass: boolean;
103
+ message: () => string;
104
+ actual: number;
105
+ expected: number;
106
+ }>;
107
+ toMaintainPerformanceBudget(this: import("playwright/test").ExpectMatcherState, receiver: any, budget: PerformanceBudgetOptions): Promise<{
108
+ pass: false;
109
+ message: () => string;
110
+ actual: number;
111
+ expected: number;
112
+ } | {
113
+ pass: boolean;
114
+ message: () => string;
115
+ actual: string;
116
+ expected: PerformanceBudgetOptions;
117
+ }>;
118
+ }>;
@@ -0,0 +1,178 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.performanceExpect = void 0;
4
+ const test_1 = require("@playwright/test");
5
+ const instrument_1 = require("./instrument");
6
+ async function fetchMetrics(receiver) {
7
+ if (receiver && typeof receiver.getPerformanceMetrics === 'function') {
8
+ return await receiver.getPerformanceMetrics();
9
+ }
10
+ if (receiver && typeof receiver.evaluate === 'function') {
11
+ const res = await receiver.evaluate("GetPerformanceMetrics", {});
12
+ return res?.data ?? { fps: 60, frameTimeMs: 16.66, memoryMb: 0 };
13
+ }
14
+ throw new Error(`Performance matchers must be called on SpecterWorld or a SpecterLocator. Received: ${typeof receiver}`);
15
+ }
16
+ exports.performanceExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
17
+ async toHaveFPS(receiver, expectedFps, options) {
18
+ const isNot = this.isNot;
19
+ const operator = options?.operator ?? '>=';
20
+ const timeout = options?.timeout ?? 5000;
21
+ const startTime = Date.now();
22
+ let lastFps = 0;
23
+ while (Date.now() - startTime < timeout) {
24
+ try {
25
+ const metrics = await fetchMetrics(receiver);
26
+ lastFps = metrics.fps;
27
+ let pass = false;
28
+ if (operator === '===')
29
+ pass = Math.abs(lastFps - expectedFps) < 0.5;
30
+ else if (operator === '>')
31
+ pass = lastFps > expectedFps;
32
+ else if (operator === '>=')
33
+ pass = lastFps >= expectedFps;
34
+ else if (operator === '<')
35
+ pass = lastFps < expectedFps;
36
+ else if (operator === '<=')
37
+ pass = lastFps <= expectedFps;
38
+ if (pass === !isNot) {
39
+ return { pass: !isNot, message: () => 'passed' };
40
+ }
41
+ }
42
+ catch (e) { }
43
+ await new Promise(r => setTimeout(r, 100));
44
+ }
45
+ return {
46
+ pass: isNot,
47
+ message: () => `Expected FPS to${isNot ? ' not' : ''} be ${operator} ${expectedFps}, but got ${lastFps.toFixed(1)} FPS`,
48
+ actual: lastFps,
49
+ expected: expectedFps
50
+ };
51
+ },
52
+ async toHaveMinFPS(receiver, expectedMinFps, options) {
53
+ const isNot = this.isNot;
54
+ const timeout = options?.timeout ?? 5000;
55
+ const startTime = Date.now();
56
+ let lastFps = 0;
57
+ while (Date.now() - startTime < timeout) {
58
+ try {
59
+ const metrics = await fetchMetrics(receiver);
60
+ lastFps = metrics.fps;
61
+ const pass = lastFps >= expectedMinFps;
62
+ if (pass === !isNot) {
63
+ return { pass: !isNot, message: () => 'passed' };
64
+ }
65
+ }
66
+ catch (e) { }
67
+ await new Promise(r => setTimeout(r, 100));
68
+ }
69
+ return {
70
+ pass: isNot,
71
+ message: () => `Expected FPS to${isNot ? ' not' : ''} be >= ${expectedMinFps}, but got ${lastFps.toFixed(1)} FPS`,
72
+ actual: lastFps,
73
+ expected: expectedMinFps
74
+ };
75
+ },
76
+ async toHaveFrameTimeBelow(receiver, maxFrameTimeMs, options) {
77
+ const isNot = this.isNot;
78
+ const timeout = options?.timeout ?? 5000;
79
+ const startTime = Date.now();
80
+ let lastFrameTime = 0;
81
+ while (Date.now() - startTime < timeout) {
82
+ try {
83
+ const metrics = await fetchMetrics(receiver);
84
+ lastFrameTime = metrics.frameTimeMs;
85
+ const pass = lastFrameTime <= maxFrameTimeMs;
86
+ if (pass === !isNot) {
87
+ return { pass: !isNot, message: () => 'passed' };
88
+ }
89
+ }
90
+ catch (e) { }
91
+ await new Promise(r => setTimeout(r, 100));
92
+ }
93
+ return {
94
+ pass: isNot,
95
+ message: () => `Expected frame time to${isNot ? ' not' : ''} be <= ${maxFrameTimeMs}ms, but got ${lastFrameTime.toFixed(2)}ms`,
96
+ actual: lastFrameTime,
97
+ expected: maxFrameTimeMs
98
+ };
99
+ },
100
+ async toHaveMemoryBelow(receiver, maxMemoryMb, options) {
101
+ const isNot = this.isNot;
102
+ const timeout = options?.timeout ?? 5000;
103
+ const startTime = Date.now();
104
+ let lastMemoryMb = 0;
105
+ while (Date.now() - startTime < timeout) {
106
+ try {
107
+ const metrics = await fetchMetrics(receiver);
108
+ lastMemoryMb = metrics.memoryMb;
109
+ const pass = lastMemoryMb <= maxMemoryMb;
110
+ if (pass === !isNot) {
111
+ return { pass: !isNot, message: () => 'passed' };
112
+ }
113
+ }
114
+ catch (e) { }
115
+ await new Promise(r => setTimeout(r, 100));
116
+ }
117
+ return {
118
+ pass: isNot,
119
+ message: () => `Expected memory usage to${isNot ? ' not' : ''} be <= ${maxMemoryMb}MB, but got ${lastMemoryMb.toFixed(1)}MB`,
120
+ actual: lastMemoryMb,
121
+ expected: maxMemoryMb
122
+ };
123
+ },
124
+ async toMaintainPerformanceBudget(receiver, budget) {
125
+ const isNot = this.isNot;
126
+ const duration = budget.sampleDurationMs ?? 1000;
127
+ const interval = budget.sampleIntervalMs ?? 100;
128
+ const startTime = Date.now();
129
+ const samples = [];
130
+ while (Date.now() - startTime < duration) {
131
+ try {
132
+ const m = await fetchMetrics(receiver);
133
+ samples.push(m);
134
+ }
135
+ catch (e) { }
136
+ await new Promise(r => setTimeout(r, interval));
137
+ }
138
+ if (samples.length === 0) {
139
+ return {
140
+ pass: false,
141
+ message: () => `Failed to collect any performance samples from engine.`,
142
+ actual: 0,
143
+ expected: duration
144
+ };
145
+ }
146
+ const lowestFps = Math.min(...samples.map(s => s.fps));
147
+ const avgFps = samples.reduce((acc, s) => acc + s.fps, 0) / samples.length;
148
+ const highestFrameTime = Math.max(...samples.map(s => s.frameTimeMs));
149
+ const peakMemory = Math.max(...samples.map(s => s.memoryMb));
150
+ const violations = [];
151
+ if (budget.minFps !== undefined && lowestFps < budget.minFps) {
152
+ violations.push(`- Min FPS: ${lowestFps.toFixed(1)} (Budget floor: >= ${budget.minFps}) [FAILED]`);
153
+ }
154
+ if (budget.avgFps !== undefined && avgFps < budget.avgFps) {
155
+ violations.push(`- Avg FPS: ${avgFps.toFixed(1)} (Budget average: >= ${budget.avgFps}) [FAILED]`);
156
+ }
157
+ if (budget.maxFrameTimeMs !== undefined && highestFrameTime > budget.maxFrameTimeMs) {
158
+ violations.push(`- Peak Frame Time: ${highestFrameTime.toFixed(2)}ms (Budget ceiling: <= ${budget.maxFrameTimeMs}ms) [FAILED]`);
159
+ }
160
+ if (budget.maxMemoryMb !== undefined && peakMemory > budget.maxMemoryMb) {
161
+ violations.push(`- Peak Memory: ${peakMemory.toFixed(1)}MB (Budget ceiling: <= ${budget.maxMemoryMb}MB) [FAILED]`);
162
+ }
163
+ const pass = violations.length === 0;
164
+ const summary = `Collected ${samples.length} samples over ${duration}ms: ` +
165
+ `FPS(min: ${lowestFps.toFixed(1)}, avg: ${avgFps.toFixed(1)}), ` +
166
+ `FrameTime(peak: ${highestFrameTime.toFixed(2)}ms), ` +
167
+ `Memory(peak: ${peakMemory.toFixed(1)}MB)`;
168
+ if (pass === !isNot) {
169
+ return { pass: !isNot, message: () => 'passed', actual: summary, expected: budget };
170
+ }
171
+ return {
172
+ pass: isNot,
173
+ message: () => `Performance budget violation over ${duration}ms:\n${violations.join('\n')}\n${summary}`,
174
+ actual: summary,
175
+ expected: budget
176
+ };
177
+ }
178
+ }));
@@ -0,0 +1,42 @@
1
+ import { SpecterWorld } from '../core/specter-client';
2
+ import { SpecterLocator } from '../core/locators';
3
+ export interface MatchScreenshotOptions {
4
+ /** Allowed perceptual color difference threshold per pixel (0 to 1, default 0.2). */
5
+ threshold?: number;
6
+ /** Maximum allowed differing pixels. */
7
+ maxDiffPixels?: number;
8
+ /** Maximum allowed ratio of differing pixels (0 to 1, e.g. 0.02 for 2%). */
9
+ maxDiffPixelRatio?: number;
10
+ /** Whether to include UMG / Slate widgets in the screenshot (default false). */
11
+ showUI?: boolean;
12
+ /** Milliseconds to retry taking screenshots if the comparison fails (waits for visual stabilization). */
13
+ timeout?: number;
14
+ }
15
+ declare global {
16
+ namespace PlaywrightTest {
17
+ interface Matchers<R, T> {
18
+ toMatchScreenshot(this: Matchers<R, SpecterWorld | SpecterLocator>, snapshotName: string, options?: MatchScreenshotOptions): Promise<R>;
19
+ }
20
+ }
21
+ }
22
+ export interface VisualMatchers {
23
+ toMatchScreenshot(snapshotName: string, options?: MatchScreenshotOptions): Promise<void>;
24
+ }
25
+ export declare const visualExpect: import("playwright/test").Expect<{
26
+ toMatchScreenshot(this: import("playwright/test").ExpectMatcherState, receiver: any, snapshotName: string, options?: MatchScreenshotOptions): Promise<{
27
+ pass: true;
28
+ message: () => string;
29
+ actual?: undefined;
30
+ expected?: undefined;
31
+ } | {
32
+ pass: false;
33
+ message: () => string;
34
+ actual?: undefined;
35
+ expected?: undefined;
36
+ } | {
37
+ pass: boolean;
38
+ message: () => any;
39
+ actual: string;
40
+ expected: string;
41
+ }>;
42
+ }>;
@@ -0,0 +1,129 @@
1
+ "use strict";
2
+ var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
3
+ if (k2 === undefined) k2 = k;
4
+ var desc = Object.getOwnPropertyDescriptor(m, k);
5
+ if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
6
+ desc = { enumerable: true, get: function() { return m[k]; } };
7
+ }
8
+ Object.defineProperty(o, k2, desc);
9
+ }) : (function(o, m, k, k2) {
10
+ if (k2 === undefined) k2 = k;
11
+ o[k2] = m[k];
12
+ }));
13
+ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
14
+ Object.defineProperty(o, "default", { enumerable: true, value: v });
15
+ }) : function(o, v) {
16
+ o["default"] = v;
17
+ });
18
+ var __importStar = (this && this.__importStar) || (function () {
19
+ var ownKeys = function(o) {
20
+ ownKeys = Object.getOwnPropertyNames || function (o) {
21
+ var ar = [];
22
+ for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
23
+ return ar;
24
+ };
25
+ return ownKeys(o);
26
+ };
27
+ return function (mod) {
28
+ if (mod && mod.__esModule) return mod;
29
+ var result = {};
30
+ if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
31
+ __setModuleDefault(result, mod);
32
+ return result;
33
+ };
34
+ })();
35
+ Object.defineProperty(exports, "__esModule", { value: true });
36
+ exports.visualExpect = void 0;
37
+ const test_1 = require("@playwright/test");
38
+ const instrument_1 = require("./instrument");
39
+ const fs = __importStar(require("fs"));
40
+ exports.visualExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
41
+ async toMatchScreenshot(receiver, snapshotName, options) {
42
+ const isNot = this.isNot;
43
+ const normalizedName = snapshotName.endsWith('.png') ? snapshotName : `${snapshotName}.png`;
44
+ const timeout = options?.timeout ?? 0;
45
+ const startTime = Date.now();
46
+ const showUI = options?.showUI ?? false;
47
+ let lastError = null;
48
+ let lastScreenshotPath = '';
49
+ const pollUntil = startTime + timeout;
50
+ do {
51
+ try {
52
+ // 1. Take fresh screenshot from engine
53
+ const tempFileName = `specter_snap_${Date.now()}_${normalizedName}`;
54
+ if (typeof receiver.takeScreenshot === 'function') {
55
+ lastScreenshotPath = await receiver.takeScreenshot(tempFileName, showUI, { attach: false });
56
+ }
57
+ else if (typeof receiver.evaluate === 'function') {
58
+ const res = await receiver.evaluate('TakeScreenshot', { fileName: tempFileName, showUI });
59
+ lastScreenshotPath = res?.data?.savedPath ?? '';
60
+ }
61
+ else {
62
+ throw new Error(`toMatchScreenshot must be called on SpecterWorld or a SpecterLocator. Received: ${typeof receiver}`);
63
+ }
64
+ if (!lastScreenshotPath || !fs.existsSync(lastScreenshotPath)) {
65
+ throw new Error(`Screenshot was not saved to disk: ${lastScreenshotPath}`);
66
+ }
67
+ // 2. Read image buffer
68
+ const imageBuffer = await fs.promises.readFile(lastScreenshotPath);
69
+ // 3. Delegate to Playwright's built-in visual comparator
70
+ // Playwright compares imageBuffer against __snapshots__/<normalizedName>
71
+ const snapshotOptions = {};
72
+ if (options?.threshold !== undefined)
73
+ snapshotOptions.threshold = options.threshold;
74
+ if (options?.maxDiffPixels !== undefined)
75
+ snapshotOptions.maxDiffPixels = options.maxDiffPixels;
76
+ if (options?.maxDiffPixelRatio !== undefined)
77
+ snapshotOptions.maxDiffPixelRatio = options.maxDiffPixelRatio;
78
+ try {
79
+ (0, test_1.expect)(imageBuffer).toMatchSnapshot(normalizedName, snapshotOptions);
80
+ // Attach matching screenshot to test report
81
+ try {
82
+ test_1.test.info().attachments.push({
83
+ name: normalizedName,
84
+ path: lastScreenshotPath,
85
+ contentType: 'image/png'
86
+ });
87
+ }
88
+ catch { }
89
+ if (!isNot) {
90
+ return { pass: true, message: () => 'passed' };
91
+ }
92
+ }
93
+ catch (compareError) {
94
+ lastError = compareError;
95
+ if (isNot) {
96
+ return { pass: false, message: () => 'passed' };
97
+ }
98
+ }
99
+ }
100
+ catch (e) {
101
+ lastError = e;
102
+ }
103
+ if (timeout > 0 && Date.now() < pollUntil) {
104
+ await new Promise(r => setTimeout(r, 200));
105
+ }
106
+ else {
107
+ break;
108
+ }
109
+ } while (Date.now() < pollUntil);
110
+ // Attach last taken image for inspection on failure
111
+ if (lastScreenshotPath && fs.existsSync(lastScreenshotPath)) {
112
+ try {
113
+ test_1.test.info().attachments.push({
114
+ name: `actual-${normalizedName}`,
115
+ path: lastScreenshotPath,
116
+ contentType: 'image/png'
117
+ });
118
+ }
119
+ catch { }
120
+ }
121
+ const failureMessage = lastError?.message || `Screenshot did not match baseline '${normalizedName}'`;
122
+ return {
123
+ pass: isNot,
124
+ message: () => failureMessage,
125
+ actual: `actual-${normalizedName}`,
126
+ expected: normalizedName
127
+ };
128
+ }
129
+ }));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.126",
3
+ "version": "1.0.128",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",