kb-testing-nextjs

What problem does it solve?

It solves brittle and flaky unit/component tests in Next.js by standardizing mock, query, and assertion patterns for Vitest and React Testing Library.

Core Features & Use Cases

• Hoist-safe factory mocks: Prevent Vitest hoisting ReferenceErrors by declaring mocks outside vi.mock() factories and binding them at call time.
• Behavior-first RTL queries: Apply a consistent DOM query priority using roles and labels, reserving getByTestId as a last resort.
• Chainable thenable mocks for query builders: Mock fluent Drizzle-style builders with a thenable chain that resolves when awaited.
• ActionResult-shape assertions: Verify discriminated { data } | { error }-style results by checking return shape instead of expecting throws.
• Interaction realism: Use userEvent.setup() to drive clicks and form interactions in a way that matches real browser behavior.

Quick Start

Use the kb-testing-nextjs guidelines to write a Next.js Vitest unit test for an action or component by mocking dependencies with hoist-safe vi.mock factories, rendering with RTL, interacting via userEvent.setup(), and asserting on observable output shapes rather than caught exceptions.