@lvce-editor/test-with-playwright 18.0.0 → 19.0.0

package/README.md

@@ -5,7 +5,15 @@
 ```json
 {
   "scripts": {
-    "e2e": "node ./node_modules/@lvce-editor/test-with-playwright/bin/test-with-playwright.js --only-extension=. --test-path=./e2e"
+    "e2e": "node ./node_modules/@lvce-editor/test-with-playwright/bin/test-with-playwright.js --runtime=browser --only-extension=. --test-path=./e2e"
+  }
+}
+```
+
+```json
+{
+  "scripts": {
+    "e2e:electron": "node ./node_modules/@lvce-editor/test-with-playwright/bin/test-with-playwright.js --runtime=electron --electron-version=v0.84.0 --test-path=./e2e"
   }
 }
 ```
@@ -19,6 +27,7 @@ test('sample.hello-world', async () => {
 
 ## CLI Flags
 
+- `--runtime`: `browser` (default) or `electron`
 - `--only-extension`: path to the extension under test
 - `--test-path`: path to the test root
 - `--server-path`: explicit server entry point
@@ -26,6 +35,17 @@ test('sample.hello-world', async () => {
 - `--headless`: run Playwright in headless mode
 - `--browser`: browser engine to launch, either `chromium` or `firefox`
 - `--trace-focus`: add `traceFocus=true` to test URLs
+- `--electron-path`: path to an existing Electron app executable
+- `--electron-version`: Lvce release version to download, required for `--runtime=electron` when `--electron-path` is not provided
+- `--electron-cache-dir`: directory for downloaded Electron apps, defaults to `.test-with-playwright/electron`
+- `--electron-arg`: extra Electron app argument, can be provided multiple times
+- `--electron-env`: Electron environment variable in `NAME=value` form, can be provided multiple times
+
+## Runtime Notes
+
+- `browser` keeps the server-backed HTML test execution flow.
+- `electron` downloads or reuses a Lvce Electron app, launches it with Playwright, and runs each test module against the first window.
+- `--electron-path` skips downloading and is useful for custom local builds.
 
 ## Environment Variables
 

package/dist/main.js

@@ -1,4 +1,10 @@
-import { join } from 'node:path';
+import { dirname, join, resolve as resolve$1, basename } from 'node:path';
+import { createWriteStream, existsSync } from 'node:fs';
+import { mkdir, readdir, stat, readFile, chmod, writeFile, rm, mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { pipeline } from 'node:stream/promises';
+import { execFile as execFile$1 } from 'node:child_process';
+import { promisify } from 'node:util';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 
 const HandleResult = 'HandleResult';
@@ -110,6 +116,30 @@ const commandMap = {
   [HandleResult]: handleResult
 };
 
+const getHelpMessage = () => {
+  return `Usage: test-with-playwright [options]
+
+Options:
+  --browser=<browser>       Browser to run tests in: chromium or firefox
+  --runtime=<runtime>       Runtime to run tests in: browser or electron
+  --filter=<pattern>        Only run tests matching the filter
+  --headless                Run the browser in headless mode
+  --only-extension=<path>   Path to the extension under test
+  --server-path=<path>      Path to the editor server entrypoint
+  --test-path=<path>        Path to the test files
+  --trace-focus             Log focus changes while tests run
+  --electron-path=<path>    Path to an existing Electron app executable
+  --electron-version=<ver>  Lvce release version to download, for example v0.84.0
+  --electron-cache-dir=<p>  Directory for downloaded Electron apps
+  --electron-arg=<arg>      Extra Electron app argument, repeatable
+  --electron-env=<env>      Electron environment variable as NAME=value, repeatable
+  -h, --help                Show this help message
+
+Environment:
+  ONLY_EXTENSION            Default extension path
+  TEST_PATH                 Default test path`;
+};
+
 function getDefaultExportFromCjs (x) {
 	return x && x.__esModule && Object.prototype.hasOwnProperty.call(x, 'default') ? x['default'] : x;
 }
@@ -347,26 +377,67 @@ function requireMinimist () {
 var minimistExports = requireMinimist();
 const parseArgv = /*@__PURE__*/getDefaultExportFromCjs(minimistExports);
 
+const toCliString = value => {
+  if (typeof value === 'string') {
+    return value;
+  }
+  if (typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+  throw new TypeError('expected cli argument value to be a string, number, or boolean');
+};
+const toStringArray = value => {
+  if (value === undefined) {
+    return undefined;
+  }
+  if (Array.isArray(value)) {
+    return value.map(toCliString);
+  }
+  return [toCliString(value)];
+};
 const parseCliArgs = argv => {
   const parsed = parseArgv(argv);
   const result = Object.create(null);
   if (parsed.browser) {
-    result.browser = parsed.browser;
+    result.browser = String(parsed.browser);
+  }
+  if (parsed.runtime) {
+    result.runtime = String(parsed.runtime);
   }
   if (parsed.filter) {
-    result.filter = parsed.filter;
+    result.filter = String(parsed.filter);
+  }
+  if (parsed.help || parsed.h) {
+    result.help = true;
   }
   if (parsed.headless) {
     result.headless = true;
   }
   if (parsed['only-extension']) {
-    result.onlyExtension = parsed['only-extension'];
+    result.onlyExtension = String(parsed['only-extension']);
   }
   if (parsed['test-path']) {
-    result.testPath = parsed['test-path'];
+    result.testPath = String(parsed['test-path']);
   }
   if (parsed['server-path']) {
-    result.serverPath = parsed['server-path'];
+    result.serverPath = String(parsed['server-path']);
+  }
+  if (parsed['electron-path']) {
+    result.electronPath = String(parsed['electron-path']);
+  }
+  if (parsed['electron-version']) {
+    result.electronVersion = String(parsed['electron-version']);
+  }
+  if (parsed['electron-cache-dir']) {
+    result.electronCacheDir = String(parsed['electron-cache-dir']);
+  }
+  const electronArgs = toStringArray(parsed['electron-arg']);
+  if (electronArgs) {
+    result.electronArgs = electronArgs;
+  }
+  const electronEnv = toStringArray(parsed['electron-env']);
+  if (electronEnv) {
+    result.electronEnv = electronEnv;
   }
   if (parsed['trace-focus']) {
     result.traceFocus = true;
@@ -389,26 +460,405 @@ const defaultOptions = {
   browser: 'chromium',
   extensionPath: '',
   headless: false,
+  help: false,
+  runtime: 'browser',
   testPath: ''
 };
 const isBrowser = value => {
   return value === 'chromium' || value === 'firefox';
 };
+const isRuntime = value => {
+  return value === 'browser' || value === 'electron';
+};
 const getOptions = ({
   argv,
   env
 }) => {
   const parsedEnv = parseEnv(env);
   const parsedArgs = parseCliArgs(argv);
-  const browser = parsedArgs.browser ?? defaultOptions.browser;
-  if (!isBrowser(browser)) {
-    throw new Error(`[test-with-playwright] unsupported browser: ${browser}`);
+  if (parsedArgs.browser !== undefined && !isBrowser(parsedArgs.browser)) {
+    throw new Error(`[test-with-playwright] unsupported browser: ${parsedArgs.browser}`);
   }
+  if (parsedArgs.runtime !== undefined && !isRuntime(parsedArgs.runtime)) {
+    throw new Error(`[test-with-playwright] unsupported runtime: ${parsedArgs.runtime}`);
+  }
+  const browser = parsedArgs.browser ?? defaultOptions.browser;
+  const runtime = parsedArgs.runtime ?? defaultOptions.runtime;
   return {
     ...defaultOptions,
     ...parsedEnv,
     ...parsedArgs,
-    browser
+    browser,
+    runtime
+  };
+};
+
+const downloadFile = async ({
+  to,
+  url
+}) => {
+  await mkdir(dirname(to), {
+    recursive: true
+  });
+  const response = await fetch(url);
+  if (!response.ok || !response.body) {
+    throw new Error(`[test-with-playwright] failed to download ${url}: ${response.status} ${response.statusText}`);
+  }
+  await pipeline(response.body, createWriteStream(to));
+};
+
+const execFileAsync = promisify(execFile$1);
+const execFile = async ({
+  args,
+  command
+}) => {
+  await execFileAsync(command, [...args], {
+    windowsHide: true
+  });
+};
+
+const isWindowsExecutable = entry => {
+  return entry.toLowerCase().endsWith('.exe') && entry.toLowerCase().includes('lvce');
+};
+const isMacosExecutable = entry => {
+  return entry.endsWith('.app');
+};
+const findFile = async (directory, predicate) => {
+  const entries = await readdir(directory, {
+    withFileTypes: true
+  });
+  for (const entry of entries) {
+    const absolutePath = join(directory, entry.name);
+    if (entry.isDirectory()) {
+      const nestedResult = await findFile(absolutePath, predicate);
+      if (nestedResult) {
+        return nestedResult;
+      }
+      continue;
+    }
+    if (entry.isFile() && predicate(entry.name)) {
+      return absolutePath;
+    }
+  }
+  return undefined;
+};
+const findApp = async directory => {
+  const entries = await readdir(directory, {
+    withFileTypes: true
+  });
+  for (const entry of entries) {
+    const absolutePath = join(directory, entry.name);
+    if (entry.isDirectory() && isMacosExecutable(entry.name)) {
+      return absolutePath;
+    }
+    if (entry.isDirectory()) {
+      const nestedResult = await findApp(absolutePath);
+      if (nestedResult) {
+        return nestedResult;
+      }
+    }
+  }
+  return undefined;
+};
+const findMacosExecutable = async directory => {
+  const app = await findApp(directory);
+  if (!app) {
+    return undefined;
+  }
+  const macosDirectory = join(app, 'Contents', 'MacOS');
+  const entries = await readdir(macosDirectory);
+  for (const entry of entries) {
+    const absolutePath = join(macosDirectory, entry);
+    const fileStat = await stat(absolutePath);
+    if (fileStat.isFile()) {
+      return absolutePath;
+    }
+  }
+  return undefined;
+};
+const findElectronExecutable = async ({
+  directory,
+  platform
+}) => {
+  if (platform === 'darwin') {
+    const executable = await findMacosExecutable(directory);
+    if (executable) {
+      return executable;
+    }
+  } else if (platform === 'win32') {
+    const executable = await findFile(directory, isWindowsExecutable);
+    if (executable) {
+      return executable;
+    }
+  } else {
+    const executable = await findFile(directory, entry => entry === 'lvce');
+    if (executable) {
+      return executable;
+    }
+  }
+  throw new Error(`[test-with-playwright] failed to locate Electron executable in ${directory}`);
+};
+
+const getLinuxArch = arch => {
+  switch (arch) {
+    case 'arm':
+      return 'armhf';
+    case 'arm64':
+      return 'arm64';
+    case 'x64':
+      return 'amd64';
+    default:
+      throw new Error(`[test-with-playwright] unsupported electron platform: linux/${arch}`);
+  }
+};
+const getWindowsArch = arch => {
+  switch (arch) {
+    case 'arm64':
+      return 'arm64';
+    case 'x64':
+      return 'x64';
+    default:
+      throw new Error(`[test-with-playwright] unsupported electron platform: win32/${arch}`);
+  }
+};
+const resolveElectronAsset = ({
+  arch = process.arch,
+  platform = process.platform,
+  version
+}) => {
+  switch (platform) {
+    case 'darwin':
+      if (arch !== 'arm64') {
+        throw new Error(`[test-with-playwright] unsupported electron platform: darwin/${arch}`);
+      }
+      return {
+        archiveType: 'dmg',
+        assetName: `lvce-${version}_arm64.dmg`
+      };
+    case 'linux':
+      return {
+        archiveType: 'deb',
+        assetName: `lvce-${version}_${getLinuxArch(arch)}.deb`
+      };
+    case 'win32':
+      return {
+        archiveType: 'exe',
+        assetName: `Lvce-Setup-${version}-${getWindowsArch(arch)}.exe`
+      };
+    default:
+      throw new Error(`[test-with-playwright] unsupported electron platform: ${platform}/${arch}`);
+  }
+};
+
+const getDownloadUrl = ({
+  assetName,
+  version
+}) => {
+  return `https://github.com/lvce-editor/lvce-editor/releases/download/${version}/${assetName}`;
+};
+const prepareLinux = async ({
+  assetPath,
+  cachePath
+}) => {
+  await execFile({
+    args: ['-x', assetPath, cachePath],
+    command: 'dpkg-deb'
+  });
+};
+const prepareMacos = async ({
+  assetPath,
+  cachePath
+}) => {
+  const mountRoot = await mkdtemp(join(tmpdir(), 'test-with-playwright-dmg-'));
+  try {
+    await execFile({
+      args: ['attach', assetPath, '-mountpoint', mountRoot, '-nobrowse', '-quiet'],
+      command: 'hdiutil'
+    });
+    const entries = await readdir(mountRoot);
+    const appName = entries.find(entry => entry.endsWith('.app'));
+    if (!appName) {
+      throw new Error(`[test-with-playwright] failed to locate .app in ${assetPath}`);
+    }
+    await execFile({
+      args: ['-R', join(mountRoot, appName), join(cachePath, appName)],
+      command: 'cp'
+    });
+  } finally {
+    try {
+      await execFile({
+        args: ['detach', mountRoot, '-quiet'],
+        command: 'hdiutil'
+      });
+    } catch {
+      // ignore detach errors during cleanup
+    }
+    await rm(mountRoot, {
+      force: true,
+      recursive: true
+    });
+  }
+};
+const prepareWindows = async ({
+  assetPath,
+  cachePath
+}) => {
+  await execFile({
+    args: ['/S', `/D=${cachePath}`],
+    command: assetPath
+  });
+};
+const prepareArchive = async ({
+  archiveType,
+  assetPath,
+  cachePath
+}) => {
+  await rm(cachePath, {
+    force: true,
+    recursive: true
+  });
+  await mkdir(cachePath, {
+    recursive: true
+  });
+  switch (archiveType) {
+    case 'deb':
+      await prepareLinux({
+        assetPath,
+        cachePath
+      });
+      break;
+    case 'dmg':
+      await prepareMacos({
+        assetPath,
+        cachePath
+      });
+      break;
+    case 'exe':
+      await prepareWindows({
+        assetPath,
+        cachePath
+      });
+      break;
+    default:
+      throw new Error(`[test-with-playwright] unsupported Electron archive type: ${archiveType}`);
+  }
+};
+const prepareElectronApp = async ({
+  cacheDir,
+  electronPath,
+  version
+}) => {
+  if (electronPath) {
+    return resolve$1(electronPath);
+  }
+  if (!version) {
+    throw new Error('[test-with-playwright] --electron-version is required when --runtime=electron and --electron-path is not provided');
+  }
+  const {
+    archiveType,
+    assetName
+  } = resolveElectronAsset({
+    version
+  });
+  const cachePath = resolve$1(cacheDir, version, process.platform, process.arch);
+  const downloadsPath = join(cachePath, 'downloads');
+  const appPath = join(cachePath, 'app');
+  const executableMarkerPath = join(cachePath, 'executable-path.txt');
+  if (existsSync(executableMarkerPath)) {
+    const cachedExecutablePathContent = await readFile(executableMarkerPath, 'utf8');
+    const cachedExecutablePath = cachedExecutablePathContent.trim();
+    if (existsSync(cachedExecutablePath)) {
+      return cachedExecutablePath;
+    }
+  }
+  const assetPath = join(downloadsPath, basename(assetName));
+  await mkdir(downloadsPath, {
+    recursive: true
+  });
+  if (!existsSync(assetPath)) {
+    await downloadFile({
+      to: assetPath,
+      url: getDownloadUrl({
+        assetName,
+        version
+      })
+    });
+  }
+  await prepareArchive({
+    archiveType,
+    assetPath,
+    cachePath: appPath
+  });
+  const executablePath = await findElectronExecutable({
+    directory: appPath,
+    platform: process.platform
+  });
+  if (process.platform !== 'win32') {
+    await chmod(executablePath, 0o755);
+  }
+  await writeFile(executableMarkerPath, executablePath);
+  return executablePath;
+};
+
+const parseElectronEnv = electronEnv => {
+  const env = Object.create(null);
+  if (!electronEnv) {
+    return env;
+  }
+  for (const item of electronEnv) {
+    const index = item.indexOf('=');
+    if (index === -1) {
+      env[item] = '';
+      continue;
+    }
+    const key = item.slice(0, index);
+    const value = item.slice(index + 1);
+    env[key] = value;
+  }
+  return env;
+};
+const getBrowserRuntimeOptions = serverPath => {
+  if (serverPath) {
+    return {
+      serverPath,
+      type: 'browser'
+    };
+  }
+  return {
+    type: 'browser'
+  };
+};
+const getRuntimeOptions = async ({
+  cwd,
+  electronArgs,
+  electronCacheDir,
+  electronEnv,
+  electronPath,
+  electronVersion,
+  runtime,
+  serverPath
+}) => {
+  if (runtime !== undefined && runtime !== 'browser' && runtime !== 'electron') {
+    throw new Error(`[test-with-playwright] unsupported runtime: ${runtime}`);
+  }
+  if (runtime !== 'electron') {
+    return getBrowserRuntimeOptions(serverPath);
+  }
+  const cacheDir = resolve$1(cwd, electronCacheDir || '.test-with-playwright/electron');
+  const executablePath = await prepareElectronApp({
+    cacheDir,
+    ...(electronPath && {
+      electronPath: resolve$1(cwd, electronPath)
+    }),
+    ...(electronVersion && {
+      version: electronVersion
+    })
+  });
+  return {
+    args: electronArgs || [],
+    env: parseElectronEnv(electronEnv),
+    executablePath,
+    type: 'electron'
   };
 };
 
@@ -1343,7 +1793,7 @@ const runAllTests = async ({
   filter,
   headless,
   onlyExtension,
-  serverPath,
+  runtimeOptions,
   testPath,
   testWorkerUri,
   timeout,
@@ -1357,7 +1807,7 @@ const runAllTests = async ({
     path,
     stdio: 'inherit'
   });
-  await rpc.invoke(RunAllTests, onlyExtension, testPath, cwd, browser, headless, timeout, serverPath, traceFocus, filter);
+  await rpc.invoke(RunAllTests, onlyExtension, testPath, cwd, browser, headless, timeout, runtimeOptions, traceFocus, filter);
   await rpc.dispose();
 };
 
@@ -1373,15 +1823,48 @@ const handleCliArgs = async ({
   });
   const {
     browser,
+    electronArgs,
+    electronCacheDir,
+    electronEnv,
+    electronPath,
+    electronVersion,
     filter,
     headless,
+    help,
     onlyExtension,
+    runtime,
     serverPath,
     testPath,
     traceFocus
   } = options;
+  if (help) {
+    console.info(getHelpMessage());
+    return;
+  }
   const timeout = 30_000;
   const testWorkerUri = getTestWorkerUrl();
+  const runtimeOptions = await getRuntimeOptions({
+    cwd,
+    ...(electronArgs && {
+      electronArgs
+    }),
+    ...(electronCacheDir && {
+      electronCacheDir
+    }),
+    ...(electronEnv && {
+      electronEnv
+    }),
+    ...(electronPath && {
+      electronPath
+    }),
+    ...(electronVersion && {
+      electronVersion
+    }),
+    runtime,
+    ...(serverPath && {
+      serverPath
+    })
+  });
   await runAllTests({
     browser,
     commandMap,
@@ -1390,7 +1873,7 @@ const handleCliArgs = async ({
     headless,
     // @ts-ignore
     onlyExtension,
-    serverPath,
+    runtimeOptions,
     testPath,
     testWorkerUri,
     timeout,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lvce-editor/test-with-playwright",
-  "version": "18.0.0",
+  "version": "19.0.0",
   "description": "CLI tool for running Playwright tests",
   "repository": {
     "type": "git",
@@ -12,8 +12,8 @@
   "main": "dist/main.js",
   "bin": "bin/test-with-playwright.js",
   "dependencies": {
-    "@lvce-editor/test-with-playwright-worker": "18.0.0",
-    "@lvce-editor/test-worker": "^16.0.0"
+    "@lvce-editor/test-with-playwright-worker": "19.0.0",
+    "@lvce-editor/test-worker": "^16.2.0"
   },
   "engines": {
     "node": ">=24"