Skip to content package
react-introspect v0.0.10 Host-agnostic React component introspection for unit tests
node ^26.9.0 3 deps esm open source
overview readme
license MIT
deps 3
unpacked 287.2 kB
files 84
node ^26.9.0 $ npm install react-introspect@0.0.10n npmREADME GitHub-flavored package documentation.
downloads Across all versions.
Download trend unavailable.
compatibility Runtime metadata.
keywords Tagged topics.
react test testing components shallow-rendering
versions Latest published Oct 15, 2026
maintainers Registry package owners.
install size Estimated unpacked size across 6 packages.
3.7 MB
Includes dependencies.
dependencies 3 direct dependencies.
contents
React Introspect
Simple component tests. No DOM. No globals. No compiler plugin. No browser.
npm install --save-dev react-introspect copy
React Introspect is for unit testing React components by their render surface.
You can ask:
Which components did this component render?
Which props did it pass?
Which text did it expose?
What changed after an event?
Did it pass the right children, without rendering those children too? You do not need to know what every child component renders.
You do not need JSX, but you can.
Quick Guide Parent executes
Child does not execute
GrandChild does not execute copy You still see the props and children Parent gave to Child.
Queries search everything Parent returned, including elements nested inside Child.
You do not see what Child renders unless you opt in.
import assert from 'node:assert/strict' ;
import test from 'node:test' ;
import { introspect } from 'react-introspect' ;
type SaveButtonProps = {
label : string ;
disabled : boolean ;
onSave () : void ;
};
const SaveButton : React . FC < SaveButtonProps > = () => {
throw new Error ( 'SaveButton should not run in this test' );
};
const Toolbar : React . FC <{ saving : boolean ; onSave () : void ; }> = (props) => {
return (
<>
< SaveButton label= 'Save' disabled={ props.saving } onSave={ props.onSave } />{ ' ' }
< SaveButton label= 'Save as copy' disabled={ false } onSave={ props.onSave } />
</>
);
};
test ( 'passes props and events to children' , () => {
let saves = 0 ;
const view = introspect (
< Toolbar
saving={ true }
onSave={ () => {
saves += 1 ;
} }
/>
);
assert. equal (view. findAll (SaveButton).length, 2 );
const save = view. find ({
type: SaveButton,
props: { label: 'Save' }
});
assert. ok (save);
assert. equal (save.props.disabled, true );
save. sendEvent ( 'save' );
assert. equal (saves, 1 );
}); copy Go deeper when you want to inspect a child component's output:
const view = introspect ( < Toolbar saving={ false } onSave={ () => {} } /> , {
depth: 2
});
const button = view. find ( 'button' );
assert. ok (button);
assert. equal (button.textContent, 'Save' ); copy
API By Example
introspect(element, options)const view = introspect ( < ProfileCard user={ user } /> , {
depth: 1 ,
idPrefix: 'profile-test-'
}); copy Option Default What it does depth1Component depth to execute. Use a number or 'full'. depthFromnone Starts counting depth at the first instance of this component. errorMode'capture'Captures uncaught render errors on the view. Use 'throw'. hostEvent{}Default fields for event stubs sent to host elements. idPrefixgenerated Prefix passed to React for useId. idGeneratornone Rewrites React-generated ids in string props and text after commit. refsnone Injects fake host ref nodes. waitTimeout1000Milliseconds a wait API waits before it rejects with a timeout error. strictModetrueWraps the React Introspect root in React.StrictMode. transparent[]Components that execute without consuming depth. warningMode'throw'Throws on React warnings. Use 'capture' or 'ignore'.
createIntrospect(defaults)Returns an introspect function with preset options, for a shared test harness.
import { createIntrospect } from 'react-introspect' ;
export const introspectPage = createIntrospect < React . JSX . IntrinsicElements >({
transparent: [ AppProviders ],
waitTimeout: 500
});
const view = introspectPage ( < SettingsPage /> , { depth: 2 }); copy Per-call options override the defaults key by key. Arrays such as transparent replace the default; they are not merged.
Typed host props Pass a host schema to type host element props. React.JSX.IntrinsicElements works as is.
const view = introspect < React . JSX . IntrinsicElements >( < SignupForm /> );
const submit = view. find ( 'button' );
assert. ok (submit);
assert. equal (submit.props.type, 'submit' ); // 'button' | 'reset' | 'submit' | undefined copy Any object type works as a schema. Tags missing from it have unknown props. children is never part of host props; use givenChildren.
View properties are lazy views of the latest committed snapshot.
Node properties read the snapshot that produced that node. Query again after updates.
view.rootReturns the root node, or undefined after unmount.
const view = introspect ( < ProfileCard user={ user } /> );
assert. equal (view.root?.type, ProfileCard); copy
view.renderedChildrenReturns direct rendered children of the root.
Use it when directness matters.
const view = introspect ( < Page /> );
assert. deepEqual (
[ ... view.renderedChildren ]. map ((node) => node.type),
[ Header, Content, Footer ]
); copy
view.find(typeOrSelector)Returns the first match, or undefined.
const card = view. find (UserCard);
assert. ok (card);
assert. equal (card.props.variant, 'compact' ); copy Host elements use the same API:
const submit = view. find ({
type: 'button' ,
props: { type: 'submit' },
textContent: 'Save'
});
assert. ok (submit);
assert. equal (submit.props.disabled, false ); copy view. find (Button);
view. find ( 'button' );
view. find ({ type: Button });
view. find ({ props: { disabled: true } });
view. find ({ textContent: /saved/ i });
view. find ({ type: 'form' , has: { type: 'button' , props: { type: 'submit' } } });
view. find ({ where : (node) => node.name. startsWith ( 'Menu' ) }); copy props selectors use deep partial matching.
view. find ({
type: UserCard,
props: {
user: { id: '1' }
}
}); copy
view.findAll(typeOrSelector)Returns an IntrospectionList.
const items = view. findAll ( 'li' );
assert. equal (items.length, 5 ); copy Lists do not throw for empty, one, or many results.
assert. equal (view. findAll (Button).first, undefined);
assert. equal (view. findAll (Tab). at ( 42 ), undefined); copy IntrospectionList is iterable:
for ( const item of view. findAll (MenuItem)) {
assert. equal (item.props.disabled, false );
} copy Modern iterator helpers work:
const labels = Iterator
. from (view. findAll (Button))
. map ((button) => button.props.label)
. toArray ();
assert. deepEqual (labels, [ 'Save' , 'Cancel' ]); copy const labels = Array
. from (view. findAll (Button))
. map ((button) => button.props.label); copy const submitButtons = view. findAll ( 'button' ). filterBy ({
props: { type: 'submit' }
});
assert. equal (submitButtons.length, 1 ); copy
view.locate(typeOrSelector) and view.locateAll(typeOrSelector)Use them when you want one query handle to re-read the latest committed snapshot after updates.
const save = view. locate ({
type: Button,
props: { label: 'Save' }
});
assert. equal (save.exists, true );
assert. equal (save.node?.props.disabled, false );
save. sendEvent ( 'save' );
await view. waitForNextRender ();
assert. equal (save.node?.props.disabled, true ); copy Locators project node data the same way. Each projection returns undefined when nothing matches, so one assertion covers both cases.
assert. deepEqual (view. locate ( 'button' ). pickProps ([ 'type' , 'disabled' ]), { type: 'submit' , disabled: false });
assert. equal (view. locate (Status).textContent, 'Saved' );
assert. equal (view. locate (ErrorBanner).props, undefined); copy Projections: props, pickProps(), omitProps(), textContent, type, name, key, and kind.
List locators stay live too.
const rows = view. locateAll (Row);
assert. equal (rows.length, 2 );
view. update ( < Table rows={ nextRows } /> );
assert. equal (rows.length, 3 ); copy
node.find() and node.findAll()const toolbar = view. find (Toolbar);
assert. ok (toolbar);
assert. equal (toolbar. findAll (Button).length, 2 ); copy
node.type, node.name, and node.keyconst button = view. find (Button);
assert. ok (button);
assert. equal (button.type, Button);
assert. equal (button.name, 'Button' );
assert. equal (button.key, 'primary' ); copy Names follow React's warnings: a displayName wins, memo components take the wrapped component's name (or Memo), lazy components that executed take the name of the component they resolved to (unexecuted ones, below the depth or in props, read Component), and forwardRef components are named ForwardRef(Render).
node.kindTells you what a node models, without matching on '#empty' or '#text'.
'component'
'host'
'fragment'
'text'
'empty' for null, undefined, and booleans
'opaque' for values React Introspect does not model
Empty children keep their position.
const Toolbar = (props : { canSave : boolean ; }) => (
< Shell >
{ props.canSave && < SaveButton />}
< CancelButton />
</ Shell >
);
const view = introspect ( < Toolbar canSave={ false } /> );
const shell = view. find (Shell);
assert. ok (shell);
assert. equal (shell.givenChildren. at ( 0 )?.kind, 'empty' );
assert. equal (shell.givenChildren. at ( 1 )?.type, CancelButton); copy
node.isStaleisStale tells you whether a newer committed snapshot exists.
const button = view. find (Button);
assert. ok (button);
assert. equal (button.isStale, false );
button. sendEvent ( 'save' );
assert. equal (button.isStale, true ); copy
node.propsReturns typed props without children, key and ref.
type UserCardProps = {
user : User ;
variant : 'full' | 'compact' ;
};
const UserCard : React . FC < UserCardProps > = () => null;
const card = view. find (UserCard);
assert. ok (card);
assert. equal (card.props.variant, 'compact' ); copy Functions stay available:
const button = view. find (Button);
assert. ok (button);
button.props. onSave (); copy React elements inside props are introspection nodes, also inside arrays and plain objects:
type TabProps = {
icon : React . ReactElement < IconProps >;
badge : React . ReactNode ;
label : string ;
};
const tab = view. find (Tab);
assert. ok (tab);
assert. equal (tab.props.icon.type, Icon);
assert. equal (tab.props.icon.props.name, 'inbox' );
assert. equal (tab.props.icon.path, 'Toolbar > Tab[0] > Icon[icon]' );
assert. equal (tab.props.label, 'Inbox' ); copy Their types follow: React.ReactElement becomes IntrospectionNode. A React.ReactNode prop can also hold a string, number, or null at runtime, so it stays a union; type slot props as React.ReactElement when they always hold an element.
view.find() does not search inside props. Search from the prop node instead: tab.props.icon.find('svg').
Every other prop value is the reference the parent passed. Plain objects, arrays, Map, Set, and class instances keep their identity, so a test can check that a component hands an object through:
const appContext = createAppContext ();
const view = introspect ( < App appContext={ appContext } /> );
const provider = view. find (AppContextProvider);
assert. ok (provider);
assert. equal (provider.props.value, appContext); copy Only a plain object or array that holds a React element is rebuilt: it becomes a frozen copy with the elements replaced by nodes, and every value inside it that holds no element keeps its identity. A reference back to a rebuilt container becomes the string '[Circular]'. React Introspect does not look inside Map, Set, or class instances, so elements in there stay React elements.
node.pickProps(keys) and node.omitProps(keys)Both methods are type-aware.
const button = view. find (Button);
assert. ok (button);
assert. deepEqual (button. pickProps ([ 'label' , 'disabled' ]), {
label: 'Save' ,
disabled: false
}); copy Unknown prop keys are TypeScript errors. pickProps() needs at least two keys. Read a single prop from props.
button. pickProps ([ 'label' , 'disabled' ]);
button. omitProps ([ 'onSave' ]); copy Use givenChildren for children.
const shell = view. find (Shell);
assert. ok (shell);
assert. equal (shell.givenChildren.first?.type, Button); copy
node.givenChildrenReturns children passed to the node.
const shell = view. find (Shell);
assert. ok (shell);
const givenButton = shell.givenChildren.first;
assert. ok (givenButton);
assert. equal (givenButton.type, Button); copy
node.renderedChildrenReturns what the node rendered at the selected depth.
A component below the selected depth does not execute. It passes the children it was given through, the way a shallow renderer does. That keeps everything the executed component built in the tree.
const Page = () => (
< PageLayout >
< SaveButton label= 'Save' />
</ PageLayout >
);
const view = introspect ( < Page /> );
const layout = view. find (PageLayout);
assert. ok (layout);
assert. equal (layout.renderedChildren.status, 'rendered' );
assert. equal (layout.state.reason, 'depth' );
assert. ok (view. find (SaveButton));
assert. equal (view. find ( 'button' ), undefined); copy node.state still tells you the component did not execute.
const card = view. find (Card);
assert. ok (card);
assert. equal (card.renderedChildren.status, 'rendered' );
assert. equal (card.renderedChildren.nodes.length, 2 ); copy The only 'notRendered' reason is 'unsupported', for values React Introspect cannot execute.
view.textContent and node.textContentReturns concatenated text.
React Introspect does not trim or collapse whitespace.
const Label = () => {
return (
<>
Save < Icon name= 'disk' /> changes
</>
);
};
const view = introspect ( < Label /> );
assert. equal (view.textContent, 'Save changes' ); copy const button = view. find (Button);
assert. ok (button);
assert. equal (button.textContent, 'Save changes' ); copy
node.sendEvent(name, ...args)Calls a conventional event prop at discrete priority, like a user event, and commits the resulting update before it returns.
const input = view. find (SearchInput);
assert. ok (input);
input. sendEvent ( 'change' , 'react' ); copy
save -> onSave
change -> onChange
myCustomEvent -> onMyCustomEvent
pressCapture -> onPressCapture
Component nodes receive the arguments as passed.
Host nodes receive an event stub, because their handlers expect an event:
const form = view. find ( 'form' );
assert. ok (form);
form. sendEvent ( 'submit' );
// onSubmit({ type: 'submit', preventDefault, stopPropagation, defaultPrevented, ... })
const input = view. find ( 'input' );
assert. ok (input);
input. sendEvent ( 'change' , { target: { value: 'Ada' } });
// onChange({ type: 'change', preventDefault, ..., target: { value: 'Ada' } }) copy An object as first argument is merged over the stub. Any other first argument is passed as is. The stub has type, defaultPrevented, preventDefault(), isDefaultPrevented(), stopPropagation(), and isPropagationStopped(). Add defaults with the hostEvent option.
Use locate() for actions when the target may be missing. view.locate(Button).sendEvent('save') throws on a missing node; view.find(Button)?.sendEvent('save') silently does nothing.
node.callProp(propName, ...args)Low-level API for exact function props.
const button = view. find (Button);
assert. ok (button);
button. callProp ( 'onSave' ); copy
node.stateReturns render and visibility metadata.
const panel = view. find (SettingsPanel);
assert. ok (panel);
assert. equal (panel.state.rendered, true );
assert. equal (panel.state.visible, false );
assert. equal (panel.state.activityMode, 'hidden' ); copy type IntrospectionNodeState = {
readonly rendered : boolean ;
readonly visible : boolean ;
readonly activityMode : 'visible' | 'hidden' | undefined ;
readonly reason : 'depth' | 'unsupported' | 'activity' | 'suspended' | undefined ;
}; copy reason reports why a node was not rendered ('depth', 'unsupported') before why it is hidden. An executed node that is hidden reports 'activity' below a hidden <Activity>, or 'suspended' when Suspense keeps it behind a fallback after an update suspended; the outermost cause wins. Use visible to check visibility for every node.
node.caughtErrorReturns the latest error this error boundary caught, or undefined.
const view = introspect (
< Boundary >
< Crashes />
</ Boundary > ,
{ depth: 'full' }
);
const boundary = view. find (Boundary);
assert. ok (boundary);
const error = boundary.caughtError;
assert. ok (error);
assert. match (error.message, /boom/ ); copy
node.visibilityconst panel = view. find (SettingsPanel);
assert. ok (panel);
assert. equal (panel.visibility, 'hidden' ); copy
'visible'
'hidden'
'notRendered'
Only unsupported nodes are 'notRendered'. A component below the selected depth reports the visibility of where it sits.
node.findClosest(selector)Finds the nearest parent that matches a selector.
const text = view. find ({ textContent: 'Email' });
assert. ok (text);
const field = text. findClosest ({ type: Field });
assert. ok (field); copy
node.pathReturns a readable debug path.
const button = view. find (Button);
assert. ok (button);
assert. equal (button.path, 'ProfileForm > Actions > Button[0]' ); copy
assert. match (view. formatTree (), /ProfileForm/ );
const button = view. find (Button);
assert. ok (button);
assert. match (button. formatTree (), /Button/ ); copy
view.update(element)Renders a new root element into the same view.
view. update ( < ProfileCard user={ nextUser } /> );
const avatar = view. find (Avatar);
assert. ok (avatar);
assert. equal (avatar.props.userId, nextUser.id); copy
view.unmount()There is no mount() or remount().
Create a new view instead.
view. unmount ();
assert. equal (view.root, undefined);
const nextView = introspect ( < ProfileCard user={ user } /> ); copy A view is disposable. Declare it with using to unmount it when the scope ends.
test ( 'focuses the search box' , () => {
using view = introspect ( < SearchBox autoFocus={ true } /> );
assert. ok (view. find ( 'input' ));
}); copy Unmounting an unmounted view does nothing. See Cleanup for when this matters.
view.uncaughtErrors and view.caughtErrorsuncaughtErrors returns render errors no error boundary caught. They unmount the root.
caughtErrors returns every error an error boundary caught, in order, including ones the boundary has recovered from since.
Use .at(-1) for the latest one.
const view = introspect ( < Crashes /> );
const error = view.uncaughtErrors. at ( - 1 );
assert. ok (error);
assert. match (error.message, /boom/ );
assert. equal (view.uncaughtErrors.length, 1 );
assert. equal (view.caughtErrors.length, 0 ); copy Use errorMode: 'throw' when a thrown render error should escape introspect().
In throw mode, the call that did the work throws the first error or warning it recorded. If that call fails on its own, for example a wait that times out, its own error wins and the recorded ones stay in the lists. Anything recorded by work that runs between calls, or that keeps running after a timed out wait, is thrown by the next call.
assert. throws (() => {
introspect ( < Crashes /> , { errorMode: 'throw' });
}, /boom/ ); copy
view.warnings and view.hasWarningsReact Introspect throws on warnings by default.
Use warningMode: 'capture' when you want to assert them.
const view = introspect ( < List items={ items } /> , {
warningMode: 'capture'
});
assert. equal (view.hasWarnings, false );
assert. deepEqual (view.warnings, []); copy Warnings include React recoverable errors and React warnings printed through console.warn or console.error while React Introspect owns the React work.
Non-React logs still pass through.
assert. throws (() => {
introspect ( < ListWithoutKeys items={ items } /> );
}, /React warning/ ); copy
view.waitForNextRender()Waits for one more committed render.
const waiting = view. waitForNextRender ();
const button = view. find (Button);
assert. ok (button);
button. sendEvent ( 'save' );
await waiting; copy
view.waitForRenderCount(count)Waits until the committed render count reaches count.
const target = view.renderCount + 1 ;
const button = view. find (Button);
assert. ok (button);
button. sendEvent ( 'save' );
await view. waitForRenderCount (target); copy
view.waitForIdle()Waits until React work known to React Introspect is flushed.
const button = view. find (Button);
assert. ok (button);
button. sendEvent ( 'save' );
await view. waitForIdle (); copy Render work that is already scheduled when you call it is committed first, including transitions scheduled outside React, for example by a store or router subscription, and commits React delays on purpose, such as revealing resolved Suspense content.
cartStore. add (item);
await view. waitForIdle ();
const badge = view. find (CartBadge);
assert. ok (badge);
assert. equal (badge.props.count, 1 ); copy
view.waitUntil(predicate)await view. waitUntil (() => {
const status = view. find (Status);
return status !== undefined && status.props.state === 'saved' ;
}); copy
Special Cases
Refs Use host tag shorthand for the common case.
import { createFakeRefNode } from 'react-introspect' ;
const inputNode = createFakeRefNode ({
focusCalled: false ,
focus () {
this .focusCalled = true ;
}
});
introspect ( < SearchBox autoFocus={ true } /> , {
refs: {
input: inputNode
}
});
assert. equal (inputNode.focusCalled, true ); copy Object keys are host tag names.
If a shorthand matches zero refs or more than one ref, React Introspect should throw a clear error.
Use matchRefs() when you need selectors.
import { createFakeRefNode, matchRefs } from 'react-introspect' ;
const emailInput = createFakeRefNode ({ focus () {} });
const passwordInput = createFakeRefNode ({ focus () {} });
const submitButton = createFakeRefNode ({ click () {} });
introspect ( < SignupForm /> , {
refs: matchRefs ([
{
type: 'input' ,
props: { name: 'email' },
node: emailInput
},
{
type: 'input' ,
props: { name: 'password' },
node: passwordInput
},
{
type: 'button' ,
props: { type: 'submit' },
node: submitButton
}
])
}); copy Use a factory for repeated refs.
introspect ( < FieldList /> , {
refs: matchRefs ([
{
type: 'input' ,
props: { role: 'field' },
node : () => createFakeRefNode ({ focus () {} })
}
])
}); copy
Context Providers pass through, and Context.Consumer runs its render prop with the nearest provider's value.
const ThemeContext = React. createContext ( 'light' );
const Panel = () => {
const theme = React. useContext (ThemeContext);
return < Card theme={ theme } /> ;
};
const view = introspect (
< ThemeContext.Provider value= 'dark' >
< Panel />
</ ThemeContext.Provider > ,
{ depth: 2 }
);
const card = view. find (Card);
assert. ok (card);
assert. equal (card.props.theme, 'dark' ); copy
StrictMode and Profiler Both pass through: their children execute and they show up as StrictMode and Profiler nodes.
Profiler's onRender reports timings for the introspected tree, not for your app's real renderer.
Harness wrappers and routers Every executed component consumes one level of depth. Wrappers from the test harness would eat that budget.
Use transparent for wrappers you own.
const view = introspect (
< ThemeProvider >
< SettingsPage />
</ ThemeProvider > ,
{ transparent: [ ThemeProvider ] }
); copy ThemeProvider executes, SettingsPage executes, and its children stay leaves.
Use depthFrom when the wrapper renders components you cannot name, such as router internals.
const view = introspect ( < RouterProvider router={ router } /> , {
depthFrom: SettingsPage
}); copy Everything above SettingsPage executes. On each branch, depth counts from the first SettingsPage. Nested instances do not restart the count.
Components beside the path to depthFrom, such as a layout's header, also execute. If depthFrom never renders, the whole tree executes.
Updates outside act React Introspect does not use act, and your tests do not need it either. Store, router, and timer updates are committed by waitForIdle().
const view = introspect ( < RouterProvider router={ router } /> , {
depthFrom: SettingsPage
});
router. navigate ( '/settings' );
await view. waitForIdle ();
assert. ok (view. find (SettingsPage)); copy Trigger the update and wait on the view instead of wrapping it in React.act. React.act only exists in development builds of React, and an open await act(async () => ...) scope collects the work of every React root in the process until it ends. Run tests that hold such a scope serially, not concurrently with other tests.
If your suite sets IS_REACT_ACT_ENVIRONMENT = true, React Introspect clears it while it commits its own renders and events, so those do not warn. Updates your test triggers outside React still warn about missing act. Scope the flag to the tests that need it instead of the whole suite.
Render props Render props are user code.
React Introspect does not call them unless the component under test calls them.
const List = (props : {
items : string [];
children (item : string ) : React . ReactNode ;
}) => {
return props.items. map ((item) => props. children (item));
};
const view = introspect (
< List items={ [ 'a' , 'b' ] }>
{ (item) => < Row item={ item } />}
</ List >
);
assert. equal (view. findAll (Row).length, 2 ); copy
Class components Class components execute at the selected depth, also when wrapped in memo or lazy.
class Counter extends React .Component<{ label : string ; }, { count : number ; }> {
state = { count: 0 };
increment = () => {
this . setState ((state) => ({ count: state.count + 1 }));
};
render () {
return < CounterView count={this .state.count } label={this .props.label } onIncrement={this .increment } /> ;
}
}
const view = introspect ( < Counter label= 'Clicks' /> , { depth: 2 });
const counter = view. find (CounterView);
assert. ok (counter);
assert. equal (counter.props.count, 0 );
counter. sendEvent ( 'increment' );
const updated = view. find (CounterView);
assert. ok (updated);
assert. equal (updated.props.count, 1 ); copy Below the selected depth, a class component is still just a leaf.
const view = introspect ( < Toolbar /> , { depth: 1 });
const legacyButton = view. find (LegacyButton);
assert. ok (legacyButton);
assert. equal (legacyButton.props.label, 'Save' );
assert. equal (legacyButton.state.rendered, false ); copy
Error boundaries React Introspect supports error boundaries as real component boundaries.
class Boundary extends React .Component< React . PropsWithChildren , { failed : boolean ; }> {
state = { failed: false };
static getDerivedStateFromError () {
return { failed: true };
}
componentDidCatch (error : Error ) {
reportError (error);
}
render () {
return this .state.failed ? < Fallback /> : this .props.children;
}
}
const view = introspect (
< Boundary >
< Crashes />
</ Boundary > ,
{ depth: 'full' }
);
const fallback = view. find (Fallback);
const boundary = view. find (Boundary);
assert. ok (fallback);
assert. ok (boundary);
const error = boundary.caughtError;
assert. ok (error);
assert. match (error.message, /boom/ );
assert. equal (view.caughtErrors.length, 1 );
assert. equal (view.uncaughtErrors.length, 0 ); copy Uncaught errors stay inspectable on the view.
const view = introspect ( < Crashes /> );
const error = view.uncaughtErrors. at ( - 1 );
assert. ok (error);
assert. match (error.message, /boom/ ); copy
Lazy and Suspense If a lazy component is not executed because of depth, it is just a component leaf.
const LazyDetails = React. lazy (loadDetails);
const view = introspect ( < Page /> , { depth: 1 });
const details = view. find (LazyDetails);
assert. ok (details);
assert. equal (details.state.rendered, false ); copy If React Introspect needs to execute a lazy component, wait for it through Suspense.
const view = introspect ( < PageWithSuspense /> , {
depth: 2
});
assert. equal (view. findAll (Spinner).length, 1 );
await view. waitForNextRender ();
assert. equal (view. findAll (Details).length, 1 ); copy Suspended render attempts do not publish partial trees.
use(promise)const userPromise = Promise . resolve ({ name: 'Ada' });
const Profile = () => {
const user = React. use (userPromise);
return < UserCard user={ user } /> ;
};
const view = introspect ( < Profile /> );
await view. waitForIdle ();
const card = view. find (UserCard);
assert. ok (card);
assert. equal (card.props.user.name, 'Ada' ); copy let resolveUser !: (user : User ) => void ;
const userPromise = new Promise < User >((resolve) => {
resolveUser = resolve;
});
const view = introspect ( < Profile userPromise={ userPromise } /> );
assert. equal (view. findAll (Loading).length, 1 );
resolveUser ({ name: 'Ada' });
await view. waitForNextRender ();
const card = view. find (UserCard);
assert. ok (card);
assert. equal (card.props.user.name, 'Ada' ); copy
Async components Async components are server-style React.
React Introspect treats them like Suspense work.
async function Profile (props : { id : string ; }) {
const user = await loadUser (props.id);
return < UserCard user={ user } /> ;
}
const view = introspect ( < Profile id= '1' /> );
await view. waitForIdle ();
const card = view. find (UserCard);
assert. ok (card);
assert. equal (card.props.user.id, '1' ); copy If the React version or runtime does not support async components here, React Introspect should fail with a clear unsupported error.
View transitions React Introspect does not run browser view transitions.
It can still test the render surface around React's transition components.
const view = introspect ( < Gallery /> );
const thumbnail = view. find (Thumbnail);
assert. ok (thumbnail);
thumbnail. sendEvent ( 'open' , 'image-1' );
const photo = view. find (PhotoView);
assert. ok (photo);
assert. equal (photo.props.id, 'image-1' ); copy Use browser tests for animation and CSS transition behavior.
<Activity />When the React version supports Activity, React Introspect treats it as a React wrapper.
React renders hidden Activity content at a lower priority after the first commit, so it appears once the view is idle.
const view = introspect ( < SettingsPage /> );
await view. waitForIdle ();
const activity = view. find (React.Activity);
assert. ok (activity);
assert. equal (activity.props.mode, 'hidden' );
const child = activity.givenChildren.first;
assert. ok (child);
assert. equal (child.type, SettingsPanel);
const panel = view. find (SettingsPanel);
assert. ok (panel);
assert. equal (panel.visibility, 'hidden' ); copy
cache and cacheSignalReact Introspect uses a fresh React root per view.
That keeps cache state local to the test.
const getUser = React. cache ( async (id : string ) => {
return loadUser (id);
});
const Profile = (props : { id : string ; }) => {
const user = React. use ( getUser (props.id));
return < UserCard user={ user } /> ;
};
const view = introspect ( < Profile id= '1' /> );
await view. waitForIdle ();
const card = view. find (UserCard);
assert. ok (card);
assert. equal (card.props.user.id, '1' ); copy cacheSignal should abort when the view unmounts.
view. unmount ();
assert. equal (requestWasAborted, true ); copy
useIdUse idPrefix for real React ids with a stable prefix.
const view = introspect ( < SignupForm /> , {
idPrefix: 'signup-'
});
const email = view. find ({
type: 'input' ,
props: { name: 'email' }
});
assert. ok (email);
assert. match (email.props.id, /^signup-/ ); copy Use idGenerator when you want nice deterministic ids in React Introspect output. It rewrites string props and text content. Strings inside object or array props stay untouched, because those values keep their identity.
const ids = [ 'field-a' , 'field-b' ];
const view = introspect ( < SignupForm /> , {
idGenerator () {
return ids. shift () ?? 'field-extra' ;
}
});
const firstInput = view. findAll ( 'input' ). at ( 0 );
const secondInput = view. findAll ( 'input' ). at ( 1 );
assert. ok (firstInput);
assert. ok (secondInput);
assert. equal (firstInput.props.id, 'field-a' );
assert. equal (secondInput.props.id, 'field-b' ); copy
Cleanup Cleanup is optional. React Introspect keeps no global registry of views, so a view that goes out of scope is garbage collected together with its React tree.
A view survives a test only when something outside the test keeps a reference into the tree. Typical cases are a component that subscribes to a module-level store in an effect, or one that starts an interval. The subscription or timer holds the component's state setter, and through it the whole tree.
Only the effect cleanups release those references, and only unmounting runs them. Call view.unmount() or declare the view with using in such tests.
test ( 'renders the cart badge' , () => {
using view = introspect ( < CartBadge store={ cartStore } /> );
assert. equal (view. find (Badge)?.props.count, 0 );
}); copy Consider the same when a large suite grows in memory.
Use without JSX React Introspect accepts normal React elements. JSX is optional.
import React from 'react' ;
import { introspect } from 'react-introspect' ;
const view = introspect (
React. createElement (Menu, {
selectedId: 'settings'
})
);
const list = view. find (MenuList);
assert. ok (list);
assert. equal (list.props.selectedId, 'settings' ); copy
Unsupported React Concepts React Introspect should fail loudly for these until support is designed.
Portals Portals are not flattened into the current tree.
import { createPortal } from 'react-dom' ;
const Modal = () => {
return createPortal ( < Dialog title= 'Delete file?' /> , document.body);
};
assert. throws (() => {
introspect ( < Modal /> );
}, /portal/ i ); copy An error boundary above the portal does not stop this failure. The boundary's getDerivedStateFromError and componentDidCatch still run, but the call still throws.
Use a browser or DOM test when the portal target matters.
Lazy roots without Suspense Lazy component leaves are fine.
Executing an unresolved lazy root needs Suspense.
const LazyPage = React. lazy (loadPage);
assert. throws (() => {
introspect ( < LazyPage /> );
}, /suspense|lazy/ i ); copy Wrap it when you want to test the loading and loaded states.
const view = introspect (
< React.Suspense fallback={< Spinner />}>
< LazyPage />
</ React.Suspense >
);
assert. equal (view. findAll (Spinner).length, 1 ); copy
Testing Library Use it when you want to test what a user can see or do.
React Introspect is for smaller unit tests where the component contract is:
rendered child components
props passed to them
given children
text content
event props
react-test-rendererreact-test-renderer is deprecated.
It also tends to push tests toward host output.
React Introspect is shallow by default and component-first.
test-rendererReact Introspect also inspects intermediate component nodes.
FAQ
Why does find() not throw?
React Introspect inspects.
Your assertion library asserts.
const button = view. find (Button);
assert. ok (button);
assert. equal (button.props.label, 'Save' ); copy
This keeps Introspection useful with any assertion style.
Why does find() return undefined instead of a Maybe-like node?
Because TypeScript already understands undefined.
const button = view. find (Button);
assert. ok (button);
button.props.label; copy
A Maybe-like node makes props.label hard to type. It would need to return string | unavailable, and that spreads through the whole API.
Do non-React console logs fail the test?
No.
React Introspect only collects React diagnostics it can attribute to Introspection-owned work.
Normal app logs still pass through.
If a warning looks like React output but cannot be attributed, React Introspect throws so the attribution can be fixed instead of silently hiding it.
Why is introspect() not async?
Most unit tests do not suspend.
introspect() returns the first committed view synchronously.
If React work is async, wait on the view:
const view = introspect ( < Profile userPromise={ promise } /> );
await view. waitForIdle (); copy
This avoids await introspect(...) in thousands of simple tests.
How does use(promise) work with sync introspect()?
If a component suspends, React commits the nearest fallback if one exists.
React Introspect publishes only committed snapshots.
When the promise resolves, React schedules another render.
const view = introspect ( < Profile userPromise={ promise } /> );
await view. waitForNextRender (); copy
No partial suspended tree is exposed.
Why is idGenerator only applied to React Introspect output?
React owns useId.
React Introspect does not monkey patch React and does not replace the dispatcher.
So idGenerator maps React-generated ids inside React Introspect snapshots after commit. The component itself still saw React's real id during render.
Does Introspection replace browser tests?
No.
Use browser tests for layout, real focus behavior, pointer events, CSS, animations, and view transitions.
Use React Introspect for component contracts.
Design Promises
no DOM requirement
no browser globals
no compiler plugin
no JSX requirement
no monkey patching
no act, works with development and production builds of React
no raw React internals in public output
committed snapshots only
shallow by default
explicit opt-in for deeper rendering
typed component props when you query by component value
Links