test(rspress-plugin-katex): add e2e test with playwright

.github/workflows/test-Windows.yml

@@ -40,11 +40,11 @@ jobs:
       - name: Install Dependencies
         run: pnpm install
 
-      - name: Build Packages
-        run: pnpm run build
-
       - name: Build Docs
         run: pnpm run docs:build
 
       - name: Unit Test
         run: pnpm run test
+
+      - name: E2E Test
+        run: pnpm playwright install --with-deps chromium && pnpm run e2e

.github/workflows/test-macOS.yml

@@ -40,11 +40,11 @@ jobs:
       - name: Install Dependencies
         run: pnpm install
 
-      - name: Build Packages
-        run: pnpm run build
-
       - name: Build Docs
         run: pnpm run docs:build
 
       - name: Unit Test
         run: pnpm run test
+
+      - name: E2E Test
+        run: pnpm playwright install --with-deps chromium && pnpm run e2e

.gitignore

@@ -28,4 +28,7 @@ doc_build
 
 .TODO
 .env
-backup
+backup
+
+playwright-report
+test-results

AGENTS.md

@@ -11,12 +11,30 @@ This file describes the `rspress-plugins` project, the tools and frameworks it u
 This project utilizes the following tools and frameworks:
 
 *   **Package Manager:** [pnpm](https://pnpm.io/)
-*   **Testing:** [Vitest](https://vitest.dev/)
+*   **Testing:** [Vitest](https://vitest.dev/) (Unit), [Playwright](https://playwright.dev/) (E2E)
 *   **Language:** [TypeScript](https://www.typescriptlang.org/)
 *   **Linting & Formatting:** [ESLint](https://eslint.org/) and [Prettier](https://prettier.io/)
 *   **Versioning:** [Changesets](https://github.com/changesets/changesets)
 *   **UI Framework:** [React](https://reactjs.org/)
 
+## Setup commands
+
+- Install deps: `pnpm install`
+
+- Start dev server: `pnpm dev`
+
+- Run unit tests: `pnpm test`
+
+- Run e2e tests: `pnpm e2e`
+
+## Code style
+
+- TypeScript strict mode
+
+- Single quotes, no semicolons
+
+- Use functional patterns where possible
+
 ## Content from rspress.rs
 
 The following content was retrieved from [https://v2.rspress.rs/llms.txt](https://v2.rspress.rs/llms.txt):

e2e/utils.ts

@@ -0,0 +1,134 @@
+import { ChildProcess } from 'child_process';
+import spawn from 'cross-spawn';
+import getPortLib from 'get-port';
+import treeKill from 'tree-kill';
+
+export const getRandomPort = async () => {
+  return getPortLib();
+};
+
+export const killProcess = async (instance: ChildProcess) => {
+  return new Promise((resolve, reject) => {
+    if (!instance || !instance.pid) {
+      resolve(null);
+      return;
+    }
+    treeKill(instance.pid, (err) => {
+      if (err) {
+        if (
+          process.platform === 'win32' &&
+          typeof err.message === 'string' &&
+          (err.message.includes('no running instance of the task') ||
+            err.message.includes('not found'))
+        ) {
+          // Windows throws an error if the process is already dead
+          return resolve(null);
+        }
+        return reject(err);
+      }
+      return resolve(null);
+    });
+  });
+};
+
+export const runDevCommand = async (
+  root: string,
+  port?: number,
+): Promise<{ process: ChildProcess; url: string }> => {
+  const targetPort = port || (await getRandomPort());
+  const childProcess = spawn('pnpm', ['rspress', 'dev', '--port', targetPort.toString()], {
+    cwd: root,
+    stdio: 'pipe',
+    env: {
+      ...process.env,
+      NODE_ENV: 'development',
+    },
+  });
+
+  return new Promise((resolve, reject) => {
+    let resolved = false;
+    childProcess.stdout?.on('data', (data) => {
+      const output = data.toString();
+      // Rspress dev server started
+      if (output.includes('http://localhost') && !resolved) {
+        resolved = true;
+        resolve({ process: childProcess, url: `http://localhost:${targetPort}` });
+      }
+    });
+
+    childProcess.stderr?.on('data', (data) => {
+      console.error(`Dev Error: ${data}`);
+    });
+
+    childProcess.on('error', (err) => {
+      reject(err);
+    });
+
+    childProcess.on('close', (code) => {
+        if (!resolved && code !== 0) {
+            reject(new Error(`Dev process exited with code ${code}`));
+        }
+    });
+  });
+};
+
+export const runBuildCommand = async (root: string) => {
+  return new Promise<void>((resolve, reject) => {
+    const childProcess = spawn('pnpm', ['rspress', 'build'], {
+      cwd: root,
+      stdio: 'ignore',
+      env: {
+        ...process.env,
+        NODE_ENV: 'production',
+      },
+    });
+
+    childProcess.on('close', (code) => {
+      if (code === 0) {
+        resolve();
+      } else {
+        reject(new Error(`Build failed with code ${code}`));
+      }
+    });
+  });
+};
+
+export const runPreviewCommand = async (
+  root: string,
+  port?: number,
+): Promise<{ process: ChildProcess; url: string }> => {
+  const targetPort = port || (await getRandomPort());
+  const childProcess = spawn('npx', ['rspress', 'preview', '--port', targetPort.toString()], {
+    cwd: root,
+    stdio: 'pipe',
+    env: {
+      ...process.env,
+      NODE_ENV: 'production',
+    },
+  });
+
+  return new Promise((resolve, reject) => {
+    let resolved = false;
+    childProcess.stdout?.on('data', (data) => {
+      const output = data.toString();
+      if (output.includes('http://localhost') && !resolved) {
+          resolved = true;
+          resolve({ process: childProcess, url: `http://localhost:${targetPort}` });
+      }
+    });
+
+    childProcess.stderr?.on('data', (data) => {
+      console.error(`Preview Error: ${data}`);
+    });
+
+    childProcess.on('error', (err) => {
+      reject(err);
+    });
+
+    childProcess.on('close', (code) => {
+        if (!resolved && code !== 0) {
+            reject(new Error(`Preview process exited with code ${code}`));
+        }
+    });
+  });
+};

package.json

@@ -2,10 +2,12 @@
   "name": "rspress-plugins",
   "version": "0.0.0",
   "private": true,
+  "type": "module",
   "workspaces": [
     "packages/*"
   ],
   "scripts": {
+    "prepare": "npm run packages:build",
     "clean": "rm -rf ./packages/**/{dist,build}",
     "build": "pnpm run clean && pnpm packages:build",
     "commit": "git add -A && czg",
@@ -14,6 +16,7 @@
     "docs:build": "pnpm -r --filter=./packages/**/* run docs:build",
     "test": "vitest",
     "testu": "vitest --update",
+    "e2e": "playwright test",
     "test:cov": "vitest --coverage",
     "version": "changeset version && pnpm install --frozen-lockfile",
     "version:beta": "changeset pre enter beta && changeset version",
@@ -27,6 +30,8 @@
   },
   "devDependencies": {
     "@changesets/cli": "^2.27.1",
+    "@playwright/test": "^1.57.0",
+    "@types/cross-spawn": "^6.0.6",
     "@types/fs-extra": "^11.0.4",
     "@types/lodash": "^4.17.0",
     "@types/pacote": "^11.1.8",
@@ -36,17 +41,21 @@
     "clipboardy": "^4.0.0",
     "clsx": "^2.1.0",
     "consola": "^3.2.3",
+    "cross-spawn": "^7.0.6",
     "czg": "^1.9.1",
     "eslint": "^9.0.0",
     "execa": "^8.0.1",
+    "get-port": "^7.1.0",
     "lodash": "^4.17.21",
     "npm-run-all": "^4.1.5",
     "p-try": "^3.0.0",
+    "playwright": "^1.57.0",
     "prettier": "^3.2.5",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",
     "rimraf": "^5.0.5",
     "stylelint": "^16.3.1",
+    "tree-kill": "^1.2.2",
     "typescript": "^5.4.4",
     "util-ts-types": "^1.0.0",
     "vitest": "1.4.0"

packages/rspress-plugin-katex/index.spec.ts

@@ -0,0 +1,31 @@
+import { test, expect } from '@playwright/test';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { runDevCommand, killProcess } from '../../e2e/utils.ts';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+test.describe('rspress-plugin-katex', () => {
+  let devProcess: any;
+  let url: string;
+
+  test.beforeAll(async () => {
+    const result = await runDevCommand(__dirname);
+    devProcess = result.process;
+    url = result.url;
+  });
+
+  test.afterAll(async () => {
+    if (devProcess) {
+      await killProcess(devProcess);
+    }
+  });
+
+  test('should render katex math', async ({ page }) => {
+    await page.goto(url, { waitUntil: 'networkidle' });
+    // Check if katex-html element exists, which is generated by katex
+    const katexElement = page.locator('.katex-html');
+    await expect(katexElement).toBeVisible();
+  });
+});

packages/rspress-plugin-katex/vitest.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    exclude: ['**/*.spec.ts', 'node_modules'],
+  },
+});

playwright.config.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testMatch: 'packages/**/*.spec.ts',
+ // 30 min for all tests
+  globalTimeout: 30 * 60 * 1000,
+  // 1 min for each test
+  timeout: 60 * 1000,
+  quiet: true,
+  reporter: 'list',
+  use: {
+    trace: 'on',
+    video: 'on',
+    viewport: { width: 1440, height: 900 }, // screen size
+  },
+  retries: process.env.CI ? 3 : 0,
+});