@octanejs/testing-library 0.1.49 → 0.1.51

package/README.md

@@ -10,13 +10,17 @@ npm install @octanejs/testing-library
 pnpm add @octanejs/testing-library
 ```
 
+This package peers on **Octane `^0.2.5`**. Published 0.2.4 and earlier do not export
+`isInActScope`, which both public entries import.
+
 The split mirrors RTL's own architecture (and
 `docs/react-library-compat-plan.md` §2): **`@testing-library/dom` is
 framework-agnostic and reused verbatim** — every query, `screen`, `within`,
-`waitFor`/`waitForElementToBeRemoved`, `findBy*`, `fireEvent`, `prettyDOM`,
+`waitFor`/`waitForElementToBeRemoved`, `findBy*`, `prettyDOM`,
 `configure` — while only react-testing-library's thin React layer is ported to
 octane: `render`, `cleanup`, `renderHook`, the `act` re-export, and the
-dom-testing-library config wiring (`eventWrapper`/`asyncWrapper`) that makes
+focus/blur event helpers and dom-testing-library config wiring
+(`eventWrapper`/`asyncWrapper`) that makes
 every dispatch/wait commit octane's scheduled work before your assertions run.
 
 ```ts
@@ -40,7 +44,13 @@ test('increments', () => {
   `RTL_SKIP_AUTO_CLEANUP=true` or import `@octanejs/testing-library/pure`)
 - `renderHook(callback, { initialProps, wrapper, ... }?)` → `{ result, rerender, unmount }`
 - `act` — octane's `act`, re-exported (always async; always `await` it)
-- `fireEvent`, `screen`, `waitFor`, `within`, … — dom-testing-library, re-exported
+- `screen`, `waitFor`, `within`, … — dom-testing-library, re-exported
+- `fireEvent` — DOM event helpers, with focus/blur pairs for delegated handlers
+
+Multiple `rerender` calls inside one `act` callback commit together when that
+callback finishes. Await `act` before asserting results that depend on promises
+or effects. Promise work settles even when timeout clocks are frozen; advance
+fake timers explicitly when the behavior itself depends on a timer.
 
 ## Octane-specific surface
 
@@ -60,8 +70,8 @@ remounts — exactly RTL's rerender semantics.
 ## Differences from react-testing-library
 
 Octane dispatches **native, delegated DOM events — there is no synthetic event
-layer** — so `fireEvent` is dom-testing-library's, deliberately *without* RTL's
-React-specific remappings:
+layer**. `fireEvent` uses DOM Testing Library with focus/blur pairs for
+delegation. Other helpers keep native semantics:
 
 - **`fireEvent.change` fires a native `change`; `fireEvent.input` a native
   `input`.** In React, `onChange` handlers actually run off native `input`
@@ -85,18 +95,21 @@ React-specific remappings:
   sequence and automatic checked-state transition. `fireEvent.change(checkbox)`
   is only an explicit change dispatch; it does not model the click, activation,
   cancellation/rollback, or full event ordering.
-- **No enter/leave/focus double-dispatch.** RTL's `fireEvent.mouseEnter` also
-  fires `mouseover` (and `focus` fires `focusin`, `select` fires `keyup`, …)
-  purely to feed React's plugin system, which listens to different native
-  events than the handler names suggest. Octane's `onMouseEnter` receives the
-  real `mouseenter` (non-bubbling events are capture-delegated), so
-  `fireEvent.mouseEnter` alone triggers it — no compensation needed or wanted.
-- **Commit timing is wired, not synthesized.** Octane already commits discrete
-  events (`click`, `input`, `keydown`, …) synchronously; this package
-  additionally wraps *every* `fireEvent` dispatch in `flushSync` + an effect
-  drain via dom-testing-library's `eventWrapper`, so non-discrete/programmatic
-  events also commit — with their `useEffect` cascades — before `fireEvent`
-  returns (the equivalent of RTL's `act()` around each dispatch).
+- **Focus helpers emit both native focus events.** `fireEvent.focus` dispatches
+  `focus` then `focusin`; `fireEvent.blur` dispatches `blur` then `focusout`,
+  matching browser order.
+  Octane's delegated `onFocus`/`onBlur` handlers receive `focusin`/`focusout`.
+  Both events preserve the supplied options, including `relatedTarget`, except
+  that the paired `focusin`/`focusout` always bubbles. The return value is false
+  when the native `focus`/`blur` event was canceled.
+  Use `user.tab()` or native `focus()`/`blur()` to move actual focus.
+- **No enter/leave remapping.** `fireEvent.mouseEnter` dispatches a real
+  `mouseenter`, which Octane's capture delegation delivers directly. It does
+  not also dispatch `mouseover` to drive React's synthetic event plugins.
+- **Every dispatch commits before returning.** The DOM library's
+  `eventWrapper` runs every `fireEvent` dispatch in `flushSync` and then drains
+  effects, so the event's state updates and `useEffect` cascades are visible
+  before the helper returns.
 - **Host elements at the root are `container.firstChild`, like RTL.**
   `render(createElement('div', …))` goes through octane's value-position
   renderer, which mounts a lone host element anchorless (the element
@@ -150,3 +163,10 @@ text commit on `tab()`, checkbox click ordering, `keyboard()`).
 Current scope, known divergences, and verification status are tracked in the
 generated [bindings status table](../../docs/bindings-status.md), sourced from
 this package's [`status.json`](./status.json).
+
+## Runtime requirement
+
+This release requires Octane 0.2.5 or later in the 0.2 line. Upgrade Octane together
+with testing-library so the `isInActScope` API used for nested `act` batching is
+available. The packed-consumer checks exercise that API and rendering inside
+an outer `act` scope.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/testing-library",
-  "version": "0.1.49",
+  "version": "0.1.51",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -41,14 +41,16 @@
     "@testing-library/dom": "^10.4.1"
   },
   "peerDependencies": {
-    "octane": "^0.1.51 || ^0.2.0"
+    "octane": "^0.2.5"
   },
   "devDependencies": {
     "@testing-library/user-event": "^14.6.1",
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7",
+    "esbuild": "^0.28.1",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "semver": "7.8.5",
     "vitest": "^4.1.10",
-    "octane": "0.2.0"
+    "octane": "0.2.5"
   },
   "scripts": {
     "test": "vitest run"

package/src/dom-query-helpers.ts

@@ -0,0 +1,45 @@
+import * as dom from '@testing-library/dom';
+import type { GetErrorFunction, QueryMethod, Variant, waitForOptions } from '@testing-library/dom';
+
+// DOM Testing Library 10.4.1 exports these values but omits their declarations.
+// Preserve the original functions and describe their pinned query contracts.
+interface RuntimeQueryHelpers {
+	getMultipleElementsFoundError(message: string, container: Element): Error;
+	makeSingleQuery<Args extends unknown[], ElementType extends HTMLElement>(
+		query: QueryMethod<Args, ElementType[]>,
+		getMultipleError: GetErrorFunction<Args>,
+	): QueryMethod<Args, ElementType | null>;
+	makeGetAllQuery<Args extends unknown[], ElementType extends HTMLElement>(
+		query: QueryMethod<Args, ElementType[]>,
+		getMissingError: GetErrorFunction<Args>,
+	): QueryMethod<Args, ElementType[]>;
+	makeFindQuery<Text, Options, Result>(
+		query: (container: HTMLElement, text: Text, options?: Options) => Result,
+	): (
+		container: HTMLElement,
+		text: Text,
+		options?: Options,
+		waitOptions?: waitForOptions,
+	) => Promise<Awaited<Result>>;
+	wrapSingleQueryWithSuggestion<Args extends unknown[], Result extends HTMLElement | null>(
+		query: QueryMethod<Args, Result>,
+		queryName: string,
+		variant: Variant,
+	): QueryMethod<Args, Result>;
+	wrapAllByQueryWithSuggestion<Args extends unknown[], ElementType extends HTMLElement>(
+		query: QueryMethod<Args, ElementType[]>,
+		queryName: string,
+		variant: Variant,
+	): QueryMethod<Args, ElementType[]>;
+}
+
+export const {
+	getMultipleElementsFoundError,
+	makeSingleQuery,
+	makeGetAllQuery,
+	makeFindQuery,
+	wrapSingleQueryWithSuggestion,
+	wrapAllByQueryWithSuggestion,
+} = dom as typeof dom & RuntimeQueryHelpers;
+
+export const queryHelpers = dom.queryHelpers as typeof dom.queryHelpers & RuntimeQueryHelpers;

package/src/fire-event.ts

@@ -1,22 +1,26 @@
-// `fireEvent` — dom-testing-library's, re-exported UNWRAPPED.
-//
-// react-testing-library layers remappings on top of dom-testing-library's
-// fireEvent because React's synthetic event system listens to DIFFERENT native
-// events than the handler names suggest (mouseEnter handlers run off native
-// mouseover, focus/blur off focusin/focusout, `select` is synthesized from key
-// events, `onChange` fires on native input, …), so RTL double-dispatches to
-// feed React's plugins.
-//
-// Octane has NO synthetic event layer — `onX` handlers receive the native `x`
-// event, delegated. `fireEvent.mouseEnter` therefore dispatches a real
-// `mouseenter` and octane's capture-phase delegation of non-bubbling events
-// delivers it; `fireEvent.change` fires a native `change` (NOT React's
-// input-as-change); no remapping is wanted. The commit wiring (flushSync +
-// effect drain around every dispatch) rides on dom-testing-library's
-// `eventWrapper` config hook — see pure.ts.
-//
-// In particular, `fireEvent.change(textbox)` means “dispatch an explicit native
-// commit event”; it does not simulate typing or blur. Likewise, change on a
-// checkbox does not reproduce click activation/toggling or click → input →
-// change ordering. Use user-event's type/tab/click flows for those sequences.
-export { fireEvent } from '@testing-library/dom';
+import { fireEvent as domFireEvent } from '@testing-library/dom';
+
+// Keep the DOM helpers independent: callers importing @testing-library/dom
+// directly still get one native event per helper. Octane's onFocus/onBlur
+// delegation listens to focusin/focusout, so those two convenience helpers
+// emit native focus/blur followed by the corresponding bubbling event.
+export const fireEvent: typeof domFireEvent = Object.assign(
+	(...args: Parameters<typeof domFireEvent>) => domFireEvent(...args),
+	domFireEvent,
+);
+
+fireEvent.focus = (element, options) => {
+	const result = domFireEvent.focus(element, options);
+	domFireEvent.focusIn(element, { ...options, bubbles: true });
+	return result;
+};
+fireEvent.blur = (element, options) => {
+	const result = domFireEvent.blur(element, options);
+	domFireEvent.focusOut(element, { ...options, bubbles: true });
+	return result;
+};
+
+// Other helpers retain DOM semantics: change dispatches an explicit native
+// commit event; mouseEnter does not also dispatch mouseover. Use user-event
+// for complete typing, click activation, and focus movement sequences.
+// Commit/effect flushing uses the DOM library's eventWrapper (see pure.ts).

package/src/pure.ts

@@ -3,7 +3,7 @@
  *
  * Strategy (docs/react-library-compat-plan.md §2): `@testing-library/dom` is
  * framework-agnostic, so it is depended on VERBATIM and re-exported wholesale
- * (queries, `screen`, `within`, `waitFor`, `fireEvent`, `prettyDOM`, …). Only
+ * (queries, `screen`, `within`, `waitFor`, `prettyDOM`, …). Only
  * react-testing-library's thin React layer is ported here, onto octane:
  *
  *  - `render` / `cleanup` / `renderHook` mount through octane's `createRoot`
@@ -22,6 +22,7 @@
  */
 import {
 	act,
+	isInActScope,
 	createElement,
 	createRoot,
 	drainPassiveEffects,
@@ -33,6 +34,7 @@ import {
 	withSlot,
 	type ComponentBody,
 	type ElementDescriptor,
+	type OctaneNode,
 	type Root,
 } from 'octane';
 import {
@@ -43,6 +45,7 @@ import {
 } from '@testing-library/dom';
 import type { BoundFunctions, Queries } from '@testing-library/dom';
 import { getIsOctaneActEnvironment, setOctaneActEnvironment } from './act-environment';
+import { fireEvent as octaneFireEvent } from './fire-event';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // dom-testing-library config wiring (RTL pure.js does the same three hooks).
@@ -87,13 +90,8 @@ configureDTL({
 			setOctaneActEnvironment(previousActEnvironment);
 		}
 	},
-	// Every `fireEvent` dispatch runs through here. Octane's DISCRETE delegated
-	// events (click/input/keydown/…) already commit synchronously on their own
-	// (maybeFlushDiscrete → flushSync), but fireEvent also dispatches event types
-	// with no discrete path — non-delegated or programmatic events whose updates
-	// would otherwise sit queued until the next microtask, i.e. after the test's
-	// assertion. flushSync commits those too, and the passive drain mirrors RTL's
-	// act(): effects scheduled by the event have run before fireEvent returns.
+	// Every fireEvent dispatch commits its updates and drains passive effects
+	// before returning, including programmatic and non-discrete events.
 	eventWrapper: (cb) => {
 		let result: unknown;
 		flushSync(() => {
@@ -112,6 +110,7 @@ configureDTL({
 interface RootEntry {
 	container: Element;
 	root: Root;
+	valueRoot: boolean;
 }
 const mountedContainers = new Set<Element>();
 const mountedRootEntries: RootEntry[] = [];
@@ -120,13 +119,11 @@ const mountedRootEntries: RootEntry[] = [];
 // UI normalization — octane's two authoring forms into one mountable element.
 // ─────────────────────────────────────────────────────────────────────────────
 
-/** What `render`/`rerender` accept: a component body, or a `createElement` result. */
-export type OctaneUI<P = any> = ComponentBody<P> | ElementDescriptor<P>;
+/** A component body with optional props, or any Octane renderable. */
+export type OctaneUI<P = any> = ComponentBody<P> | OctaneNode;
 
-// A root can only mount a COMPONENT. `render(createElement('div', …))` (RTL's
-// `render(<div/>)`) produces a HOST descriptor, so it is returned from a pass-
-// through component and rendered by the runtime's value-position renderer.
-function ValueRoot(props: { children: unknown }): unknown {
+// Arrays and host values share a stable value-rendering owner across rerenders.
+function ValueRoot(props: { children: OctaneNode }): OctaneNode {
 	return props.children;
 }
 
@@ -141,12 +138,12 @@ function toElement<P>(ui: OctaneUI<P>, props: P | undefined): ElementDescriptor
 		return ui;
 	}
 	if (typeof ui !== 'function') {
-		throw new Error(
-			'render/rerender expects an octane component (a function) or an element ' +
-				`descriptor from createElement(...); received ${typeof ui}.`,
-		);
+		if (props !== undefined) {
+			throw new Error('render/rerender only accepts the props option with a bare component.');
+		}
+		return createElement(ValueRoot, { children: ui });
 	}
-	return createElement(ui, props);
+	return createElement(ui as ComponentBody<P>, props);
 }
 
 function wrapUiIfNeeded(
@@ -156,8 +153,10 @@ function wrapUiIfNeeded(
 	return wrapperComponent ? createElement(wrapperComponent, { children: element }) : element;
 }
 
-function mountable(element: ElementDescriptor): ElementDescriptor {
-	return typeof element.type === 'string'
+function mountable(element: ElementDescriptor, valueRoot: boolean): ElementDescriptor {
+	// Retain one value-rendering owner when rerender moves between an array,
+	// fragment, and single element. Keyed children keep their state across them.
+	return valueRoot && element.type !== ValueRoot
 		? createElement(ValueRoot, { children: element })
 		: element;
 }
@@ -174,14 +173,21 @@ function mountable(element: ElementDescriptor): ElementDescriptor {
 // `waitFor`/`findBy*`/`act` are for, same as RTL.
 function settleSync(): void {
 	for (let i = 0; i < 50 && hasPendingWork(); i++) {
-		drainPassiveEffects();
-		flushSync(() => {});
+		// Passive effects may schedule state updates too. They belong to this
+		// testing-library commit, so keep the drain inside its synchronous scope.
+		flushSync(() => {
+			drainPassiveEffects();
+		});
 	}
 }
 
 // Commit a render synchronously — flushSync for the render itself, then the
 // cascade settle. Equivalent to RTL's `act(() => root.render(ui))` (sync form).
 function commitRender(root: Root, element: ElementDescriptor): void {
+	if (isInActScope()) {
+		root.render(element);
+		return;
+	}
 	flushSync(() => {
 		root.render(element);
 	});
@@ -246,27 +252,32 @@ export function render<P = any>(ui: OctaneUI<P>, options: RenderOptions<P> = {})
 		container = baseElement.appendChild(document.createElement('div'));
 	}
 
-	const element = mountable(wrapUiIfNeeded(toElement(ui, props), WrapperComponent));
+	const normalized = wrapUiIfNeeded(toElement(ui, props), WrapperComponent);
+	const previousEntry = mountedRootEntries.find((entry) => entry.container === container);
+	const valueRoot =
+		previousEntry?.valueRoot ??
+		(typeof normalized.type !== 'function' || normalized.type === ValueRoot);
+	const element = mountable(normalized, valueRoot);
 
 	let root: Root;
 	if (!mountedContainers.has(container)) {
 		if (hydrate) {
-			// hydrateRoot adopts the server DOM during creation (it renders once,
-			// synchronously) — only the effect settle is left to do.
-			root = hydrateRoot(container, element);
+			// Adoption queues insertion/layout effects. Commit those before the
+			// passive settle, so descendants can use callbacks installed by them.
+			root = flushSync(() => hydrateRoot(container, element));
 			settleSync();
 		} else {
 			root = createRoot(container);
 			commitRender(root, element);
 		}
-		mountedRootEntries.push({ container, root });
+		mountedRootEntries.push({ container, root, valueRoot });
 		// Track the container regardless of whether WE created it, so cleanup()
 		// handles caller-supplied containers too (RTL does the same).
 		mountedContainers.add(container);
 	} else {
 		// Same container rendered again → reuse its root (same component updates
 		// props in place; a different component tears down and remounts).
-		root = mountedRootEntries.find((entry) => entry.container === container)!.root;
+		root = previousEntry!.root;
 		commitRender(root, element);
 	}
 
@@ -294,16 +305,22 @@ export function render<P = any>(ui: OctaneUI<P>, options: RenderOptions<P> = {})
 			let element: ElementDescriptor;
 			if (rerenderUi === undefined) {
 				element = toElement(ui, props); // re-run with the original props
-			} else if (isValidElement(rerenderUi) || typeof rerenderUi === 'function') {
-				element = toElement(rerenderUi as OctaneUI, rerenderOptions?.props);
-			} else {
+			} else if (
+				rerenderUi !== null &&
+				typeof rerenderUi === 'object' &&
+				!isValidElement(rerenderUi) &&
+				!Array.isArray(rerenderUi) &&
+				Object.prototype.hasOwnProperty.call(rerenderUi, 'props')
+			) {
 				// `{ props }` shorthand: reuse the ORIGINAL component with new props.
 				const comp = isValidElement(ui) ? (ui as ElementDescriptor).type : ui;
 				element = createElement(comp as any, (rerenderUi as { props?: any }).props);
+			} else {
+				element = toElement(rerenderUi, rerenderOptions?.props);
 			}
 			// The wrapper is re-applied so component identity is stable across
 			// rerenders (same body ⇒ octane updates props in place).
-			commitRender(root, mountable(wrapUiIfNeeded(element, WrapperComponent)));
+			commitRender(root, mountable(wrapUiIfNeeded(element, WrapperComponent), valueRoot));
 		},
 		asFragment: () => document.createRange().createContextualFragment(container.innerHTML),
 		...(getQueriesForElement(baseElement, queries as any) as BoundFunctions<typeof defaultQueries>),
@@ -407,10 +424,93 @@ export function renderHook<Result, Props = undefined>(
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Exports — everything dom-testing-library ships, plus the octane layer.
-// `fireEvent` is dom-testing-library's own (see fire-event.ts for why there is
-// deliberately NO react-testing-library-style event remapping on top).
+// fireEvent adds native focus/blur pairs for delegated focus handlers.
+// Other convenience helpers retain DOM Testing Library's event semantics.
 // ─────────────────────────────────────────────────────────────────────────────
 
-export * from '@testing-library/dom';
-export { fireEvent } from './fire-event';
+export const fireEvent = octaneFireEvent;
+// Explicit value exports keep older SSR module runners from replacing our
+// focus-aware fireEvent with the DOM helper during wildcard re-export.
+export {
+	buildQueries,
+	configure,
+	createEvent,
+	findAllByAltText,
+	findAllByDisplayValue,
+	findAllByLabelText,
+	findAllByPlaceholderText,
+	findAllByRole,
+	findAllByTestId,
+	findAllByText,
+	findAllByTitle,
+	findByAltText,
+	findByDisplayValue,
+	findByLabelText,
+	findByPlaceholderText,
+	findByRole,
+	findByTestId,
+	findByText,
+	findByTitle,
+	getAllByAltText,
+	getAllByDisplayValue,
+	getAllByLabelText,
+	getAllByPlaceholderText,
+	getAllByRole,
+	getAllByTestId,
+	getAllByText,
+	getAllByTitle,
+	getByAltText,
+	getByDisplayValue,
+	getByLabelText,
+	getByPlaceholderText,
+	getByRole,
+	getByTestId,
+	getByText,
+	getByTitle,
+	getConfig,
+	getDefaultNormalizer,
+	getElementError,
+	getNodeText,
+	getQueriesForElement,
+	getRoles,
+	getSuggestedQuery,
+	isInaccessible,
+	logDOM,
+	logRoles,
+	prettyDOM,
+	prettyFormat,
+	queries,
+	queryAllByAltText,
+	queryAllByAttribute,
+	queryAllByDisplayValue,
+	queryAllByLabelText,
+	queryAllByPlaceholderText,
+	queryAllByRole,
+	queryAllByTestId,
+	queryAllByText,
+	queryAllByTitle,
+	queryByAltText,
+	queryByAttribute,
+	queryByDisplayValue,
+	queryByLabelText,
+	queryByPlaceholderText,
+	queryByRole,
+	queryByTestId,
+	queryByText,
+	queryByTitle,
+	screen,
+	waitFor,
+	waitForElementToBeRemoved,
+	within,
+} from '@testing-library/dom';
+export {
+	getMultipleElementsFoundError,
+	makeFindQuery,
+	makeGetAllQuery,
+	makeSingleQuery,
+	queryHelpers,
+	wrapAllByQueryWithSuggestion,
+	wrapSingleQueryWithSuggestion,
+} from './dom-query-helpers';
+export type * from '@testing-library/dom';
 export { act } from 'octane';