@specter-automation/test 1.0.130 → 1.0.131

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.
@@ -66,6 +66,26 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
66
66
  duration?: number;
67
67
  color?: string;
68
68
  }): Promise<void>;
69
+ /**
70
+ * Clicks the actor.
71
+ *
72
+ * @param options.strategy
73
+ * - 'function' (default): runs its click events (OnClicked, the blueprint's ActorOnClicked) when it has any.
74
+ * When nothing listens for clicks on it, it is clicked through the game view instead.
75
+ * - 'viewport': clicks where it is on screen. The click goes straight to the game's view, so the game reads it like
76
+ * a player's (GetMousePosition, the button press, Enhanced Input, click events) without moving the real mouse
77
+ * or needing focus. Fails when something else is in front of it.
78
+ * - 'broadcast': runs its click events whether or not anything listens.
79
+ * @param options.button 'left' (default), 'right' or 'middle'
80
+ * @param options.timeout How long to keep trying, e.g. while it walks on screen (default: 5000ms)
81
+ * @param options.context Optional text to tell identical steps apart in the report
82
+ */
83
+ click(options?: {
84
+ strategy?: 'function' | 'viewport' | 'broadcast';
85
+ button?: 'left' | 'right' | 'middle';
86
+ timeout?: number;
87
+ context?: string;
88
+ }): Promise<void>;
69
89
  /**
70
90
  * Explicitly destroys this actor in the Unreal Engine world.
71
91
  */
@@ -138,6 +138,50 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
138
138
  async updateStatsBillboard(options) {
139
139
  return this.showStatsBillboard(options);
140
140
  }
141
+ /**
142
+ * Clicks the actor.
143
+ *
144
+ * @param options.strategy
145
+ * - 'function' (default): runs its click events (OnClicked, the blueprint's ActorOnClicked) when it has any.
146
+ * When nothing listens for clicks on it, it is clicked through the game view instead.
147
+ * - 'viewport': clicks where it is on screen. The click goes straight to the game's view, so the game reads it like
148
+ * a player's (GetMousePosition, the button press, Enhanced Input, click events) without moving the real mouse
149
+ * or needing focus. Fails when something else is in front of it.
150
+ * - 'broadcast': runs its click events whether or not anything listens.
151
+ * @param options.button 'left' (default), 'right' or 'middle'
152
+ * @param options.timeout How long to keep trying, e.g. while it walks on screen (default: 5000ms)
153
+ * @param options.context Optional text to tell identical steps apart in the report
154
+ */
155
+ async click(options) {
156
+ const baseName = `Click Actor @ ${this.toString()}`;
157
+ const stepName = options?.context ? `${baseName} [${options.context}]` : baseName;
158
+ return await test_1.default.step(stepName, async () => {
159
+ const strategy = options?.strategy || 'function';
160
+ const button = options?.button || 'left';
161
+ const timeout = options?.timeout ?? 5000;
162
+ const startTime = Date.now();
163
+ let lastError = null;
164
+ while (Date.now() - startTime < timeout) {
165
+ try {
166
+ const response = await this.evaluate('ClickActor', { strategy, button }, undefined, true);
167
+ if (response?.status === 'success') {
168
+ return;
169
+ }
170
+ lastError = new Error(response?.error || 'ClickActor failed');
171
+ }
172
+ catch (err) {
173
+ lastError = err;
174
+ const msg = err instanceof Error ? err.message : String(err);
175
+ if (msg.toLowerCase().includes('strict mode')) {
176
+ throw err;
177
+ }
178
+ }
179
+ await new Promise(resolve => setTimeout(resolve, 100));
180
+ }
181
+ const details = lastError ? `\nUnderlying Error: ${lastError.message}` : '';
182
+ throw new Error(`[Specter Timeout] Timed out after ${timeout}ms attempting to click actor: ${this.toString()}.${details}`);
183
+ });
184
+ }
141
185
  /**
142
186
  * Explicitly destroys this actor in the Unreal Engine world.
143
187
  */
@@ -78,6 +78,13 @@ export declare class WidgetLocator<T = any> extends SpecterLocator<T> {
78
78
  getByText(text: string | RegExp, options?: {
79
79
  exact?: boolean;
80
80
  }): WidgetLocator;
81
+ /**
82
+ * Finds UI inside this one by a name that stays the same when its words change: a UMG widget's name in the
83
+ * designer, the test id a hand-drawn HUD reports with FSpecterHUD, or a Slate widget's tag or Automation Driver id.
84
+ */
85
+ getByTestId(testId: string, options?: {
86
+ exact?: boolean;
87
+ }): WidgetLocator;
81
88
  /**
82
89
  * Alias for getChild / navigating down the widget hierarchy.
83
90
  */
@@ -181,6 +181,17 @@ class WidgetLocator extends specter_locator_1.SpecterLocator {
181
181
  ];
182
182
  return new WidgetLocator(this.transport, newPipeline);
183
183
  }
184
+ /**
185
+ * Finds UI inside this one by a name that stays the same when its words change: a UMG widget's name in the
186
+ * designer, the test id a hand-drawn HUD reports with FSpecterHUD, or a Slate widget's tag or Automation Driver id.
187
+ */
188
+ getByTestId(testId, options) {
189
+ const newPipeline = [
190
+ ...this.pipeline,
191
+ { action: 'getWidgetByTestId', value: testId, exact: options?.exact ?? true }
192
+ ];
193
+ return new WidgetLocator(this.transport, newPipeline);
194
+ }
184
195
  /**
185
196
  * Alias for getChild / navigating down the widget hierarchy.
186
197
  */
@@ -196,7 +196,14 @@ export interface SpawnOptions {
196
196
  name?: string;
197
197
  }
198
198
  export interface ClickOptions {
199
- strategy?: 'hardware' | 'broadcast' | 'function';
199
+ /**
200
+ * - 'function' (default): runs the click handler directly; falls back to a click when there is none.
201
+ * - 'hardware': a real mouse click through Slate. Moves the real cursor.
202
+ * - 'viewport': a click handed straight to the game's view, as the game reads a player's click. The real cursor
203
+ * doesn't move and the game doesn't need focus. For things the game draws or picks itself: HUD elements.
204
+ * - 'broadcast': only the click handler; fails when there is none.
205
+ */
206
+ strategy?: 'hardware' | 'broadcast' | 'function' | 'viewport';
200
207
  timeout?: number;
201
208
  tolerance?: number;
202
209
  waitForStable?: boolean;
@@ -381,6 +388,13 @@ export declare class SpecterWorld {
381
388
  getByText(text: string | RegExp, options?: {
382
389
  exact?: boolean;
383
390
  }): WidgetLocator;
391
+ /**
392
+ * Finds UI by a name that stays the same when its words change: a UMG widget's name in the designer, the test
393
+ * id a hand-drawn HUD reports with FSpecterHUD, or a Slate widget's tag or Automation Driver id.
394
+ */
395
+ getByTestId(testId: string, options?: {
396
+ exact?: boolean;
397
+ }): WidgetLocator;
384
398
  getByPlayerId(playerId: number): ActorLocator;
385
399
  subsystem(subsystemName: string): SpecterLocator;
386
400
  /**
@@ -732,6 +732,13 @@ class SpecterWorld {
732
732
  const exactMatch = options?.exact ?? (typeof text === 'string' ? true : false);
733
733
  return new locators_1.WidgetLocator(this.transport, [{ action: 'getWidgetByText', value: textStr, exact: exactMatch }]);
734
734
  }
735
+ /**
736
+ * Finds UI by a name that stays the same when its words change: a UMG widget's name in the designer, the test
737
+ * id a hand-drawn HUD reports with FSpecterHUD, or a Slate widget's tag or Automation Driver id.
738
+ */
739
+ getByTestId(testId, options) {
740
+ return new locators_1.WidgetLocator(this.transport, [{ action: 'getWidgetByTestId', value: testId, exact: options?.exact ?? true }]);
741
+ }
735
742
  getByPlayerId(playerId) {
736
743
  return new locators_1.ActorLocator(this.transport, [{ action: 'getByPlayerId', value: playerId.toString() }]);
737
744
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.130",
3
+ "version": "1.0.131",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",