@specter-automation/test 1.0.159 → 1.0.161

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.
@@ -129,6 +129,11 @@ export interface SpecterDiagnosticsReport {
129
129
  worldTime: number;
130
130
  deltaSeconds: number;
131
131
  };
132
+ /** What the test before this one left changed: a moved pawn or camera, a screen left open, pause */
133
+ previousTestLeftChanged?: {
134
+ test: string;
135
+ changes: string[];
136
+ };
132
137
  }
133
138
  export type { Vector3, Vector2D, Rotator, Transform } from './specter-math';
134
139
  export { VectorUtils, RotatorUtils, resolveVector3, resolveRotator, normalizeAxis, findLookAtRotation, getRotationBetween, calculateDistance, calculateDistance2D, normalizeRotator, deltaRotator } from './specter-math';
@@ -570,6 +575,17 @@ export declare class SpecterWorld {
570
575
  map: string;
571
576
  serverAddress: string;
572
577
  }>;
578
+ /**
579
+ * Notes the state a test can leave behind for the next one (each player's pawn and camera, the screens
580
+ * showing, pause, time dilation). The test fixture calls it when a test starts; `endLeftStateCheck` compares.
581
+ * Does nothing on a plugin that doesn't have it.
582
+ */
583
+ beginLeftStateCheck(testName: string): Promise<void>;
584
+ /**
585
+ * What changed since `beginLeftStateCheck`, after the test's afterEach hooks. Specter can't put the game
586
+ * back itself (only the game knows its starting state), but the next test's failure report names these.
587
+ */
588
+ endLeftStateCheck(): Promise<string[]>;
573
589
  cleanup(): Promise<void>;
574
590
  /**
575
591
  * Restores the primary PlayerController to its pre-possession state
@@ -1209,6 +1209,32 @@ class SpecterWorld {
1209
1209
  const response = await this.evaluate("GetNetworkStatus", {});
1210
1210
  return response.data;
1211
1211
  }
1212
+ /**
1213
+ * Notes the state a test can leave behind for the next one (each player's pawn and camera, the screens
1214
+ * showing, pause, time dilation). The test fixture calls it when a test starts; `endLeftStateCheck` compares.
1215
+ * Does nothing on a plugin that doesn't have it.
1216
+ */
1217
+ async beginLeftStateCheck(testName) {
1218
+ try {
1219
+ await this.evaluate("BeginLeftStateCheck", { testName }, undefined, undefined, true);
1220
+ }
1221
+ catch (e) {
1222
+ // An older plugin: no check
1223
+ }
1224
+ }
1225
+ /**
1226
+ * What changed since `beginLeftStateCheck`, after the test's afterEach hooks. Specter can't put the game
1227
+ * back itself (only the game knows its starting state), but the next test's failure report names these.
1228
+ */
1229
+ async endLeftStateCheck() {
1230
+ try {
1231
+ const response = await this.evaluate("EndLeftStateCheck", {}, undefined, undefined, true);
1232
+ return Array.isArray(response?.data?.changes) ? response.data.changes : [];
1233
+ }
1234
+ catch (e) {
1235
+ return [];
1236
+ }
1237
+ }
1212
1238
  async cleanup() {
1213
1239
  if (!this.transport.isConnected)
1214
1240
  return;
@@ -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", "toHaveRotation", "toBeFacing", "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", "toBeHidden", "toHavePropertyValue", "toBeInViewport", "toBeDestroyed", "toHaveCount", "toHaveText", "toHaveValue", "toContainText", "toBeEnabled", "toBeDisabled", "toHaveMaterialScalarParameter", "toHaveMaterialVectorParameter", "toHaveMaterial", "toBeDynamicMaterial", "toHaveMaterialTextureParameter", "toHaveBlackboardValue", "toHaveAIState", "toBeMovingTowards", "toBeMovingAwayFrom", "toBeWithinDistance", "toBeFollowing", "toHaveLineOfSightTo", "toBeRunningBehaviorTree", "toBeInState", "toHaveBlackboardChange", "toHaveVisitedState", "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", "toHaveRotation", "toBeFacing", "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", "toBeHidden", "toHavePropertyValue", "toBeInViewport", "toBeDestroyed", "toHaveCount", "toHaveText", "toHaveValue", "toContainText", "toBeEnabled", "toBeDisabled", "toOverlap", "toHaveMaterialScalarParameter", "toHaveMaterialVectorParameter", "toHaveMaterial", "toBeDynamicMaterial", "toHaveMaterialTextureParameter", "toHaveBlackboardValue", "toHaveAIState", "toBeMovingTowards", "toBeMovingAwayFrom", "toBeWithinDistance", "toBeFollowing", "toHaveLineOfSightTo", "toBeRunningBehaviorTree", "toBeInState", "toHaveBlackboardChange", "toHaveVisitedState", "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"`.
@@ -26,7 +26,7 @@ exports.SPECTER_MATCHER_NAMES = [
26
26
  // locator-matchers
27
27
  'toBeVisible', 'toBeHidden', 'toHavePropertyValue', 'toBeInViewport', 'toBeDestroyed', 'toHaveCount',
28
28
  // widget-matchers
29
- 'toHaveText', 'toHaveValue', 'toContainText', 'toBeEnabled', 'toBeDisabled',
29
+ 'toHaveText', 'toHaveValue', 'toContainText', 'toBeEnabled', 'toBeDisabled', 'toOverlap',
30
30
  // material-matchers
31
31
  'toHaveMaterialScalarParameter', 'toHaveMaterialVectorParameter', 'toHaveMaterial',
32
32
  'toBeDynamicMaterial', 'toHaveMaterialTextureParameter',
@@ -79,11 +79,20 @@ const extendedTest = test_1.test.extend({
79
79
  if (fixedDeltaSeconds && fixedDeltaSeconds > 0) {
80
80
  await world.console(`r.FixedDeltaTime ${fixedDeltaSeconds}`);
81
81
  }
82
+ // Tests share one game: note what this one might leave changed for the next
83
+ await world.beginLeftStateCheck(testInfo.titlePath.slice(1).join(' > '));
82
84
  try {
83
85
  await use(world);
84
86
  }
85
87
  finally {
86
88
  (0, failure_capture_1.setActiveWorld)(null);
89
+ // After afterEach: what this test left changed. Said here, on the test that did it, and again in the
90
+ // next test's failure report.
91
+ const leftChanged = await world.endLeftStateCheck();
92
+ if (leftChanged.length > 0) {
93
+ console.warn(`[SPECTER] This test left the game changed for the next test:\n${leftChanged.map(change => ` - ${change}`).join('\n')}\n` +
94
+ ` Specter can't reset game state (only the game knows its start). Reset it in your fixture or afterEach if later tests depend on it.`);
95
+ }
87
96
  // Teardown: Reset fixed delta time if configured
88
97
  if (fixedDeltaSeconds && fixedDeltaSeconds > 0) {
89
98
  try {
@@ -69,6 +69,16 @@ function formatAiDiagnostics(diagnostics) {
69
69
  lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
70
70
  lines.push('🧠 SPECTER AI DIAGNOSTICS REPORT');
71
71
  lines.push('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
72
+ // 0. What the test before this one left changed. First: in a full run it's often the whole story.
73
+ const left = diagnostics.previousTestLeftChanged;
74
+ if (left?.changes?.length) {
75
+ lines.push(`⚠️ The previous test${left.test ? ` ("${left.test}")` : ''} left the game changed:`);
76
+ for (const change of left.changes) {
77
+ lines.push(` • ${change}`);
78
+ }
79
+ lines.push(' If this test expects the starting state, reset it in the project\'s fixture or a beforeEach/afterEach.');
80
+ lines.push('');
81
+ }
72
82
  // 1. Actor Identity Mapping
73
83
  if (diagnostics.actorMap && Object.keys(diagnostics.actorMap).length > 0) {
74
84
  lines.push('📍 Actor Identity Mapping:');
@@ -37,6 +37,20 @@ declare global {
37
37
  toBeDisabled(options?: {
38
38
  timeout?: number;
39
39
  }): T extends WidgetLocator ? Promise<R> : never;
40
+ /**
41
+ * Asserts that the widget overlaps another on screen. Mostly used negated, to catch one panel drawn
42
+ * over another:
43
+ * - `await expect(selectionBar).not.toOverlap(toolbar)`: these two don't overlap;
44
+ * - `await expect(selectionBar).not.toOverlap()`: it overlaps nothing. "Anything" is every visible widget
45
+ * that draws (text, images, buttons, borders), except the widget's own contents and the panels it sits in.
46
+ *
47
+ * Compares rectangles in screen pixels. A widget that isn't visible overlaps nothing; touching edges don't count.
48
+ * - `threshold`: how much of the smaller widget must be covered to count, in percent (default 0: any overlap).
49
+ * - `ignore` (no other widget): names, classes or owning widgets meant to be underneath, as text or patterns.
50
+ * Auto-retries for up to `timeout` ms (default: 5000). With no other widget, needs a plugin with GetOverlappingWidgets.
51
+ */
52
+ toOverlap(other?: WidgetLocator, options?: OverlapOptions): T extends WidgetLocator ? Promise<R> : never;
53
+ toOverlap(options?: OverlapOptions): T extends WidgetLocator ? Promise<R> : never;
40
54
  }
41
55
  }
42
56
  }
@@ -56,6 +70,15 @@ export interface WidgetMatchers {
56
70
  toBeDisabled(options?: {
57
71
  timeout?: number;
58
72
  }): Promise<void>;
73
+ toOverlap(other?: WidgetLocator, options?: OverlapOptions): Promise<void>;
74
+ toOverlap(options?: OverlapOptions): Promise<void>;
75
+ }
76
+ export interface OverlapOptions {
77
+ /** How much of the smaller widget must be covered to count as overlapping, in percent. Default 0: any overlap. */
78
+ threshold?: number;
79
+ /** With no other widget: names, classes or owning widgets to leave out (backgrounds meant to be underneath) */
80
+ ignore?: Array<string | RegExp>;
81
+ timeout?: number;
59
82
  }
60
83
  export declare const widgetExpect: import("playwright/test").Expect<{
61
84
  toHaveText(this: import("playwright/test").ExpectMatcherState, locator: WidgetLocator, expectedText: string, options?: {
@@ -88,6 +111,10 @@ export declare const widgetExpect: import("playwright/test").Expect<{
88
111
  pass: boolean;
89
112
  message: () => string;
90
113
  }>;
114
+ toOverlap(this: import("playwright/test").ExpectMatcherState, locator: WidgetLocator, otherOrOptions?: WidgetLocator | OverlapOptions, maybeOptions?: OverlapOptions): Promise<{
115
+ pass: boolean;
116
+ message: () => string;
117
+ }>;
91
118
  toBeDisabled(this: import("playwright/test").ExpectMatcherState, locator: WidgetLocator, options?: {
92
119
  timeout?: number;
93
120
  }): Promise<{
@@ -3,9 +3,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.widgetExpect = void 0;
4
4
  const test_1 = require("@playwright/test");
5
5
  const instrument_1 = require("./instrument");
6
- // ============================================================
7
- // SHARED POLLING HELPER
8
- // ============================================================
6
+ const widget_locator_1 = require("../core/locators/widget-locator");
7
+ /** A widget's rectangle in screen pixels. `pixelSize` comes from newer plugins; older ones give the centre, which is enough. */
8
+ async function screenRect(locator) {
9
+ const geometry = await locator.getGeometry();
10
+ const width = geometry.pixelSize?.width ?? 2 * (geometry.center.x - geometry.position.x);
11
+ const height = geometry.pixelSize?.height ?? 2 * (geometry.center.y - geometry.position.y);
12
+ return {
13
+ left: geometry.position.x,
14
+ top: geometry.position.y,
15
+ right: geometry.position.x + width,
16
+ bottom: geometry.position.y + height,
17
+ visible: geometry.isVisible !== false && geometry.isRendered !== false,
18
+ };
19
+ }
20
+ function describeRect(rect) {
21
+ return `(${Math.round(rect.left)}, ${Math.round(rect.top)}) to (${Math.round(rect.right)}, ${Math.round(rect.bottom)})`;
22
+ }
9
23
  async function poll(fn, check, timeout) {
10
24
  const startTime = Date.now();
11
25
  let last = undefined;
@@ -71,6 +85,96 @@ exports.widgetExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)
71
85
  };
72
86
  })();
73
87
  },
88
+ async toOverlap(locator, otherOrOptions, maybeOptions) {
89
+ const isNot = this.isNot;
90
+ const other = otherOrOptions instanceof widget_locator_1.WidgetLocator ? otherOrOptions : undefined;
91
+ const options = (otherOrOptions instanceof widget_locator_1.WidgetLocator ? maybeOptions : otherOrOptions) ?? {};
92
+ const timeout = options.timeout ?? 5000;
93
+ const threshold = Math.max(0, options.threshold ?? 0);
94
+ const ignore = options.ignore ?? [];
95
+ // How much of the smaller widget is covered, in percent: a small badge fully under a big panel is 100
96
+ const percentCovered = (a, b, overlapX, overlapY) => {
97
+ const smaller = Math.min((a.right - a.left) * (a.bottom - a.top), (b.right - b.left) * (b.bottom - b.top));
98
+ return smaller > 0 ? (100 * overlapX * overlapY) / smaller : 0;
99
+ };
100
+ const counts = (overlapX, overlapY, percent) => overlapX > 0 && overlapY > 0 && percent > threshold;
101
+ const thresholdText = threshold > 0 ? ` (counting overlaps over ${threshold}% of the smaller widget)` : '';
102
+ if (other) {
103
+ const read = async () => {
104
+ const [a, b] = await Promise.all([screenRect(locator), screenRect(other)]);
105
+ const overlapX = Math.min(a.right, b.right) - Math.max(a.left, b.left);
106
+ const overlapY = Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top);
107
+ const percent = percentCovered(a, b, overlapX, overlapY);
108
+ const overlaps = a.visible && b.visible && counts(overlapX, overlapY, percent);
109
+ return { a, b, overlapX, overlapY, percent, overlaps };
110
+ };
111
+ const { passed, last } = await poll(read, reading => isNot ? !reading.overlaps : reading.overlaps, timeout);
112
+ const names = `${locator.toString()} and ${other.toString()}`;
113
+ return {
114
+ pass: isNot ? !passed : passed,
115
+ message: () => {
116
+ if (!last) {
117
+ return `Couldn't read the geometry of ${names} (do both exist?).`;
118
+ }
119
+ const where = `\n ${locator.toString()}: ${describeRect(last.a)}${last.a.visible ? '' : ' (not visible)'}` +
120
+ `\n ${other.toString()}: ${describeRect(last.b)}${last.b.visible ? '' : ' (not visible)'}`;
121
+ return last.overlaps
122
+ ? `Expected ${names} not to overlap${thresholdText}, but they overlap by ${Math.round(last.overlapX)} x ${Math.round(last.overlapY)} px ` +
123
+ `(${Math.round(last.percent)}% of the smaller one).${where}`
124
+ : `Expected ${names} to overlap${thresholdText}, but they don't.${where}`;
125
+ }
126
+ };
127
+ }
128
+ // No other widget: anything visible on screen that isn't the widget's own contents or the panels it sits in
129
+ const isIgnored = (entry) => ignore.some(pattern => [entry.name, entry.className, entry.in].some(text => !!text && (typeof pattern === 'string' ? text.includes(pattern) : pattern.test(text))));
130
+ const read = async () => {
131
+ const response = await locator.evaluate("GetOverlappingWidgets", {}, undefined, true);
132
+ if (response?.status && response.status !== 'success') {
133
+ throw new Error(response.error ?? 'GetOverlappingWidgets failed');
134
+ }
135
+ const data = response?.data ?? {};
136
+ if (!data.isVisible || !data.rect) {
137
+ return { visible: false, hits: [] };
138
+ }
139
+ const rect = { ...data.rect, visible: true };
140
+ const hits = (data.overlaps ?? [])
141
+ .filter(entry => !isIgnored(entry))
142
+ .map(entry => ({ ...entry, percent: percentCovered(rect, { ...entry.rect, visible: true }, entry.overlapWidth, entry.overlapHeight) }))
143
+ .filter(entry => counts(entry.overlapWidth, entry.overlapHeight, entry.percent))
144
+ .sort((x, y) => y.percent - x.percent);
145
+ return { visible: true, rect, hits };
146
+ };
147
+ let readError;
148
+ const { passed, last } = await poll(async () => {
149
+ try {
150
+ return await read();
151
+ }
152
+ catch (e) {
153
+ readError = e;
154
+ throw e;
155
+ }
156
+ }, reading => isNot ? reading.hits.length === 0 : reading.hits.length > 0, timeout);
157
+ return {
158
+ pass: isNot ? !passed : passed,
159
+ message: () => {
160
+ if (!last) {
161
+ const why = readError?.message?.includes('Unknown command')
162
+ ? 'this needs a newer Specter plugin (GetOverlappingWidgets)'
163
+ : (readError?.message ?? 'does it exist?');
164
+ return `Couldn't check what ${locator.toString()} overlaps: ${why}.`;
165
+ }
166
+ if (!isNot) {
167
+ return `Expected ${locator.toString()} to overlap another widget${thresholdText}, but it ${last.visible ? "doesn't" : "isn't visible"}.`;
168
+ }
169
+ const lines = last.hits.slice(0, 8).map(hit => ` - ${hit.name} (${hit.className}${hit.in ? ` in ${hit.in}` : ''}): ${Math.round(hit.overlapWidth)} x ${Math.round(hit.overlapHeight)} px, ` +
170
+ `${Math.round(hit.percent)}% of the smaller widget, at ${describeRect({ ...hit.rect, visible: true })}`);
171
+ const more = last.hits.length > 8 ? `\n ...and ${last.hits.length - 8} more` : '';
172
+ return `Expected ${locator.toString()} not to overlap anything${thresholdText}, but it overlaps ${last.hits.length} widget(s).\n` +
173
+ ` ${locator.toString()}: ${describeRect(last.rect)}\n${lines.join('\n')}${more}\n` +
174
+ ` (Leave out widgets that are meant to be underneath with { ignore: ["WBP_Background", /Vignette/] }.)`;
175
+ }
176
+ };
177
+ },
74
178
  async toBeDisabled(locator, options) {
75
179
  const isNot = this.isNot;
76
180
  const timeout = options?.timeout ?? 5000;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.159",
3
+ "version": "1.0.161",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",