@specter-automation/test 1.0.157 → 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;
@@ -427,3 +427,5 @@ class WidgetLocator extends specter_locator_1.SpecterLocator {
427
427
  }
428
428
  }
429
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);
@@ -463,13 +463,21 @@ export declare class SpecterWorld {
463
463
  *
464
464
  * The image is attached to the current step, so it shows in Playwright's report and in the
465
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 })`.
466
469
  * @param fileName The name of the saved file.
467
- * @param showUI Whether to render the UMG/Slate UI layer into the screenshot (defaults to false).
468
- * @param options.attachmentName Name shown for the attachment (defaults to the file name).
469
- * @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.
470
474
  * @returns The absolute file path where the image was saved on disk.
471
475
  */
472
- takeScreenshot(fileName: string, showUI?: boolean, options?: {
476
+ takeScreenshot(fileName: string, showUIOrOptions?: boolean | {
477
+ showUI?: boolean;
478
+ attachmentName?: string;
479
+ attach?: boolean;
480
+ }, legacyOptions?: {
473
481
  attachmentName?: string;
474
482
  attach?: boolean;
475
483
  }): Promise<string>;
@@ -914,13 +914,19 @@ class SpecterWorld {
914
914
  *
915
915
  * The image is attached to the current step, so it shows in Playwright's report and in the
916
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 })`.
917
920
  * @param fileName The name of the saved file.
918
- * @param showUI Whether to render the UMG/Slate UI layer into the screenshot (defaults to false).
919
- * @param options.attachmentName Name shown for the attachment (defaults to the file name).
920
- * @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.
921
925
  * @returns The absolute file path where the image was saved on disk.
922
926
  */
923
- 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;
924
930
  let savedPath = '';
925
931
  await test_1.default.step(`Specter: Capturing Screenshot [${fileName}] (UI: ${showUI})`, async () => {
926
932
  const response = await this.evaluate('TakeScreenshot', { fileName, showUI });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.157",
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",