Testing and Quality

🧪 Testing & Quality Assurance

react-hook-lab takes quality, performance, and cross-environment reliability seriously. The library is thoroughly tested using the native Node.js test runner (node:test and node:assert/strict) along with react-test-renderer and react-dom/server.

There are zero external test runners (no Jest, no Vitest, no Mocha), keeping the development environment lightweight and execution blazing fast.

---

🏗️ 4-Tier Testing Architecture

The test suite consists of 171 automated runtime tests across 92 test files plus 42 dedicated compile-time TypeScript type test files (134 test files in total), divided into four distinct layers:

1. Isolated Unit Tests (tests/unit/)

• 42 test files / 118 tests
• Each hook and utility has its own dedicated *.unit.test.js file.
• Verifies exact edge cases, parameter validations, reactive state setters, mount/unmount memory cleanup, and browser API error handling.

2. Composite Integration Tests (tests/integration/)

• 8 composite scenarios / 8 tests
• Verifies realistic multi-hook workflows operating together in real-world component pipelines:
  • Form autosaving with debounced storage and dirty tracking (useDebounce + useLocalStorage + usePrevious)
  • Session auto-logout on inactivity (useIdle + useSessionStorage + useCookie + useToggle)
  • Bounded rate-limited counter (useCounter + useThrottle + usePrevious)
  • Interactive modal dialogs with click-outside and clipboard copy (useClickOutside + useBoolean + useClipboard)
  • Network reconnection and push notification alerting (useOnlineStatus + useNotifications + useBoolean)
  • Container-aware layout adaptations (useElementSize + useToggle + useDeepMemo)
  • Resilient background polling (useTabVisibility + useInterval + usePrevious)
  • Async fetching with timeouts and retries (useAsync + useTimeout + useCounter)

3. Server-Side Rendering (SSR) & Hydration Tests (tests/ssr/)

• 42 test files / 45 tests
• Every hook and utility is tested in a clean Node.js server environment using renderToString from react-dom/server.
• Zero Browser Globals: Tests execute with window, document, and navigator removed to guarantee that hooks never crash or attempt DOM access during server render.
• Hydration Matching: Validates that initial client render markup matches server output byte-for-byte to prevent React hydration mismatch errors in Next.js (App Router & Pages Router) and Remix.

4. Compile-Time TypeScript Type Tests (tests/types/)

• 42 dedicated type test files (1:1 parity with unit and SSR test suites: tests/types/<hookName>.type.test.ts)
• Powered by zero-runtime compile-time type assertions (Expect<Equal<Actual, Expected>>, Extends<A, B>, NotAny<T>).
• Validates generic parameter inference, exact return interfaces, and negative compiler failure paths using // @ts-expect-error.

---

🏃 Running Tests

Command	Description
npm test	Runs the complete 4-tier test suite (Unit + Integration + SSR + Type Tests)
npm run test:unit	Runs only isolated unit tests
npm run test:integration	Runs only composite multi-hook integration tests
npm run test:ssr	Runs dedicated server-side rendering & hydration tests
npm run test:types	Runs compile-time TypeScript type verification (tsc --project tests/types/tsconfig.json)
npm run validate	Runs full pre-release pipeline (version check, formatting, linting, typechecking, all tests, and build)

---

🛡️ Next.js & SSR Compatibility Guarantee

Every release is tested to ensure:

1. No window is not defined errors during server builds or SSR requests.
2. Clean fallback values during initial render (e.g. useWidth returns 0, useTimezone returns null until hydrated, useIdle returns false).
3. Client effects (useEffect, event listeners, polling timers) remain dormant until the component is mounted in the browser.