@specter-automation/test 1.0.117 → 1.0.119

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.
@@ -0,0 +1,27 @@
1
+ /**
2
+ * Runs a group of assertions together and reports every result, instead of
3
+ * stopping at the first failure the way `Promise.all` does.
4
+ *
5
+ * Start the checks BEFORE triggering the action so they are already listening
6
+ * for the engine events the action produces:
7
+ *
8
+ * ```ts
9
+ * await expectAll(
10
+ * enemies.flatMap((enemy, i) => [
11
+ * expect(enemy).toHaveGameplayTag('Status.Stunned'),
12
+ * expect(enemy).toHaveAttributeChange('HealthSet', 'Health', { delta: -100 }),
13
+ * expect(enemy).toHaveMovedFurtherThan(spawnLocations[i], 100),
14
+ * ]),
15
+ * () => steelActor.triggerAbilityWithTarget(steel.abilityCharge, target),
16
+ * );
17
+ * ```
18
+ *
19
+ * If any check fails, throws an `AggregateError` whose message reads
20
+ * "N of M checks passed" followed by each failure. If the action itself throws,
21
+ * the checks are still awaited (so no step keeps running after the test ends)
22
+ * and the action's error is rethrown.
23
+ *
24
+ * @param checks Assertion promises, already started (e.g. `expect(x).toHave…()`).
25
+ * @param action Optional trigger to run after the checks are listening.
26
+ */
27
+ export declare function expectAll(checks: ReadonlyArray<PromiseLike<unknown>>, action?: () => unknown | Promise<unknown>): Promise<void>;
@@ -0,0 +1,66 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.expectAll = expectAll;
4
+ /**
5
+ * Runs a group of assertions together and reports every result, instead of
6
+ * stopping at the first failure the way `Promise.all` does.
7
+ *
8
+ * Start the checks BEFORE triggering the action so they are already listening
9
+ * for the engine events the action produces:
10
+ *
11
+ * ```ts
12
+ * await expectAll(
13
+ * enemies.flatMap((enemy, i) => [
14
+ * expect(enemy).toHaveGameplayTag('Status.Stunned'),
15
+ * expect(enemy).toHaveAttributeChange('HealthSet', 'Health', { delta: -100 }),
16
+ * expect(enemy).toHaveMovedFurtherThan(spawnLocations[i], 100),
17
+ * ]),
18
+ * () => steelActor.triggerAbilityWithTarget(steel.abilityCharge, target),
19
+ * );
20
+ * ```
21
+ *
22
+ * If any check fails, throws an `AggregateError` whose message reads
23
+ * "N of M checks passed" followed by each failure. If the action itself throws,
24
+ * the checks are still awaited (so no step keeps running after the test ends)
25
+ * and the action's error is rethrown.
26
+ *
27
+ * @param checks Assertion promises, already started (e.g. `expect(x).toHave…()`).
28
+ * @param action Optional trigger to run after the checks are listening.
29
+ */
30
+ async function expectAll(checks, action) {
31
+ // Attach handlers to every check immediately, so a check that fails while
32
+ // the action is still running is never reported as an unhandled rejection.
33
+ const settled = Promise.allSettled(checks);
34
+ if (action) {
35
+ try {
36
+ await action();
37
+ }
38
+ catch (actionError) {
39
+ await settled;
40
+ throw actionError;
41
+ }
42
+ }
43
+ const results = await settled;
44
+ const failures = results.filter((r) => r.status === 'rejected');
45
+ if (failures.length === 0) {
46
+ return;
47
+ }
48
+ const passed = results.length - failures.length;
49
+ const summary = `${passed} of ${results.length} checks passed`;
50
+ const details = failures
51
+ .map((f, i) => ` ${i + 1}. ${firstLine(f.reason)}`)
52
+ .join('\n');
53
+ const error = new AggregateError(failures.map(f => f.reason), `${summary}\n\nFailed checks:\n${details}`);
54
+ // Point the stack (and Playwright's code frame) at the test's expectAll call, not this file.
55
+ Error.captureStackTrace?.(error, expectAll);
56
+ throw error;
57
+ }
58
+ function firstLine(reason) {
59
+ const text = reason instanceof Error ? reason.message : String(reason);
60
+ // Strip ANSI colour codes that Playwright adds to matcher messages.
61
+ const clean = text.replace(/\u001b\[[0-9;]*m/g, '');
62
+ // Specter matcher messages start with the matcher hint (matcher + locator),
63
+ // and the next line says what went wrong, so keep both.
64
+ const lines = clean.split('\n').map(l => l.trim()).filter(l => l.length > 0);
65
+ return lines.slice(0, 2).join(' — ') || clean.trim();
66
+ }
@@ -23,6 +23,8 @@ export interface FilterOptions {
23
23
  export declare class SpecterLocator<T = any> {
24
24
  pipeline: LocatorStep[];
25
25
  protected transport: SpecterTransport;
26
+ /** Friendly name set with named(), shown in step titles and the in-engine runner. */
27
+ label?: string;
26
28
  constructor(transport: SpecterTransport, initialPipeline?: LocatorStep[]);
27
29
  protected clone(): this;
28
30
  get port(): string;
@@ -49,6 +51,18 @@ export declare class SpecterLocator<T = any> {
49
51
  */
50
52
  all(): Promise<this[]>;
51
53
  count(bHideStep?: boolean): Promise<number>;
54
+ /**
55
+ * Gives this locator a friendly name for step titles, error messages and the
56
+ * in-engine runner, e.g. `enemies[0]` instead of `getByTag('Spawned_c36e0554')`.
57
+ * Returns a copy; locators derived from it later (nth, filter, …) do not inherit the name.
58
+ *
59
+ * ```ts
60
+ * const enemies = spawned.map((enemy, i) => enemy.named(`enemies[${i}]`));
61
+ * ```
62
+ */
63
+ named(label: string): this;
64
+ /** The locator pipeline only, without the friendly name. */
65
+ toSelectorString(): string;
52
66
  toString(): string;
53
67
  /**
54
68
  * The "Generic Bridge": Calls any C++ command and returns the raw data.
@@ -8,6 +8,8 @@ const test_1 = __importDefault(require("@playwright/test"));
8
8
  class SpecterLocator {
9
9
  pipeline = [];
10
10
  transport;
11
+ /** Friendly name set with named(), shown in step titles and the in-engine runner. */
12
+ label;
11
13
  constructor(transport, initialPipeline = []) {
12
14
  this.transport = transport;
13
15
  this.pipeline = initialPipeline;
@@ -183,9 +185,28 @@ class SpecterLocator {
183
185
  const response = await this.evaluate("GetCount", {}, undefined, bHideStep);
184
186
  return response?.data?.count ?? 0;
185
187
  }
186
- toString() {
188
+ /**
189
+ * Gives this locator a friendly name for step titles, error messages and the
190
+ * in-engine runner, e.g. `enemies[0]` instead of `getByTag('Spawned_c36e0554')`.
191
+ * Returns a copy; locators derived from it later (nth, filter, …) do not inherit the name.
192
+ *
193
+ * ```ts
194
+ * const enemies = spawned.map((enemy, i) => enemy.named(`enemies[${i}]`));
195
+ * ```
196
+ */
197
+ named(label) {
198
+ const namedLocator = this.clone();
199
+ namedLocator.label = label;
200
+ return namedLocator;
201
+ }
202
+ /** The locator pipeline only, without the friendly name. */
203
+ toSelectorString() {
187
204
  return this.pipeline.map(step => `${step.action}('${step.value}')`).join(' -> ');
188
205
  }
206
+ toString() {
207
+ const selector = this.toSelectorString();
208
+ return this.label ? `${this.label} (${selector})` : selector;
209
+ }
189
210
  // ==========================================
190
211
  // THE "ENTITY" METHODS
191
212
  // ==========================================
@@ -309,7 +330,9 @@ class SpecterLocator {
309
330
  * Clones the locator and binds it to a different player/client's world connection.
310
331
  */
311
332
  client(world) {
312
- return new this.constructor(world.transport, [...this.pipeline]);
333
+ const bound = new this.constructor(world.transport, [...this.pipeline]);
334
+ bound.label = this.label; // Same actor on another connection keeps its name.
335
+ return bound;
313
336
  }
314
337
  async evaluate(command, payload = {}, context, bHideStep = false) {
315
338
  if (bHideStep) {
@@ -191,6 +191,15 @@ export declare class SpecterTransport {
191
191
  get port(): string;
192
192
  get friendlyPortTag(): string;
193
193
  constructor(url?: string);
194
+ /**
195
+ * Probes the Editor Control Server (default port 8079) and requests PIE to start.
196
+ * Returns true if the editor acknowledged the request, false otherwise.
197
+ */
198
+ static requestEditorPIE(editorUrl?: string): Promise<boolean>;
199
+ /**
200
+ * Sends a command to the Editor Control Server (e.g. 'stopPIE', 'getStatus').
201
+ */
202
+ static sendEditorCommand(command: string, editorUrl?: string): Promise<any>;
194
203
  connect(timeoutMs?: number): Promise<void>;
195
204
  private setupMessageRouter;
196
205
  sendCommand(payload: SpecterPayload): Promise<any>;
@@ -82,12 +82,123 @@ class SpecterTransport {
82
82
  SpecterTransport.instance = this;
83
83
  }
84
84
  }
85
+ /**
86
+ * Probes the Editor Control Server (default port 8079) and requests PIE to start.
87
+ * Returns true if the editor acknowledged the request, false otherwise.
88
+ */
89
+ static async requestEditorPIE(editorUrl = 'ws://127.0.0.1:8079') {
90
+ return new Promise((resolve) => {
91
+ let settled = false;
92
+ const finish = (result) => {
93
+ if (!settled) {
94
+ settled = true;
95
+ resolve(result);
96
+ }
97
+ };
98
+ const timer = setTimeout(() => {
99
+ try {
100
+ socket.close();
101
+ }
102
+ catch (e) { }
103
+ finish(false);
104
+ }, 2500);
105
+ let socket;
106
+ try {
107
+ socket = new ws_1.default(editorUrl);
108
+ }
109
+ catch (e) {
110
+ clearTimeout(timer);
111
+ return finish(false);
112
+ }
113
+ socket.on('open', () => {
114
+ const req = JSON.stringify({
115
+ command: 'requestPIE',
116
+ messageId: 'auto-pie-start'
117
+ });
118
+ socket.send(req);
119
+ });
120
+ socket.on('message', (data) => {
121
+ try {
122
+ const parsed = JSON.parse(data.toString('utf-8'));
123
+ if (parsed.status === 'success') {
124
+ clearTimeout(timer);
125
+ try {
126
+ socket.close();
127
+ }
128
+ catch (e) { }
129
+ finish(true);
130
+ }
131
+ }
132
+ catch (e) { }
133
+ });
134
+ socket.on('error', () => {
135
+ clearTimeout(timer);
136
+ finish(false);
137
+ });
138
+ });
139
+ }
140
+ /**
141
+ * Sends a command to the Editor Control Server (e.g. 'stopPIE', 'getStatus').
142
+ */
143
+ static async sendEditorCommand(command, editorUrl = 'ws://127.0.0.1:8079') {
144
+ return new Promise((resolve) => {
145
+ let settled = false;
146
+ const finish = (result) => {
147
+ if (!settled) {
148
+ settled = true;
149
+ resolve(result);
150
+ }
151
+ };
152
+ const timer = setTimeout(() => {
153
+ try {
154
+ socket.close();
155
+ }
156
+ catch (e) { }
157
+ finish(null);
158
+ }, 2500);
159
+ let socket;
160
+ try {
161
+ socket = new ws_1.default(editorUrl);
162
+ }
163
+ catch (e) {
164
+ clearTimeout(timer);
165
+ return finish(null);
166
+ }
167
+ socket.on('open', () => {
168
+ socket.send(JSON.stringify({
169
+ command,
170
+ messageId: `cmd-${Date.now()}`
171
+ }));
172
+ });
173
+ socket.on('message', (data) => {
174
+ try {
175
+ const parsed = JSON.parse(data.toString('utf-8'));
176
+ clearTimeout(timer);
177
+ try {
178
+ socket.close();
179
+ }
180
+ catch (e) { }
181
+ finish(parsed);
182
+ }
183
+ catch (e) {
184
+ finish(null);
185
+ }
186
+ });
187
+ socket.on('error', () => {
188
+ clearTimeout(timer);
189
+ finish(null);
190
+ });
191
+ });
192
+ }
85
193
  async connect(timeoutMs = 20000) {
86
194
  if (this.isConnected) {
87
195
  return;
88
196
  }
89
197
  const startTime = Date.now();
90
198
  let lastError = null;
199
+ let pieRequested = false;
200
+ let editorDetected = false;
201
+ const isDefaultPort = this.url.includes(':8080');
91
202
  while (Date.now() - startTime < timeoutMs) {
92
203
  try {
93
204
  await new Promise((resolve, reject) => {
@@ -127,9 +238,26 @@ class SpecterTransport {
127
238
  }
128
239
  catch (err) {
129
240
  lastError = err;
241
+ // If connecting to default game port 8080 and haven't probed Editor Control Server yet
242
+ if (isDefaultPort && !pieRequested) {
243
+ pieRequested = true;
244
+ try {
245
+ const editorPort = process.env.SPECTER_EDITOR_PORT || '8079';
246
+ const editorUrl = `ws://127.0.0.1:${editorPort}`;
247
+ const requested = await SpecterTransport.requestEditorPIE(editorUrl);
248
+ if (requested) {
249
+ editorDetected = true;
250
+ console.log(`[SPECTER] Unreal Editor detected on ${editorUrl}. Auto-started PIE session, awaiting game server...`);
251
+ }
252
+ }
253
+ catch (e) { }
254
+ }
130
255
  await new Promise(resolve => setTimeout(resolve, 1000));
131
256
  }
132
257
  }
258
+ if (isDefaultPort && !editorDetected) {
259
+ throw new Error(`Specter Connection Timeout: Could not connect to Unreal Engine on URL ${this.url} after ${timeoutMs}ms. Neither an active PIE session (port 8080) nor an open Unreal Editor (port 8079) was detected.`);
260
+ }
133
261
  throw new Error(`Specter Connection Timeout: Could not connect to Unreal Engine on URL ${this.url} after ${timeoutMs}ms. Details: ${lastError?.message}`);
134
262
  }
135
263
  // The core router that prevents race conditions and parses JSON automatically
@@ -0,0 +1,42 @@
1
+ /**
2
+ * Shared contract between the worker-side matcher instrumentation and the
3
+ * SpecterReporter. Keep this file free of runtime imports so the reporter can
4
+ * load it without pulling in Playwright's test runtime or the transport.
5
+ */
6
+ import type { GasMatchers } from '../matchers/gas-matchers';
7
+ import type { ActorMatchers } from '../matchers/actor-matchers';
8
+ import type { LocatorMatchers } from '../matchers/locator-matchers';
9
+ import type { WidgetMatchers } from '../matchers/widget-matchers';
10
+ import type { MaterialMatchers } from '../matchers/material-matchers';
11
+ import type { AiMatchers } from '../matchers/ai-matchers';
12
+ /** Attachment name used to carry a matcher result from the worker to the reporter. Leading "_" hides it in Playwright's reports. */
13
+ export declare const SPECTER_MATCHER_ATTACHMENT = "_specter-matcher";
14
+ /** Structured result of one Specter matcher call. */
15
+ export interface SpecterMatcherReport {
16
+ matcher: string;
17
+ isNot: boolean;
18
+ pass: boolean;
19
+ /** Locator pipeline, e.g. getByTag('Spawned_c36e0554') */
20
+ locator: string;
21
+ /** Friendly name set with locator.named(), e.g. enemies[0] */
22
+ locatorLabel?: string;
23
+ /** Which connection ran the check in multi-client tests, e.g. "Server", "Client 1" */
24
+ client?: string;
25
+ expected?: unknown;
26
+ actual?: unknown;
27
+ }
28
+ export type SpecterMatcherName = keyof GasMatchers | keyof ActorMatchers | keyof LocatorMatchers | keyof WidgetMatchers | keyof MaterialMatchers | keyof AiMatchers;
29
+ /**
30
+ * Every Specter matcher. The compile-time check below fails the build if a
31
+ * matcher is added to one of the matcher interfaces but not to this list.
32
+ */
33
+ export declare const SPECTER_MATCHER_NAMES: readonly ["toHaveAttributeValue", "toHaveAttributeChange", "toHaveGameplayTag", "toHaveGameplayEffect", "toHaveAppliedGameplayEffect", "toHaveGameplayAbility", "toHaveAbilityCooldown", "toHaveGameplayEffectStackCount", "toHaveGameplayEffectLevel", "toHaveAttributeBaseValue", "toBeExecutingAbility", "toHaveActivatedAbility", "toHaveGameplayTagCount", "toHaveAnyGameplayTags", "toHaveAllGameplayTags", "toHaveMovedFurtherThan", "toHaveLocation", "toHaveInputMappingContext", "toHaveInputActionValue", "toHavePlayerScore", "toBeNiagaraActive", "toHaveNiagaraAsset", "toBeAudioPlaying", "toHaveSoundAsset", "toBePhysicsSimulating", "toBePhysicsAsleep", "toHaveVelocity", "toHaveCameraFOV", "toBeCameraShaking", "toHaveCameraViewTarget", "toBeAINavigating", "toHaveTeamId", "toBeHostileTowards", "toBePossessed", "toBePlayerControlled", "toBeLocallyControlled", "toHaveController", "toBeFalling", "toBeSwimming", "toBeFlying", "toBeCrouching", "toBeMovingOnGround", "toHaveMovementMode", "toBeVisible", "toHavePropertyValue", "toBeInViewport", "toBeDestroyed", "toHaveCount", "toHaveText", "toHaveValue", "toContainText", "toBeEnabled", "toHaveMaterialScalarParameter", "toHaveMaterialVectorParameter", "toHaveMaterial", "toBeDynamicMaterial", "toHaveMaterialTextureParameter", "toHaveBlackboardValue", "toHaveAIState", "toBeMovingTowards", "toBeMovingAwayFrom", "toBeWithinDistance", "toBeFollowing", "toHaveLineOfSightTo", "toBeRunningBehaviorTree"];
34
+ export declare function isSpecterMatcher(name: string): boolean;
35
+ /**
36
+ * Parses Playwright's expect step title, e.g. `Expect "soft not toHaveGameplayTag"`.
37
+ * Returns null for titles that are not a Specter matcher (built-ins, custom messages).
38
+ */
39
+ export declare function parseSpecterExpectTitle(title: string): {
40
+ matcher: string;
41
+ isNot: boolean;
42
+ } | null;
@@ -0,0 +1,54 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.SPECTER_MATCHER_NAMES = exports.SPECTER_MATCHER_ATTACHMENT = void 0;
4
+ exports.isSpecterMatcher = isSpecterMatcher;
5
+ exports.parseSpecterExpectTitle = parseSpecterExpectTitle;
6
+ /** Attachment name used to carry a matcher result from the worker to the reporter. Leading "_" hides it in Playwright's reports. */
7
+ exports.SPECTER_MATCHER_ATTACHMENT = '_specter-matcher';
8
+ /**
9
+ * Every Specter matcher. The compile-time check below fails the build if a
10
+ * matcher is added to one of the matcher interfaces but not to this list.
11
+ */
12
+ exports.SPECTER_MATCHER_NAMES = [
13
+ // gas-matchers
14
+ 'toHaveAttributeValue', 'toHaveAttributeChange', 'toHaveGameplayTag', 'toHaveGameplayEffect',
15
+ 'toHaveAppliedGameplayEffect', 'toHaveGameplayAbility', 'toHaveAbilityCooldown',
16
+ 'toHaveGameplayEffectStackCount', 'toHaveGameplayEffectLevel', 'toHaveAttributeBaseValue',
17
+ 'toBeExecutingAbility', 'toHaveActivatedAbility', 'toHaveGameplayTagCount',
18
+ 'toHaveAnyGameplayTags', 'toHaveAllGameplayTags',
19
+ // actor-matchers
20
+ 'toHaveMovedFurtherThan', 'toHaveLocation', 'toHaveInputMappingContext', 'toHaveInputActionValue',
21
+ 'toHavePlayerScore', 'toBeNiagaraActive', 'toHaveNiagaraAsset', 'toBeAudioPlaying', 'toHaveSoundAsset',
22
+ 'toBePhysicsSimulating', 'toBePhysicsAsleep', 'toHaveVelocity', 'toHaveCameraFOV', 'toBeCameraShaking',
23
+ 'toHaveCameraViewTarget', 'toBeAINavigating', 'toHaveTeamId', 'toBeHostileTowards', 'toBePossessed',
24
+ 'toBePlayerControlled', 'toBeLocallyControlled', 'toHaveController', 'toBeFalling', 'toBeSwimming',
25
+ 'toBeFlying', 'toBeCrouching', 'toBeMovingOnGround', 'toHaveMovementMode',
26
+ // locator-matchers
27
+ 'toBeVisible', 'toHavePropertyValue', 'toBeInViewport', 'toBeDestroyed', 'toHaveCount',
28
+ // widget-matchers
29
+ 'toHaveText', 'toHaveValue', 'toContainText', 'toBeEnabled',
30
+ // material-matchers
31
+ 'toHaveMaterialScalarParameter', 'toHaveMaterialVectorParameter', 'toHaveMaterial',
32
+ 'toBeDynamicMaterial', 'toHaveMaterialTextureParameter',
33
+ // ai-matchers
34
+ 'toHaveBlackboardValue', 'toHaveAIState', 'toBeMovingTowards', 'toBeMovingAwayFrom',
35
+ 'toBeWithinDistance', 'toBeFollowing', 'toHaveLineOfSightTo', 'toBeRunningBehaviorTree',
36
+ ];
37
+ // If this line errors, add the names shown in the error to SPECTER_MATCHER_NAMES.
38
+ const _allMatchersListed = true;
39
+ void _allMatchersListed;
40
+ const SPECTER_MATCHER_SET = new Set(exports.SPECTER_MATCHER_NAMES);
41
+ function isSpecterMatcher(name) {
42
+ return SPECTER_MATCHER_SET.has(name);
43
+ }
44
+ /**
45
+ * Parses Playwright's expect step title, e.g. `Expect "soft not toHaveGameplayTag"`.
46
+ * Returns null for titles that are not a Specter matcher (built-ins, custom messages).
47
+ */
48
+ function parseSpecterExpectTitle(title) {
49
+ const match = title.match(/^Expect "(?:poll )?(?:soft )?(not )?([A-Za-z]+)"$/);
50
+ if (!match || !isSpecterMatcher(match[2])) {
51
+ return null;
52
+ }
53
+ return { matcher: match[2], isNot: !!match[1] };
54
+ }
@@ -5,12 +5,17 @@ export default class SpecterReporter implements Reporter {
5
5
  private queue;
6
6
  private testStepCounters;
7
7
  private stepIdMap;
8
+ /** Playwright's outer `Expect "<matcher>"` steps for Specter matchers. They are shown under their wrapper step's name. */
9
+ private specterExpectSteps;
8
10
  constructor();
9
11
  private connect;
10
12
  private send;
11
13
  onBegin(config: FullConfig, suite: Suite): void;
12
14
  onTestBegin(test: TestCase): void;
13
15
  private isNestedExpect;
16
+ /** The step opened by instrumentMatchers directly under a Specter expect step. */
17
+ private isSpecterWrapper;
18
+ private readMatcherReport;
14
19
  private getParentStepName;
15
20
  onStepBegin(test: TestCase, result: TestResult, step: TestStep): void;
16
21
  private customStepDurations;