shallowly
v1.1.2
Published
Shallow rendering for isolated React component tests. Inspect component output, child props, and callbacks with an Enzyme-like API.
Maintainers
Readme
Shallowly 🏝️
Shallow rendering for isolated React component tests. Inspect component output, child props, and callbacks with an Enzyme-like API.
Shallowly calls the component under test and lets you inspect the React elements it returns. Child components stay as elements: their bodies and hooks are not executed. No DOM is required.
Install
Use Shallowly in a React 19 project. The package declares react: "^19.0.0" as a peer dependency; React 18 is outside that supported range.
npm install --save-dev shallowly vitestFor a new project, install React first with npm install react@^19.
First test with Vitest
Save this as Parent.test.jsx:
import React from 'react';
import { shallow } from 'shallowly';
import { expect, test, vi } from 'vitest';
function Child() {
throw new Error('This child must not render in the parent unit test');
}
function Parent({ label, onSave }) {
return (
<section>
<Child label={label} onSave={onSave} />
</section>
);
}
test('passes the label and save callback to Child', () => {
const onSave = vi.fn();
const wrapper = shallow(<Parent label="Save" onSave={onSave} />);
expect(wrapper.textInline()).toBe('<section><Child /></section>');
const child = wrapper.find(Child);
expect(child.prop('label')).toBe('Save');
const save = child.prop('onSave');
if (typeof save !== 'function') throw new Error('Expected onSave callback');
save();
expect(onSave).toHaveBeenCalledOnce();
});Run it with npx vitest run. This test inspects the parent output, reads a child's props, and calls a callback directly. It does not mount Child or dispatch a DOM event.
For a complete example with a mocked data hook, read Testing component output, props, and callbacks or run the example project.
What to test
- Output structure and conditional elements returned by your component.
- Props passed to child components, including values from mocked hooks or services.
- Callbacks passed to children and the application code those callbacks call.
Mock hooks and context used by the component under test. Shallowly calls a function component directly; it does not provide React's hook dispatcher, manage state updates, run effects, or propagate context. A Suspense element can be inspected as output, but Shallowly does not resolve suspended work or render its fallback. Use integration tests to verify those React behaviors and DOM interactions.
API at a glance
| Method | Behavior |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| shallow(element) | Calls the root component and wraps its output. No options argument. |
| find(Component) | Finds elements by function or class identity without rendering them. |
| find('Child'), find('button') | Finds by component name or host tag. |
| find('.save'), find('#save') | Finds host elements by a single class or ID. Arbitrary CSS selectors are not supported. |
| props(), prop(name) | Reads the input props on the root wrapper, or the matched element's props after a single-match find. |
| exists() | Checks whether a search has at least one match. |
| text(), textInline() | Serializes output structure including tags, without props, in multiple lines or one line. |
| textWithProps(), textWithPropsInline() | Serializes output structure with props for debugging and snapshots. |
If find matches zero or multiple elements, props() returns {} and prop(name) returns undefined. There is no length or at() API; use a selector that identifies a single element when reading props. TypeScript declarations are included: shallow has no generic type parameter, and prop values are not inferred from your component's props. Check values before using them.
See the English API reference or справочник на русском for examples and limits.
Moving Enzyme shallow tests
Shallowly provides an Enzyme-like subset, not a drop-in replacement. Tests that inspect child props with shallow, find, and prop may need only an import change; check the behavior below before migrating a suite.
| Existing test pattern | Shallowly approach |
| ---------------------------------------------------- | -------------------------------------------------------------------------------- |
| Inspect child props with find(Child).prop('value') | Supported when the search matches exactly one element. |
| Read output with .text() | Returns a serialized tree with tags, not Enzyme's plain text content. |
| Update with .setProps() | Create a new shallow(<Component ... />) wrapper for each input. |
| Trigger .simulate('click') | Read the callback prop and invoke it directly with the expected arguments. |
| Select with .at() or count .length | Not implemented. Use a unique simple selector for a prop assertion. |
| Use complex CSS selectors | Replace with a supported name, tag, class, or ID selector. |
| Test hook state, context, or lifecycle updates | Mock dependencies for the unit test; verify React behavior in integration tests. |
See the migration example.
Performance
The project's existing performance claims are 2x quicker render cycles than Enzyme, 7x faster than React Testing Library, and 40% less memory usage compared to Enzyme. The existing timing comparison is retained below:
| Operation | Shallowly | React Testing Library | | -------------------- | --------: | --------------------: | | Basic component | 12ms | 85ms (7.1x slower) | | 100 components | 650ms | 4500ms (6.9x slower) | | Hook-heavy component | 18ms | 210ms | | Tree traversal | 8ms | 150ms |
A reproducible benchmark suite with scenarios, library versions, runtime measurements, and memory measurements is tracked separately in issue #24. The figures above have not been revalidated by that suite. Shallowly skips DOM setup and child component execution; comparisons must account for the different work performed by each tool.
Documentation and contributing
- English documentation · Документация на русском
- Testing component output, props, and callbacks
- React architecture guide · Архитектура React
- Development guide · Руководство разработки
- Contributing · Report an issue
MIT © Bad4iz
