@testsmith/api-spector 0.3.3 → 0.3.5

package/bin/cli.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 'use strict'
 
+const fs = require('fs')
+const os = require('os')
 const path = require('path')
-const { spawn } = require('child_process')
+const { spawn, spawnSync } = require('child_process')
 
 const [, , cmd = 'ui', ...rest] = process.argv
 
@@ -61,23 +63,140 @@ if (!command) {
   process.exit(1)
 }
 
-// ui: spawn electron with the app dir
-if (command.runner === 'electron') {
-  // `require('electron')` throws if electron's postinstall didn't download
-  // the platform binary (common behind corporate proxies on Windows: the
-  // npm install completes but the GitHub Releases download is blocked).
-  // The raw stack trace is intimidating; turn it into actionable steps.
-  let electron
+// ─── Electron binary self-repair ─────────────────────────────────────────────
+//
+// `require('electron')` throws when the postinstall didn't download the
+// platform binary. On corporate machines the ~100 MB zip often IS fully
+// downloaded into electron's cache — it's the extraction into node_modules
+// that got interrupted (antivirus, killed install, …). In that case we can
+// repair the install ourselves, using the OS's own unzip tooling (which is
+// not affected by whatever broke Node's extractor), and launch anyway.
+
+// Mirrors getPlatformPath() in electron's install.js — path.txt must contain
+// exactly this value.
+function electronPlatformPath() {
+  switch (process.platform) {
+    case 'win32': return 'electron.exe'
+    case 'darwin':
+    case 'mas': return 'Electron.app/Contents/MacOS/Electron'
+    default: return 'electron'
+  }
+}
+
+// Default cache roots used by @electron/get, per OS. `electron_config_cache`
+// overrides them (same variable electron's own installer respects).
+function electronCacheDirs() {
+  if (process.env.electron_config_cache) return [process.env.electron_config_cache]
+  const home = os.homedir()
+  if (process.platform === 'win32') {
+    return [path.join(process.env.LOCALAPPDATA || path.join(home, 'AppData', 'Local'), 'electron', 'Cache')]
+  }
+  if (process.platform === 'darwin') {
+    return [path.join(home, 'Library', 'Caches', 'electron')]
+  }
+  return [path.join(process.env.XDG_CACHE_HOME || path.join(home, '.cache'), 'electron')]
+}
+
+// Find a fully-downloaded electron zip for this version/platform/arch in the
+// cache. Entries live in hash-named subdirectories; a real zip is >20 MB —
+// anything smaller is a truncated download or a proxy's HTML block page.
+function findCachedElectronZip(version) {
+  const wanted = `electron-v${version}-${process.platform}-${process.arch}.zip`
+  for (const root of electronCacheDirs()) {
+    let entries
+    try { entries = fs.readdirSync(root) } catch { continue }
+    for (const entry of ['', ...entries]) {
+      const candidate = path.join(root, entry, wanted)
+      try {
+        if (fs.statSync(candidate).size > 20 * 1024 * 1024) return candidate
+      } catch { /* not there — keep looking */ }
+    }
+  }
+  return null
+}
+
+// Extract with OS-native tools: PowerShell on Windows, ditto on macOS (it
+// preserves the symlinks inside Electron.app, plain unzip does not), unzip on
+// Linux. Deliberately NOT extract-zip — when we get here, that path already
+// failed once on this machine.
+function extractZipNative(zip, destDir) {
+  let r
+  if (process.platform === 'win32') {
+    r = spawnSync('powershell.exe', [
+      '-NoProfile', '-NonInteractive', '-Command',
+      `Expand-Archive -LiteralPath "${zip}" -DestinationPath "${destDir}" -Force`,
+    ], { stdio: 'ignore' })
+  } else if (process.platform === 'darwin') {
+    r = spawnSync('ditto', ['-x', '-k', zip, destDir], { stdio: 'ignore' })
+  } else {
+    r = spawnSync('unzip', ['-o', '-q', zip, '-d', destDir], { stdio: 'ignore' })
+  }
+  return Boolean(r && r.status === 0)
+}
+
+// Attempt to rebuild node_modules/electron/dist from a cached zip.
+// Returns 'repaired', 'no-zip', or a { zip } object when extraction failed.
+function tryRepairElectron() {
+  let pkgPath
+  try { pkgPath = require.resolve('electron/package.json') } catch { return 'no-zip' }
+  const electronDir = path.dirname(pkgPath)
+  const version = require(pkgPath).version
+  const zip = findCachedElectronZip(version)
+  if (!zip) return 'no-zip'
+
+  console.error(`  Electron ${version} was already downloaded — repairing the`)
+  console.error('  installation from the local cache...')
+  const distDir = path.join(electronDir, 'dist')
+  try { fs.rmSync(distDir, { recursive: true, force: true }) } catch { /* best effort */ }
+  if (!extractZipNative(zip, distDir) || !fs.existsSync(path.join(distDir, electronPlatformPath()))) {
+    return { zip }
+  }
+  fs.writeFileSync(path.join(electronDir, 'path.txt'), electronPlatformPath())
+  console.error('  Repaired.')
+  console.error('')
+  return 'repaired'
+}
+
+// Resolve the electron executable, classifying the failure modes.
+function loadElectron() {
   try {
-    electron = require('electron')
+    const electron = require('electron')
+    // path.txt can exist while dist/ is incomplete (interrupted extraction) —
+    // require() succeeds but points at a binary that isn't there.
+    if (typeof electron === 'string' && !fs.existsSync(electron)) {
+      return { status: 'binary-missing' }
+    }
+    return { status: 'ok', electron }
   } catch (err) {
     const msg = err && err.message ? err.message : String(err)
-    const notInstalled = /Cannot find module 'electron'/i.test(msg)
-    const binaryMissing = /Electron failed to install correctly/i.test(msg)
+    if (/Cannot find module 'electron'/i.test(msg)) return { status: 'not-installed' }
+    if (/Electron failed to install correctly/i.test(msg)) return { status: 'binary-missing' }
+    return { status: 'error', message: msg }
+  }
+}
+
+const TROUBLESHOOTING_URL =
+  'https://github.com/testsmith-io/api-spector/blob/main/docs/getting-started/troubleshooting.md'
+
+// ui: spawn electron with the app dir
+if (command.runner === 'electron') {
+  let loaded = loadElectron()
+  let failedZip = null
+
+  if (loaded.status === 'binary-missing') {
+    const repair = tryRepairElectron()
+    if (repair === 'repaired') {
+      loaded = loadElectron()
+    } else if (repair && repair.zip) {
+      failedZip = repair.zip
+    }
+  }
+
+  if (loaded.status !== 'ok') {
     console.error('')
     console.error('  API Spector — failed to launch the UI.')
     console.error('')
-    if (notInstalled) {
+    if (loaded.status === 'not-installed') {
       console.error('  The electron package is not installed alongside API Spector.')
       console.error('  Versions 0.3.1 and 0.3.2 shipped without it by mistake.')
       console.error('')
@@ -89,39 +208,61 @@ if (command.runner === 'electron') {
       console.error('')
       console.error('    2. Or keep this version and install electron yourself:')
       console.error('         npm install -D electron@31')
+    } else if (loaded.status === 'binary-missing') {
+      let electronDir = null
+      let version = '<version>'
+      try {
+        const pkgPath = require.resolve('electron/package.json')
+        electronDir = path.dirname(pkgPath)
+        version = require(pkgPath).version
+      } catch { /* keep placeholders */ }
+      const zipName = `electron-v${version}-${process.platform}-${process.arch}.zip`
+
+      if (failedZip) {
+        console.error('  Electron\'s binary is missing. A downloaded copy exists at')
+        console.error(`    ${failedZip}`)
+        console.error('  but it could not be extracted — the file may be corrupt (delete')
+        console.error('  it and reinstall), or antivirus is blocking the extraction.')
+      } else {
+        console.error('  Electron is installed, but its platform binary is missing and no')
+        console.error('  usable download was found in the local cache. The download during')
+        console.error('  `npm install` was probably blocked.')
+        console.error('')
+        console.error('  Common causes on corporate machines:')
+        console.error('')
+        console.error('    - Proxy blocks github.com downloads. Note: npm\'s proxy settings')
+        console.error('      do NOT apply to electron\'s downloader — it needs:')
+        console.error('        ELECTRON_GET_USE_PROXY=1')
+        console.error('        GLOBAL_AGENT_HTTPS_PROXY=http://your-proxy:port')
+        console.error('      then: npm install -D @testsmith/api-spector --force')
+        console.error('')
+        console.error('    - TLS-intercepting proxy (certificate errors): point Node at')
+        console.error('      your corporate root CA:')
+        console.error('        NODE_EXTRA_CA_CERTS=/path/to/corporate-root-ca.pem')
+        console.error('')
+        console.error('    - ELECTRON_SKIP_BINARY_DOWNLOAD=1 set machine-wide (some IT')
+        console.error('      images do this) — unset it and reinstall.')
+      }
       console.error('')
-      console.error('  CLI subcommands (run / mock / record / contract / wsdl) do not')
-      console.error('  need electron and work even while this is broken.')
-    } else if (binaryMissing) {
-      const installDir = path.dirname(__dirname)
-      console.error('  Electron is installed, but its platform binary is missing — the')
-      console.error('  download during `npm install` did not complete (often a proxy or')
-      console.error('  firewall blocking github.com / electronjs.org).')
-      console.error('')
-      console.error('  Fix options (try in order):')
-      console.error('')
-      console.error('    1. Reinstall and force the postinstall script to run:')
-      console.error('         npm install -D @testsmith/api-spector --force')
-      console.error('       (use -g instead of -D if you installed globally)')
-      console.error('')
-      console.error('    2. Behind a proxy? Set npm + electron mirrors and reinstall:')
-      console.error('         npm config set proxy http://your-proxy:port')
-      console.error('         npm config set https-proxy http://your-proxy:port')
-      console.error('         set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/')
-      console.error('         npm install -D @testsmith/api-spector --force')
-      console.error('')
-      console.error('    3. Re-run electron\'s postinstall manually:')
-      console.error(`         cd "${path.join(installDir, 'node_modules', 'electron')}"`)
-      console.error('         node install.js')
-      console.error('')
-      console.error('  CLI subcommands (run / mock / record / contract / wsdl) do not')
-      console.error('  need the UI binary and should work even while this is broken.')
+      console.error('  Manual fix (works without any of the above): download')
+      console.error(`    https://github.com/electron/electron/releases/download/v${version}/${zipName}`)
+      console.error('  in a browser, extract ALL of it into:')
+      console.error(`    ${electronDir ? path.join(electronDir, 'dist') : '<node_modules>/electron/dist'}`)
+      console.error(`  and create a file "path.txt" next to "dist" containing exactly:`)
+      console.error(`    ${electronPlatformPath()}`)
     } else {
-      console.error(`  ${msg}`)
+      console.error(`  ${loaded.message}`)
     }
     console.error('')
+    console.error('  CLI subcommands (run / mock / record / contract / wsdl) do not')
+    console.error('  need the UI binary and work even while this is broken.')
+    console.error('')
+    console.error(`  Full troubleshooting guide: ${TROUBLESHOOTING_URL}`)
+    console.error('')
     process.exit(1)
   }
+
+  const electron = loaded.electron
   const appDir = path.join(__dirname, '..')
   // Forward the user's cwd so the main process can decide whether to open a
   // workspace in this folder, or fall through to the welcome screen. Without

package/out/main/index.js

@@ -1015,7 +1015,7 @@ function buildAuth(security, securitySchemes) {
   }
   return { type: "none" };
 }
-const HTTP_METHODS$1 = ["get", "post", "put", "patch", "delete", "head", "options"];
+const HTTP_METHODS$1 = ["get", "post", "put", "patch", "delete", "head", "options", "query"];
 function buildCollection(spec) {
   const info = spec.info ?? {};
   const servers = spec.servers ?? [{}];
@@ -1262,7 +1262,7 @@ function parseKv(blockContent) {
   }
   return result;
 }
-const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "head", "options"];
+const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "head", "options", "query"];
 function parseBruFile(content, fileName) {
   const meta = parseKv(extractBlock(content, "meta"));
   let method = "GET";
@@ -1375,7 +1375,7 @@ async function importBruno(filePath) {
     requests
   };
 }
-const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
+const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS", "QUERY"];
 const HTTP_TO_SPECTOR = {
   $guid: "$uuid",
   $randomInt: "$randomInt",
@@ -1734,6 +1734,13 @@ function renderTree(paths) {
   }
   return [".", ...render(root)].join("\n");
 }
+const PLAYWRIGHT_VERBS = ["get", "post", "put", "patch", "delete", "head"];
+const SUPERTEST_VERBS = ["get", "post", "put", "patch", "delete", "head", "options"];
+function restAssuredCall(method, pathArg) {
+  const verbs = ["get", "post", "put", "patch", "delete", "head", "options"];
+  return verbs.includes(method) ? `.${method}(${pathArg})` : `.request("${method.toUpperCase()}", ${pathArg})`;
+}
+const ROBOT_REQUESTS_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"];
 function safeName(name) {
   return name.replace(/[^\w\s]/g, " ").split(/\s+/).filter(Boolean).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
 }
@@ -1818,6 +1825,12 @@ function buildKeywordsFile(collection, varMap, nameMap, hookExtractedVars) {
       const method = req.method.charAt(0) + req.method.slice(1).toLowerCase();
       lines.push(kwName);
       lines.push(`    [Documentation]    Hook: ${req.hookType} — ${req.name}`);
+      if (!ROBOT_REQUESTS_METHODS.includes(req.method)) {
+        lines.push(`    Log    ${req.method} is not supported by robotframework-requests — hook skipped    WARN`);
+        lines.push(`    RETURN    \${None}`);
+        lines.push("");
+        continue;
+      }
       const { body } = req;
       if (hasBody(req) && body.mode === "json" && body.json) {
         const bodyPairs = jsonToRfDictPairs(body.json, varMap);
@@ -1853,6 +1866,12 @@ function buildKeywordsFile(collection, varMap, nameMap, hookExtractedVars) {
       const url = interpolate(req.url, varMap);
       lines.push(kwName);
       lines.push(`    [Documentation]    ${req.description || req.name}`);
+      if (!ROBOT_REQUESTS_METHODS.includes(req.method)) {
+        lines.push(`    Log    ${req.method} is not supported by robotframework-requests — request skipped    WARN`);
+        lines.push(`    RETURN    \${None}`);
+        lines.push("");
+        continue;
+      }
       const inherited = requestCollection.resolveInheritedAuthAndHeaders(reqId, collection);
       const effectiveAuth = resolveEffectiveAuth(req, inherited);
       const allHeaders = mergeHeaders(req, inherited);
@@ -2084,12 +2103,15 @@ function buildHookLines$1(req, sharedVars) {
     } catch {
     }
   }
+  const nativeVerb = PLAYWRIGHT_VERBS.includes(method);
+  if (!nativeVerb) optionParts.unshift(`method: '${req.method}'`);
   const opts = optionParts.length ? `, { ${optionParts.join(", ")} }` : "";
+  const hookCall = nativeVerb ? `request.${method}(${pathExpr}${opts})` : `request.fetch(${pathExpr}${opts})`;
   const lines = [];
   lines.push(`    // ${req.name}`);
   const parsed = parsePostScript(req.postRequestScript);
   if (parsed.extractions.length > 0) {
-    lines.push(`    const hookResponse = await request.${method}(${pathExpr}${opts});`);
+    lines.push(`    const hookResponse = await ${hookCall};`);
     lines.push(`    const hookJson = await hookResponse.json();`);
     for (const e of parsed.extractions) {
       const jsonPath = e.accessor.replace(/^json\.?/, "");
@@ -2099,7 +2121,7 @@ function buildHookLines$1(req, sharedVars) {
       lines.push(`    ${varName} = String(${expr});`);
     }
   } else {
-    lines.push(`    await request.${method}(${pathExpr}${opts});`);
+    lines.push(`    await ${hookCall};`);
   }
   return lines;
 }
@@ -2199,13 +2221,16 @@ ${lines.join("\n")}
         optionParts.push(`      data: \`${interpolateEnvVars(req.body.json, sharedVars)}\``);
       }
     }
+    const nativeVerb = PLAYWRIGHT_VERBS.includes(method);
+    if (!nativeVerb) optionParts.unshift(`      method: '${req.method}'`);
     const optionsStr = optionParts.length ? `, {
 ${optionParts.join(",\n")},
     }` : "";
+    const callExpr = nativeVerb ? `request.${method}(${pathExpr}${optionsStr})` : `request.fetch(${pathExpr}${optionsStr})`;
     const parsed = parsePostScript(req.postRequestScript);
     const lines = [
       `  test('${testName}', async ({ request }) => {`,
-      `    const response = await request.${method}(${pathExpr}${optionsStr});`
+      `    const response = await ${callExpr};`
     ];
     const needsJson = parsed.assertions.some((a) => a.accessor.startsWith("json")) || parsed.extractions.length > 0;
     if (needsJson) {
@@ -2364,11 +2389,14 @@ function buildHookLines(req, sharedVars) {
     } catch {
     }
   }
+  const nativeVerb = PLAYWRIGHT_VERBS.includes(method);
+  if (!nativeVerb) optParts.unshift(`method: '${req.method}'`);
   const opts = optParts.length ? `, { ${optParts.join(", ")} }` : "";
+  const hookCall = nativeVerb ? `request.${method}(${pathExpr}${opts})` : `request.fetch(${pathExpr}${opts})`;
   const lines = [`    // ${req.name}`];
   const parsed = parsePostScript(req.postRequestScript);
   if (parsed.extractions.length > 0) {
-    lines.push(`    const hookResponse = await request.${method}(${pathExpr}${opts});`);
+    lines.push(`    const hookResponse = await ${hookCall};`);
     lines.push(`    const hookJson = await hookResponse.json();`);
     for (const e of parsed.extractions) {
       const jp = e.accessor.replace(/^json\.?/, "");
@@ -2378,7 +2406,7 @@ function buildHookLines(req, sharedVars) {
       lines.push(`    ${varName} = String(${expr});`);
     }
   } else {
-    lines.push(`    await request.${method}(${pathExpr}${opts});`);
+    lines.push(`    await ${hookCall};`);
   }
   return lines;
 }
@@ -2476,13 +2504,16 @@ ${lines.join("\n")}
         optionParts.push(`      data: \`${interpolateEnvVars(req.body.json, sharedVars)}\``);
       }
     }
+    const nativeVerb = PLAYWRIGHT_VERBS.includes(method);
+    if (!nativeVerb) optionParts.unshift(`      method: '${req.method}'`);
     const optionsStr = optionParts.length ? `, {
 ${optionParts.join(",\n")},
     }` : "";
+    const callExpr = nativeVerb ? `request.${method}(${pathExpr}${optionsStr})` : `request.fetch(${pathExpr}${optionsStr})`;
     const parsed = parsePostScript(req.postRequestScript);
     const lines = [
       `  test('${testName}', async ({ request }) => {`,
-      `    const response = await request.${method}(${pathExpr}${optionsStr});`
+      `    const response = await ${callExpr};`
     ];
     const needsJson = parsed.assertions.some((a) => a.accessor.startsWith("json")) || parsed.extractions.length > 0;
     if (needsJson) {
@@ -2643,6 +2674,10 @@ function buildTestFile$1(folderName, folder, collection) {
   function buildSupertestHookLines(h) {
     const lines = [`    // ${h.name}`];
     const method = h.method.toLowerCase();
+    if (!SUPERTEST_VERBS.includes(method)) {
+      lines.push(`    // ${h.method} (RFC 10008) is not supported by supertest -- hook skipped`);
+      return lines;
+    }
     const path2 = h.url.replace(/^https?:\/\/[^/]+/, "") || "/";
     const parsed = parsePostScript(h.postRequestScript);
     if (parsed.extractions.length > 0) {
@@ -2687,6 +2722,13 @@ ${lines.join("\n")}
     const allHeaders = mergeHeaders(req, inherited);
     const enabledParams = req.params.filter((p) => p.enabled && p.key);
     const lines = [];
+    if (!SUPERTEST_VERBS.includes(method)) {
+      lines.push(`  // ${req.method} (RFC 10008) is not supported by supertest`);
+      lines.push(`  it.skip('${nameMap.get(reqId)} [${req.method} unsupported]', () => {});`);
+      lines.push("");
+      tests.push(...lines);
+      continue;
+    }
     lines.push(`  it('${nameMap.get(reqId)}', async () => {`);
     lines.push(`    const res = await api`);
     lines.push(`      .${method}(\`${path2}\`)`);
@@ -2896,6 +2938,10 @@ function buildTestFile(folderName, folder, collection) {
   function buildJsHookLines(h) {
     const lines = [`    // ${h.name}`];
     const method = h.method.toLowerCase();
+    if (!SUPERTEST_VERBS.includes(method)) {
+      lines.push(`    // ${h.method} (RFC 10008) is not supported by supertest -- hook skipped`);
+      return lines;
+    }
     const path2 = h.url.replace(/^https?:\/\/[^/]+/, "") || "/";
     const parsed = parsePostScript(h.postRequestScript);
     if (parsed.extractions.length > 0) {
@@ -2940,6 +2986,13 @@ ${lines.join("\n")}
     const allHeaders = mergeHeaders(req, inherited);
     const enabledParams = req.params.filter((p) => p.enabled && p.key);
     const lines = [];
+    if (!SUPERTEST_VERBS.includes(method)) {
+      lines.push(`  // ${req.method} (RFC 10008) is not supported by supertest`);
+      lines.push(`  it.skip('${nameMap.get(reqId)} [${req.method} unsupported]', () => {});`);
+      lines.push("");
+      tests.push(...lines);
+      continue;
+    }
     lines.push(`  it('${nameMap.get(reqId)}', async () => {`);
     lines.push(`    const res = await api`);
     lines.push(`      .${method}(\`${path2}\`)`);
@@ -3234,7 +3287,7 @@ function buildTestClass(folderName, folder, collection) {
         const escaped = h.body.json.replace(/"/g, '\\"').replace(/\n/g, "\\n");
         lines.push(`            .body("${escaped}")`);
       }
-      lines.push(`            .when().${method}("${path2}");`);
+      lines.push(`            .when()${restAssuredCall(method, `"${path2}"`)};`);
       for (const e of parsed.extractions) {
         const jp = accessorToJsonPath(e.accessor);
         const varName = toEnvVar(e.varName);
@@ -3242,7 +3295,7 @@ function buildTestClass(folderName, folder, collection) {
         lines.push(`        ${varName} = hookResponse.jsonPath().getString("${jp}");`);
       }
     } else {
-      lines.push(`        given().spec(requestSpec).when().${method}("${path2}");`);
+      lines.push(`        given().spec(requestSpec).when()${restAssuredCall(method, `"${path2}"`)};`);
     }
     return lines;
   }
@@ -3318,7 +3371,7 @@ ${lines.join("\n")}
       }
     }
     lines.push(`        .when()`);
-    lines.push(`            .${method}(${javaPath})`);
+    lines.push(`            ${restAssuredCall(method, javaPath)}`);
     lines.push(`        .then()`);
     const parsed = parsePostScript(req.postRequestScript);
     if (parsed.assertions.length > 0) {

package/out/main/runner.js

@@ -393,7 +393,7 @@ async function main() {
   if (envName && !env) {
     console.warn(cliCommon.color(`Warning: environment "${envName}" not found. Running without environment.`, cliCommon.C.yellow));
   }
-  const version = `v${"0.3.3"}`;
+  const version = `v${"0.3.5"}`;
   console.log("");
   console.log(cliCommon.color("  API Test Runner" + (version ? ` ${version}` : ""), cliCommon.C.bold, cliCommon.C.white));
   console.log(cliCommon.color(`  Workspace:   ${wsPath}`, cliCommon.C.gray));