@specter-automation/test 1.0.156 → 1.0.158

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.
@@ -1478,3 +1478,5 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
1478
1478
  }
1479
1479
  }
1480
1480
  exports.ActorLocator = ActorLocator;
1481
+ // An object reference the engine returns (a property, a function's result) becomes this kind of locator
1482
+ specter_locator_1.SpecterLocator.locatorFactories.actor = (transport, pipeline) => new ActorLocator(transport, pipeline);
@@ -86,7 +86,22 @@ export declare class SpecterLocator<T = any> {
86
86
  callFunctionWithReturn(functionName: string, parameters?: Record<string, any>): Promise<any>;
87
87
  hasGameplayTag(tagToCheck: string, bHideStep?: boolean): Promise<boolean>;
88
88
  getObjectName(): Promise<string>;
89
+ /**
90
+ * Reads a property (a C++ UPROPERTY or a Blueprint variable).
91
+ *
92
+ * A reference to an actor, component or widget comes back as a locator you can use directly:
93
+ * `const marker = await guide.getPropertyValue("BarrelMarker"); await expect(marker).toBeVisible();`
94
+ * As text (`String(value)`, in a template) it is the object's name. A reference to an asset (a Niagara
95
+ * system, a material) has `objectName` and `className` too.
96
+ */
89
97
  getPropertyValue(propertyName: string): Promise<any>;
98
+ /**
99
+ * How to build the locator for an object reference of each kind ("actor", "widget"). The actor and widget
100
+ * locator files add themselves here, since this file can't import them.
101
+ */
102
+ static locatorFactories: Record<string, (transport: SpecterTransport, pipeline: LocatorStep[]) => SpecterLocator<any>>;
103
+ /** Turns the engine's object references (in a value, an array or a struct) into locators */
104
+ protected hydrateValue(val: any): any;
90
105
  getMaterialScalarParameter(parameterName: string, options?: {
91
106
  slotIndex?: number;
92
107
  componentName?: string;
@@ -246,24 +246,7 @@ class SpecterLocator {
246
246
  if (!data || typeof data !== 'object') {
247
247
  return data;
248
248
  }
249
- const unpackValue = (val) => {
250
- if (val && typeof val === 'object' && val.__specterLocator) {
251
- let loc;
252
- if (val.locatorKind === 'component' && Array.isArray(val.pipeline) && this.pipeline.length > 0) {
253
- loc = new SpecterLocator(this.transport, [...this.pipeline, ...val.pipeline]);
254
- }
255
- else {
256
- loc = new SpecterLocator(this.transport, val.pipeline ?? []);
257
- }
258
- loc.objectName = val.objectName;
259
- loc.name = val.objectName;
260
- loc.className = val.className;
261
- loc.toString = () => val.objectName;
262
- loc.valueOf = () => val.objectName;
263
- return loc;
264
- }
265
- return val;
266
- };
249
+ const unpackValue = (val) => this.hydrateValue(val);
267
250
  const keys = Object.keys(data);
268
251
  if (keys.length === 1 && (keys[0] === 'ReturnValue' || keys[0] === 'returnValue')) {
269
252
  return unpackValue(data[keys[0]]);
@@ -291,9 +274,61 @@ class SpecterLocator {
291
274
  const response = await this.evaluate("GetObjectName", {}, undefined, true);
292
275
  return response.data.objectName;
293
276
  }
277
+ /**
278
+ * Reads a property (a C++ UPROPERTY or a Blueprint variable).
279
+ *
280
+ * A reference to an actor, component or widget comes back as a locator you can use directly:
281
+ * `const marker = await guide.getPropertyValue("BarrelMarker"); await expect(marker).toBeVisible();`
282
+ * As text (`String(value)`, in a template) it is the object's name. A reference to an asset (a Niagara
283
+ * system, a material) has `objectName` and `className` too.
284
+ */
294
285
  async getPropertyValue(propertyName) {
295
286
  const response = await this.evaluate("GetPropertyValue", { propertyName }, propertyName);
296
- return response.data.value;
287
+ return this.hydrateValue(response.data.value);
288
+ }
289
+ /**
290
+ * How to build the locator for an object reference of each kind ("actor", "widget"). The actor and widget
291
+ * locator files add themselves here, since this file can't import them.
292
+ */
293
+ static locatorFactories = {};
294
+ /** Turns the engine's object references (in a value, an array or a struct) into locators */
295
+ hydrateValue(val) {
296
+ if (Array.isArray(val)) {
297
+ return val.map(inner => this.hydrateValue(inner));
298
+ }
299
+ if (val && typeof val === 'object') {
300
+ if (val.__specterLocator) {
301
+ const pipeline = Array.isArray(val.pipeline) ? val.pipeline : [];
302
+ if (pipeline.length === 0) {
303
+ // An asset (a Niagara system, a material): nothing in the world to locate. Its name as text.
304
+ const asset = { ...val };
305
+ Object.defineProperty(asset, 'toString', { value: () => val.objectName, enumerable: false });
306
+ return asset;
307
+ }
308
+ let loc;
309
+ if (val.locatorKind === 'component' && this.pipeline.length > 0) {
310
+ loc = new SpecterLocator(this.transport, [...this.pipeline, ...pipeline]);
311
+ }
312
+ else {
313
+ const make = SpecterLocator.locatorFactories[val.locatorKind];
314
+ loc = make ? make(this.transport, pipeline) : new SpecterLocator(this.transport, pipeline);
315
+ }
316
+ loc.objectName = val.objectName;
317
+ loc.name = val.objectName;
318
+ loc.className = val.className;
319
+ loc.toString = () => val.objectName;
320
+ loc.valueOf = () => val.objectName;
321
+ return loc;
322
+ }
323
+ if (Object.getPrototypeOf(val) === Object.prototype) {
324
+ const out = {};
325
+ for (const [key, inner] of Object.entries(val)) {
326
+ out[key] = this.hydrateValue(inner);
327
+ }
328
+ return out;
329
+ }
330
+ }
331
+ return val;
297
332
  }
298
333
  async getMaterialScalarParameter(parameterName, options) {
299
334
  const response = await this.evaluate("GetMaterialParameter", {
@@ -48,14 +48,22 @@ export interface WidgetFilterOptions extends Partial<FilterOptions> {
48
48
  export interface WidgetGeometry {
49
49
  isRendered: boolean;
50
50
  isVisible: boolean;
51
+ /** Top-left corner, in screen pixels */
51
52
  position: {
52
53
  x: number;
53
54
  y: number;
54
55
  };
56
+ /** Size in the widget's own units, before DPI scale. For maths with `position` and `center`, use `pixelSize`. */
55
57
  size: {
56
58
  width: number;
57
59
  height: number;
58
60
  };
61
+ /** Size in screen pixels, the same units as `position` and `center` (missing with plugins older than this field) */
62
+ pixelSize?: {
63
+ width: number;
64
+ height: number;
65
+ };
66
+ /** Centre, in screen pixels */
59
67
  center: {
60
68
  x: number;
61
69
  y: number;
@@ -140,6 +148,12 @@ export declare class WidgetLocator<T = any> extends SpecterLocator<T> {
140
148
  * Queries the UMG Slate system to see if the widget is actively drawn on screen.
141
149
  */
142
150
  isEnabled(): Promise<boolean>;
151
+ /** Why the last checkVisibility() said the widget isn't visible (a collapsed parent, an inactive switcher page...) */
152
+ lastHiddenReason: string | undefined;
153
+ /**
154
+ * Whether a player can see the widget: it and everything above it are shown, it's on its switcher's
155
+ * active page, and its screen is still attached to a window.
156
+ */
143
157
  checkVisibility(): Promise<boolean>;
144
158
  /**
145
159
  * 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);
@@ -419,3 +427,5 @@ class WidgetLocator extends specter_locator_1.SpecterLocator {
419
427
  }
420
428
  }
421
429
  exports.WidgetLocator = WidgetLocator;
430
+ // An object reference the engine returns (a property, a function's result) becomes this kind of locator
431
+ specter_locator_1.SpecterLocator.locatorFactories.widget = (transport, pipeline) => new WidgetLocator(transport, pipeline);
@@ -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;
@@ -461,13 +463,21 @@ export declare class SpecterWorld {
461
463
  *
462
464
  * The image is attached to the current step, so it shows in Playwright's report and in the
463
465
  * in-engine runner next to the step that took it.
466
+ *
467
+ * The UI (HUD, menus) is left out unless you ask for it:
468
+ * `takeScreenshot("hint-banner", { showUI: true })`.
464
469
  * @param fileName The name of the saved file.
465
- * @param showUI Whether to render the UMG/Slate UI layer into the screenshot (defaults to false).
466
- * @param options.attachmentName Name shown for the attachment (defaults to the file name).
467
- * @param options.attach Set to false to only save the file, without attaching it.
470
+ * @param showUIOrOptions `{ showUI, attachmentName, attach }`, or just `showUI` as a boolean.
471
+ * @param showUIOrOptions.showUI Whether to render the UMG/Slate UI layer into the screenshot (defaults to false).
472
+ * @param showUIOrOptions.attachmentName Name shown for the attachment (defaults to the file name).
473
+ * @param showUIOrOptions.attach Set to false to only save the file, without attaching it.
468
474
  * @returns The absolute file path where the image was saved on disk.
469
475
  */
470
- takeScreenshot(fileName: string, showUI?: boolean, options?: {
476
+ takeScreenshot(fileName: string, showUIOrOptions?: boolean | {
477
+ showUI?: boolean;
478
+ attachmentName?: string;
479
+ attach?: boolean;
480
+ }, legacyOptions?: {
471
481
  attachmentName?: string;
472
482
  attach?: boolean;
473
483
  }): Promise<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
  }
@@ -895,13 +914,19 @@ class SpecterWorld {
895
914
  *
896
915
  * The image is attached to the current step, so it shows in Playwright's report and in the
897
916
  * in-engine runner next to the step that took it.
917
+ *
918
+ * The UI (HUD, menus) is left out unless you ask for it:
919
+ * `takeScreenshot("hint-banner", { showUI: true })`.
898
920
  * @param fileName The name of the saved file.
899
- * @param showUI Whether to render the UMG/Slate UI layer into the screenshot (defaults to false).
900
- * @param options.attachmentName Name shown for the attachment (defaults to the file name).
901
- * @param options.attach Set to false to only save the file, without attaching it.
921
+ * @param showUIOrOptions `{ showUI, attachmentName, attach }`, or just `showUI` as a boolean.
922
+ * @param showUIOrOptions.showUI Whether to render the UMG/Slate UI layer into the screenshot (defaults to false).
923
+ * @param showUIOrOptions.attachmentName Name shown for the attachment (defaults to the file name).
924
+ * @param showUIOrOptions.attach Set to false to only save the file, without attaching it.
902
925
  * @returns The absolute file path where the image was saved on disk.
903
926
  */
904
- async takeScreenshot(fileName, showUI = false, options = {}) {
927
+ async takeScreenshot(fileName, showUIOrOptions = false, legacyOptions = {}) {
928
+ const showUI = typeof showUIOrOptions === 'object' ? showUIOrOptions.showUI === true : showUIOrOptions === true;
929
+ const options = typeof showUIOrOptions === 'object' ? { ...legacyOptions, ...showUIOrOptions } : legacyOptions;
905
930
  let savedPath = '';
906
931
  await test_1.default.step(`Specter: Capturing Screenshot [${fileName}] (UI: ${showUI})`, async () => {
907
932
  const response = await this.evaluate('TakeScreenshot', { fileName, showUI });
@@ -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.156",
3
+ "version": "1.0.158",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",