@sharadox/test-web-library 0.1.0 → 0.2.0

package/README.md

@@ -9,6 +9,8 @@
 - **`describeStyleMemory`:** a style group starts on its default and remembers the visitor's choice.
 - **`describeConsent`:** Deny lasts for the visit, manual choices are kept, and the preferences link reopens the panel.
 
+For Vitest component tests, `installBrowserEnvironment()` adds what happy-dom lacks: intersection and resize observers, media queries, `scrollTo`, and Motion animations that finish at once. `reportIntersection()` marks watched elements as visible.
+
 ## Install
 
 ```sh

package/distribution/browser-environment/index.d.ts

@@ -0,0 +1,22 @@
+import type { BrowserEnvironmentOptions, ObserverRecord } from "@sharadox/test-web-library/browser-environment/type";
+/** Every IntersectionObserver created since `installBrowserEnvironment`, so tests can report elements as visible. */
+export declare const observers: ObserverRecord[];
+/**
+ * Gives a Vitest happy-dom environment the browser features components use and the DOM lacks: intersection and
+ * resize observers, media queries (reduced motion, fine pointer, colour scheme), `scrollTo`, and Motion animations
+ * that finish at once (so unmounting never cancels one mid-way). Call it in `beforeEach`, and restore with
+ * `vi.restoreAllMocks()` and `vi.unstubAllGlobals()`.
+ *
+ * @example
+ * beforeEach(() => installBrowserEnvironment({ reducedMotion: true }));
+ */
+export declare function installBrowserEnvironment({ reducedMotion, finePointer, dark, }?: BrowserEnvironmentOptions): void;
+/**
+ * Reports elements as visible (or not) to every observer created so far: all watched elements by default, or only
+ * those matching `filter`.
+ *
+ * @example
+ * act(() => reportIntersection());
+ */
+export declare function reportIntersection(isIntersecting?: boolean, filter?: (element: Element) => boolean): void;
+//# sourceMappingURL=index.d.ts.map

package/distribution/browser-environment/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/browser-environment/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,yBAAyB,EAAE,cAAc,EAAE,MAAM,qDAAqD,CAAC;AAErH,qHAAqH;AACrH,eAAO,MAAM,SAAS,EAAE,cAAc,EAAO,CAAC;AAE9C;;;;;;;;GAQG;AACH,wBAAgB,yBAAyB,CAAC,EACxC,aAAqB,EACrB,WAAkB,EAClB,IAAW,GACZ,GAAE,yBAA8B,GAAG,IAAI,CA8CvC;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,cAAc,UAAO,EAAE,MAAM,GAAE,CAAC,OAAO,EAAE,OAAO,KAAK,OAAoB,GAAG,IAAI,CAYlH"}

package/distribution/browser-environment/index.js

@@ -0,0 +1,68 @@
+import { MotionGlobalConfig } from "motion";
+import { vi } from "vitest";
+/** Every IntersectionObserver created since `installBrowserEnvironment`, so tests can report elements as visible. */
+export const observers = [];
+/**
+ * Gives a Vitest happy-dom environment the browser features components use and the DOM lacks: intersection and
+ * resize observers, media queries (reduced motion, fine pointer, colour scheme), `scrollTo`, and Motion animations
+ * that finish at once (so unmounting never cancels one mid-way). Call it in `beforeEach`, and restore with
+ * `vi.restoreAllMocks()` and `vi.unstubAllGlobals()`.
+ *
+ * @example
+ * beforeEach(() => installBrowserEnvironment({ reducedMotion: true }));
+ */
+export function installBrowserEnvironment({ reducedMotion = false, finePointer = true, dark = true, } = {}) {
+    MotionGlobalConfig.skipAnimations = true;
+    observers.length = 0;
+    vi.stubGlobal("IntersectionObserver", class {
+        record;
+        constructor(callback, options) {
+            this.record = { callback, options, elements: [] };
+            observers.push(this.record);
+        }
+        observe(element) {
+            this.record.elements.push(element);
+        }
+        unobserve() { }
+        disconnect() { }
+        takeRecords() {
+            return [];
+        }
+    });
+    vi.stubGlobal("ResizeObserver", class {
+        observe() { }
+        unobserve() { }
+        disconnect() { }
+    });
+    const matches = (query) => (query.includes("reduce") && reducedMotion) ||
+        (query.includes("pointer: fine") && finePointer) ||
+        (query.includes("dark") && dark) ||
+        (query.includes("light") && !dark);
+    vi.spyOn(window, "matchMedia").mockImplementation((query) => ({
+        matches: matches(query),
+        media: query,
+        addEventListener: () => { },
+        removeEventListener: () => { },
+        addListener: () => { },
+        removeListener: () => { },
+    }));
+    vi.stubGlobal("scrollTo", vi.fn());
+}
+/**
+ * Reports elements as visible (or not) to every observer created so far: all watched elements by default, or only
+ * those matching `filter`.
+ *
+ * @example
+ * act(() => reportIntersection());
+ */
+export function reportIntersection(isIntersecting = true, filter = () => true) {
+    for (const observer of observers) {
+        const entries = observer.elements.filter(filter).map((target) => ({
+            isIntersecting,
+            target,
+            intersectionRatio: isIntersecting ? 1 : 0,
+        }));
+        observer.callback(entries, {});
+    }
+}
+//# sourceMappingURL=index.js.map

package/distribution/browser-environment/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../source/browser-environment/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,QAAQ,CAAC;AAC5C,OAAO,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAC;AAG5B,qHAAqH;AACrH,MAAM,CAAC,MAAM,SAAS,GAAqB,EAAE,CAAC;AAE9C;;;;;;;;GAQG;AACH,MAAM,UAAU,yBAAyB,CAAC,EACxC,aAAa,GAAG,KAAK,EACrB,WAAW,GAAG,IAAI,EAClB,IAAI,GAAG,IAAI,MACkB,EAAE;IAC/B,kBAAkB,CAAC,cAAc,GAAG,IAAI,CAAC;IACzC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;IACrB,EAAE,CAAC,UAAU,CACX,sBAAsB,EACtB;QACE,MAAM,CAAiB;QACvB,YAAY,QAAsC,EAAE,OAAkC;YACpF,IAAI,CAAC,MAAM,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;YAClD,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC9B,CAAC;QACD,OAAO,CAAC,OAAgB;YACtB,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACrC,CAAC;QACD,SAAS,KAAI,CAAC;QACd,UAAU,KAAI,CAAC;QACf,WAAW;YACT,OAAO,EAAE,CAAC;QACZ,CAAC;KACF,CACF,CAAC;IACF,EAAE,CAAC,UAAU,CACX,gBAAgB,EAChB;QACE,OAAO,KAAI,CAAC;QACZ,SAAS,KAAI,CAAC;QACd,UAAU,KAAI,CAAC;KAChB,CACF,CAAC;IACF,MAAM,OAAO,GAAG,CAAC,KAAa,EAAE,EAAE,CAChC,CAAC,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,aAAa,CAAC;QAC3C,CAAC,KAAK,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,WAAW,CAAC;QAChD,CAAC,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC;QAChC,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrC,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC,kBAAkB,CAC/C,CAAC,KAAa,EAAE,EAAE,CAChB,CAAC;QACC,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC;QACvB,KAAK,EAAE,KAAK;QACZ,gBAAgB,EAAE,GAAG,EAAE,GAAE,CAAC;QAC1B,mBAAmB,EAAE,GAAG,EAAE,GAAE,CAAC;QAC7B,WAAW,EAAE,GAAG,EAAE,GAAE,CAAC;QACrB,cAAc,EAAE,GAAG,EAAE,GAAE,CAAC;KACzB,CAA8B,CAClC,CAAC;IACF,EAAE,CAAC,UAAU,CAAC,UAAU,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,cAAc,GAAG,IAAI,EAAE,SAAwC,GAAG,EAAE,CAAC,IAAI;IAC1G,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAClD,CAAC,MAAM,EAAE,EAAE,CACT,CAAC;YACC,cAAc;YACd,MAAM;YACN,iBAAiB,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SAC1C,CAAyC,CAC7C,CAAC;QACF,QAAQ,CAAC,QAAQ,CAAC,OAAO,EAAE,EAA0B,CAAC,CAAC;IACzD,CAAC;AACH,CAAC"}

package/distribution/browser-environment/type.d.ts

@@ -0,0 +1,15 @@
+export interface BrowserEnvironmentOptions {
+    /** Whether `prefers-reduced-motion: reduce` matches; false by default. */
+    reducedMotion?: boolean;
+    /** Whether `pointer: fine` matches (mouse or trackpad); true by default. */
+    finePointer?: boolean;
+    /** Whether `prefers-color-scheme: dark` matches; true by default (light matches otherwise). */
+    dark?: boolean;
+}
+/** An IntersectionObserver created during a test, with the elements it watches. */
+export interface ObserverRecord {
+    callback: IntersectionObserverCallback;
+    options?: IntersectionObserverInit;
+    elements: Element[];
+}
+//# sourceMappingURL=type.d.ts.map

package/distribution/browser-environment/type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.d.ts","sourceRoot":"","sources":["../../source/browser-environment/type.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,yBAAyB;IACxC,0EAA0E;IAC1E,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,+FAA+F;IAC/F,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,4BAA4B,CAAC;IACvC,OAAO,CAAC,EAAE,wBAAwB,CAAC;IACnC,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB"}

package/distribution/browser-environment/type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=type.js.map

package/distribution/browser-environment/type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"type.js","sourceRoot":"","sources":["../../source/browser-environment/type.ts"],"names":[],"mappings":""}

package/llms.txt

@@ -7,3 +7,4 @@
 - /installability-suite describeInstallability(path) (Chromium CDP Page.getInstallabilityErrors)
 - /preference-suite describeLocaleMemory({ browserLocale, automaticPath, switchName, pick: { link, path } }), describeStyleMemory({ path, attribute, switchName, colorScheme, initial, pick: { radio, style } }), describeConsent({ path, dialogName, deny, customize, save, preferences, category, storageKey, expectedGranted })
 - Peer: @playwright/test. Licence: Sharadox Open Source Licence 0.1.0
+- /browser-environment installBrowserEnvironment({ reducedMotion=false, finePointer=true, dark=true }) (Vitest happy-dom: IntersectionObserver/ResizeObserver stubs, matchMedia, scrollTo, Motion skipAnimations); reportIntersection(isIntersecting=true, filter?); observers

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sharadox/test-web-library",
-  "version": "0.1.0",
-  "description": "Playwright helpers for websites: deterministic visual snapshots and shared end-to-end suites for search engines, installability, remembered language and style, and cookie consent.",
+  "version": "0.2.0",
+  "description": "Test helpers for websites: Playwright visual snapshots and shared end-to-end suites (search engines, installability, remembered language and style, cookie consent), and a browser environment for Vitest component tests.",
   "private": false,
   "license": "SEE LICENSE IN LICENCA.md",
   "author": "Sharadox <contact@sharadox.com>",
@@ -56,8 +56,10 @@
     "@types/node": "^24.19.2",
     "@vitest/coverage-v8": "^5.1.0",
     "eslint": "9.39.5",
+    "happy-dom": "^21.0.4",
     "husky": "^9.1.7",
     "lint-staged": "^17.6.0",
+    "motion": "^12.43.0",
     "prettier": "^3.10.0",
     "turbo": "^2.11.10",
     "typedoc": "^0.28.20",
@@ -68,7 +70,20 @@
     "@sharadox/web-library": "^0.5.0"
   },
   "peerDependencies": {
-    "@playwright/test": ">=1.50"
+    "@playwright/test": ">=1.50",
+    "vitest": ">=5",
+    "motion": ">=12"
+  },
+  "peerDependenciesMeta": {
+    "@playwright/test": {
+      "optional": true
+    },
+    "vitest": {
+      "optional": true
+    },
+    "motion": {
+      "optional": true
+    }
   },
   "scripts": {
     "build": "rm -rf distribution && tsc -p tsconfig.build.json",