testing

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

# 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):

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:

# 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:

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:

# 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.