Testing Strategy

Reliable Foundations: The Testing Strategy

The Next.js Boilerplate is engineered with a "test-first" philosophy to ensure your application remains stable as it scales. By integrating industry-standard tools for unit, integration, and end-to-end testing, the boilerplate provides a safety net that catches regressions before they reach your users.

Unit and Integration Testing with Vitest

For rapid feedback during development, the boilerplate utilizes Vitest paired with React Testing Library. Vitest offers a blazing-fast execution environment compatible with the Vite ecosystem, while React Testing Library ensures your tests focus on user behavior rather than implementation details.

• Fast Feedback Loops: Execution is significantly faster than traditional Jest setups, allowing for instantaneous validation of logic changes.
• User-Centric Validation: Components are tested based on how users interact with them, ensuring accessibility and functional correctness.
• Built-in Coverage: Easily monitor how much of your codebase is protected by automated tests.

Usage:

# Run all unit tests
npm run test

# Run tests in watch mode during development
npm run test:watch

End-to-End (E2E) Testing with Playwright

To validate complete user journeys—from authentication via Clerk to database mutations with DrizzleORM—the boilerplate includes Playwright. This ensures your application works across different browsers and mobile viewports.

Isolated Testing Environments

A standout feature of this boilerplate is its approach to database isolation during E2E tests. By utilizing the x-e2e-random-id header in API routes, the system can isolate requests and database records for specific test runs. This prevents parallel tests from interfering with each other's data.

Key Benefits:

• Multi-Browser Support: Test your app on Chromium, Firefox, and WebKit simultaneously.
• Visual Regression: Capture screenshots and videos of failed tests to debug UI inconsistencies.
• Database Safety: Use isolated IDs to perform CRUD operations without polluting your development or staging data.

Usage:

# Run E2E tests
npm run test:e2e

# Open Playwright UI for interactive debugging
npx playwright show-report

Component Development with Storybook

UI components are developed in isolation using Storybook. This allows you to build and document your design system without worrying about the application's complex business logic or data dependencies.

• Visual Documentation: View all component states (loading, error, success) in a single dashboard.
• Accessibility (a11y) Testing: Built-in accessibility addons help identify contrast issues or missing ARIA labels during the design phase.
• App Router Support: Pre-configured to work with Next.js App Router features, including React Server Components (RSC) support.

Usage:

# Start the Storybook development server
npm run storybook

# Build Storybook for static hosting
npm run build-storybook

Automated Quality Gates

Maintaining high code quality is enforced automatically through a series of pre-configured tools that act as "gatekeepers" for your repository.

• Lefthook & Git Hooks: Replaces Husky to provide faster execution of linting (ESLint), formatting (Prettier), and type-checking (TypeScript) before every commit.
• AI-Powered Code Reviews: Integrated with CodeRabbit, the boilerplate provides automated, context-aware feedback on your Pull Requests, catching logic flaws that static analysis might miss.
• Monitoring as Code: Integration with Checkly allows you to transform your Playwright tests into production monitors, ensuring your site is up and functional 24/7.

Continuous Integration (CI)

The boilerplate includes a pre-configured GitHub Actions workflow that runs your entire testing suite on every push. This ensures that:

1. Code is properly formatted and linted.
2. All unit tests pass.
3. E2E flows (Sign-in, Dashboard access, etc.) are fully functional.
4. Type safety is maintained across the entire project.