@specter-automation/test 1.0.147 → 1.0.149

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.
@@ -151,7 +151,33 @@ export interface Vector2D {
151
151
  X?: number;
152
152
  Y?: number;
153
153
  }
154
+ /**
155
+ * Vector maths for the plain `{ x, y, z }` objects Specter returns (TypeScript has no operator overloading,
156
+ * so `a + b` on two vectors won't work). Every function returns a new vector and leaves its inputs alone.
157
+ *
158
+ * @example
159
+ * const { add, distance2D } = VectorUtils;
160
+ * await boss.setLocation(add(home, { x: 2100, y: 0, z: 0 }));
161
+ * expect(distance2D(await hero.getLocation(), start)).toBeLessThan(40);
162
+ */
154
163
  export declare const VectorUtils: {
164
+ /** `a + b` */
165
+ add: (a: Vector3, b: Vector3) => Vector3;
166
+ /** `a - b`: the vector from `b` to `a` */
167
+ sub: (a: Vector3, b: Vector3) => Vector3;
168
+ /** `v * scalar` */
169
+ scale: (v: Vector3, scalar: number) => Vector3;
170
+ /** Length of `v` */
171
+ length: (v: Vector3) => number;
172
+ /** `v` scaled to length 1; a zero vector stays zero */
173
+ normalize: (v: Vector3) => Vector3;
174
+ /** Dot product of `a` and `b` */
175
+ dot: (a: Vector3, b: Vector3) => number;
176
+ /** Distance between `a` and `b` */
177
+ distance: (a: Vector3, b: Vector3) => number;
178
+ /** Distance between `a` and `b` on the ground (x and y only), so height doesn't count */
179
+ distance2D: (a: Vector3, b: Vector3) => number;
180
+ /** `location + direction * offset`: a point `offset` units along `direction` from `location` */
155
181
  addOffset: (location: Vector3, direction: Vector3, offset: number) => Vector3;
156
182
  };
157
183
  export interface Rotator {
@@ -23,7 +23,36 @@ var SpecterEventType;
23
23
  /** An AI's logic moved, a blackboard key changed, or its tree started or finished (the AI trail) */
24
24
  SpecterEventType["AIState"] = "AIState";
25
25
  })(SpecterEventType || (exports.SpecterEventType = SpecterEventType = {}));
26
+ /**
27
+ * Vector maths for the plain `{ x, y, z }` objects Specter returns (TypeScript has no operator overloading,
28
+ * so `a + b` on two vectors won't work). Every function returns a new vector and leaves its inputs alone.
29
+ *
30
+ * @example
31
+ * const { add, distance2D } = VectorUtils;
32
+ * await boss.setLocation(add(home, { x: 2100, y: 0, z: 0 }));
33
+ * expect(distance2D(await hero.getLocation(), start)).toBeLessThan(40);
34
+ */
26
35
  exports.VectorUtils = {
36
+ /** `a + b` */
37
+ add: (a, b) => ({ x: a.x + b.x, y: a.y + b.y, z: a.z + b.z }),
38
+ /** `a - b`: the vector from `b` to `a` */
39
+ sub: (a, b) => ({ x: a.x - b.x, y: a.y - b.y, z: a.z - b.z }),
40
+ /** `v * scalar` */
41
+ scale: (v, scalar) => ({ x: v.x * scalar, y: v.y * scalar, z: v.z * scalar }),
42
+ /** Length of `v` */
43
+ length: (v) => Math.hypot(v.x, v.y, v.z),
44
+ /** `v` scaled to length 1; a zero vector stays zero */
45
+ normalize: (v) => {
46
+ const len = Math.hypot(v.x, v.y, v.z);
47
+ return len === 0 ? { x: 0, y: 0, z: 0 } : { x: v.x / len, y: v.y / len, z: v.z / len };
48
+ },
49
+ /** Dot product of `a` and `b` */
50
+ dot: (a, b) => a.x * b.x + a.y * b.y + a.z * b.z,
51
+ /** Distance between `a` and `b` */
52
+ distance: (a, b) => Math.hypot(a.x - b.x, a.y - b.y, a.z - b.z),
53
+ /** Distance between `a` and `b` on the ground (x and y only), so height doesn't count */
54
+ distance2D: (a, b) => Math.hypot(a.x - b.x, a.y - b.y),
55
+ /** `location + direction * offset`: a point `offset` units along `direction` from `location` */
27
56
  addOffset: (location, direction, offset) => {
28
57
  return {
29
58
  x: location.x + (direction.x * offset),
@@ -24,7 +24,12 @@ declare global {
24
24
  x: number;
25
25
  y: number;
26
26
  z: number;
27
- }, expectedDistance: number): T extends ActorLocator ? Promise<R> : never;
27
+ }, expectedDistance: number, axisOrOptions?: MovementAxis | {
28
+ axis?: MovementAxis;
29
+ timeout?: number;
30
+ }, options?: {
31
+ timeout?: number;
32
+ }): T extends ActorLocator ? Promise<R> : never;
28
33
  toHaveLocation(expectedLocation: {
29
34
  x: number;
30
35
  y: number;
@@ -101,12 +106,25 @@ declare global {
101
106
  }
102
107
  }
103
108
  }
109
+ /**
110
+ * Which part of the movement toHaveMovedFurtherThan measures: one axis ('z' for a jump or a knock-up), the ground
111
+ * plane ('xy'), or the straight-line distance ('xyz', the default).
112
+ */
113
+ export type MovementAxis = 'x' | 'y' | 'z' | 'xy' | 'xyz';
104
114
  export interface ActorMatchers {
115
+ /**
116
+ * Passes once the actor is further than expectedDistance from startLocation, measured along `axis`:
117
+ * `expect(hero).toHaveMovedFurtherThan(start, 100, 'z')` for thrown 100 up. It polls the location every 50ms, so
118
+ * a short hop counts even when the actor is back down by the time the check ends.
119
+ */
105
120
  toHaveMovedFurtherThan(startLocation: {
106
121
  x: number;
107
122
  y: number;
108
123
  z: number;
109
- }, expectedDistance: number, options?: {
124
+ }, expectedDistance: number, axisOrOptions?: MovementAxis | {
125
+ axis?: MovementAxis;
126
+ timeout?: number;
127
+ }, options?: {
110
128
  timeout?: number;
111
129
  }): Promise<void>;
112
130
  toHaveLocation(expectedLocation: {
@@ -206,7 +224,10 @@ export declare const actorExpect: import("playwright/test").Expect<{
206
224
  x: number;
207
225
  y: number;
208
226
  z: number;
209
- }, expectedDistance: number, options?: {
227
+ }, expectedDistance: number, axisOrOptions?: MovementAxis | {
228
+ axis?: MovementAxis;
229
+ timeout?: number;
230
+ }, options?: {
210
231
  timeout?: number;
211
232
  }): Promise<{
212
233
  pass: true;
@@ -4,36 +4,51 @@ exports.actorExpect = void 0;
4
4
  const test_1 = require("@playwright/test");
5
5
  const instrument_1 = require("./instrument");
6
6
  exports.actorExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
7
- async toHaveMovedFurtherThan(locator, startLocation, expectedDistance, options) {
7
+ async toHaveMovedFurtherThan(locator, startLocation, expectedDistance, axisOrOptions, options) {
8
8
  const assertionName = 'toHaveMovedFurtherThan';
9
- const timeout = options?.timeout ?? 5000;
9
+ const opts = typeof axisOrOptions === 'object' ? axisOrOptions : options;
10
+ const axis = (typeof axisOrOptions === 'string' ? axisOrOptions : axisOrOptions?.axis) ?? 'xyz';
11
+ if (!['x', 'y', 'z', 'xy', 'xyz'].includes(axis)) {
12
+ throw new Error(`${assertionName}: axis must be 'x', 'y', 'z', 'xy' or 'xyz', not '${axis}'`);
13
+ }
14
+ const timeout = opts?.timeout ?? 5000;
10
15
  const startTime = Date.now();
11
- let currentDistance = 0;
16
+ const along = axis === 'xyz' ? '' : ` along ${axis}`;
17
+ const measure = (loc) => {
18
+ const dx = axis.includes('x') ? loc.x - startLocation.x : 0;
19
+ const dy = axis.includes('y') ? loc.y - startLocation.y : 0;
20
+ const dz = axis.includes('z') ? loc.z - startLocation.z : 0;
21
+ return Math.sqrt(dx * dx + dy * dy + dz * dz);
22
+ };
23
+ let maxDistance = 0;
24
+ let lastLocation = null;
12
25
  while (Date.now() - startTime < timeout) {
13
26
  const loc = await locator.getLocation();
14
- const dx = loc.x - startLocation.x;
15
- const dy = loc.y - startLocation.y;
16
- const dz = loc.z - startLocation.z;
17
- currentDistance = Math.sqrt(dx * dx + dy * dy + dz * dz);
18
- if (currentDistance > expectedDistance) {
27
+ lastLocation = loc;
28
+ const distance = measure(loc);
29
+ maxDistance = Math.max(maxDistance, distance);
30
+ if (distance > expectedDistance) {
19
31
  return {
20
32
  pass: true,
21
- message: () => 'passed',
22
- actual: currentDistance,
23
- expected: `> ${expectedDistance}`
33
+ message: () => `${this.utils.matcherHint(assertionName, locator.toString(), expectedDistance.toString())}\n\n` +
34
+ `Expected actor "${locator.toString()}" not to move further than ${expectedDistance}${along}, ` +
35
+ `but it moved ${Math.round(distance)}${along} (now at ${JSON.stringify(loc)})`,
36
+ actual: Math.round(distance),
37
+ expected: `> ${expectedDistance}${along}`
24
38
  };
25
39
  }
26
- // Sleep for 100ms before polling again
27
- await new Promise(resolve => setTimeout(resolve, 100));
40
+ // Often enough to catch a short hop (a knock-up is up and down in well under a second)
41
+ await new Promise(resolve => setTimeout(resolve, 50));
28
42
  }
29
43
  return {
30
44
  pass: false,
31
45
  message: () => `${this.utils.matcherHint(assertionName, locator.toString(), expectedDistance.toString())}\n\n` +
32
- `Timed out after ${timeout}ms waiting for actor "${locator.toString()}" to move.\n` +
33
- `Expected distance: > ${expectedDistance}\n` +
34
- `Received max distance: ${currentDistance}`,
35
- actual: currentDistance,
36
- expected: `> ${expectedDistance}`
46
+ `Timed out after ${timeout}ms waiting for actor "${locator.toString()}" to move${along}.\n` +
47
+ `Expected distance${along}: > ${expectedDistance}\n` +
48
+ `Received max distance${along}: ${Math.round(maxDistance)}\n` +
49
+ `Start: ${JSON.stringify(startLocation)}, last seen at: ${JSON.stringify(lastLocation)}`,
50
+ actual: Math.round(maxDistance),
51
+ expected: `> ${expectedDistance}${along}`
37
52
  };
38
53
  },
39
54
  async toHaveLocation(locator, expectedLocation, tolerance = 5.0, options) {
@@ -446,8 +446,9 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
446
446
  if (event.eventName !== attributeName && !event.eventName?.includes(attributeName)) {
447
447
  return false;
448
448
  }
449
- // Only changes to this actor's attributes count (the event's target is the avatar, a hero rather than its PlayerState)
450
- if (targetName && (event.target || '').trim() !== targetName.trim()) {
449
+ // Only changes to this actor's attributes count (the event's target is the avatar, a hero rather than its
450
+ // PlayerState). Engines older than the target field don't send it: those events can't be told apart.
451
+ if (targetName && event.target && event.target.trim() !== targetName.trim()) {
451
452
  return false;
452
453
  }
453
454
  lastEvent = event;
@@ -532,7 +533,7 @@ exports.gasExpect = test_1.expect.extend((0, instrument_1.instrumentMatchers)({
532
533
  // Verify whether any conflicting attribute change events arrived
533
534
  const conflictingEvent = capturedEvents.find(ev => (ev.eventType === specter_client_1.SpecterEventType.GameplayAttribute || ev.eventType === 'GameplayAttribute') &&
534
535
  (ev.eventName === attributeName || ev.eventName?.includes(attributeName)) &&
535
- (!targetName || (ev.target || '').trim() === targetName.trim()) &&
536
+ (!targetName || !ev.target || ev.target.trim() === targetName.trim()) &&
536
537
  parseFloat(ev.oldValue) !== parseFloat(ev.newValue));
537
538
  if (!conflictingEvent) {
538
539
  const currentVal = await locator.getAttributeValue(attributeSet, attributeName).catch(() => initialValue);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.147",
3
+ "version": "1.0.149",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",