@nice2dev/testing 1.2.2 → 1.3.0

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.
package/dist/index.d.ts CHANGED
@@ -426,6 +426,15 @@ export declare const DEFAULT_BREAKPOINTS: [string, number][];
426
426
  */
427
427
  export declare const DEFAULT_STYLE_PROPERTIES: string[];
428
428
 
429
+ /**
430
+ * Declares one test per device. Pass your runner's `describe` and `it` (vitest, jest):
431
+ *
432
+ * ```ts
433
+ * describeInputContract('NiceTabs', { render, setup, steps }, { describe, it });
434
+ * ```
435
+ */
436
+ export declare function describeInputContract(title: string, contract: InputContract, api: TestApi): void;
437
+
429
438
  /**
430
439
  * Device configurations for mobile testing
431
440
  */
@@ -633,6 +642,33 @@ export declare interface I18nTestResult {
633
642
  rtlIssues: string[];
634
643
  }
635
644
 
645
+ export declare interface InputContract {
646
+ /** Mounts the control; may return a cleanup. */
647
+ render: () => void | (() => void);
648
+ /** Runs after render, before the steps (e.g. focus the first item). */
649
+ setup?: () => void;
650
+ steps: InputContractStep[];
651
+ /** Devices to run (default both). */
652
+ devices?: ('keyboard' | 'gamepad')[];
653
+ /** Pad family for the gamepad run (default `xbox`). */
654
+ family?: MockGamepadFamily;
655
+ }
656
+
657
+ export declare type InputContractDirection = 'up' | 'down' | 'left' | 'right';
658
+
659
+ export declare type InputContractIntent = 'navigate' | 'activate' | 'back' | 'secondary' | 'tertiary' | 'menu' | 'view' | 'sectionPrev' | 'sectionNext' | 'pagePrev' | 'pageNext' | 'first' | 'last' | 'toggleHints';
660
+
661
+ export declare interface InputContractStep {
662
+ intent: InputContractIntent;
663
+ direction?: InputContractDirection;
664
+ /** Only for one device (a keyboard-only key, a pad-only rule). */
665
+ only?: 'keyboard' | 'gamepad';
666
+ /** Where focus must be after the step: a selector, or a check of the focused element. */
667
+ expectFocus?: string | ((el: Element | null) => boolean);
668
+ /** Any other check after the step (throw to fail). */
669
+ expect?: () => void;
670
+ }
671
+
636
672
  /**
637
673
  * Check if a checkbox/toggle is checked.
638
674
  */
@@ -726,6 +762,47 @@ export declare interface MockDataSourceOptions<T> {
726
762
  keyField?: string;
727
763
  }
728
764
 
765
+ export declare interface MockGamepad {
766
+ readonly index: number;
767
+ readonly id: string;
768
+ connect(): void;
769
+ disconnect(): void;
770
+ press(button: MockGamepadButton, value?: number): void;
771
+ release(button: MockGamepadButton): void;
772
+ /** Press, let a couple of frames run, release, let a frame run. */
773
+ tap(button: MockGamepadButton): void;
774
+ /** Press, keep it down for `ms` of frames (repeats happen), release. */
775
+ hold(button: MockGamepadButton, ms: number): void;
776
+ /** Push a stick to x / y in −1…1 (y down positive). */
777
+ tilt(stick: 'left' | 'right', x: number, y: number): void;
778
+ /** Back to the centre. */
779
+ center(stick: 'left' | 'right'): void;
780
+ /** Run `ms` of animation frames (default one frame). */
781
+ tick(ms?: number): void;
782
+ }
783
+
784
+ /**
785
+ * A fake pad. The first one installs the fake Gamepad API and frame clock on the window; call
786
+ * `resetMockGamepads()` after the test to put the real ones back.
787
+ */
788
+ export declare function mockGamepad(options?: MockGamepadOptions): MockGamepad;
789
+
790
+ /** Positions of the W3C standard mapping, or their Xbox names. */
791
+ export declare type MockGamepadButton = 'south' | 'east' | 'west' | 'north' | 'leftBumper' | 'rightBumper' | 'leftTrigger' | 'rightTrigger' | 'select' | 'start' | 'leftStick' | 'rightStick' | 'dpadUp' | 'dpadDown' | 'dpadLeft' | 'dpadRight' | 'home' | 'A' | 'B' | 'X' | 'Y' | 'LB' | 'RB' | 'LT' | 'RT' | 'View' | 'Menu' | 'LS' | 'RS';
792
+
793
+ export declare type MockGamepadFamily = 'xbox' | 'playstation' | 'nintendo' | 'steam' | 'generic';
794
+
795
+ export declare interface MockGamepadOptions {
796
+ /** Decides `Gamepad.id` (default `xbox`). */
797
+ family?: MockGamepadFamily;
798
+ /** A `Gamepad.id` of your own. */
799
+ id?: string;
800
+ index?: number;
801
+ mapping?: string;
802
+ /** Connect at once (default true). */
803
+ connect?: boolean;
804
+ }
805
+
729
806
  /**
730
807
  * Mock GraphQL operations
731
808
  */
@@ -913,6 +990,9 @@ export declare interface NiceTestWrapperProps {
913
990
  t?: (key: string, defaultValue: string) => string;
914
991
  }
915
992
 
993
+ /** Animation frames waiting to run — 0 when nothing polls the pads. */
994
+ export declare function pendingAnimationFrames(): number;
995
+
916
996
  /**
917
997
  * Percy configuration for CI
918
998
  * Use with @percy/cli
@@ -970,6 +1050,35 @@ export declare interface PerformanceBenchmarkConfig {
970
1050
  budgets: Record<string, number>;
971
1051
  }
972
1052
 
1053
+ /**
1054
+ * An intent through its default binding. Keyboard: the key on the focused element. Gamepad: the
1055
+ * button on a mock pad, with the frames the engine needs to read it. `first` / `last` have no
1056
+ * default button; on a pad they are the triggers of an engaged control.
1057
+ */
1058
+ export declare function pressIntent(intent: InputContractIntent, options?: PressIntentOptions): void;
1059
+
1060
+ export declare interface PressIntentOptions {
1061
+ device?: 'keyboard' | 'gamepad';
1062
+ /** For `navigate` (default `down`). */
1063
+ direction?: InputContractDirection;
1064
+ /** The pad to press on (default: a connected Xbox mock pad, created on first use). */
1065
+ pad?: MockGamepad;
1066
+ /** Family of the default pad. */
1067
+ family?: MockGamepadFamily;
1068
+ target?: Element | null;
1069
+ }
1070
+
1071
+ /** A keydown and keyup on the target (default: the focused element). Returns whether it was consumed. */
1072
+ export declare function pressKey(key: string, options?: PressKeyOptions): boolean;
1073
+
1074
+ export declare interface PressKeyOptions {
1075
+ target?: Element | null;
1076
+ shiftKey?: boolean;
1077
+ ctrlKey?: boolean;
1078
+ altKey?: boolean;
1079
+ metaKey?: boolean;
1080
+ }
1081
+
973
1082
  export declare interface PropertyTestConfig {
974
1083
  /** Number of test runs (default: 100) */
975
1084
  numRuns?: number;
@@ -988,11 +1097,17 @@ export declare interface PropertyTestConfig {
988
1097
  */
989
1098
  export declare function renderToSnapshot(element: ReactElement, options?: SnapshotOptions): string;
990
1099
 
1100
+ /** Disconnects every mock pad and puts back the real Gamepad API and frame clock. */
1101
+ export declare function resetMockGamepads(): void;
1102
+
991
1103
  export declare interface ResponsiveSnapshotOptions extends SnapshotOptions {
992
1104
  /** Breakpoints to test [name, width] */
993
1105
  breakpoints?: [string, number][];
994
1106
  }
995
1107
 
1108
+ /** Runs a contract once for one device; returns the failures (empty = passed). */
1109
+ export declare function runInputContract(contract: InputContract, device: 'keyboard' | 'gamepad'): string[];
1110
+
996
1111
  export declare type ScanType = 'sast' | 'dast' | 'sca' | 'secret-scan';
997
1112
 
998
1113
  export declare interface SecurityFinding {
@@ -1195,6 +1310,30 @@ export declare interface StressTestResult {
1195
1310
  errors: string[];
1196
1311
  }
1197
1312
 
1313
+ /**
1314
+ * Lays elements out in a grid of `columns` cells of `size` px with `gap` px between them, starting
1315
+ * at `origin` — a row of tabs is `columns: n`, a column of list items `columns: 1`.
1316
+ */
1317
+ export declare function stubGridLayout(elements: ArrayLike<Element>, options: {
1318
+ columns: number;
1319
+ size?: [number, number];
1320
+ gap?: number;
1321
+ origin?: [number, number];
1322
+ }): void;
1323
+
1324
+ /**
1325
+ * jsdom has no layout. Gives an element the box a spatial-navigation test needs (both
1326
+ * `getBoundingClientRect` and `getClientRects`); stub every element the test moves between.
1327
+ */
1328
+ export declare function stubLayout(el: Element, rect: StubRect): void;
1329
+
1330
+ export declare interface StubRect {
1331
+ left: number;
1332
+ top: number;
1333
+ width: number;
1334
+ height: number;
1335
+ }
1336
+
1198
1337
  export declare interface StyleSnapshotOptions extends SnapshotOptions {
1199
1338
  /** CSS properties to capture */
1200
1339
  properties?: string[];
@@ -1221,6 +1360,11 @@ export declare interface TelemetryConfig {
1221
1360
  flushInterval: number;
1222
1361
  }
1223
1362
 
1363
+ declare interface TestApi {
1364
+ describe: (name: string, fn: () => void) => void;
1365
+ it: (name: string, fn: () => void | Promise<void>) => void;
1366
+ }
1367
+
1224
1368
  /**
1225
1369
  * Generate consistent data-testid attributes.
1226
1370
  *