From fbdd1c4da1278b92f4a9d661499e76aecece05c3 Mon Sep 17 00:00:00 2001 From: Andrew Beveridge Date: Fri, 26 Dec 2025 01:07:33 -0500 Subject: [PATCH] Add frontend README with testing documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Documents: - Development setup and cloud backend proxy - Authentication configuration - Unit and E2E testing commands - Test architecture and debugging tips - Project structure overview πŸ€– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- frontend/README.md | 145 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 frontend/README.md diff --git a/frontend/README.md b/frontend/README.md new file mode 100644 index 00000000..539e53be --- /dev/null +++ b/frontend/README.md @@ -0,0 +1,145 @@ +# Karaoke Generator Frontend + +Next.js frontend for the Karaoke Generator application. + +## Quick Start + +```bash +# Install dependencies +npm install + +# Run development server +npm run dev +``` + +The app will be available at http://localhost:3000 + +## Development Setup + +### Connecting to the Cloud Backend + +In development, the frontend proxies API requests to the cloud backend (`api.nomadkaraoke.com`) via Next.js rewrites. This avoids CORS issues and allows local development without running a local backend. + +The proxy is configured in `next.config.mjs`: +- All `/api/*` requests are forwarded to the cloud backend +- You can override the backend URL with `BACKEND_URL` environment variable + +### Authentication + +The backend requires authentication. To authenticate: + +1. Create a `.env.local` file in the frontend directory: + ``` + KARAOKE_ACCESS_TOKEN=your-token-here + ``` + +2. The token is automatically loaded by Playwright tests +3. In the browser, the token is stored in `localStorage` as `karaoke_access_token` + +## Testing + +### Unit Tests (Jest) + +```bash +# Run tests in watch mode +npm test + +# Run tests with coverage +npm run test:coverage + +# Run tests in CI mode +npm run test:ci +``` + +### E2E Tests (Playwright) + +E2E tests run against the local dev server connected to the real cloud backend. + +```bash +# Run all E2E tests +npm run test:e2e + +# Run with UI (interactive mode) +npm run test:e2e:ui + +# Run in headed mode (see the browser) +npm run test:e2e:headed + +# Run in debug mode +npm run test:e2e:debug +``` + +#### Authentication for E2E Tests + +E2E tests require a valid access token. Set it in `.env.local`: + +``` +KARAOKE_ACCESS_TOKEN=your-token-here +``` + +The Playwright config (`playwright.config.ts`) automatically loads this file. + +#### Test Structure + +Tests are located in `e2e/`: + +- `karaoke-generation.spec.ts` - Main test suite covering: + - Homepage loading and form display + - Search tab functionality + - Audio search submission + - Audio selection dialog flow + - API health checks + +#### Test Architecture + +``` +β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” +β”‚ Playwright │────▢│ Next.js Dev │────▢│ Cloud Backend β”‚ +β”‚ Browser β”‚ β”‚ Server (:3000) β”‚ β”‚ api.nomadkaraoke β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ + β”‚ + β–Ό + API Proxy + /api/* β†’ backend +``` + +#### Debugging Test Failures + +1. **Screenshots**: Failed tests save screenshots to `test-results/` +2. **Videos**: First retry captures video (when retries enabled) +3. **Traces**: View detailed traces with `npx playwright show-trace ` +4. **HTML Report**: After running tests, view `npx playwright show-report` + +#### Common Issues + +- **401 Unauthorized**: Token missing or invalid - check `.env.local` +- **Socket hang up**: Backend operation taking too long - some operations (like audio download) can take minutes +- **Element outside viewport**: Dialog scrolling issues - tests use JavaScript click to handle this + +## Project Structure + +``` +frontend/ +β”œβ”€β”€ app/ # Next.js app router pages +β”œβ”€β”€ components/ # React components +β”‚ β”œβ”€β”€ ui/ # shadcn/ui components +β”‚ └── audio-search/ # Audio search feature components +β”œβ”€β”€ lib/ # Utilities and API client +β”‚ └── api.ts # Backend API client +β”œβ”€β”€ e2e/ # Playwright E2E tests +β”œβ”€β”€ playwright.config.ts # Playwright configuration +└── next.config.mjs # Next.js configuration +``` + +## Scripts + +| Script | Description | +|--------|-------------| +| `npm run dev` | Start development server | +| `npm run build` | Build for production | +| `npm run start` | Start production server | +| `npm run lint` | Run ESLint | +| `npm test` | Run unit tests (watch mode) | +| `npm run test:ci` | Run unit tests (CI mode with coverage) | +| `npm run test:e2e` | Run E2E tests | +| `npm run test:e2e:ui` | Run E2E tests with interactive UI |