Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cloudflare/vinext/llms.txt

Use this file to discover all available pages before exploring further.

vinext has a comprehensive test suite covering unit tests, integration tests, and end-to-end browser tests.

​
Running Tests

pnpm test             # Vitest unit + integration tests
pnpm run test:e2e     # Playwright E2E tests (5 projects)
pnpm run typecheck    # TypeScript checking (tsgo)
pnpm run lint         # Linting (oxlint)

​
Test Structure

​
Unit and Integration Tests

Unit and integration tests are written using Vitest and live in the tests/ directory. 
tests/
  *.test.ts             # Vitest unit + integration tests
  nextjs-compat/        # Tests ported from Next.js test suite
  fixtures/             # Test apps (pages-basic, app-basic, ecosystem libs)
Unit tests go in tests/*.test.ts. When adding new functionality, always add corresponding test cases.

​
E2E Tests

Browser-level tests are written using Playwright and live in the tests/e2e/ directory. 
pnpm run test:e2e     # Playwright E2E tests (5 projects)
E2E tests cover:
  • Pages Router (dev + production)
  • App Router (dev)
  • Both routers on Cloudflare Workers via wrangler dev
Browser-level tests go in tests/e2e/. These are essential for catching subtle browser issues that unit tests miss — rendered output, client-side navigation, hydration behavior, etc.

​
Test Fixtures

Test fixtures are minimal Next.js applications used for integration testing:
  • tests/fixtures/pages-basic/ — Pages Router test app
  • tests/fixtures/app-basic/ — App Router test app
  • examples/app-router-cloudflare/ — App Router on Workers
  • examples/pages-router-cloudflare/ — Pages Router on Workers
Add new test pages to fixtures, not to examples. Examples are for user-facing demos.

​
Integration Tests

The Vercel App Router Playground runs on vinext as an integration test. See it live at app-router-playground.vinext.workers.dev.

​
Test Coverage

The test suite includes: Test coverage includes:
  • Routing (file-system routing, dynamic routes, catch-all, route groups)
  • SSR and RSC rendering
  • Server actions
  • Caching (ISR, "use cache", fetch cache)
  • Metadata generation
  • Middleware execution
  • Streaming SSR
  • Client-side navigation and hydration
See tests/nextjs-compat/TRACKING.md for detailed compatibility tracking.

​
Debugging Tests

For browser-level debugging, we recommend agent-browser. It’s effective at verifying:
  • Rendered output
  • Client-side navigation
  • Hydration behavior
  • Interactive component behavior
Unit tests miss a lot of subtle browser issues. agent-browser has been effective at catching them throughout this project.

​
Writing Tests

When adding new functionality:
  1. Add tests first — put test cases in the appropriate tests/*.test.ts file
  2. Add fixture pages if needed — create test pages in tests/fixtures/ for integration testing
  3. Run the full test suite before committing — ensure all tests pass
  4. Add E2E tests for UI behavior — if the feature affects browser behavior, add Playwright tests

​
Smoke Tests

scripts/smoke-test.sh is a lightweight post-deploy check that curls every deployed example and verifies HTTP 200 + expected content. It runs automatically in CI after the deploy job completes. 
./scripts/smoke-test.sh                    # check production URLs
./scripts/smoke-test.sh --preview pr-42    # check PR preview URLs
When adding a new example, always add a corresponding smoke test entry. The format is: 
"worker-name  /path  expected-text"
where expected-text is a case-insensitive string that must appear in the response body.

Build docs developers (and LLMs) love

Get started for freeTalk to us