@blotch/angular-lynx-testing-library 22.2.1 → 22.2.3

package/README.md

@@ -5,27 +5,44 @@ Testing utilities for [AngularLynx](https://github.com/Blotch-Smart-Frames/Angul
 ## Installation
 
 ```sh
-npm install --save-dev @blotch/angular-lynx-testing-library \
-  @lynx-js/testing-environment \
-  @testing-library/dom \
-  @testing-library/jest-dom \
-  vitest jsdom
+ng generate @blotch/angular-lynx:add-testing
 ```
 
+It installs this package (and Vitest and jsdom, if the project doesn't have them; `ng new` adds both) and makes sure `ng test` runs through AngularLynx's unit-test builder. To install it by hand: `npm install --save-dev @blotch/angular-lynx-testing-library`.
+
 ## Setup
 
-Add a `vitest.config.ts` to your project:
+None. Tests run with `ng test`, whose builder (`@blotch/angular-lynx-build:unit-test`, which `ng add` sets up) loads this package's setup before the tests whenever the project has it. There is no Vitest config or setup file to write.
+
+The setup:
+
+- Enables Angular JIT compilation (`@angular/compiler`), for components compiled at runtime
+- Installs `LynxTestingEnv` on the jsdom window
+- Switches to the Lynx main thread (where PAPI functions live)
+- Polyfills PAPI functions the testing environment doesn't implement (`__GetParent`, `__QuerySelector`, etc.)
+- Makes `lynx.reportError` return for a warning, as Lynx does, instead of throwing it, so an `@boundary` shows its fallback with the default error handler
+- Installs `@testing-library/jest-dom` matchers
+
+`ng test` compiles the tests ahead of time, like the app, and checks templates strictly, as the Angular Language Service does: a component that uses Lynx elements imports `LYNX_ELEMENTS` from `@blotch/angular-lynx`. The examples below do.
+
+### Without Angular CLI
+
+Under plain Vitest, load the setup yourself and define the compile-time flags the AngularLynx runtime reads (the rsbuild plugin defines them in the app, and `ng test` sets them too):
 
 ```ts
 // vitest.config.ts
 import { defineConfig } from 'vitest/config';
-import path from 'node:path';
 
 export default defineConfig({
   define: {
     __DEV__: JSON.stringify(true),
     __MAIN_THREAD__: JSON.stringify(true),
+    __WEB__: JSON.stringify(false),
+    __PROFILE__: JSON.stringify(false),
+    __ENABLE_SSR__: JSON.stringify(false),
   },
+  // Angular's JIT compiler reads the metadata of legacy decorators.
+  oxc: { decorator: { legacy: true } },
   test: {
     environment: 'jsdom',
     globals: true,
@@ -34,14 +51,6 @@ export default defineConfig({
 });
 ```
 
-The setup file:
-
-- Enables Angular JIT compilation (`@angular/compiler`)
-- Installs `LynxTestingEnv` on the jsdom window
-- Switches to the Lynx main thread (where PAPI functions live)
-- Polyfills PAPI functions the testing environment doesn't implement (`__GetParent`, `__QuerySelector`, etc.)
-- Installs `@testing-library/jest-dom` matchers
-
 ## API
 
 ### `render(component, options?)`
@@ -144,10 +153,12 @@ console.log(Object.keys(eventMap));
 
 ```ts
 import { Component } from '@angular/core';
+import { LYNX_ELEMENTS } from '@blotch/angular-lynx';
 import { render } from '@blotch/angular-lynx-testing-library';
 
 @Component({
   selector: 'greeting',
+  imports: [LYNX_ELEMENTS],
   template: `<text>Hello, {{ name }}!</text>`,
 })
 class GreetingComponent {
@@ -163,13 +174,15 @@ it('renders the greeting', async () => {
 ### Injecting providers
 
 ```ts
-import { InjectionToken, inject } from '@angular/core';
+import { Component, InjectionToken, inject } from '@angular/core';
+import { LYNX_ELEMENTS } from '@blotch/angular-lynx';
 import { render } from '@blotch/angular-lynx-testing-library';
 
 const GREETING = new InjectionToken<string>('GREETING');
 
 @Component({
   selector: 'test-greeting',
+  imports: [LYNX_ELEMENTS],
   template: `<text>{{ greeting() }}</text>`,
 })
 class GreetingComponent {
@@ -189,15 +202,16 @@ it('uses the injected value', async () => {
 Define the signal outside the component so both the component and the test can access it:
 
 ```ts
-import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { Component, signal } from '@angular/core';
+import { LYNX_ELEMENTS } from '@blotch/angular-lynx';
 import { render, waitForUpdate } from '@blotch/angular-lynx-testing-library';
 
 const count = signal(0);
 
 @Component({
   selector: 'test-counter',
+  imports: [LYNX_ELEMENTS],
   template: `<text>{{ count() }}</text>`,
-  changeDetection: ChangeDetectionStrategy.OnPush,
 })
 class CounterComponent {
   count = count;
@@ -219,7 +233,8 @@ it('updates when the signal changes', async () => {
 AngularLynx event bindings use Lynx prefixes: `(bindtap)`, `(catchtap)`, `(bindinput)`, etc.
 
 ```ts
-import { Component, signal, ChangeDetectionStrategy } from '@angular/core';
+import { Component, signal } from '@angular/core';
+import { LYNX_ELEMENTS } from '@blotch/angular-lynx';
 import {
   render,
   fireEvent,
@@ -228,12 +243,12 @@ import {
 
 @Component({
   selector: 'test-button',
+  imports: [LYNX_ELEMENTS],
   template: `
     <view (bindtap)="increment()">
       <text>{{ count() }}</text>
     </view>
   `,
-  changeDetection: ChangeDetectionStrategy.OnPush,
 })
 class ButtonComponent {
   count = signal(0);
@@ -260,10 +275,10 @@ it('shows content conditionally', async () => {
 
   @Component({
     selector: 'test-if',
+    imports: [LYNX_ELEMENTS],
     template: `@if (visible()) {
       <text>Hello</text>
     }`,
-    changeDetection: ChangeDetectionStrategy.OnPush,
   })
   class IfComponent {
     visible = visible;
@@ -286,10 +301,10 @@ it('renders a dynamic list', async () => {
 
   @Component({
     selector: 'test-for',
+    imports: [LYNX_ELEMENTS],
     template: `@for (item of items(); track item) {
       <text>{{ item }}</text>
     }`,
-    changeDetection: ChangeDetectionStrategy.OnPush,
   })
   class ListComponent {
     items = items;
@@ -361,7 +376,7 @@ Template binding → PAPI registration → DOM listener key:
 | Auto-cleanup env var    | `PTL_SKIP_AUTO_CLEANUP` | —                 | `ATL_SKIP_AUTO_CLEANUP` |
 | `renderHook()`          | ✓                       | —                 | —                       |
 | Snapshot serializer     | ✓ (RefProxy)            | —                 | —                       |
-| Vitest plugin           | ✓                       | —                 | —                       |
+| Vitest plugin           | ✓                       | —                 | — (`ng test` sets up)   |
 | Named fireEvent helpers | 30+                     | 16                | 16                      |
 | Thread-aware fireEvent  | ✓                       | ✓                 | — (single thread)       |
 | Async state helper      | `waitSchedule()`        | `waitForUpdate()` | `waitForUpdate()`       |

package/dist/render.d.ts

@@ -48,10 +48,11 @@ export type RenderResult<Q extends Queries = typeof domQueries> = {
      *   - `componentRef.injector.get(Token)` — retrieve a service provided to the app.
      *   - `componentRef.instance.someSignal.set(v)` — drive writable signal state directly.
      *
-     * Note: `componentRef.setInput()` requires the full AOT pipeline to register
-     * signal inputs (input()) or @Input() decorators in component metadata. In the
-     * Vitest JIT environment this metadata is not available, so the recommended
-     * pattern is to expose writable signals on the component instance instead.
+     * Note: `componentRef.setInput()` needs the input metadata that ahead-of-time
+     * compilation registers for signal inputs (input()) and @Input() decorators.
+     * `ng test` compiles tests that way, so it works there. Under plain Vitest,
+     * which compiles components just in time, that metadata isn't available;
+     * expose writable signals on the component instance instead.
      */
     componentRef: ComponentRef<unknown>;
 } & BoundFunctions<typeof domQueries> & BoundFunctions<Q>;

package/dist/render.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,QAAQ,EAEb,KAAK,IAAI,EACV,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,OAAO,EACZ,OAAO,IAAI,UAAU,EAEtB,MAAM,sBAAsB,CAAC;AAG9B,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,UAAU,IAAI;IACjE,SAAS,CAAC,EAAE,CAAC,QAAQ,GAAG,oBAAoB,CAAC,EAAE,CAAC;IAChD;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,UAAU,IAAI;IAChE;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB;;;OAGG;IACH,QAAQ,EAAE,CAAC,CAAC,SAAS,OAAO,GAAG,CAAC,EAC9B,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,EACxB,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,KACvB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9B;;OAEG;IACH,UAAU,EAAE,MAAM,gBAAgB,CAAC;IACnC;;;;;;;;;;;OAWG;IACH,YAAY,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;CACrC,GAAG,cAAc,CAAC,OAAO,UAAU,CAAC,GACnC,cAAc,CAAC,CAAC,CAAC,CAAC;AAIpB,eAAO,MAAM,OAAO,QAAO,IAM1B,CAAC;AAEF,eAAO,MAAM,MAAM,GAAU,CAAC,SAAS,OAAO,GAAG,OAAO,UAAU,EAChE,eAAe,IAAI,CAAC,OAAO,CAAC,EAC5B,UAAS,aAAa,CAAC,CAAC,CAA0B,KACjD,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAkDzB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,QAAa,OAAO,CAAC,IAAI,CAKlD,CAAC"}
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,oBAAoB,EACzB,KAAK,QAAQ,EAEb,KAAK,IAAI,EACV,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,OAAO,EACZ,OAAO,IAAI,UAAU,EAEtB,MAAM,sBAAsB,CAAC;AAG9B,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,UAAU,IAAI;IACjE,SAAS,CAAC,EAAE,CAAC,QAAQ,GAAG,oBAAoB,CAAC,EAAE,CAAC;IAChD;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,CAAC;CACb,CAAC;AAEF,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,OAAO,GAAG,OAAO,UAAU,IAAI;IAChE;;OAEG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;OAEG;IACH,OAAO,EAAE,MAAM,IAAI,CAAC;IACpB;;;OAGG;IACH,QAAQ,EAAE,CAAC,CAAC,SAAS,OAAO,GAAG,CAAC,EAC9B,SAAS,EAAE,IAAI,CAAC,OAAO,CAAC,EACxB,OAAO,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,KACvB,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9B;;OAEG;IACH,UAAU,EAAE,MAAM,gBAAgB,CAAC;IACnC;;;;;;;;;;;;OAYG;IACH,YAAY,EAAE,YAAY,CAAC,OAAO,CAAC,CAAC;CACrC,GAAG,cAAc,CAAC,OAAO,UAAU,CAAC,GACnC,cAAc,CAAC,CAAC,CAAC,CAAC;AAIpB,eAAO,MAAM,OAAO,QAAO,IAM1B,CAAC;AAEF,eAAO,MAAM,MAAM,GAAU,CAAC,SAAS,OAAO,GAAG,OAAO,UAAU,EAChE,eAAe,IAAI,CAAC,OAAO,CAAC,EAC5B,UAAS,aAAa,CAAC,CAAC,CAA0B,KACjD,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAkDzB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,QAAa,OAAO,CAAC,IAAI,CAKlD,CAAC"}

package/dist/setup.js

@@ -40,8 +40,79 @@ globalThis.fetch = (url, ...args) => {
 if (typeof Element.prototype.animate !== 'function') {
     Element.prototype.animate = () => ({ cancel: () => { }, finished: Promise.resolve() });
 }
+// ─── lynx.reportError warnings ───────────────────────────────────────────────
+/**
+ * Makes `lynx.reportError` return for a warning, as Lynx does, instead of
+ * throwing it.
+ *
+ * The testing environment's `lynx.reportError` throws whatever it's given, so
+ * a reported error fails the test the way it would stop the app on a device.
+ * On a device, though, a `warning`-level report doesn't interrupt anything,
+ * and that's the level `LynxErrorHandler.onViewError()` reports an error that
+ * an `@boundary` caught at. Angular calls onViewError() before it swaps in the
+ * `@error` block, so the throw stopped the swap, and a test using the default
+ * error handler saw neither the content nor its fallback. Other reports still
+ * throw.
+ *
+ * The environment gives each thread a new `lynx` whenever it injects its
+ * globals: once when it's created, and again on every reset(), which runs
+ * after each test (see index.ts). So this runs from its inject hooks, which
+ * must be set before the environment is created below.
+ */
+const returnOnWarnings = (threadGlobals) => {
+    const { lynx } = threadGlobals;
+    const reportError = lynx.reportError;
+    lynx.reportError = (error, options) => {
+        if (options?.level === 'warning')
+            return;
+        reportError(error, options);
+    };
+};
+globalThis.onInjectMainThreadGlobals = returnOnWarnings;
+globalThis.onInjectBackgroundThreadGlobals = returnOnWarnings;
 // ─── Install LynxTestingEnv ──────────────────────────────────────────────────
-const lynxTestingEnv = new LynxTestingEnv({ window: globalThis.window });
+/**
+ * Turns the globals the testing environment is about to write into plain data
+ * properties, so the writes stay on the global object.
+ *
+ * Vitest's jsdom environment defines each jsdom window property on the global
+ * as an accessor. Since Vitest 5 its setter also writes the value through to
+ * the jsdom window. A thread switch copies every thread global onto the
+ * global, and two of those writes break the window: jsdom 30's
+ * `window.document` has no setter, so assigning it threw "Cannot set property
+ * document of [object Window] which has only a getter", and `_globalProxy` is
+ * the object jsdom returns as `dom.window`, so overwriting it made Vitest's
+ * teardown fail with "dom.window.close is not a function". The thread
+ * globals' values are the window's own (`document`, `Event`) or replace them
+ * only for the test (`requestAnimationFrame`), so keeping them on the global
+ * matches what Vitest 4 did.
+ */
+const keepWritesOffWindow = (keys) => {
+    for (const key of keys) {
+        const descriptor = Object.getOwnPropertyDescriptor(globalThis, key);
+        if (!descriptor?.set)
+            continue;
+        Object.defineProperty(globalThis, key, {
+            value: globalThis[key],
+            writable: true,
+            configurable: true,
+            enumerable: descriptor.enumerable,
+        });
+    }
+};
+class AngularLynxTestingEnv extends LynxTestingEnv {
+    switchToMainThread() {
+        keepWritesOffWindow(Object.getOwnPropertyNames(this.mainThread.globalThis));
+        super.switchToMainThread();
+    }
+    switchToBackgroundThread() {
+        keepWritesOffWindow(Object.getOwnPropertyNames(this.backgroundThread.globalThis));
+        super.switchToBackgroundThread();
+    }
+}
+const lynxTestingEnv = new AngularLynxTestingEnv({
+    window: globalThis.window,
+});
 globalThis.lynxTestingEnv = lynxTestingEnv;
 // Expose Node so @testing-library/dom detects element types correctly.
 globalThis.Node = globalThis.window.Node;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blotch/angular-lynx-testing-library",
-  "version": "22.2.1",
+  "version": "22.2.3",
   "description": "Testing utilities for AngularLynx apps",
   "homepage": "https://github.com/Blotch-Smart-Frames/AngularLynx#readme",
   "bugs": {
@@ -43,14 +43,14 @@
   },
   "dependencies": {
     "@lynx-js/testing-environment": "^0.3.4",
-    "@testing-library/dom": "^10.4.1"
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1"
   },
   "devDependencies": {
     "@angular/compiler": "^22.2.1",
     "@angular/core": "^22.2.1",
     "@angular/platform-browser": "^22.2.1",
     "@blotch/angular-lynx": "*",
-    "@testing-library/jest-dom": "^6.9.1",
     "@types/node": "^22.0.0",
     "jsdom": "^25.0.0",
     "typescript": "~6.0.0"
@@ -60,5 +60,14 @@
     "@angular/core": "^22.2.0",
     "@angular/platform-browser": "^22.2.0",
     "@blotch/angular-lynx": "^22.2.0"
+  },
+  "ng-update": {
+    "packageGroup": [
+      "@blotch/angular-lynx",
+      "@blotch/angular-lynx-build",
+      "@blotch/angular-lynx-testing-library",
+      "@blotch/rsbuild-plugin-angular-lynx",
+      "@blotch/angular-lynx-native"
+    ]
   }
 }