@octanejs/testing-library 0.1.49 → 0.1.50

package/README.md

@@ -13,10 +13,11 @@ pnpm add @octanejs/testing-library
 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 +41,8 @@ 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
 
 ## Octane-specific surface
 
@@ -60,8 +62,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 +87,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octanejs/testing-library",
-  "version": "0.1.49",
+  "version": "0.1.50",
   "license": "MIT",
   "type": "module",
   "engines": {
@@ -48,7 +48,7 @@
     "react": "^19.2.7",
     "react-dom": "^19.2.7",
     "vitest": "^4.1.10",
-    "octane": "0.2.0"
+    "octane": "0.2.3"
   },
   "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`
@@ -43,6 +43,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 +88,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(() => {
@@ -407,10 +403,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';