Shallowly 🏝️ - The Modern Unit Testing Tool for React

📚 Documentation

• English Documentation
• Документация на русском
• Development Guide
• Руководство разработки на русском

🎯 Key Purpose: Laser-Focused Unit Testing

"Shallowly exists for one purpose: fast, isolated unit tests of YOUR React components."

Why Unit Testing Matters:

• 🔍 Isolated verification - Test components in complete isolation
• ⚡ Instant feedback - Get results in milliseconds, not seconds
• 🧩 Precise targeting - Verify one component at a time
• 🛡️ Safe refactoring - Change implementation without breaking tests

🧪 Testing Philosophy

"Don't test React or third-party libraries - only test the code YOU wrote here."
Shallowly's core mantra

Why this matters:

1. 🚫 No redundant tests - React and popular libraries are already well-tested by their maintainers
2. 💡 Focus on business logic - Verify only your unique functionality
3. ⚡ Blazing fast - Skip unnecessary rendering of entire component trees
4. 🎯 Precise targeting - Test components in complete isolation
5. 🔒 Future-proof - Your tests won't break when dependencies update

"Good tests don't check how React works - they check how YOUR application works with React."

What this means in practice:

✅ DO test:

• Your component's output
• Your business logic
• Your custom hooks
• Your state management

❌ DON'T test:

• React's internal behavior
• Third-party component rendering
• Library implementation details

The Modern Shallow Renderer for React 18+ Testing

The modern Enzyme alternative for fast unit testing with:

• ✅ Full React 18+ support (Hooks, Context, Suspense)
• 🚀 Enzyme 🔚💀 It is no longer supported or operational.
• ⚡ 7x faster than React Testing Library
• 🔍 Built-in debug with .textWithProps()
• 📦 5KB size (3x smaller than Enzyme) 🔚💀 It is no longer supported or operational.
• 🛠 Familiar API - easy migration from Enzyme

🚀 Why Shallowly?

Enzyme is deprecated, and React Testing Library doesn't support shallow rendering. Shallowly solves this with:

• ✔ Future-proof - Full support for React 18+ (Hooks, Context, Suspense)
• ✔ Blazing fast - 2x quicker render cycles than Enzyme (benchmarks)
• ✔ Familiar API - Enzyme-like syntax for painless migration
• ✔ Debug-friendly - .textWithProps() reveals your component structure
• ✔ Tiny footprint - 5KB (gzipped), zero dependencies

npm install shallowly

# or

yarn add shallowly

✨ Key Features

1. React 18+ Ready

Test modern features without workarounds:

shallow(
  <Suspense fallback={<Loader />}>
    <AsyncComponent />
  </Suspense>,
);

2. Enzyme Compatibility Layer

- import { shallow } from 'enzyme';
+ import { shallow } from 'shallowly'; // Same API!

3. Visual Debugging

console.log(wrapper.textWithProps());
// Outputs:
// <DataFetching isLoading={true}>
// <Spinner />
// </DataFetching>

4. TypeScript Native

const wrapper = shallow<Props>(<User id={123} />);
wrapper.prop("id"); // Type-safe: number

📦 Quick Start

Install:

npm install shallowly --save-dev

Write tests:

import { shallow } from "shallowly";
import vi from "vitest";

const MyComponent = ({ name, age, onClick }) => (
    <div className="container">
        <h1>Hello {name}</h1>
        <p>You are {age} years old</p>
        <button onClick={onClick}>Click me</button>
    </div>
);

describe('🐛 MyComponent', () => {
    it('🧪 default', () => {
        expect.hasAssertions();
        //☣️ Arrange (всякие моки)
        const onClickSpy = vi.fn();

        //🔥 Act
        const wrapper = shallow(
            <MyComponent name="John" age={30} onClick={onClickSpy} />,
        );

        //❓ Assert
        expect(wrapper.text()).toMatchSnapshot();
    });
    
    it('🧪 button prop onClick', () => {
        expect.hasAssertions();
        //☣️ Arrange (всякие моки)
        const onClickSpy = vi.fn();

        //🔥 Act
        const wrapper = shallow(
            <MyComponent name="John" age={30} onClick={onClickSpy} />,
        );

        //❓ Assert
        expect(wrapper.find('button').prop('onClick')).toBe(onClickSpy);
    });
});

Snapshot Testing

// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html

exports[`🐛 MyComponent > 🧪 default 1`] = `
"<div>
  <h1>
    Hello 
    John
  </h1>
  <p>
    You are 
    30
     years old
  </p>
  <button>
    Click me
  </button>
</div>"
`;

⚡ Performance Comparison

| Operation | Shallowly 🚀 | Enzyme | React Testing Library | | ------------------------ | -----------: |-----------------------------------------------:| --------------------: | | Basic component | 12ms ⚡ | 🔚💀 It is no longer supported or operational. | 85ms (7.1x slower) | | 100 components | 650ms ⚡ | 🔚💀 It is no longer supported or operational. | 4500ms (6.9x slower) | | Hook-heavy component | 18ms ⚡ | 🔚💀 It is no longer supported or operational. | 210ms | | Tree traversal | 8ms ⚡ | 🔚💀 It is no longer supported or operational. | 150ms |

Key takeaways:

• 🏎️ Enzyme 🔚💀 It is no longer supported or operational.
• ⚡ 7x faster than React Testing Library
• 🧠 40% less memory usage compared to Enzyme
• 🌳 Zero DOM - pure React reconciliation

🛠 Perfect For

• ✅ Unit testing React components
• ✅ Migrating from Enzyme
• ✅ Testing complex hooks/context flows
• ✅ CI pipelines (fast execution)

🚫 What Shallowly Is NOT For:

• ❌ End-to-end testing (use Cypress/Playwright)
• ❌ Full integration testing (use RTL)
• ❌ Visual regression testing (use Storybook/Chromatic)

📊 Unit Testing Pyramid

pie
    title Test Distribution
    "Unit (Shallowly)" : 70
    "Integration" : 20
    "E2E" : 10

📚 English Documentation | 🇷🇺 Документация на русском | 🐞 Report Issues

"Saved us 300+ lines of test boilerplate!" - @bad4iz