1. Context & Goals

This document defines best practices for testing a React SPA built with Vite. The application is UI-focused, API-driven, and optimized for fast rendering of large datasets (inventory-style screens).

==== Goals ====

Align testing with the Vite build ecosystem

Ensure fast, reliable, and deterministic tests

Enable auth token reuse across Unit, Integration, and E2E tests

Support CI/CD quality gates

React + TypeScript + Vite
│
├── Unit Tests → Vitest + React Testing Library
├── Integration Tests → Vitest + RTL + MSW
├── API Contract → MSW
├── Hybrid E2E → Playwright + MSW
└── Full E2E → Playwright (real backend)

==== Example Code Snippets (Vite + Vitest + React) ====

src/app/App.tsx</font>
import { BrowserRouter } from 'react-router-dom';
import RoutesConfig from './routes';

export default function App() {
return (
<BrowserRouter>
<RoutesConfig />
</BrowserRouter>
);
} src/layouts/MainLayout/MainLayout.tsx</font>
import { Outlet } from 'react-router-dom';
import { Header } from '@/components/layout/Header';
import { Footer } from '@/components/layout/Footer';
import { Menu } from '@/components/layout/Navigation';

export const MainLayout = () ⇒ (
<>
<Header />
<Menu />
<main>
<Outlet />
</main>
<Footer />
</>
); src/app/routes.tsx</font>
import { Routes, Route } from 'react-router-dom';
import { MainLayout } from '@/layouts/MainLayout';
import HomePage from '@/pages/Home/HomePage';
import InventoryPage from '@/pages/Inventory/InventoryPage';

export default function RoutesConfig() {
return (
<Routes>
<Route element={<MainLayout />}>
<Route path=“/” element={<HomePage />} />
<Route path=“/inventory” element={<InventoryPage />} />
</Route>
</Routes>
);
} —- ===== 4. Test Classification & Scope ===== ==== 4.1 Unit Tests ==== Purpose: Validate isolated UI logic What to test - Presentational components - Hooks - Utility functions What NOT to test - API calls - Auth flows Tools - Vitest - React Testing Library —- ==== 4.2 Integration Tests ==== Purpose: Validate UI + API interaction What to test - API data rendering - Error states - Token attached to requests Tools - Vitest - RTL - MSW (Mock Service Worker) —- ==== 4.3 API Contract Tests (via MSW) ==== * Validate request headers, query params, payloads * Ensure frontend-backend contract stability —- ==== 4.4 Hybrid E2E Tests ==== Purpose: Fast, stable E2E without backend dependency Characteristics - Real browser (Playwright) - Real authentication token - Business APIs mocked via MSW —- ==== 4.5 Full E2E Tests ==== Purpose: Validate critical production flows * Real backend * Real authentication * Minimal coverage (smoke tests only) —- ===== 5. Authentication Token Strategy (Single Source of Truth) ===== ==== Design Principles ==== * Fetch auth token once * Reuse across all test layers * No hardcoding inside tests ==== Flow ==== Auth Token
│
├─ Generated via Playwright global setup
├─ Stored in env / storageState
├─ Consumed by MSW handlers
└─ Used by Vitest integration tests ==== Benefits ==== * Consistent auth behavior * Faster test execution * Reduced flakiness —- ===== 6. Project Directory Structure ===== The following directory structure is the recommended standard for this React + TypeScript + Vite SPA. It cleanly separates app bootstrapping, layouts, pages, features, services, and tests, and scales well for large inventory-style applications. src/
├── app/
│ ├── App.tsx
│ ├── routes.tsx
│ └── providers.tsx
│
├── layouts/
│ └── MainLayout/
│ ├── MainLayout.tsx
│ └── index.ts
│
├── components/
│ ├── layout/
│ │ ├── Header/
│ │ │ ├── Header.tsx
│ │ │ └── index.ts
│ │ ├── Footer/
│ │ │ ├── Footer.tsx
│ │ │ └── index.ts
│ │ └── Navigation/
│ │ ├── Menu.tsx
│ │ └── index.ts
│ │
│ └── common/
│ ├── Button/
│ ├── Input/
│ ├── Loader/
│ └── Modal/
│
├── pages/
│ ├── Home/
│ │ ├── HomePage.tsx
│ │ └── index.ts
│ │
│ ├── Inventory/
│ │ ├── InventoryPage.tsx
│ │ ├── InventoryTable.tsx
│ │ └── index.ts
│ │
│ └── NotFound/
│ └── NotFoundPage.tsx
│
├── features/
│ └── inventory/
│ ├── components/
│ ├── hooks/
│ ├── services/
│ └── types.ts
│
├── services/
│ ├── apiClient.ts
│ └── inventoryService.ts
│
├── hooks/
│ └── useDebounce.ts
│
├── types/
│ └── common.types.ts
│
├── utils/
│ └── formatters.ts
│
├── styles/
│ └── global.css
│
├── tests/
│ ├── unit/
│ ├── integration/
│ └── msw/
│
├── main.tsx
└── vite-env.d.ts ==== Structural Guidelines ==== * app/ – Application bootstrap, routing, and providers * layouts/ – Shared page layouts (Header, Footer, Navigation) * components/ – Reusable UI components * pages/ – Route-level components * features/ – Feature-scoped logic for scalability * services/ – API and backend interaction layer * tests/ – Unit, integration, and MSW setup —- ===== 7. CI/CD Best Practices ===== ==== Pipeline Order ==== - Lint + Type Check - Unit Tests (Vitest) - Integration Tests (Vitest + MSW) - Hybrid E2E (Playwright) - Optional Full E2E (nightly) ==== Failure Handling ==== * Fail pipeline on any test failure * Upload Playwright traces/screenshots * Publish test reports —- ===== 8. Performance Considerations ===== * Prefer client-side rendering (SPA) * Use virtualization for large datasets * Avoid SSR unless SEO is required * Testing should not depend on real backend performance —- ===== 10. Tooling Configuration (Vitest + RTL) ===== ==== Vitest Configuration ==== CKGE_TMP_i vitest.config.ts CKGE_TMP_i
import { defineConfig } from 'vitest/config' ;
import react from '@vitejs/plugin-react' ;

export default defineConfig ({
plugins : [ react ()] ,
test : {
environment : 'jsdom' ,
setupFiles : './src/tests/setupTests.ts' ,
globals : true ,
css : true ,
coverage : {
reporter : [ 'text' , 'html' ] ,
} ,
} ,
}) ; ==== <font 14pt/Aptos,sans-serif;;#0f4761;;inherit>Test Setup ==== CKGE_TMP_i src/tests/setupTests.ts CKGE_TMP_i</font>
import '@testing-library/jest-dom' ; —- ===== 11. Unit Test Example (Vitest + RTL) ===== src/tests/unit/Header.test.tsx</font>
import { render, screen } from '@testing-library/react';
import { describe, it, expect } from 'vitest';
import { Header } from '@/components/layout/Header';

describe('Header', () ⇒ {
it('renders application title', () ⇒ {
render(<Header />);
expect(screen.getByText(/inventory/i)).toBeInTheDocument();
});
}); —- ===== 12. Integration Test Example (Vitest + RTL + MSW) ===== ==== MSW Handler ==== CKGE_TMP_i src/tests/msw/handlers.ts CKGE_TMP_i
import { rest } from 'msw' ;

export const handlers = [
rest . get ( '/api/inventory' , (req , res , ctx) ⇒ {
const token = req . headers . get ( 'Authorization' ) ;
if ( ! token) return res (ctx . status ( 401 )) ;

return res (
ctx . status ( 200 ) ,
ctx . json ([{ id : 1 , name : 'Item A' }])
) ;
}) ,
] ; ==== <font 14pt/Aptos,sans-serif;;#0f4761;;inherit>MSW Server Setup ==== CKGE_TMP_i src/tests/msw/server.ts CKGE_TMP_i</font>
import { setupServer } from 'msw/node' ;
import { handlers } from './handlers' ;

export const server = setupServer ( … handlers) ; CKGE_TMP_i src/tests/setupTests.ts CKGE_TMP_i</font>
import '@testing-library/jest-dom' ;
import { server } from './msw/server' ;

beforeAll ¹⁾