test(e2e): align preview URL encoding and docs

* test(e2e): phase-3 add nightly workflow and perf smoke suite

* test(e2e): address copilot review for phase-3 fixture and readiness flow

.github/workflows/nightly-e2e.yml

@@ -0,0 +1,118 @@
+name: Nightly E2E Full
+
+on:
+  schedule:
+    - cron: '30 18 * * *' # 02:30 Asia/Shanghai
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  e2e-nightly:
+    runs-on: ubuntu-latest
+    timeout-minutes: 50
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup JDK 21
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+          cache: maven
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: tests/e2e/package-lock.json
+
+      - name: Setup Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install LibreOffice + zip
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libreoffice zip
+
+      - name: Setup Python deps for office fixtures
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r tests/e2e/requirements.txt
+
+      - name: Build kkFileView
+        run: mvn -q -pl server -DskipTests package
+
+      - name: Install E2E deps
+        working-directory: tests/e2e
+        run: |
+          npm ci
+          npx playwright install --with-deps chromium
+
+      - name: Start fixture server
+        run: |
+          cd tests/e2e/fixtures
+          python3 -m http.server 18080 > /tmp/fixture-server.log 2>&1 &
+
+      - name: Start kkFileView
+        run: |
+          JAR_PATH=$(ls server/target/kkFileView-*.jar | head -n 1)
+          nohup env KK_TRUST_HOST='*' KK_NOT_TRUST_HOST='10.*,172.16.*,192.168.*' java -jar "$JAR_PATH" > /tmp/kkfileview.log 2>&1 &
+
+      - name: Wait for services
+        run: |
+          fixture_ready=false
+          for i in {1..60}; do
+            if curl -fsS http://127.0.0.1:18080/sample.txt >/dev/null; then
+              fixture_ready=true
+              break
+            fi
+            sleep 1
+          done
+          if [ "$fixture_ready" != "true" ]; then
+            echo "Error: fixture server did not become ready within 60 seconds." >&2
+            exit 1
+          fi
+
+          kkfileview_ready=false
+          for i in {1..120}; do
+            if curl -fsS http://127.0.0.1:8012/ >/dev/null; then
+              kkfileview_ready=true
+              break
+            fi
+            sleep 1
+          done
+          if [ "$kkfileview_ready" != "true" ]; then
+            echo "Error: kkFileView service did not become ready within 120 seconds." >&2
+            exit 1
+          fi
+
+      - name: Run nightly E2E suites
+        working-directory: tests/e2e
+        env:
+          KK_BASE_URL: http://127.0.0.1:8012
+          FIXTURE_BASE_URL: http://127.0.0.1:18080
+          E2E_MAX_PREVIEW_MS: 20000
+        run: npm run test:ci
+
+      - name: Upload Playwright report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: nightly-playwright-report
+          path: tests/e2e/playwright-report
+
+      - name: Upload service logs
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: nightly-e2e-service-logs
+          path: |
+            /tmp/kkfileview.log
+            /tmp/fixture-server.log

.github/workflows/pr-e2e-mvp.yml

@@ -31,10 +31,20 @@ jobs:
           cache: 'npm'
           cache-dependency-path: tests/e2e/package-lock.json
 
-      - name: Install LibreOffice
+      - name: Setup Python 3.11
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install LibreOffice + zip
         run: |
           sudo apt-get update
-          sudo apt-get install -y libreoffice
+          sudo apt-get install -y libreoffice zip
+
+      - name: Setup Python deps for office fixtures
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r tests/e2e/requirements.txt
 
       - name: Build kkFileView
         run: mvn -q -pl server -DskipTests package
@@ -45,9 +55,6 @@ jobs:
           npm install
           npx playwright install --with-deps chromium
 
-      - name: Generate fixtures
-        run: node tests/e2e/scripts/generate-fixtures.mjs
-
       - name: Start fixture server
         run: |
           cd tests/e2e/fixtures

tests/e2e/.gitignore

@@ -1,3 +1,9 @@
 node_modules/
 playwright-report/
 test-results/
+
+__pycache__/
+fixtures/zip-tmp/
+fixtures/sample.docx
+fixtures/sample.xlsx
+fixtures/sample.pptx

tests/e2e/README.md

@@ -5,10 +5,14 @@ This folder contains a first MVP of end-to-end automated tests.
 ## What is covered
 
 - Basic preview smoke checks for common file types (txt/md/json/xml/csv/html/png)
+- Office Phase-2 smoke checks (docx/xlsx/pptx)
+- Archive smoke check (zip)
 - Basic endpoint reachability
 - Security regression checks for blocked internal-network hosts (`10.*`) on:
   - `/onlinePreview`
   - `/getCorsFile`
+- Basic performance smoke checks (configurable threshold): txt/docx/xlsx preview response time
+- CI combined run command available via `npm run test:ci`
 
 ## Local run
 
@@ -24,13 +28,16 @@ mvn -q -pl server -DskipTests package
 cd tests/e2e
 npm install
 npx playwright install --with-deps chromium
+pip3 install -r requirements.txt
 ```
 
+> Prerequisite: ensure `zip` command is available in PATH (used for `sample.zip` fixture generation).
+
 3. Generate fixtures and start fixture server:
 
 ```bash
 cd /path/to/kkFileView
-node tests/e2e/scripts/generate-fixtures.mjs
+npm run gen:all
 cd tests/e2e/fixtures && python3 -m http.server 18080
 ```
 
@@ -47,3 +54,16 @@ KK_TRUST_HOST='*' KK_NOT_TRUST_HOST='10.*,172.16.*,192.168.*' java -jar "$JAR_PA
 cd tests/e2e
 KK_BASE_URL=http://127.0.0.1:8012 FIXTURE_BASE_URL=http://127.0.0.1:18080 npm test
 ```
+
+Optional:
+
+```bash
+# smoke only (self-contained: will auto-generate fixtures)
+npm run test:smoke
+
+# perf smoke (self-contained; default threshold 15000ms)
+E2E_MAX_PREVIEW_MS=15000 npm run test:perf
+
+# CI-style combined run (single fixture generation)
+E2E_MAX_PREVIEW_MS=20000 npm run test:ci
+```

tests/e2e/package.json

@@ -4,9 +4,17 @@
   "version": "0.1.0",
   "type": "module",
   "scripts": {
+    "gen:fixtures": "node ./scripts/generate-fixtures.mjs",
+    "gen:office": "python3 ./scripts/generate-office-fixtures.py",
+    "gen:all": "npm run gen:fixtures && npm run gen:office",
+    "pretest": "npm run gen:all",
     "test": "playwright test",
     "test:headed": "playwright test --headed",
-    "gen:fixtures": "node ./scripts/generate-fixtures.mjs"
+    "pretest:smoke": "npm run gen:all",
+    "test:smoke": "playwright test specs/preview-smoke.spec.ts",
+    "pretest:perf": "npm run gen:all",
+    "test:perf": "playwright test specs/perf-smoke.spec.ts",
+    "test:ci": "npm run gen:all && playwright test specs/preview-smoke.spec.ts specs/perf-smoke.spec.ts"
   },
   "devDependencies": {
     "@playwright/test": "^1.55.0"

tests/e2e/playwright.config.ts

@@ -4,8 +4,10 @@ export default defineConfig({
   testDir: './specs',
   timeout: 30_000,
   expect: { timeout: 10_000 },
+  retries: process.env.CI ? 1 : 0,
   reporter: [['list'], ['html', { outputFolder: 'playwright-report', open: 'never' }]],
   use: {
     baseURL: process.env.KK_BASE_URL || 'http://127.0.0.1:8012',
+    trace: 'on-first-retry',
   },
 });

tests/e2e/requirements.txt

@@ -0,0 +1,3 @@
+python-docx==1.1.2
+openpyxl==3.1.5
+python-pptx==1.0.2

tests/e2e/scripts/generate-fixtures.mjs

@@ -1,7 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
 
-const fixturesDir = path.resolve(process.cwd(), 'tests/e2e/fixtures');
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const fixturesDir = path.resolve(__dirname, '..', 'fixtures');
 fs.mkdirSync(fixturesDir, { recursive: true });
 
 const write = (name, content) => fs.writeFileSync(path.join(fixturesDir, name), content);
@@ -13,6 +16,22 @@ write('sample.xml', '<root><name>kkFileView</name><e2e>true</e2e></root>');
 write('sample.csv', 'name,value\nkkFileView,1\ne2e,1\n');
 write('sample.html', '<!doctype html><html><body><h1>kkFileView fixture</h1></body></html>');
 
+// zip (contains txt) - only generate if missing to avoid noisy local diffs
+const zipPath = path.join(fixturesDir, 'sample.zip');
+if (!fs.existsSync(zipPath)) {
+  const zipWork = path.join(fixturesDir, 'zip-tmp');
+  fs.mkdirSync(zipWork, { recursive: true });
+  fs.writeFileSync(path.join(zipWork, 'inner.txt'), 'kkFileView zip inner file');
+  try {
+    execFileSync('zip', ['-X', '-q', '-r', zipPath, 'inner.txt'], { cwd: zipWork });
+  } catch (err) {
+    console.error('Failed to create sample.zip fixture. Ensure "zip" is installed and available in PATH.');
+    throw err instanceof Error ? err : new Error(String(err));
+  } finally {
+    fs.rmSync(zipWork, { recursive: true, force: true });
+  }
+}
+
 // 1x1 png
 write(
   'sample.png',

tests/e2e/scripts/generate-office-fixtures.py

@@ -0,0 +1,35 @@
+#!/usr/bin/env python3
+from pathlib import Path
+
+from docx import Document
+from openpyxl import Workbook
+from pptx import Presentation
+
+fixtures = Path(__file__).resolve().parent.parent / "fixtures"
+fixtures.mkdir(parents=True, exist_ok=True)
+
+# DOCX
+_doc = Document()
+_doc.add_heading("kkFileView E2E", level=1)
+_doc.add_paragraph("This is a DOCX fixture for Phase-2 E2E.")
+_doc.save(fixtures / "sample.docx")
+
+# XLSX
+_wb = Workbook()
+_ws = _wb.active
+_ws.title = "Sheet1"
+_ws["A1"] = "name"
+_ws["B1"] = "value"
+_ws["A2"] = "kkFileView"
+_ws["B2"] = 2
+_wb.save(fixtures / "sample.xlsx")
+
+# PPTX
+_prs = Presentation()
+slide_layout = _prs.slide_layouts[1]
+slide = _prs.slides.add_slide(slide_layout)
+slide.shapes.title.text = "kkFileView E2E"
+slide.placeholders[1].text = "This is a PPTX fixture for Phase-2 E2E."
+_prs.save(fixtures / "sample.pptx")
+
+print("office fixtures generated in", fixtures)

tests/e2e/specs/perf-smoke.spec.ts

@@ -0,0 +1,49 @@
+import { test, expect, request as playwrightRequest } from '@playwright/test';
+import type { APIRequestContext } from '@playwright/test';
+
+const fixtureBase = process.env.FIXTURE_BASE_URL || 'http://127.0.0.1:18080';
+const DEFAULT_MAX_MS = 15000;
+const envMaxMs = Number(process.env.E2E_MAX_PREVIEW_MS);
+const maxMs = Number.isFinite(envMaxMs) && envMaxMs >= 1 ? Math.floor(envMaxMs) : DEFAULT_MAX_MS;
+
+function b64(v: string): string {
+  return Buffer.from(v).toString('base64');
+}
+
+async function timedPreview(request: APIRequestContext, fileUrl: string) {
+  const started = Date.now();
+  const resp = await request.get(`/onlinePreview?url=${encodeURIComponent(b64(fileUrl))}`);
+  const elapsed = Date.now() - started;
+  return { resp, elapsed };
+}
+
+test.beforeAll(async () => {
+  const api = await playwrightRequest.newContext();
+  const required = ['sample.txt', 'sample.docx', 'sample.xlsx'];
+  try {
+    for (const name of required) {
+      const resp = await api.get(`${fixtureBase}/${name}`);
+      expect(resp.ok(), `fixture missing or unavailable: ${name}`).toBeTruthy();
+    }
+  } finally {
+    await api.dispose();
+  }
+});
+
+test('perf: txt preview response under threshold', async ({ request }) => {
+  const { resp, elapsed } = await timedPreview(request, `${fixtureBase}/sample.txt`);
+  expect(resp.status()).toBe(200);
+  expect(elapsed).toBeLessThan(maxMs);
+});
+
+test('perf: docx preview response under threshold', async ({ request }) => {
+  const { resp, elapsed } = await timedPreview(request, `${fixtureBase}/sample.docx`);
+  expect(resp.status()).toBe(200);
+  expect(elapsed).toBeLessThan(maxMs);
+});
+
+test('perf: xlsx preview response under threshold', async ({ request }) => {
+  const { resp, elapsed } = await timedPreview(request, `${fixtureBase}/sample.xlsx`);
+  expect(resp.status()).toBe(200);
+  expect(elapsed).toBeLessThan(maxMs);
+});

tests/e2e/specs/preview-smoke.spec.ts

@@ -1,4 +1,4 @@
-import { test, expect } from '@playwright/test';
+import { test, expect, request as playwrightRequest } from '@playwright/test';
 
 const fixtureBase = process.env.FIXTURE_BASE_URL || 'http://127.0.0.1:18080';
 
@@ -7,10 +7,36 @@ function b64(v: string): string {
 }
 
 async function openPreview(request: any, fileUrl: string) {
-  const encoded = b64(fileUrl);
+  const encoded = encodeURIComponent(b64(fileUrl));
   return request.get(`/onlinePreview?url=${encoded}`);
 }
 
+test.beforeAll(async () => {
+  const api = await playwrightRequest.newContext();
+  const required = [
+    'sample.txt',
+    'sample.md',
+    'sample.json',
+    'sample.xml',
+    'sample.csv',
+    'sample.html',
+    'sample.png',
+    'sample.docx',
+    'sample.xlsx',
+    'sample.pptx',
+    'sample.zip',
+  ];
+
+  try {
+    for (const name of required) {
+      const resp = await api.get(`${fixtureBase}/${name}`);
+      expect(resp.ok(), `fixture missing or unavailable: ${name}`).toBeTruthy();
+    }
+  } finally {
+    await api.dispose();
+  }
+});
+
 test('01 home/index reachable', async ({ request }) => {
   const resp = await request.get('/');
   expect(resp.status()).toBeLessThan(500);
@@ -51,13 +77,33 @@ test('08 png preview', async ({ request }) => {
   expect(resp.status()).toBe(200);
 });
 
-test('09 security: block 10.x host in onlinePreview', async ({ request }) => {
+test('09 docx preview', async ({ request }) => {
+  const resp = await openPreview(request, `${fixtureBase}/sample.docx`);
+  expect(resp.status()).toBe(200);
+});
+
+test('10 xlsx preview', async ({ request }) => {
+  const resp = await openPreview(request, `${fixtureBase}/sample.xlsx`);
+  expect(resp.status()).toBe(200);
+});
+
+test('11 pptx preview', async ({ request }) => {
+  const resp = await openPreview(request, `${fixtureBase}/sample.pptx`);
+  expect(resp.status()).toBe(200);
+});
+
+test('12 zip preview', async ({ request }) => {
+  const resp = await openPreview(request, `${fixtureBase}/sample.zip`);
+  expect(resp.status()).toBe(200);
+});
+
+test('13 security: block 10.x host in onlinePreview', async ({ request }) => {
   const resp = await openPreview(request, `http://10.1.2.3/a.pdf`);
   const body = await resp.text();
   expect(body).toContain('不受信任');
 });
 
-test('10 security: block 10.x host in getCorsFile', async ({ request }) => {
+test('14 security: block 10.x host in getCorsFile', async ({ request }) => {
   const encoded = b64('http://10.1.2.3/a.pdf');
   const resp = await request.get(`/getCorsFile?urlPath=${encoded}`);
   const body = await resp.text();