Feat: repo cleanup + test suite restructuring + extending docs

.cursor/skills/testing/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: testing
+description: >-
+  Run tests and add Next.js version coverage for the cache handler. Use when
+  running tests, adding a new Next.js version to the test matrix, creating test
+  apps, or debugging CI failures.
+---
+
+# Testing
+
+## Running Tests
+
+```bash
+# Unit tests (fast, no Redis needed)
+pnpm test:unit
+pnpm test:unit:watch          # watch mode
+pnpm test:unit:coverage       # with coverage
+
+# Integration tests (needs Redis + pre-built Next.js app)
+pnpm test:integration
+pnpm test:integration:build-id-prefix
+pnpm test:integration:cache-components
+
+# E2E / Playwright for cached components (needs Redis, auto-starts Next.js app)
+pnpm test:e2e
+```
+
+## Test Structure
+
+```
+test/
+├── playwright/              # E2E (Playwright browser tests)
+├── vitest/
+│   ├── unit/                # Unit tests (no external deps)
+│   └── integration/         # Integration tests (Redis + Next.js)
+│       └── cache-components/
+└── nextjs-test-projects/    # Shared Next.js app fixtures
+```
+
+For details on each layer, see `test/README.md`.
+
+## Adding a New Next.js Version
+
+### 1. Standard Integration Test App
+
+For testing the core cache handler against a new Next.js version (e.g. 16.5.0):
+
+```bash
+cp -r test/nextjs-test-projects/next-app-16-2-6 test/nextjs-test-projects/next-app-16-5-0
+rm -rf test/nextjs-test-projects/next-app-16-5-0/{node_modules,.next,pnpm-lock.yaml}
+```
+
+Edit `test/nextjs-test-projects/next-app-16-5-0/package.json`:
+
+- Change `"name"` to `"next-app-16-5-0"`
+- Change `"next"` version to `"16.5.0"`
+- Change `"eslint-config-next"` version to `"16.5.0"`
+
+Then add the app to the CI integration matrix in `.github/workflows/ci.yml`:
+
+```yaml
+# In the `integration` job → strategy.matrix.next-test-app
+- next-app-16-5-0
+```
+
+### 2. Cache Components Test App (Next.js 16+ only)
+
+If the new version supports `use cache` / `cacheTag` / `cacheLife`:
+
+```bash
+cp -r test/nextjs-test-projects/next-app-16-2-6-cache-components test/nextjs-test-projects/next-app-16-5-0-cache-components
+rm -rf test/nextjs-test-projects/next-app-16-5-0-cache-components/{node_modules,.next,pnpm-lock.yaml}
+```
+
+Edit the `package.json`:
+
+- Change `"name"` to `"next-app-16-5-0-cache-components"`
+- Change `"next"` to `"16.5.0"`
+- Change `"eslint-config-next"` to `"16.5.0"`
+
+Then add it to both CI matrix jobs in `.github/workflows/ci.yml`:
+
+```yaml
+# In `integration-cache-components` → strategy.matrix.cache-components-app
+- next-app-16-5-0-cache-components
+
+# In `e2e` → strategy.matrix.cache-components-app
+- next-app-16-5-0-cache-components
+```
+
+### 3. Checklist After Adding
+
+- [ ] `package.json` has correct Next.js version + matching `eslint-config-next`
+- [ ] `"@trieb.work/nextjs-turbo-redis-cache": "file:../../../"` path is correct
+- [ ] No leftover `node_modules/`, `.next/`, or `pnpm-lock.yaml` from the copy
+- [ ] CI matrix updated (integration and/or cache-components + e2e)
+- [ ] `test/README.md` → "Next.js Test Projects" table updated
+- [ ] Run `cd test/nextjs-test-projects/next-app-16-5-0 && pnpm install && pnpm build` to verify it builds
+
+### 4. Removing a Version
+
+Remove the folder, remove it from the CI matrix entries, and update `test/README.md`.
+
+## Environment Variables
+
+| Variable               | Default                            | Purpose                                   |
+| ---------------------- | ---------------------------------- | ----------------------------------------- |
+| `NEXT_TEST_APP`        | `next-app-15-4-11`                 | Which app for `pnpm test:integration`     |
+| `CACHE_COMPONENTS_APP` | `next-app-16-2-6-cache-components` | Which app for cache-components tests      |
+| `PLAYWRIGHT_TEST_APP`  | `next-app-16-2-6-cache-components` | Which app Playwright starts               |
+| `PLAYWRIGHT_BASE_URL`  | `http://localhost:3101`            | Override to use an already-running server |
+| `SKIP_BUILD`           | —                                  | Skip Next.js build in integration tests   |
+| `DEBUG_INTEGRATION`    | —                                  | Print child process output                |
+
+## Writing New Tests
+
+- **Unit tests**: Add `*.test.ts` in `test/vitest/unit/`. No Redis, no Next.js. Use mocks.
+- **Integration tests**: Add `*.test.ts` in `test/vitest/integration/`. Spawn Next.js, use `fetch()`, check Redis.
+- **E2E tests**: Add `*.spec.ts` in `test/playwright/`. Use Playwright browser automation.
+
+Unit tests use `.test.ts` extension. Playwright tests use `.spec.ts` extension.