feat: add E2E NUT tests for webapp dev command @W-21111429@ (#32)

* feat: add E2E NUT tests for webapp dev command @W-21111429@

- Add Tier 1 (no auth) and Tier 2 (CLI validation) tests for dev.nut.ts
- Add devPort.nut.ts for --port and --proxy-port flag tests
- Add devWithUrl.nut.ts for --url, proxy detection, and Vite integration tests
- Add shared helpers: devServerUtils (spawn, port reservation) and webappProjectUtils
- Add _cleanup.nut.ts for test session cleanup
- Add .env.template for NUT credentials (TESTKIT_AUTH_URL, etc.)
- Update GitHub Actions to run NUTs on ubuntu-latest and windows-latest
- Fix Windows CI: use spawnWebappDev, taskkill, --sfdx-url-file auth
- Extend dev.ts to support OPEN_BROWSER=false for headless test runs

Author: deepu-mungamuri94

.env.template

@@ -0,0 +1,21 @@
+# ── NUT Credentials ──────────────────────────────────────────────
+# Only ONE of the two options below is needed.
+#
+# Option A: AUTH_URL (simplest — recommended for getting started)
+#   1. sf org login web --alias nut-org
+#   2. sf org display -o nut-org --json | jq -r .result.sfdxAuthUrl
+#   3. Paste the value below
+# TESTKIT_AUTH_URL=
+
+# Option B: JWT (no token expiration — recommended for CI)
+# TESTKIT_JWT_KEY=
+# TESTKIT_JWT_CLIENT_ID=
+# TESTKIT_HUB_USERNAME=
+# TESTKIT_HUB_INSTANCE=https://login.salesforce.com
+
+# ── Optional ─────────────────────────────────────────────────────
+# Path to sf CLI executable (defaults to global sf in PATH)
+# TESTKIT_EXECUTABLE_PATH=
+
+# Prevent browser from opening during tests
+OPEN_BROWSER=false

.github/workflows/test.yml

@@ -24,3 +24,4 @@ jobs:
       fail-fast: false
     with:
       os: ${{ matrix.os }}
+      retries: 3

.gitignore

@@ -44,6 +44,9 @@ node_modules
 # --
 # put files here you don't want cleaned with sf-clean
 
+# local NUT credentials
+.env
+
 # os specific files
 .DS_Store
 .idea

package.json

@@ -24,6 +24,7 @@
     "@salesforce/plugin-command-reference": "^3.1.77",
     "@types/http-proxy": "^1.17.14",
     "@types/micromatch": "^4.0.10",
+    "dotenv": "^17.3.1",
     "eslint-plugin-sf-plugin": "^1.20.33",
     "oclif": "^4.22.68",
     "ts-node": "^10.9.2",
@@ -82,7 +83,9 @@
     "prepack": "sf-prepack",
     "prepare": "sf-install",
     "test": "wireit",
-    "test:nuts": "nyc mocha \"**/*.nut.ts\" --slow 4500 --timeout 600000 --parallel",
+    "test:nuts": "mocha \"**/*.nut.ts\" --slow 4500 --timeout 300000 --parallel=false",
+    "test:nuts:local": "node -r dotenv/config ./node_modules/.bin/nyc mocha \"**/*.nut.ts\" --slow 4500 --timeout 300000 --parallel=false",
+    "test:nut:local": "node -r dotenv/config ./node_modules/.bin/nyc mocha --slow 4500 --timeout 300000",
     "test:only": "wireit",
     "version": "oclif readme"
   },

src/commands/webapp/dev.ts

@@ -291,10 +291,14 @@ export default class WebappDev extends SfCommand<WebAppDevResult> {
       } else if (flags.url) {
         // User explicitly passed --url; assume server is already running at that URL
         // Fail immediately if unreachable (don't start dev server)
-        throw new SfError(messages.getMessage('error.dev-url-unreachable-with-flag', [resolvedUrl]), 'DevServerUrlError', [
-          `Ensure your dev server is running at ${resolvedUrl}`,
-          'Remove --url to use dev.command to start the server automatically',
-        ]);
+        throw new SfError(
+          messages.getMessage('error.dev-url-unreachable-with-flag', [resolvedUrl]),
+          'DevServerUrlError',
+          [
+            `Ensure your dev server is running at ${resolvedUrl}`,
+            'Remove --url to use dev.command to start the server automatically',
+          ]
+        );
       } else if (manifest?.dev?.url && !manifest?.dev?.command?.trim()) {
         // dev.url in manifest but no dev.command - don't start (we can't control the port)
         throw new SfError(messages.getMessage('error.dev-url-unreachable', [resolvedUrl]), 'DevServerUrlError', [
@@ -439,7 +443,9 @@ export default class WebappDev extends SfCommand<WebAppDevResult> {
             await this.proxyServer.start();
           } catch (error) {
             const err = error as NodeJS.ErrnoException;
-            if (err.code === 'EADDRINUSE') {
+            const isAddrInUse =
+              err.code === 'EADDRINUSE' || (error instanceof SfError && error.name === 'PortInUseError');
+            if (isAddrInUse) {
               if (portExplicitlyConfigured) {
                 throw new SfError(messages.getMessage('error.port-in-use', [String(port)]), 'PortInUseError');
               }

src/error/DevServerErrorParser.ts

@@ -132,11 +132,11 @@ const ERROR_PATTERNS: ErrorPattern[] = [
 
   // Command not found - dependencies not installed
   {
-    pattern: /command not found|not recognized as.*command/i,
+    pattern: /command not found|not recognized as.*command|:\s+not found/i,
     type: 'missing-module',
     title: 'Dependencies Not Installed',
     getMessage: (stderr): string => {
-      const cmdMatch = stderr.match(/(?:sh:|bash:)\s*(\S+):\s*command not found/i);
+      const cmdMatch = stderr.match(/(?:sh:|bash:)\s*(?:\d+:\s*)?(\S+):\s*(?:command )?not found/i);
       const command = cmdMatch?.[1] ?? 'required command';
       return `Command '${command}' not found. Project dependencies may not be installed.`;
     },

test/commands/webapp/_cleanup.nut.ts

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2026, Salesforce, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * Root-level cleanup: remove any test_session_* directories left behind.
+ *
+ * TestSession.clean() normally deletes these, but they can persist when:
+ * - rm fails (e.g. Windows file locks from spawned processes)
+ * - Process is killed before after() runs (timeout, SIGKILL)
+ * - TESTKIT_SAVE_ARTIFACTS is set
+ *
+ * This hook runs after all NUTs complete as a fallback.
+ */
+after(() => {
+  const cwd = process.cwd();
+  try {
+    for (const name of readdirSync(cwd)) {
+      if (name.startsWith('test_session_')) {
+        try {
+          rmSync(join(cwd, name), { recursive: true, force: true });
+        } catch {
+          /* ignore per-dir failures */
+        }
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+});