@arcadialdev/arcality 2.4.28 → 2.4.30

package/.agents/skills/playwright-best-practices/frameworks/nextjs.md

@@ -1,469 +0,0 @@
-# Next.js Testing Patterns
-
-## Table of Contents
-
-1. [Setup](#setup)
-2. [App Router Patterns](#app-router-patterns)
-3. [Pages Router Patterns](#pages-router-patterns)
-4. [Dynamic Routes](#dynamic-routes)
-5. [API Routes](#api-routes)
-6. [Middleware Testing](#middleware-testing)
-7. [Hydration Testing](#hydration-testing)
-8. [next/image Testing](#nextimage-testing)
-9. [NextAuth.js Authentication](#nextauthjs-authentication)
-10. [Tips](#tips)
-11. [Anti-Patterns](#anti-patterns)
-12. [Related](#related)
-
-> **When to use**: Testing Next.js applications with App Router, Pages Router, API routes, middleware, SSR, dynamic routes, and server components.
-> **Prerequisites**: [configuration.md](../core/configuration.md), [locators.md](../core/locators.md)
-
-## Setup
-
-### Configuration with webServer
-
-```typescript
-// playwright.config.ts
-import { defineConfig, devices } from '@playwright/test';
-
-export default defineConfig({
-  testDir: './tests',
-  fullyParallel: true,
-  forbidOnly: !!process.env.CI,
-  retries: process.env.CI ? 2 : 0,
-  workers: process.env.CI ? '50%' : undefined,
-
-  use: {
-    baseURL: 'http://localhost:3000',
-    trace: 'on-first-retry',
-    screenshot: 'only-on-failure',
-  },
-
-  projects: [
-    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
-    { name: 'mobile', use: { ...devices['iPhone 14'] } },
-  ],
-
-  webServer: {
-    command: process.env.CI
-      ? 'npm run build && npm run start'
-      : 'npm run dev',
-    url: 'http://localhost:3000',
-    reuseExistingServer: !process.env.CI,
-    timeout: 120_000,
-    env: {
-      NODE_ENV: process.env.CI ? 'production' : 'test',
-    },
-  },
-});
-```
-
-### Environment Variables
-
-Next.js loads `.env.test` when `NODE_ENV=test`:
-
-```bash
-# .env.test (commit this)
-NEXT_PUBLIC_API_URL=http://localhost:3000/api
-DATABASE_URL=postgresql://localhost:5432/test_db
-
-# .env.test.local (gitignored)
-NEXTAUTH_SECRET=test-secret-local
-```
-
-## App Router Patterns
-
-### Server Component Content
-
-```typescript
-test('renders server component content', async ({ page }) => {
-  await page.goto('/');
-
-  await expect(page.getByRole('heading', { name: 'Welcome', level: 1 })).toBeVisible();
-  await expect(page.getByRole('navigation', { name: 'Main' })).toBeVisible();
-});
-```
-
-### Loading States with Streaming
-
-```typescript
-test('loading state during data streaming', async ({ page }) => {
-  await page.route('**/api/stats', async (route) => {
-    await new Promise((r) => setTimeout(r, 2000));
-    await route.continue();
-  });
-
-  await page.goto('/dashboard');
-
-  await expect(page.getByRole('progressbar')).toBeVisible();
-  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
-  await expect(page.getByRole('progressbar')).toBeHidden();
-});
-```
-
-### Nested Layouts
-
-```typescript
-test('layouts persist across navigation', async ({ page }) => {
-  await page.goto('/dashboard/analytics');
-
-  const sidebar = page.getByRole('navigation', { name: 'Dashboard' });
-  await expect(sidebar).toBeVisible();
-
-  await sidebar.getByRole('link', { name: 'Settings' }).click();
-  await page.waitForURL('/dashboard/settings');
-
-  await expect(sidebar).toBeVisible();
-  await expect(page.getByRole('heading', { name: 'Settings' })).toBeVisible();
-});
-```
-
-## Pages Router Patterns
-
-### SSR with getServerSideProps
-
-```typescript
-test('page with getServerSideProps renders data', async ({ page }) => {
-  await page.goto('/blog');
-
-  await expect(page.getByRole('heading', { name: 'Blog', level: 1 })).toBeVisible();
-  await expect(page.getByRole('article')).toHaveCount(10);
-  await expect(page.getByRole('article').first()).toContainText(/\w+/);
-});
-```
-
-### Static Generation with getStaticProps
-
-```typescript
-test('static page shows pre-rendered content', async ({ page }) => {
-  await page.goto('/about');
-
-  await expect(page.getByRole('heading', { name: 'About Us' })).toBeVisible();
-  await expect(page.getByText('Founded in 2020')).toBeVisible();
-});
-```
-
-## Dynamic Routes
-
-### Slug Parameters
-
-```typescript
-test('dynamic [slug] renders correct content', async ({ page }) => {
-  await page.goto('/blog/testing-guide');
-
-  await expect(page.getByRole('heading', { level: 1 })).toContainText('Testing Guide');
-  await expect(page.getByText('Page not found')).toBeHidden();
-});
-
-test('non-existent slug shows 404', async ({ page }) => {
-  const response = await page.goto('/blog/nonexistent-post');
-
-  expect(response?.status()).toBe(404);
-  await expect(page.getByRole('heading', { name: '404' })).toBeVisible();
-});
-```
-
-### Catch-All Routes
-
-```typescript
-test('catch-all handles nested paths', async ({ page }) => {
-  await page.goto('/docs/getting-started/installation');
-  await expect(page.getByRole('heading', { name: 'Installation' })).toBeVisible();
-
-  await page.goto('/docs/api/configuration');
-  await expect(page.getByRole('heading', { name: 'Configuration' })).toBeVisible();
-});
-```
-
-### Query Parameters
-
-```typescript
-test('query parameters filter content', async ({ page }) => {
-  await page.goto('/products?category=electronics&sort=price-asc');
-
-  await expect(page.getByRole('heading', { name: 'Electronics' })).toBeVisible();
-
-  const prices = await page.getByTestId('product-price').allTextContents();
-  const numericPrices = prices.map((p) => parseFloat(p.replace('$', '')));
-  expect(numericPrices).toEqual([...numericPrices].sort((a, b) => a - b));
-});
-```
-
-## API Routes
-
-### Direct API Testing
-
-```typescript
-test('GET /api/products returns list', async ({ request }) => {
-  const response = await request.get('/api/products');
-
-  expect(response.ok()).toBeTruthy();
-  const body = await response.json();
-  expect(body.products).toBeInstanceOf(Array);
-  expect(body.products[0]).toHaveProperty('id');
-  expect(body.products[0]).toHaveProperty('name');
-});
-
-test('POST /api/products creates item', async ({ request }) => {
-  const response = await request.post('/api/products', {
-    data: { name: 'Test Product', price: 29.99 },
-  });
-
-  expect(response.status()).toBe(201);
-  const body = await response.json();
-  expect(body.product.name).toBe('Test Product');
-});
-
-test('POST /api/products validates fields', async ({ request }) => {
-  const response = await request.post('/api/products', {
-    data: { name: '' },
-  });
-
-  expect(response.status()).toBe(400);
-  const body = await response.json();
-  expect(body.error).toContainEqual(expect.objectContaining({ field: 'price' }));
-});
-```
-
-### API Through UI
-
-```typescript
-test('form submission calls API', async ({ page }) => {
-  await page.goto('/products/new');
-
-  await page.getByLabel('Product name').fill('Widget');
-  await page.getByLabel('Price').fill('19.99');
-  await page.getByRole('button', { name: 'Create product' }).click();
-
-  await expect(page.getByText('Product created successfully')).toBeVisible();
-  await page.waitForURL('/products/**');
-});
-```
-
-## Middleware Testing
-
-### Auth Redirects
-
-```typescript
-test('unauthenticated user redirected to login', async ({ page }) => {
-  await page.goto('/dashboard');
-
-  expect(page.url()).toContain('/login');
-  await expect(page.getByRole('heading', { name: 'Sign in' })).toBeVisible();
-});
-
-test('redirect preserves return URL', async ({ page }) => {
-  await page.goto('/dashboard/settings');
-
-  const url = new URL(page.url());
-  expect(url.pathname).toBe('/login');
-  expect(url.searchParams.get('callbackUrl') || url.searchParams.get('returnTo'))
-    .toContain('/dashboard/settings');
-});
-```
-
-### Security Headers
-
-```typescript
-test('middleware sets security headers', async ({ page }) => {
-  const response = await page.goto('/');
-
-  const headers = response!.headers();
-  expect(headers['x-frame-options']).toBe('DENY');
-  expect(headers['x-content-type-options']).toBe('nosniff');
-});
-```
-
-### Locale Rewrites
-
-```typescript
-test('middleware rewrites based on locale', async ({ page, context }) => {
-  await context.setExtraHTTPHeaders({
-    'Accept-Language': 'fr-FR,fr;q=0.9',
-  });
-
-  await page.goto('/');
-
-  await expect(page.getByText('Bienvenue')).toBeVisible();
-});
-```
-
-## Hydration Testing
-
-### Console Error Detection
-
-```typescript
-test('no hydration errors in console', async ({ page }) => {
-  const consoleErrors: string[] = [];
-  page.on('console', (msg) => {
-    if (msg.type() === 'error') {
-      consoleErrors.push(msg.text());
-    }
-  });
-
-  await page.goto('/');
-  await page.getByRole('button', { name: 'Get started' }).click();
-
-  const hydrationErrors = consoleErrors.filter(
-    (e) =>
-      e.includes('Hydration') ||
-      e.includes('hydration') ||
-      e.includes('did not match')
-  );
-  expect(hydrationErrors).toEqual([]);
-});
-```
-
-### Interactive Elements After Hydration
-
-```typescript
-test('interactive elements work after hydration', async ({ page }) => {
-  await page.goto('/');
-
-  const counter = page.getByTestId('counter-value');
-  await expect(counter).toHaveText('0');
-
-  await page.getByRole('button', { name: 'Increment' }).click();
-  await expect(counter).toHaveText('1');
-});
-```
-
-## next/image Testing
-
-```typescript
-test('hero image loads with srcset', async ({ page }) => {
-  await page.goto('/');
-
-  const heroImage = page.getByRole('img', { name: 'Hero banner' });
-  await expect(heroImage).toBeVisible();
-
-  const srcset = await heroImage.getAttribute('srcset');
-  expect(srcset).toBeTruthy();
-  expect(srcset).toContain('w=');
-
-  const loading = await heroImage.getAttribute('loading');
-  expect(loading).not.toBe('lazy');
-});
-
-test('offscreen images lazy load', async ({ page }) => {
-  await page.goto('/gallery');
-
-  const offscreenImage = page.getByRole('img', { name: 'Gallery item 20' });
-
-  await offscreenImage.scrollIntoViewIfNeeded();
-  await expect(offscreenImage).toBeVisible();
-
-  const naturalWidth = await offscreenImage.evaluate(
-    (img: HTMLImageElement) => img.naturalWidth
-  );
-  expect(naturalWidth).toBeGreaterThan(0);
-});
-```
-
-## NextAuth.js Authentication
-
-### Setup Project
-
-```typescript
-// playwright.config.ts
-export default defineConfig({
-  projects: [
-    { name: 'setup', testMatch: /auth\.setup\.ts/ },
-    {
-      name: 'authenticated',
-      use: { storageState: 'playwright/.auth/user.json' },
-      dependencies: ['setup'],
-    },
-    { name: 'unauthenticated', testMatch: '**/*.unauth.spec.ts' },
-  ],
-});
-```
-
-### Auth Setup
-
-```typescript
-// tests/auth.setup.ts
-import { test as setup, expect } from '@playwright/test';
-
-const authFile = 'playwright/.auth/user.json';
-
-setup('authenticate via credentials', async ({ page }) => {
-  await page.goto('/login');
-  await page.getByLabel('Email').fill('test@example.com');
-  await page.getByLabel('Password').fill(process.env.TEST_PASSWORD!);
-  await page.getByRole('button', { name: 'Sign in' }).click();
-
-  await page.waitForURL('/dashboard');
-  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
-
-  await page.context().storageState({ path: authFile });
-});
-```
-
-### Authenticated Tests
-
-```typescript
-test('authenticated user sees dashboard', async ({ page }) => {
-  await page.goto('/dashboard');
-
-  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
-  await expect(page.getByText('test@example.com')).toBeVisible();
-});
-```
-
-## Tips
-
-### Dev Server vs Production Build
-
-| Scenario | Command | Trade-off |
-|---|---|---|
-| Local development | `npm run dev` | Fast iteration, no production behavior |
-| CI pipeline | `npm run build && npm run start` | Tests real production bundle |
-
-### Turbopack
-
-```typescript
-webServer: {
-  command: process.env.CI
-    ? 'npm run build && npm run start'
-    : 'npx next dev --turbopack',
-  url: 'http://localhost:3000',
-  reuseExistingServer: !process.env.CI,
-},
-```
-
-### Multiple webServer Entries
-
-```typescript
-webServer: [
-  {
-    command: 'npm run dev:api',
-    url: 'http://localhost:4000/health',
-    reuseExistingServer: !process.env.CI,
-  },
-  {
-    command: 'npm run dev',
-    url: 'http://localhost:3000',
-    reuseExistingServer: !process.env.CI,
-  },
-],
-```
-
-## Anti-Patterns
-
-| Don't Do This | Problem | Do This Instead |
-|---|---|---|
-| `await page.waitForTimeout(3000)` | Arbitrary waits are fragile | `await page.waitForURL('/path')` or `await expect(locator).toBeVisible()` |
-| Test `getServerSideProps` directly | Depends on req/res context | Navigate to page and verify rendered output |
-| Mock your own API routes | Hides real API bugs | Let real API handle requests; mock only external services |
-| `page.goto('http://localhost:3000/path')` | Breaks when port changes | Use `page.goto('/path')` with `baseURL` |
-| Run `npm run build` locally for every test | Extremely slow | Use `npm run dev` locally with `reuseExistingServer: true` |
-| Test `next/image` by checking exact URLs | Paths change between dev/prod | Assert on `alt`, visibility, `naturalWidth > 0`, `srcset` |
-| Test server actions by calling as functions | Server actions need Next.js runtime | Trigger through UI (forms, buttons) |
-
-## Related
-
-- [configuration.md](../core/configuration.md) -- Playwright configuration including `webServer`
-- [authentication.md](../advanced/authentication.md) -- authentication setup and `storageState`
-- [api-testing.md](../testing-patterns/api-testing.md) -- testing API routes with `request` context
-- [react.md](react.md) -- React patterns for Next.js client components