feat: migrate from Vitest browser mode to Playwright for E2E testing

- Replace @vitest/browser-playwright with @playwright/test for E2E tests
- Add playwright.config.ts with base configuration and test directory
- Add test:e2e npm script for running Playwright tests
- Create new Playwright test for updateTag Server Action functionality
- Add update-tag-test page to Next.js 16 test app for E2E testing
- Disable Vitest browser mode in vitest.browser.config.ts
- Add type annotations to integration

Author: JannikZed

package.json

@@ -19,7 +19,8 @@
     "test:unit": "vitest --config vite.config.ts src/**/*.test.ts src/**/*.test.tsx",
     "test:integration": "vitest --config vite.config.ts ./test/integration/nextjs-cache-handler.integration.test.ts",
     "prepare": "./scripts/prepare.sh",
-    "test:browser": "vitest --config=vitest.browser.config.ts"
+    "test:browser": "vitest --config=vitest.browser.config.ts",
+    "test:e2e": "playwright test"
   },
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -69,13 +70,13 @@
   "devDependencies": {
     "@commitlint/cli": "^19.6.0",
     "@commitlint/config-conventional": "^19.6.0",
+    "@playwright/test": "^1.56.1",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/github": "^11.0.1",
     "@semantic-release/npm": "^12.0.1",
     "@typescript-eslint/eslint-plugin": "^8.15.0",
     "@typescript-eslint/parser": "^8.15.0",
-    "@vitest/browser-playwright": "^4.0.13",
     "@vitest/coverage-v8": "^4.0.13",
     "@vitest/ui": "^4.0.13",
     "eslint": "^9.15.0",

playwright.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: 'tests',
+  use: {
+    baseURL: process.env.PLAYWRIGHT_BASE_URL || 'http://localhost:3000',
+    trace: 'on-first-retry',
+  },
+});

pnpm-lock.yaml

@@ -0,0 +1,4 @@
+{
+  "status": "passed",
+  "failedTests": []
+}

test-results/.last-run.json

@@ -0,0 +1,41 @@
+import { test, expect } from 'vitest';
+
+// Base URL of the running Next 16 app.
+// Start it separately, e.g.:
+//   cd test/integration/next-app-16-0-3 && pnpm dev
+// and ensure it listens on the same origin as below.
+const BASE_URL =
+  (globalThis as any).NEXT_BROWSER_BASE_URL || 'http://localhost:3000';
+
+// This test exercises a real Server Action that calls updateTag.
+// It does not assert Redis state, but it verifies that calling the
+// server action endpoint does not trigger the "Server Action only" error.
+
+test('Server Action calling updateTag responds without server-action-only error', async () => {
+  // 1) Fetch the SSR HTML for the page containing the Server Action form
+  const res = await fetch(`${BASE_URL}/update-tag-test`);
+  expect(res.status).toBeLessThan(500);
+  const html = await res.text();
+
+  // 2) Parse the HTML to find the form action URL that Next generated
+  const parser = new DOMParser();
+  const doc = parser.parseFromString(html, 'text/html');
+  const form = doc.querySelector('form');
+  expect(form).not.toBeNull();
+
+  const actionAttr = form!.getAttribute('action');
+  expect(actionAttr).toBeTruthy();
+
+  const actionUrl = new URL(actionAttr!, BASE_URL).toString();
+
+  // 3) Call the Server Action endpoint directly.
+  //    If updateTag were not allowed here, Next.js would respond with
+  //    an error page that contains the specific error message.
+  const actionRes = await fetch(actionUrl, { method: 'POST' });
+  const actionText = await actionRes.text();
+
+  expect(actionRes.status).toBeLessThan(500);
+  expect(actionText).not.toContain(
+    'updateTag can only be called from within a Server Action',
+  );
+});

test/browser/update-tag.browser.test.ts

@@ -0,0 +1,25 @@
+import { updateTag } from 'next/cache';
+
+export const dynamic = 'force-dynamic';
+
+let clicks = 0;
+
+async function increment() {
+  'use server';
+
+  // Simulate a mutation and call updateTag with a test tag
+  clicks++;
+  updateTag('update-tag-test');
+}
+
+export default function UpdateTagTestPage() {
+  return (
+    <main style={{ padding: 40, fontFamily: 'system-ui, sans-serif' }}>
+      <h1>UpdateTag Test</h1>
+      <form action={increment}>
+        <p data-testid="clicks">Clicks: {clicks}</p>
+        <button type="submit">Increment</button>
+      </form>
+    </main>
+  );
+}

test/integration/next-app-16-0-3/src/app/update-tag-test/page.tsx

@@ -1,5 +1,5 @@
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { spawn } from 'child_process';
+import { ChildProcessWithoutNullStreams, spawn } from 'child_process';
 import fetch from 'node-fetch';
 import { createClient, RedisClientType } from 'redis';
 import { join } from 'path';
@@ -16,7 +16,7 @@ const NEXT_START_URL = `http://localhost:${NEXT_START_PORT}`;
 
 const REDIS_BACKGROUND_SYNC_DELAY = 250; //ms delay to prevent flaky tests in slow CI environments
 
-let nextProcess;
+let nextProcess: ChildProcessWithoutNullStreams;
 let redisClient: RedisClientType;
 
 async function delay(ms: number) {
@@ -167,9 +167,9 @@ describe('Next.js Turbo Redis Cache Integration', () => {
         expect(keys.length).toBeGreaterThan(0);
 
         // check the content of redis key
-        const value = await redisClient.get(
+        const value = (await redisClient.get(
           process.env.VERCEL_URL + '/api/cached-static-fetch',
-        );
+        )) as string;
         expect(value).toBeDefined();
         const cacheEntry: CacheEntry = JSON.parse(value);
 
@@ -240,10 +240,10 @@ describe('Next.js Turbo Redis Cache Integration', () => {
         );
         expect(keys.length).toBe(1);
 
-        const hashmap = await redisClient.hGet(
+        const hashmap = (await redisClient.hGet(
           process.env.VERCEL_URL + '__sharedTags__',
           '/api/cached-static-fetch',
-        );
+        )) as string;
         expect(JSON.parse(hashmap)).toEqual([
           '_N_T_/layout',
           '_N_T_/api/layout',
@@ -519,10 +519,10 @@ describe('Next.js Turbo Redis Cache Integration', () => {
             );
             expect(keys.length).toBe(1);
 
-            const hashmap = await redisClient.hGet(
+            const hashmap = (await redisClient.hGet(
               process.env.VERCEL_URL + '__sharedTags__',
               cacheEntryKey,
-            );
+            )) as string;
             expect(JSON.parse(hashmap)).toEqual([
               'revalidated-fetch-revalidate3-nested-fetch-in-api-route',
             ]);
@@ -574,10 +574,10 @@ describe('Next.js Turbo Redis Cache Integration', () => {
             );
             expect(keys.length).toBe(1);
 
-            const hashmap = await redisClient.hGet(
+            const hashmap = (await redisClient.hGet(
               process.env.VERCEL_URL + '__sharedTags__',
               cacheEntryKey,
-            );
+            )) as string;
             expect(JSON.parse(hashmap)).toEqual([
               'revalidated-fetch-revalidate3-nested-fetch-in-api-route',
             ]);
@@ -627,9 +627,9 @@ describe('Next.js Turbo Redis Cache Integration', () => {
         });
 
         it('The data in the redis key should match the expected format', async () => {
-          const data = await redisClient.get(
+          const data = (await redisClient.get(
             process.env.VERCEL_URL + '/pages/no-fetch/default-page',
-          );
+          )) as string;
           expect(data).toBeDefined();
           const cacheEntry: CacheEntry = JSON.parse(data);
 
@@ -724,10 +724,10 @@ describe('Next.js Turbo Redis Cache Integration', () => {
           );
           expect(keys.length).toBe(1);
 
-          const hashmap = await redisClient.hGet(
+          const hashmap = (await redisClient.hGet(
             process.env.VERCEL_URL + '__sharedTags__',
             '/pages/no-fetch/default-page',
-          );
+          )) as string;
           expect(JSON.parse(hashmap)).toEqual([
             '_N_T_/layout',
             '_N_T_/pages/layout',
@@ -780,10 +780,10 @@ describe('Next.js Turbo Redis Cache Integration', () => {
         expect(keys3.length).toBe(1);
 
         // test shared tag hashmap to be set for all keys
-        const hashmap1 = await redisClient.hGet(
+        const hashmap1 = (await redisClient.hGet(
           process.env.VERCEL_URL + '__sharedTags__',
           '/pages/revalidated-fetch/revalidate15--default-page',
-        );
+        )) as string;
         expect(JSON.parse(hashmap1)).toEqual([
           '_N_T_/layout',
           '_N_T_/pages/layout',
@@ -793,17 +793,17 @@ describe('Next.js Turbo Redis Cache Integration', () => {
           '_N_T_/pages/revalidated-fetch/revalidate15--default-page',
           'revalidated-fetch-revalidate15-default-page',
         ]);
-        const hashmap2 = await redisClient.hGet(
+        const hashmap2 = (await redisClient.hGet(
           process.env.VERCEL_URL + '__sharedTags__',
           'e978cf5ddb8bf799209e828635cfe9ae6862f6735cea97f01ab752ff6fa489b4',
-        );
+        )) as string;
         expect(JSON.parse(hashmap2)).toEqual([
           'revalidated-fetch-revalidate15-default-page',
         ]);
-        const hashmap3 = await redisClient.hGet(
+        const hashmap3 = (await redisClient.hGet(
           process.env.VERCEL_URL + '__sharedTags__',
           '/api/revalidated-fetch',
-        );
+        )) as string;
         expect(JSON.parse(hashmap3)).toEqual([
           '_N_T_/layout',
           '_N_T_/api/layout',
@@ -872,10 +872,10 @@ describe('Next.js Turbo Redis Cache Integration', () => {
           process.env.VERCEL_URL + '/api/revalidated-fetch',
         );
         expect(keys3.length).toBe(1);
-        const hashmap3 = await redisClient.hGet(
+        const hashmap3 = (await redisClient.hGet(
           process.env.VERCEL_URL + '__sharedTags__',
           '/api/revalidated-fetch',
-        );
+        )) as string;
         expect(JSON.parse(hashmap3)).toEqual([
           '_N_T_/layout',
           '_N_T_/api/layout',

test/integration/nextjs-cache-handler.integration.test.ts

@@ -0,0 +1,33 @@
+import { test, expect } from '@playwright/test';
+
+// This test assumes the Next 16 app is already running, e.g.:
+//   cd test/integration/next-app-16-0-3 && pnpm dev
+// on the same origin as baseURL.
+
+test('button click triggers Server Action using updateTag', async ({
+  page,
+}) => {
+  await page.goto('/update-tag-test');
+
+  await expect(page.getByText('UpdateTag Test')).toBeVisible();
+
+  const clicks = page.getByTestId('clicks');
+  const before = await clicks.textContent();
+
+  await page.getByRole('button', { name: 'Increment' }).click();
+
+  // Wait for network and any navigation caused by the Server Action
+  await page.waitForLoadState('networkidle');
+
+  const after = await clicks.textContent();
+
+  // Server Action should have run and updated the UI
+  expect(after).not.toBe(before);
+
+  // Ensure there is no error message about updateTag usage
+  const errorLocator = page.getByText(
+    'updateTag can only be called from within a Server Action',
+    { exact: false },
+  );
+  await expect(errorLocator).toHaveCount(0);
+});