@specter-automation/test 1.0.157 → 1.0.159

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,29 @@ 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
+ private static warnedLowerCaseKeys;
104
+ /**
105
+ * Struct fields used to come back lower-cased ("eventtype" for EventType). They now come back as declared.
106
+ * Tests written against the old names keep working through hidden aliases, which warn once each.
107
+ * The aliases aren't enumerable, so they don't show in toEqual, Object.keys or JSON.
108
+ */
109
+ private static addLowerCaseAliases;
110
+ /** Turns the engine's object references (in a value, an array or a struct) into locators */
111
+ protected hydrateValue(val: any): any;
90
112
  getMaterialScalarParameter(parameterName: string, options?: {
91
113
  slotIndex?: number;
92
114
  componentName?: string;
@@ -246,26 +246,12 @@ 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);
250
+ // A function with one output gives that value, whatever the output is called: a Blueprint
251
+ // function's output pin named "Open" used to come back as { Open: true }. With several outputs,
252
+ // an object of them by name.
267
253
  const keys = Object.keys(data);
268
- if (keys.length === 1 && (keys[0] === 'ReturnValue' || keys[0] === 'returnValue')) {
254
+ if (keys.length === 1) {
269
255
  return unpackValue(data[keys[0]]);
270
256
  }
271
257
  if (keys.length === 0) {
@@ -291,9 +277,87 @@ class SpecterLocator {
291
277
  const response = await this.evaluate("GetObjectName", {}, undefined, true);
292
278
  return response.data.objectName;
293
279
  }
280
+ /**
281
+ * Reads a property (a C++ UPROPERTY or a Blueprint variable).
282
+ *
283
+ * A reference to an actor, component or widget comes back as a locator you can use directly:
284
+ * `const marker = await guide.getPropertyValue("BarrelMarker"); await expect(marker).toBeVisible();`
285
+ * As text (`String(value)`, in a template) it is the object's name. A reference to an asset (a Niagara
286
+ * system, a material) has `objectName` and `className` too.
287
+ */
294
288
  async getPropertyValue(propertyName) {
295
289
  const response = await this.evaluate("GetPropertyValue", { propertyName }, propertyName);
296
- return response.data.value;
290
+ return this.hydrateValue(response.data.value);
291
+ }
292
+ /**
293
+ * How to build the locator for an object reference of each kind ("actor", "widget"). The actor and widget
294
+ * locator files add themselves here, since this file can't import them.
295
+ */
296
+ static locatorFactories = {};
297
+ static warnedLowerCaseKeys = new Set();
298
+ /**
299
+ * Struct fields used to come back lower-cased ("eventtype" for EventType). They now come back as declared.
300
+ * Tests written against the old names keep working through hidden aliases, which warn once each.
301
+ * The aliases aren't enumerable, so they don't show in toEqual, Object.keys or JSON.
302
+ */
303
+ static addLowerCaseAliases(obj) {
304
+ for (const key of Object.keys(obj)) {
305
+ const lower = key.toLowerCase();
306
+ if (lower === key || lower in obj) {
307
+ continue;
308
+ }
309
+ Object.defineProperty(obj, lower, {
310
+ enumerable: false,
311
+ configurable: true,
312
+ get() {
313
+ if (!SpecterLocator.warnedLowerCaseKeys.has(lower)) {
314
+ SpecterLocator.warnedLowerCaseKeys.add(lower);
315
+ console.warn(`[SPECTER] "${lower}" is the old lower-cased name of the struct field "${key}". Use "${key}": the old name will stop working in a later version.`);
316
+ }
317
+ return obj[key];
318
+ },
319
+ });
320
+ }
321
+ }
322
+ /** Turns the engine's object references (in a value, an array or a struct) into locators */
323
+ hydrateValue(val) {
324
+ if (Array.isArray(val)) {
325
+ return val.map(inner => this.hydrateValue(inner));
326
+ }
327
+ if (val && typeof val === 'object') {
328
+ if (val.__specterLocator) {
329
+ const pipeline = Array.isArray(val.pipeline) ? val.pipeline : [];
330
+ if (pipeline.length === 0) {
331
+ // An asset (a Niagara system, a material): nothing in the world to locate. Its name as text.
332
+ const asset = { ...val };
333
+ Object.defineProperty(asset, 'toString', { value: () => val.objectName, enumerable: false });
334
+ return asset;
335
+ }
336
+ let loc;
337
+ if (val.locatorKind === 'component' && this.pipeline.length > 0) {
338
+ loc = new SpecterLocator(this.transport, [...this.pipeline, ...pipeline]);
339
+ }
340
+ else {
341
+ const make = SpecterLocator.locatorFactories[val.locatorKind];
342
+ loc = make ? make(this.transport, pipeline) : new SpecterLocator(this.transport, pipeline);
343
+ }
344
+ loc.objectName = val.objectName;
345
+ loc.name = val.objectName;
346
+ loc.className = val.className;
347
+ loc.toString = () => val.objectName;
348
+ loc.valueOf = () => val.objectName;
349
+ return loc;
350
+ }
351
+ if (Object.getPrototypeOf(val) === Object.prototype) {
352
+ const out = {};
353
+ for (const [key, inner] of Object.entries(val)) {
354
+ out[key] = this.hydrateValue(inner);
355
+ }
356
+ SpecterLocator.addLowerCaseAliases(out);
357
+ return out;
358
+ }
359
+ }
360
+ return val;
297
361
  }
298
362
  async getMaterialScalarParameter(parameterName, options) {
299
363
  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.159",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",