@specter-automation/test 1.0.155 → 1.0.157

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.
@@ -140,6 +140,12 @@ export declare class WidgetLocator<T = any> extends SpecterLocator<T> {
140
140
  * Queries the UMG Slate system to see if the widget is actively drawn on screen.
141
141
  */
142
142
  isEnabled(): Promise<boolean>;
143
+ /** Why the last checkVisibility() said the widget isn't visible (a collapsed parent, an inactive switcher page...) */
144
+ lastHiddenReason: string | undefined;
145
+ /**
146
+ * Whether a player can see the widget: it and everything above it are shown, it's on its switcher's
147
+ * active page, and its screen is still attached to a window.
148
+ */
143
149
  checkVisibility(): Promise<boolean>;
144
150
  /**
145
151
  * Calculates the A* path and moves hardware focus to the widget.
@@ -368,10 +368,18 @@ class WidgetLocator extends specter_locator_1.SpecterLocator {
368
368
  const response = await this.evaluate("IsWidgetEnabled", {});
369
369
  return response.data.isEnabled;
370
370
  }
371
+ /** Why the last checkVisibility() said the widget isn't visible (a collapsed parent, an inactive switcher page...) */
372
+ lastHiddenReason;
373
+ /**
374
+ * Whether a player can see the widget: it and everything above it are shown, it's on its switcher's
375
+ * active page, and its screen is still attached to a window.
376
+ */
371
377
  async checkVisibility() {
372
378
  try {
373
379
  const response = await this.evaluate("CheckWidgetVisibility", {}, undefined, true);
374
- return response?.data?.isVisible === true;
380
+ const visible = response?.data?.isVisible === true;
381
+ this.lastHiddenReason = visible ? undefined : response?.data?.reason;
382
+ return visible;
375
383
  }
376
384
  catch (e) {
377
385
  const msg = e instanceof Error ? e.message : String(e);
@@ -212,6 +212,8 @@ export declare class SpecterTransport {
212
212
  /** Keys pressed through pressKey and not released yet. World cleanup releases them after each test. */
213
213
  readonly heldKeys: Set<string>;
214
214
  private pendingRequests;
215
+ /** Commands that timed out here (id -> command), so a late reply can be named instead of logged as a stray broadcast */
216
+ private timedOutRequests;
215
217
  private eventListeners;
216
218
  recentEvents: Array<{
217
219
  eventKey: string;
@@ -49,6 +49,8 @@ class SpecterTransport {
49
49
  heldKeys = new Set();
50
50
  // The Enterprise Fix: Routing responses to the correct Promise
51
51
  pendingRequests = new Map();
52
+ /** Commands that timed out here (id -> command), so a late reply can be named instead of logged as a stray broadcast */
53
+ timedOutRequests = new Map();
52
54
  eventListeners = new Map();
53
55
  // Buffered recent events to eliminate race conditions between event arrival and listener attachment
54
56
  recentEvents = [];
@@ -303,9 +305,14 @@ class SpecterTransport {
303
305
  if (responseObj.messageId && this.pendingRequests.has(responseObj.messageId)) {
304
306
  const promiseHandlers = this.pendingRequests.get(responseObj.messageId);
305
307
  if (responseObj.status === 'error') {
306
- const errMsg = responseObj.error.startsWith('Specter C++ Error:')
308
+ // An error can arrive without its text. Reading it unguarded threw in here, and every
309
+ // later command then timed out, hiding the real failure.
310
+ const errText = typeof responseObj.error === 'string' && responseObj.error.trim()
307
311
  ? responseObj.error
308
- : `Specter C++ Error: ${responseObj.error}`;
312
+ : 'the engine reported an error without a message';
313
+ const errMsg = errText.startsWith('Specter C++ Error:')
314
+ ? errText
315
+ : `Specter C++ Error: ${errText}`;
309
316
  const error = new Error(errMsg);
310
317
  if (promiseHandlers.callSiteStack) {
311
318
  error.stack = `${error.name}: ${error.message}\n` + promiseHandlers.callSiteStack.split('\n').slice(2).join('\n');
@@ -317,6 +324,12 @@ class SpecterTransport {
317
324
  }
318
325
  this.pendingRequests.delete(responseObj.messageId);
319
326
  }
327
+ else if (responseObj.messageId && this.timedOutRequests.has(responseObj.messageId)) {
328
+ // The answer to a command that already timed out here: say so, with what the engine said
329
+ const command = this.timedOutRequests.get(responseObj.messageId);
330
+ this.timedOutRequests.delete(responseObj.messageId);
331
+ console.log(`[SPECTER] Late reply to [${command}], which had already timed out:`, responseObj.status === 'error' ? (responseObj.error ?? 'error without a message') : responseObj.status);
332
+ }
320
333
  else {
321
334
  // Catch-all for anything else the engine might spit out
322
335
  console.log("[SPECTER] Unhandled Engine Broadcast:", responseObj);
@@ -334,18 +347,24 @@ class SpecterTransport {
334
347
  return new Promise((resolve, reject) => {
335
348
  // Register the promise BEFORE sending the payload
336
349
  this.pendingRequests.set(payload.messageId, { resolve, reject, callSiteStack: callSiteError.stack });
337
- // 5-second timeout safety net
350
+ // Timeout safety net. The engine gives a screenshot 5 s to render before it answers with the reason
351
+ // it couldn't; waiting the same 5 s here lost that answer, so a screenshot gets longer.
352
+ const timeoutMs = payload.command === 'TakeScreenshot' ? 12000 : 5000;
338
353
  setTimeout(() => {
339
354
  if (this.pendingRequests.has(payload.messageId)) {
340
355
  const handlers = this.pendingRequests.get(payload.messageId);
341
356
  this.pendingRequests.delete(payload.messageId);
342
- const error = new Error(`Specter Timeout: No response for command [${payload.command}] after 5000ms.`);
357
+ this.timedOutRequests.set(payload.messageId, String(payload.command));
358
+ if (this.timedOutRequests.size > 50) {
359
+ this.timedOutRequests.delete(this.timedOutRequests.keys().next().value);
360
+ }
361
+ const error = new Error(`Specter Timeout: No response for command [${payload.command}] after ${timeoutMs}ms.`);
343
362
  if (handlers.callSiteStack) {
344
363
  error.stack = `${error.name}: ${error.message}\n` + handlers.callSiteStack.split('\n').slice(2).join('\n');
345
364
  }
346
365
  reject(error);
347
366
  }
348
- }, 5000);
367
+ }, timeoutMs);
349
368
  this.ws.send(JSON.stringify(payload));
350
369
  });
351
370
  }
@@ -16,14 +16,10 @@ class SpecterKeyboard {
16
16
  if (typeof options === 'object' && (options.until || options.while || options.when)) {
17
17
  await (0, input_conditions_1.runConditionalInputLoop)({
18
18
  driveFn: async () => {
19
- await this.world.evaluate('PressKey', {
20
- payload: { key: key, eventType: 'Pressed' }
21
- });
19
+ await this.world.evaluate('PressKey', { key, eventType: 'Pressed' }, key);
22
20
  },
23
21
  releaseFn: async () => {
24
- await this.world.evaluate('PressKey', {
25
- payload: { key: key, eventType: 'Released' }
26
- });
22
+ await this.world.evaluate('PressKey', { key, eventType: 'Released' }, key);
27
23
  },
28
24
  options
29
25
  });
@@ -31,17 +27,13 @@ class SpecterKeyboard {
31
27
  }
32
28
  const holdDurationMs = typeof options === 'number' ? options : (options?.timeout ?? 50);
33
29
  // 1. Fire the Down stroke
34
- await this.world.evaluate('PressKey', {
35
- payload: { key: key, eventType: 'Pressed' }
36
- });
30
+ await this.world.evaluate('PressKey', { key, eventType: 'Pressed' }, key);
37
31
  // 2. Wait to simulate a human holding the key (critical for "Hold to interact" mechanics)
38
32
  if (holdDurationMs > 0) {
39
33
  await new Promise(resolve => setTimeout(resolve, holdDurationMs));
40
34
  }
41
35
  // 3. Fire the Up stroke
42
- await this.world.evaluate('PressKey', {
43
- payload: { key: key, eventType: 'Released' }
44
- });
36
+ await this.world.evaluate('PressKey', { key, eventType: 'Released' }, key);
45
37
  }
46
38
  /**
47
39
  * Holds a key down indefinitely or with conditional options.
@@ -51,13 +43,13 @@ class SpecterKeyboard {
51
43
  await this.press(key, options);
52
44
  return;
53
45
  }
54
- await this.world.evaluate('PressKey', { payload: { key, eventType: 'Pressed' } });
46
+ await this.world.evaluate('PressKey', { key, eventType: 'Pressed' }, key);
55
47
  }
56
48
  /**
57
49
  * Releases a held key.
58
50
  */
59
51
  async up(key) {
60
- await this.world.evaluate('PressKey', { payload: { key, eventType: 'Released' } });
52
+ await this.world.evaluate('PressKey', { key, eventType: 'Released' }, key);
61
53
  }
62
54
  }
63
55
  exports.SpecterKeyboard = SpecterKeyboard;
@@ -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", "toHavePropertyValue", "toBeInViewport", "toBeDestroyed", "toHaveCount", "toHaveText", "toHaveValue", "toContainText", "toBeEnabled", "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", "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"`.
@@ -24,9 +24,9 @@ exports.SPECTER_MATCHER_NAMES = [
24
24
  'toBePlayerControlled', 'toBeLocallyControlled', 'toHaveController', 'toBeFalling', 'toBeSwimming',
25
25
  'toBeFlying', 'toBeCrouching', 'toBeMovingOnGround', 'toHaveMovementMode',
26
26
  // locator-matchers
27
- 'toBeVisible', 'toHavePropertyValue', 'toBeInViewport', 'toBeDestroyed', 'toHaveCount',
27
+ 'toBeVisible', 'toBeHidden', 'toHavePropertyValue', 'toBeInViewport', 'toBeDestroyed', 'toHaveCount',
28
28
  // widget-matchers
29
- 'toHaveText', 'toHaveValue', 'toContainText', 'toBeEnabled',
29
+ 'toHaveText', 'toHaveValue', 'toContainText', 'toBeEnabled', 'toBeDisabled',
30
30
  // material-matchers
31
31
  'toHaveMaterialScalarParameter', 'toHaveMaterialVectorParameter', 'toHaveMaterial',
32
32
  'toBeDynamicMaterial', 'toHaveMaterialTextureParameter',
@@ -13,6 +13,14 @@ declare global {
13
13
  onScreen?: boolean;
14
14
  timeout?: number;
15
15
  }): Promise<R>;
16
+ /**
17
+ * Asserts that a player can't see the actor or widget: it is hidden, something above it is hidden,
18
+ * it's on a switcher page that isn't showing, or it doesn't exist. The opposite of toBeVisible.
19
+ * Auto-retries for up to `timeout` ms (default: 5000).
20
+ */
21
+ toBeHidden(this: Matchers<R, ActorLocator | WidgetLocator>, options?: {
22
+ timeout?: number;
23
+ }): Promise<R>;
16
24
  toBeInViewport(this: Matchers<R, ActorLocator>, options?: {
17
25
  timeout?: number;
18
26
  }): Promise<R>;
@@ -34,6 +42,9 @@ export interface LocatorMatchers {
34
42
  onScreen?: boolean;
35
43
  timeout?: number;
36
44
  }): Promise<void>;
45
+ toBeHidden(options?: {
46
+ timeout?: number;
47
+ }): Promise<void>;
37
48
  toBeInViewport(options?: {
38
49
  timeout?: number;
39
50
  }): Promise<void>;
@@ -67,6 +78,12 @@ export declare const locatorExpect: import("playwright/test").Expect<{
67
78
  pass: any;
68
79
  message: () => string;
69
80
  }>;
81
+ toBeHidden(this: import("playwright/test").ExpectMatcherState, locator: any, options?: {
82
+ timeout?: number;
83
+ }): Promise<{
84
+ pass: boolean;
85
+ message: () => string;
86
+ }>;
70
87
  toBeInViewport(this: import("playwright/test").ExpectMatcherState, locator: any, options?: {
71
88
  timeout?: number;
72
89
  }): Promise<{
@@ -103,6 +103,8 @@ async function checkVisible(assertionName, locator, options) {
103
103
  `Timed out after ${pollTimeout}ms waiting for element to be ${isNot ? 'not visible' : 'visible'}.\n` +
104
104
  `Expected: ${this.utils.printExpected(isNot ? 'Not Visible' : 'Visible')}\n` +
105
105
  `Received: ${this.utils.printReceived(isNot ? 'Visible' : 'Not Visible')}\n` +
106
+ // The engine's reason: "'DrillDownHBox' above it is Collapsed", "a page of the switcher that isn't showing"...
107
+ (!isNot && isWidget && locator.lastHiddenReason ? `Not visible because ${locator.lastHiddenReason}.\n` : '') +
106
108
  // Optional: If it failed for a reason OTHER than "0 objects", print it here
107
109
  (errorMessage.includes('0 objects') ? '' : `\nUnderlying Engine Error: ${errorMessage}`)
108
110
  };
@@ -184,6 +186,13 @@ exports.locatorExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers
184
186
  options) {
185
187
  return checkVisible.call(this, 'toBeVisible', locator, options);
186
188
  },
189
+ async toBeHidden(locator, options) {
190
+ // toBeVisible with the expectation turned round: the same polling, strict-mode handling and messages
191
+ const flipped = Object.create(this);
192
+ Object.defineProperty(flipped, 'isNot', { value: !this.isNot });
193
+ const result = await checkVisible.call(flipped, 'toBeHidden', locator, { timeout: options?.timeout });
194
+ return { ...result, pass: !result.pass };
195
+ },
187
196
  async toBeInViewport(locator, options) {
188
197
  return checkVisible.call(this, 'toBeInViewport', locator, { onScreen: true, timeout: options?.timeout });
189
198
  },
@@ -30,6 +30,13 @@ declare global {
30
30
  toBeEnabled(options?: {
31
31
  timeout?: number;
32
32
  }): T extends WidgetLocator ? Promise<R> : never;
33
+ /**
34
+ * Asserts that the widget is disabled (greyed out, not taking input). The opposite of toBeEnabled.
35
+ * Auto-retries for up to `timeout` ms (default: 5000).
36
+ */
37
+ toBeDisabled(options?: {
38
+ timeout?: number;
39
+ }): T extends WidgetLocator ? Promise<R> : never;
33
40
  }
34
41
  }
35
42
  }
@@ -46,6 +53,9 @@ export interface WidgetMatchers {
46
53
  toBeEnabled(options?: {
47
54
  timeout?: number;
48
55
  }): Promise<void>;
56
+ toBeDisabled(options?: {
57
+ timeout?: number;
58
+ }): Promise<void>;
49
59
  }
50
60
  export declare const widgetExpect: import("playwright/test").Expect<{
51
61
  toHaveText(this: import("playwright/test").ExpectMatcherState, locator: WidgetLocator, expectedText: string, options?: {
@@ -78,4 +88,10 @@ export declare const widgetExpect: import("playwright/test").Expect<{
78
88
  pass: boolean;
79
89
  message: () => string;
80
90
  }>;
91
+ toBeDisabled(this: import("playwright/test").ExpectMatcherState, locator: WidgetLocator, options?: {
92
+ timeout?: number;
93
+ }): Promise<{
94
+ pass: boolean;
95
+ message: () => string;
96
+ }>;
81
97
  }>;
@@ -70,5 +70,16 @@ exports.widgetExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)
70
70
  message: () => `Expected widget to${isNot ? ' not' : ''} be enabled, but it was${last ? '' : ' not'}.`
71
71
  };
72
72
  })();
73
+ },
74
+ async toBeDisabled(locator, options) {
75
+ const isNot = this.isNot;
76
+ const timeout = options?.timeout ?? 5000;
77
+ return await (async () => {
78
+ const { passed, last } = await poll(() => locator.isEnabled(), enabled => isNot ? enabled : !enabled, timeout);
79
+ return {
80
+ pass: isNot ? !passed : passed,
81
+ message: () => `Expected widget to${isNot ? ' not' : ''} be disabled, but ${last === undefined ? "its state couldn't be read (does the widget exist?)" : `it was ${last ? 'enabled' : 'disabled'}`}.`
82
+ };
83
+ })();
73
84
  }
74
85
  }));
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.155",
3
+ "version": "1.0.157",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",