@specter-automation/test 1.0.110 → 1.0.112

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.
@@ -63,6 +63,13 @@ export interface SpecterActorEvents {
63
63
  z: number;
64
64
  };
65
65
  };
66
+ OnAbilityActivated: {
67
+ ability: string;
68
+ abilityName: string;
69
+ abilityClass: string;
70
+ abilityPath?: string;
71
+ tags: string[];
72
+ };
66
73
  }
67
74
  export interface SpecterWidgetEvents {
68
75
  OnClicked: void;
@@ -330,6 +330,15 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
330
330
  */
331
331
  type(text: string, delayMs?: number): Promise<void>;
332
332
  triggerAbilityByTag(inputTag: string): Promise<void>;
333
+ /**
334
+ * Simulates an ability input press or release on this actor's ASC.
335
+ * Use this to interact with active abilities that use WaitInputPress/WaitInputRelease
336
+ * (e.g. toggle abilities like Steel's Shield Block).
337
+ *
338
+ * @param abilityTag - The gameplay tag of the ability (e.g. "Ability.Slot.D")
339
+ * @param pressed - true to simulate press, false to simulate release. Defaults to true.
340
+ */
341
+ pressAbilityInput(abilityTag: string, pressed?: boolean): Promise<void>;
333
342
  triggerAbilityWithTarget(abilityTag: string, target: SpecterLocator | Vector3): Promise<void>;
334
343
  applyGameplayEffect(effectClassPath: string, level?: number): Promise<void>;
335
344
  hasActiveGameplayEffect(effectClassPath: string): Promise<boolean>;
@@ -339,7 +348,7 @@ export declare class ActorLocator<T = any> extends SpecterLocator<T> {
339
348
  getGameplayEffectStackCount(effectClassPath: string): Promise<number>;
340
349
  getGameplayEffectLevel(effectClassPath: string): Promise<number>;
341
350
  getAttributeBaseValue(attributeSet: string, attributeName: string): Promise<number>;
342
- isAbilityExecuting(abilityClassPath: string): Promise<boolean>;
351
+ isAbilityExecuting(abilityOrClassPath: string): Promise<boolean>;
343
352
  cancelAbility(abilityClassPath: string): Promise<void>;
344
353
  getGameplayTagCount(tag: string): Promise<number>;
345
354
  hasAnyGameplayTags(tags: string[]): Promise<boolean>;
@@ -265,16 +265,27 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
265
265
  }
266
266
  }
267
267
  // If a client world is provided but neither playerId nor playerIndex is specified,
268
- // query the client world for its local PlayerId.
268
+ // query the client world silently for its local PlayerId.
269
269
  if (targetWorld && targetPlayerId === undefined && targetPlayerIndex === undefined) {
270
270
  try {
271
- const idResponse = await targetWorld.evaluate("GetPlayerId", {}, undefined);
272
- if (idResponse?.data?.playerId !== undefined) {
271
+ const idResponse = await targetWorld.evaluate("GetPlayerId", {}, undefined, undefined, true);
272
+ if (idResponse?.data?.playerId !== undefined && idResponse.data.playerId > 0) {
273
273
  targetPlayerId = idResponse.data.playerId;
274
274
  }
275
275
  }
276
276
  catch {
277
- // If GetPlayerId fails or isn't available yet, proceed without targetPlayerId
277
+ // If GetPlayerId fails or isn't available yet, proceed with fallback below
278
+ }
279
+ // Fallback: if playerId couldn't be resolved, infer playerIndex from client port (port 8081 -> index 1)
280
+ if (targetPlayerId === undefined) {
281
+ const transport = targetWorld.transport;
282
+ const portStr = transport?.port;
283
+ if (portStr) {
284
+ const portNum = parseInt(portStr, 10);
285
+ if (portNum > 8080 && portNum <= 8100) {
286
+ targetPlayerIndex = portNum - 8080;
287
+ }
288
+ }
278
289
  }
279
290
  }
280
291
  const payload = {};
@@ -847,6 +858,17 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
847
858
  async triggerAbilityByTag(inputTag) {
848
859
  await this.evaluate("TriggerAbilityByTag", { inputTag });
849
860
  }
861
+ /**
862
+ * Simulates an ability input press or release on this actor's ASC.
863
+ * Use this to interact with active abilities that use WaitInputPress/WaitInputRelease
864
+ * (e.g. toggle abilities like Steel's Shield Block).
865
+ *
866
+ * @param abilityTag - The gameplay tag of the ability (e.g. "Ability.Slot.D")
867
+ * @param pressed - true to simulate press, false to simulate release. Defaults to true.
868
+ */
869
+ async pressAbilityInput(abilityTag, pressed = true) {
870
+ await this.evaluate("TriggerGasInput", { tag: abilityTag, isPressed: pressed });
871
+ }
850
872
  async triggerAbilityWithTarget(abilityTag, target) {
851
873
  let payload = { abilityTag };
852
874
  if (target instanceof specter_locator_1.SpecterLocator) {
@@ -895,9 +917,12 @@ class ActorLocator extends specter_locator_1.SpecterLocator {
895
917
  const response = await this.evaluate("GetAttributeBaseValue", { attributeSet, attributeName });
896
918
  return response.data.baseValue;
897
919
  }
898
- async isAbilityExecuting(abilityClassPath) {
899
- const response = await this.evaluate("IsAbilityExecuting", { abilityClassPath });
900
- return response.data.executing;
920
+ async isAbilityExecuting(abilityOrClassPath) {
921
+ const response = await this.evaluate("IsAbilityExecuting", {
922
+ ability: abilityOrClassPath,
923
+ abilityClassPath: abilityOrClassPath
924
+ });
925
+ return response.data?.isExecuting ?? response.data?.executing ?? false;
901
926
  }
902
927
  async cancelAbility(abilityClassPath) {
903
928
  await this.evaluate("CancelAbility", { abilityClassPath });
@@ -276,7 +276,7 @@ export declare class SpecterWorld {
276
276
  * @param payload The data payload to send
277
277
  * @param context Optional string to distinguish identical commands in the UI (e.g., "Attacker" or "Player 1")
278
278
  */
279
- evaluate(commandName: string, payload?: any, context?: string, targetLocator?: string): Promise<any>;
279
+ evaluate(commandName: string, payload?: any, context?: string, targetLocator?: string, bHideStep?: boolean): Promise<any>;
280
280
  setTimeDilation(speed: number): Promise<void>;
281
281
  spawnActor(assetPath: string, options?: SpawnOptions): Promise<ActorLocator>;
282
282
  actor<T extends RegisteredActorClasses | (string & {})>(selector: T): ActorLocator<T>;
@@ -466,7 +466,13 @@ class SpecterWorld {
466
466
  * @param payload The data payload to send
467
467
  * @param context Optional string to distinguish identical commands in the UI (e.g., "Attacker" or "Player 1")
468
468
  */
469
- async evaluate(commandName, payload = {}, context, targetLocator) {
469
+ async evaluate(commandName, payload = {}, context, targetLocator, bHideStep = false) {
470
+ if (bHideStep) {
471
+ return await this.transport.sendCommand({
472
+ command: commandName,
473
+ payload: payload
474
+ });
475
+ }
470
476
  const formattedCommand = commandName.charAt(0).toLowerCase() + commandName.slice(1);
471
477
  const portTag = this.transport.friendlyPortTag;
472
478
  // Format the title based on whether context was provided
@@ -27,6 +27,9 @@ declare global {
27
27
  toHaveGameplayEffectLevel(effectClassPath: string, expectedLevel: number): T extends SpecterLocator ? Promise<R> : never;
28
28
  toHaveAttributeBaseValue(attributeSet: string, attributeName: string, expectedValue: number): T extends SpecterLocator ? Promise<R> : never;
29
29
  toBeExecutingAbility(abilityClassPath: string): T extends SpecterLocator ? Promise<R> : never;
30
+ toHaveActivatedAbility(ability: string, optionsOrTrigger?: {
31
+ timeout?: number;
32
+ } | (() => Promise<void>), triggerAction?: () => Promise<void>): T extends SpecterLocator ? Promise<R> : never;
30
33
  toHaveGameplayTagCount(tag: string, expectedCount: number): T extends SpecterLocator ? Promise<R> : never;
31
34
  toHaveAnyGameplayTags(tags: string[]): T extends SpecterLocator ? Promise<R> : never;
32
35
  toHaveAllGameplayTags(tags: string[]): T extends SpecterLocator ? Promise<R> : never;
@@ -61,6 +64,9 @@ export interface GasMatchers {
61
64
  toHaveGameplayEffectLevel(effectClassPath: string, expectedLevel: number): Promise<void>;
62
65
  toHaveAttributeBaseValue(attributeSet: string, attributeName: string, expectedValue: number): Promise<void>;
63
66
  toBeExecutingAbility(abilityClassPath: string): Promise<void>;
67
+ toHaveActivatedAbility(ability: string, optionsOrTrigger?: {
68
+ timeout?: number;
69
+ } | (() => Promise<void>), triggerAction?: () => Promise<void>): Promise<void>;
64
70
  toHaveGameplayTagCount(tag: string, expectedCount: number): Promise<void>;
65
71
  toHaveAnyGameplayTags(tags: string[]): Promise<void>;
66
72
  toHaveAllGameplayTags(tags: string[]): Promise<void>;
@@ -172,6 +178,14 @@ export declare const gasExpect: import("playwright/test").Expect<{
172
178
  actual: boolean;
173
179
  expected: boolean;
174
180
  }>;
181
+ toHaveActivatedAbility(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, ability: string, optionsOrTrigger?: {
182
+ timeout?: number;
183
+ } | (() => Promise<void>), triggerAction?: () => Promise<void>): Promise<{
184
+ pass: boolean;
185
+ message: () => string;
186
+ actual: boolean;
187
+ expected: boolean;
188
+ }>;
175
189
  toHaveGameplayTagCount(this: import("playwright/test").ExpectMatcherState, locator: ActorLocator, tag: string, expectedCount: number): Promise<{
176
190
  pass: boolean;
177
191
  message: () => string;
@@ -768,6 +768,110 @@ exports.gasExpect = test_1.expect.extend({
768
768
  return { pass: isNot, message: () => `Expected executing: ${!isNot}. Got: ${exec}`, actual: exec, expected: !isNot };
769
769
  });
770
770
  },
771
+ async toHaveActivatedAbility(locator, ability, optionsOrTrigger, triggerAction) {
772
+ const assertionName = 'toHaveActivatedAbility';
773
+ const isNot = this.isNot;
774
+ const prefix = isNot ? 'not.toHaveActivatedAbility' : 'toHaveActivatedAbility';
775
+ const stepName = `${prefix}('${ability}') @ ${locator.toString()}`;
776
+ let timeout = 5000;
777
+ let action;
778
+ if (typeof optionsOrTrigger === 'function') {
779
+ action = optionsOrTrigger;
780
+ }
781
+ else if (optionsOrTrigger && typeof optionsOrTrigger === 'object') {
782
+ timeout = optionsOrTrigger.timeout ?? 5000;
783
+ }
784
+ if (triggerAction && typeof triggerAction === 'function') {
785
+ action = triggerAction;
786
+ }
787
+ return await test_1.default.step(stepName, async () => {
788
+ // 1. Check initially if it's already active
789
+ let isAlreadyActive = false;
790
+ try {
791
+ isAlreadyActive = await locator.isAbilityExecuting(ability);
792
+ }
793
+ catch (err) {
794
+ // Ignore initial check errors
795
+ }
796
+ if (isAlreadyActive) {
797
+ if (isNot) {
798
+ return {
799
+ pass: isNot,
800
+ message: () => `Expected ability '${ability}' not to be active on ${locator.toString()}, but it was already executing.`,
801
+ actual: true,
802
+ expected: !isNot
803
+ };
804
+ }
805
+ return {
806
+ pass: !isNot,
807
+ message: () => 'passed',
808
+ actual: true,
809
+ expected: !isNot
810
+ };
811
+ }
812
+ // 2. Set up event listener for OnAbilityActivated
813
+ const eventPromise = locator.waitForEvent('OnAbilityActivated', {
814
+ timeout,
815
+ predicate: (data) => {
816
+ if (!data)
817
+ return false;
818
+ if (data.ability === ability || data.abilityName === ability || data.abilityClass === ability) {
819
+ return true;
820
+ }
821
+ if (data.tags && Array.isArray(data.tags)) {
822
+ if (data.tags.some(t => t === ability || t.includes(ability))) {
823
+ return true;
824
+ }
825
+ }
826
+ if (data.abilityClass && data.abilityClass.includes(ability)) {
827
+ return true;
828
+ }
829
+ if (data.abilityPath && data.abilityPath.includes(ability)) {
830
+ return true;
831
+ }
832
+ return false;
833
+ }
834
+ }).then(() => true).catch(() => false);
835
+ // 3. If a trigger action was provided, run it while the listener is active
836
+ if (action) {
837
+ await action();
838
+ }
839
+ // 4. Await event with polling fallback
840
+ let didActivate = await eventPromise;
841
+ // If event did not catch it (e.g. slight timing difference), check executing state
842
+ if (!didActivate && !isNot) {
843
+ try {
844
+ didActivate = await locator.isAbilityExecuting(ability);
845
+ }
846
+ catch { }
847
+ }
848
+ if (didActivate === !isNot) {
849
+ return {
850
+ pass: !isNot,
851
+ message: () => 'passed',
852
+ actual: didActivate,
853
+ expected: !isNot
854
+ };
855
+ }
856
+ // Failure: Fetch rich AI diagnostics
857
+ let diagStr = '';
858
+ try {
859
+ const diags = await locator.getDiagnostics({ limit: 20 });
860
+ diagStr = formatAiDiagnostics(diags);
861
+ }
862
+ catch { }
863
+ return {
864
+ pass: isNot,
865
+ message: () => `${this.utils.matcherHint(assertionName, locator.toString(), ability)}\n\n` +
866
+ `Timed out after ${timeout}ms waiting for ability activation on '${ability}'.\n` +
867
+ `Expected: ${isNot ? 'not to activate ability' : 'to activate ability'} ${ability}\n` +
868
+ `Received: ${didActivate ? 'activated' : 'not activated'}` +
869
+ diagStr,
870
+ actual: didActivate,
871
+ expected: !isNot
872
+ };
873
+ });
874
+ },
771
875
  async toHaveGameplayTagCount(locator, tag, expectedCount) {
772
876
  const isNot = this.isNot;
773
877
  return await test_1.default.step(`${isNot ? 'not.' : ''}toHaveGameplayTagCount('${tag}', ${expectedCount})`, async () => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@specter-automation/test",
3
- "version": "1.0.110",
3
+ "version": "1.0.112",
4
4
  "description": "Playwright integration for Unreal Engine automation via Specter",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",