@specter-automation/test 1.0.143 → 1.0.145

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.
@@ -206,6 +206,15 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
206
206
  * Presses or releases a hardware key on this Actor's PlayerController, optionally holding until/while a condition is met.
207
207
  */
208
208
  pressKey(key: UnrealKey, eventType?: 'Pressed' | 'Released', options?: boolean | InputConditionalOptions): Promise<void>;
209
+ /**
210
+ * Taps a key: presses it, holds it briefly, then releases it. Use this for actions bound to Started or
211
+ * Completed (jump, interact, fire). pressKey on its own leaves the key held down.
212
+ * @param options.holdMs How long to hold the key before releasing it (default 100 ms, a few frames)
213
+ */
214
+ tapKey(key: UnrealKey, options?: {
215
+ holdMs?: number;
216
+ bHideStep?: boolean;
217
+ }): Promise<void>;
209
218
  /**
210
219
  * Holds a key down until/while a condition is satisfied on this Actor.
211
220
  */
@@ -595,9 +595,11 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
595
595
  await (0, input_conditions_1.runConditionalInputLoop)({
596
596
  driveFn: async () => {
597
597
  await this.evaluate("PressKey", { key, eventType: 'Pressed' }, undefined, true);
598
+ this.transport.heldKeys.add(key);
598
599
  },
599
600
  releaseFn: async () => {
600
601
  await this.evaluate("PressKey", { key, eventType: 'Released' }, undefined, true);
602
+ this.transport.heldKeys.delete(key);
601
603
  },
602
604
  options,
603
605
  actor: this
@@ -614,6 +616,31 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
614
616
  }
615
617
  const bHideStep = typeof options === 'boolean' ? options : false;
616
618
  await this.evaluate("PressKey", { key, eventType }, undefined, bHideStep);
619
+ if (eventType === 'Pressed') {
620
+ this.transport.heldKeys.add(key);
621
+ }
622
+ else {
623
+ this.transport.heldKeys.delete(key);
624
+ }
625
+ }
626
+ /**
627
+ * Taps a key: presses it, holds it briefly, then releases it. Use this for actions bound to Started or
628
+ * Completed (jump, interact, fire). pressKey on its own leaves the key held down.
629
+ * @param options.holdMs How long to hold the key before releasing it (default 100 ms, a few frames)
630
+ */
631
+ async tapKey(key, options) {
632
+ const holdMs = options?.holdMs ?? 100;
633
+ const tap = async () => {
634
+ await this.pressKey(key, 'Pressed', true);
635
+ await new Promise(resolve => setTimeout(resolve, holdMs));
636
+ await this.pressKey(key, 'Released', true);
637
+ };
638
+ if (options?.bHideStep) {
639
+ await tap();
640
+ return;
641
+ }
642
+ const portStr = this.port ? `[Client ${this.port}] ` : '';
643
+ await test_1.default.step(`${portStr}tapKey [${key}] @ ${this.toString()}`, tap);
617
644
  }
618
645
  /**
619
646
  * Holds a key down until/while a condition is satisfied on this Actor.
@@ -227,6 +227,8 @@ export declare class SpecterTransport {
227
227
  private url;
228
228
  currentMap: string;
229
229
  clientName?: string;
230
+ /** Keys pressed through pressKey and not released yet. World cleanup releases them after each test. */
231
+ readonly heldKeys: Set<string>;
230
232
  private pendingRequests;
231
233
  private eventListeners;
232
234
  recentEvents: Array<{
@@ -42,6 +42,8 @@ class SpecterTransport {
42
42
  url;
43
43
  currentMap = 'Unknown';
44
44
  clientName;
45
+ /** Keys pressed through pressKey and not released yet. World cleanup releases them after each test. */
46
+ heldKeys = new Set();
45
47
  // The Enterprise Fix: Routing responses to the correct Promise
46
48
  pendingRequests = new Map();
47
49
  eventListeners = new Map();
@@ -1141,6 +1143,17 @@ class SpecterWorld {
1141
1143
  async cleanup() {
1142
1144
  if (!this.transport.isConnected)
1143
1145
  return;
1146
+ // Release keys the test left held (pressKey without a matching release). Otherwise the next test, or a
1147
+ // retry in the same game, starts with the key already down, and actions bound to Started never fire.
1148
+ for (const key of [...this.transport.heldKeys]) {
1149
+ try {
1150
+ await this.evaluate("PressKey", { key, eventType: 'Released' }, key);
1151
+ }
1152
+ catch (e) {
1153
+ // Ignore during teardown, as below
1154
+ }
1155
+ }
1156
+ this.transport.heldKeys.clear();
1144
1157
  try {
1145
1158
  await this.evaluate("ClearAllSpawned", {});
1146
1159
  }
@@ -3,6 +3,7 @@ declare global {
3
3
  namespace PlaywrightTest {
4
4
  interface Matchers<R, T> {
5
5
  toHavePropertyValue(propertyName: string, expectedValue: any, options?: {
6
+ operator?: '>' | '<' | '>=' | '<=' | '===' | '!=' | 'regex';
6
7
  timeout?: number;
7
8
  }): T extends SpecterLocator ? Promise<R> : never;
8
9
  toHaveCount(expectedCount: number, options?: {
@@ -40,16 +41,14 @@ export interface LocatorMatchers {
40
41
  timeout?: number;
41
42
  }): Promise<void>;
42
43
  }
44
+ type PropertyOperator = '>' | '<' | '>=' | '<=' | '===' | '!=' | 'regex';
45
+ /** Compares a property value read from the engine with what the test expects. */
46
+ export declare function propertyMatches(actual: any, expected: any, operator: PropertyOperator): boolean;
43
47
  export declare const locatorExpect: import("playwright/test").Expect<{
44
48
  toHavePropertyValue(this: import("playwright/test").ExpectMatcherState, locator: SpecterLocator, propertyName: string, expectedValue: any, options?: {
45
- operator?: ">" | "<" | ">=" | "<=" | "===" | "!=" | "regex";
49
+ operator?: PropertyOperator;
46
50
  timeout?: number;
47
51
  }): Promise<{
48
- pass: boolean;
49
- message: () => string;
50
- actual?: undefined;
51
- expected?: undefined;
52
- } | {
53
52
  pass: boolean;
54
53
  message: () => string;
55
54
  actual: any;
@@ -78,3 +77,4 @@ export declare const locatorExpect: import("playwright/test").Expect<{
78
77
  message: () => string;
79
78
  }>;
80
79
  }>;
80
+ export {};
@@ -1,37 +1,91 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.locatorExpect = void 0;
4
+ exports.propertyMatches = propertyMatches;
4
5
  const test_1 = require("@playwright/test");
5
6
  const instrument_1 = require("./instrument");
6
7
  const locators_1 = require("../core/locators");
8
+ const PROPERTY_POLL_INTERVALS_MS = [100, 250, 500, 1000];
9
+ const OPERATOR_LABELS = {
10
+ '===': 'to equal',
11
+ '!=': 'to differ from',
12
+ '>': 'to be >',
13
+ '<': 'to be <',
14
+ '>=': 'to be >=',
15
+ '<=': 'to be <=',
16
+ 'regex': 'to match',
17
+ };
18
+ /** Compares a property value read from the engine with what the test expects. */
19
+ function propertyMatches(actual, expected, operator) {
20
+ switch (operator) {
21
+ case '===': return propertyEquals(actual, expected);
22
+ case '!=': return !propertyEquals(actual, expected);
23
+ case '>': return Number(actual) > Number(expected);
24
+ case '<': return Number(actual) < Number(expected);
25
+ case '>=': return Number(actual) >= Number(expected);
26
+ case '<=': return Number(actual) <= Number(expected);
27
+ case 'regex': return (expected instanceof RegExp ? expected : new RegExp(String(expected))).test(String(actual));
28
+ default: throw new Error(`toHavePropertyValue: unknown operator '${operator}'`);
29
+ }
30
+ }
31
+ function propertyEquals(actual, expected) {
32
+ // Booleans come back as JSON booleans; also accept "true"/"false" written as strings
33
+ if (typeof actual === 'boolean' && typeof expected === 'string') {
34
+ return actual === (expected.trim().toLowerCase() === 'true');
35
+ }
36
+ // Structs (vectors, rotators, ...) compare deeply
37
+ return deepEqual(actual, expected);
38
+ }
39
+ function deepEqual(a, b) {
40
+ if (Object.is(a, b))
41
+ return true;
42
+ if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
43
+ return false;
44
+ if (Array.isArray(a) !== Array.isArray(b))
45
+ return false;
46
+ const keysA = Object.keys(a), keysB = Object.keys(b);
47
+ return keysA.length === keysB.length && keysA.every(k => Object.prototype.hasOwnProperty.call(b, k) && deepEqual(a[k], b[k]));
48
+ }
7
49
  exports.locatorExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
8
50
  async toHavePropertyValue(locator, propertyName, expectedValue, options) {
9
51
  const operator = options?.operator ?? '===';
10
- const pollTimeout = options?.timeout ?? 5000;
52
+ const timeout = options?.timeout ?? 5000;
11
53
  const isNot = this.isNot;
12
- return await (async () => {
13
- let lastValue;
54
+ const deadline = Date.now() + timeout;
55
+ let actual;
56
+ let readOnce = false;
57
+ let lastError;
58
+ // The engine only reads the property; the comparison happens here. Retry until it matches (or, for
59
+ // .not, stops matching) or the timeout runs out. Only the first read shows as a step.
60
+ for (let attempt = 0;; attempt++) {
14
61
  try {
15
- await test_1.expect.poll(async () => {
16
- // Pass the operator through to the evaluation
17
- lastValue = await locator.evaluate("GetPropertyValue", {
18
- propertyName,
19
- expectedValue,
20
- operator
21
- });
22
- return lastValue.status === 'success';
23
- }, { timeout: pollTimeout }).toBe(!isNot);
24
- return { pass: !isNot, message: () => 'passed' };
62
+ const response = await locator.evaluate("GetPropertyValue", { propertyName }, propertyName, attempt > 0);
63
+ actual = response?.data?.value;
64
+ readOnce = true;
65
+ lastError = undefined;
66
+ if (propertyMatches(actual, expectedValue, operator) !== isNot) {
67
+ return { pass: !isNot, message: () => 'passed', actual, expected: expectedValue };
68
+ }
25
69
  }
26
70
  catch (e) {
27
- return {
28
- pass: isNot,
29
- message: () => `Timed out waiting for ${propertyName} ${operator} ${expectedValue}. Last value: ${lastValue?.data?.value}`,
30
- actual: lastValue?.data?.value,
31
- expected: expectedValue
32
- };
71
+ lastError = e?.message ?? String(e);
33
72
  }
34
- })();
73
+ if (Date.now() >= deadline)
74
+ break;
75
+ await new Promise(resolve => setTimeout(resolve, PROPERTY_POLL_INTERVALS_MS[Math.min(attempt, PROPERTY_POLL_INTERVALS_MS.length - 1)]));
76
+ }
77
+ const name = `${isNot ? 'not.' : ''}toHavePropertyValue`;
78
+ const hint = this.utils.matcherHint(name, locator.toString(), propertyName);
79
+ const wanted = `${isNot ? 'not ' : ''}${OPERATOR_LABELS[operator]} ${this.utils.printExpected(expectedValue)}`;
80
+ return {
81
+ pass: isNot,
82
+ message: () => lastError
83
+ ? `${hint}\n\nCould not read "${propertyName}" within ${timeout}ms: ${lastError}` +
84
+ (readOnce ? `\nLast value read: ${this.utils.printReceived(actual)}` : '')
85
+ : `${hint}\n\nExpected "${propertyName}" ${wanted}\nReceived: ${this.utils.printReceived(actual)}\n(after ${timeout}ms)`,
86
+ actual,
87
+ expected: expectedValue,
88
+ };
35
89
  },
36
90
  async toHaveCount(locator, expectedCount, options) {
37
91
  const pollTimeout = options?.timeout ?? 5000;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.143",
3
+ "version": "1.0.145",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",