test: improve nut coverage, standardize helpers, add docs

- Add 4 tests: auto-select, dev.port manifest, empty manifest, --port+--url
- Add comments explaining what each test verifies
- Extract timeout constants (SUITE_TIMEOUT, SPAWN_TIMEOUT, SPAWN_FAIL_TIMEOUT)
- Add optional proxyPort to createProjectWithDevServer
- Simplify manifests to dev-only props (name/label/version unused by command)
- Add webappPath() helper, standardize webapps path usage
- Use closeServer for blocker cleanup in devPort.nut.ts
- Document port ranges and TIME_WAIT rationale in devServerUtils

Made-with: Cursor

Author: deepu-mungamuri94

test/commands/webapp/dev.nut.ts

@@ -23,13 +23,16 @@ import {
   createEmptyWebappsDir,
   createWebappDirWithoutMeta,
   writeManifest,
+  webappPath,
   ensureSfCli,
   authOrgViaUrl,
 } from './helpers/webappProjectUtils.js';
 
 /* ------------------------------------------------------------------ *
  *  Tier 1 — No Auth                                                   *
- *  Uses devhubAuthStrategy: 'NONE'. Always runs (CI + local).        *
+ *                                                                     *
+ *  Validates flag-level parse errors that fire before any org or      *
+ *  filesystem interaction. No credentials needed; always runs.        *
  * ------------------------------------------------------------------ */
 describe('webapp dev NUTs — Tier 1 (no auth)', () => {
   let session: TestSession;
@@ -42,6 +45,8 @@ describe('webapp dev NUTs — Tier 1 (no auth)', () => {
     await session?.clean();
   });
 
+  // --target-org is declared as Flags.requiredOrg(). Running without it
+  // must fail at parse time with NoDefaultEnvError before any other logic.
   it('should require --target-org', () => {
     const result = execCmd('webapp dev --json', {
       ensureExitCode: 1,
@@ -55,9 +60,12 @@ describe('webapp dev NUTs — Tier 1 (no auth)', () => {
 
 /* ------------------------------------------------------------------ *
  *  Tier 2 — CLI Validation (with auth)                                *
- *  Requires TESTKIT_AUTH_URL or JWT credentials.                      *
- *  Skips gracefully when no credentials are present.                  *
- *  These tests exercise local validation only — no live org calls.    *
+ *                                                                     *
+ *  Validates webapp discovery errors and URL resolution errors.       *
+ *  Auth is only needed so --target-org passes parsing; these tests    *
+ *  exercise local filesystem/network checks — no live org calls.      *
+ *                                                                     *
+ *  Requires TESTKIT_AUTH_URL. Skips gracefully when absent.           *
  * ------------------------------------------------------------------ */
 describe('webapp dev NUTs — Tier 2 CLI validation', () => {
   let session: TestSession;
@@ -80,6 +88,7 @@ describe('webapp dev NUTs — Tier 2 CLI validation', () => {
 
   // ── Discovery errors ──────────────────────────────────────────
 
+  // Project has no webapplications folder at all → WebappNotFoundError.
   it('should error when no webapp found (project only, no webapps)', () => {
     const projectDir = createProject(session, 'noWebappProject');
 
@@ -91,6 +100,7 @@ describe('webapp dev NUTs — Tier 2 CLI validation', () => {
     expect(result.jsonOutput?.name).to.equal('WebappNotFoundError');
   });
 
+  // Project has webapp "realApp" but --name asks for "NonExistent" → WebappNameNotFoundError.
   it('should error when --name does not match any webapp', () => {
     const projectDir = createProjectWithWebapp(session, 'nameNotFound', 'realApp');
 
@@ -102,11 +112,13 @@ describe('webapp dev NUTs — Tier 2 CLI validation', () => {
     expect(result.jsonOutput?.name).to.equal('WebappNameNotFoundError');
   });
 
+  // cwd is inside webapp "appA" but --name asks for "appB" → WebappNameConflictError.
+  // Discovery treats this as ambiguous intent and rejects it.
   it('should error on --name conflict when inside a different webapp', () => {
     const projectDir = createProjectWithWebapp(session, 'nameConflict', 'appA');
     execSync('sf webapp generate --name appB', { cwd: projectDir, stdio: 'pipe' });
 
-    const cwdInsideAppA = `${projectDir}/force-app/main/default/webapplications/appA`;
+    const cwdInsideAppA = webappPath(projectDir, 'appA');
 
     const result = execCmd(`webapp dev --name appB --target-org ${targetOrg} --json`, {
       ensureExitCode: 1,
@@ -116,6 +128,7 @@ describe('webapp dev NUTs — Tier 2 CLI validation', () => {
     expect(result.jsonOutput?.name).to.equal('WebappNameConflictError');
   });
 
+  // webapplications/ folder exists but is empty → WebappNotFoundError.
   it('should error when webapplications folder is empty', () => {
     const projectDir = createProject(session, 'emptyWebapps');
     createEmptyWebappsDir(projectDir);
@@ -128,6 +141,7 @@ describe('webapp dev NUTs — Tier 2 CLI validation', () => {
     expect(result.jsonOutput?.name).to.equal('WebappNotFoundError');
   });
 
+  // webapplications/orphanApp/ exists but has no .webapplication-meta.xml → not a valid webapp.
   it('should error when webapp dir has no .webapplication-meta.xml', () => {
     const projectDir = createProject(session, 'noMeta');
     createWebappDirWithoutMeta(projectDir, 'orphanApp');
@@ -140,8 +154,35 @@ describe('webapp dev NUTs — Tier 2 CLI validation', () => {
     expect(result.jsonOutput?.name).to.equal('WebappNotFoundError');
   });
 
+  // ── Auto-selection ────────────────────────────────────────────
+
+  // When cwd is inside webapplications/myApp/, discovery auto-selects that
+  // webapp without --name. The command proceeds past discovery and fails at
+  // URL resolution (no dev server running) — confirming auto-select worked.
+  it('should auto-select webapp when run from inside its directory', () => {
+    const projectDir = createProjectWithWebapp(session, 'autoSelect', 'myApp');
+
+    writeManifest(projectDir, 'myApp', {
+      dev: { url: 'http://localhost:5179' },
+    });
+
+    const cwdInsideApp = webappPath(projectDir, 'myApp');
+
+    // No --name flag; cwd is inside the webapp directory.
+    // Discovery auto-selects myApp, then the command fails at URL check
+    // (nothing running on 5179). DevServerUrlError proves discovery succeeded.
+    const result = execCmd(`webapp dev --target-org ${targetOrg} --json`, {
+      ensureExitCode: 1,
+      cwd: cwdInsideApp,
+    });
+
+    expect(result.jsonOutput?.name).to.equal('DevServerUrlError');
+  });
+
   // ── URL / dev server errors ───────────────────────────────────
 
+  // --url explicitly provided but nothing is listening → DevServerUrlError.
+  // The command refuses to start a dev server when --url is given.
   it('should error when --url is unreachable', () => {
     const projectDir = createProjectWithWebapp(session, 'urlUnreachable', 'myApp');
 
@@ -153,17 +194,13 @@ describe('webapp dev NUTs — Tier 2 CLI validation', () => {
     expect(result.jsonOutput?.name).to.equal('DevServerUrlError');
   });
 
+  // Manifest has dev.url but no dev.command → command can't start the server
+  // itself and the URL is unreachable → DevServerUrlError.
   it('should error when dev.url is unreachable and no dev.command', () => {
     const projectDir = createProjectWithWebapp(session, 'urlNoCmd', 'myApp');
 
     writeManifest(projectDir, 'myApp', {
-      name: 'myApp',
-      label: 'My App',
-      version: '1.0.0',
-      outputDir: 'dist',
-      dev: {
-        url: 'http://localhost:5179',
-      },
+      dev: { url: 'http://localhost:5179' },
     });
 
     const result = execCmd(`webapp dev --name myApp --target-org ${targetOrg} --json`, {

test/commands/webapp/devPort.nut.ts

@@ -17,13 +17,24 @@
 import type { Server } from 'node:net';
 import { TestSession } from '@salesforce/cli-plugins-testkit';
 import { expect } from 'chai';
-import { createProjectWithDevServer, writeManifest, ensureSfCli, authOrgViaUrl } from './helpers/webappProjectUtils.js';
-import { occupyPort, spawnWebappDev, type WebappDevHandle } from './helpers/devServerUtils.js';
+import { createProjectWithDevServer, ensureSfCli, authOrgViaUrl } from './helpers/webappProjectUtils.js';
+import {
+  occupyPort,
+  spawnWebappDev,
+  closeServer,
+  SUITE_TIMEOUT,
+  SPAWN_TIMEOUT,
+  SPAWN_FAIL_TIMEOUT,
+  type WebappDevHandle,
+} from './helpers/devServerUtils.js';
 
 /* ------------------------------------------------------------------ *
  *  Tier 2 — Port Handling                                             *
  *                                                                     *
- *  Tests proxy port conflict (PortInUseError) and auto-increment.     *
+ *  Validates proxy port resolution logic:                             *
+ *    - Explicit --port or dev.port occupied → PortInUseError          *
+ *    - Default port occupied → auto-increment to next available       *
+ *    - Explicit --port or dev.port available → proxy binds to it      *
  *                                                                     *
  *  Requires TESTKIT_AUTH_URL. Skips otherwise.                        *
  * ------------------------------------------------------------------ */
@@ -32,7 +43,7 @@ const DEV_PORT = 18_910;
 const PROXY_PORT = 18_920;
 
 describe('webapp dev NUTs — Tier 2 port handling', function () {
-  this.timeout(180_000);
+  this.timeout(SUITE_TIMEOUT);
 
   let session: TestSession;
   let targetOrg: string;
@@ -55,18 +66,16 @@ describe('webapp dev NUTs — Tier 2 port handling', function () {
       await handle.kill();
       handle = null;
     }
-    if (blocker) {
-      await new Promise<void>((resolve) => {
-        blocker!.close(() => resolve());
-      });
-      blocker = null;
-    }
+    await closeServer(blocker);
+    blocker = null;
   });
 
   after(async () => {
     await session?.clean();
   });
 
+  // When --port is explicitly provided and that port is already occupied,
+  // the command must fail with PortInUseError (no auto-increment).
   it('should throw PortInUseError when explicit --port is occupied', async () => {
     blocker = await occupyPort(PROXY_PORT);
 
@@ -75,66 +84,74 @@ describe('webapp dev NUTs — Tier 2 port handling', function () {
     try {
       handle = await spawnWebappDev(['--name', 'myApp', '--port', String(PROXY_PORT), '--target-org', targetOrg], {
         cwd: projectDir,
-        timeout: 60_000,
+        timeout: SPAWN_FAIL_TIMEOUT,
       });
       expect.fail('Expected command to fail with PortInUseError');
     } catch (err) {
       expect((err as Error).message).to.include('PortInUseError');
     }
   });
 
+  // When dev.port is set in the manifest and that port is occupied,
+  // it is treated as an explicit configuration → PortInUseError (no auto-increment).
   it('should throw PortInUseError when dev.port in manifest is occupied', async () => {
-    const { projectDir } = createProjectWithDevServer(session, 'manifestPort', 'myApp', DEV_PORT + 1);
-
-    writeManifest(projectDir, 'myApp', {
-      name: 'myApp',
-      label: 'My App',
-      version: '1.0.0',
-      outputDir: 'dist',
-      dev: {
-        url: `http://localhost:${DEV_PORT + 1}`,
-        command: 'node dev-server.cjs',
-        port: PROXY_PORT + 1,
-      },
-    });
+    const { projectDir } = createProjectWithDevServer(session, 'manifestPort', 'myApp', DEV_PORT + 1, PROXY_PORT + 1);
 
     blocker = await occupyPort(PROXY_PORT + 1);
 
     try {
       handle = await spawnWebappDev(['--name', 'myApp', '--target-org', targetOrg], {
         cwd: projectDir,
-        timeout: 60_000,
+        timeout: SPAWN_FAIL_TIMEOUT,
       });
       expect.fail('Expected command to fail with PortInUseError');
     } catch (err) {
       expect((err as Error).message).to.include('PortInUseError');
     }
   });
 
+  // When no --port or dev.port is configured, the default (4545) is used.
+  // If 4545 is occupied, the command silently tries the next port.
   it('should auto-increment port when default port (4545) is occupied', async () => {
     blocker = await occupyPort(4545);
 
     const { projectDir } = createProjectWithDevServer(session, 'portAutoInc', 'myApp', DEV_PORT + 2);
 
     handle = await spawnWebappDev(['--name', 'myApp', '--target-org', targetOrg], {
       cwd: projectDir,
-      timeout: 120_000,
+      timeout: SPAWN_TIMEOUT,
     });
 
     const proxyPort = new URL(handle.proxyUrl).port;
     expect(Number(proxyPort)).to.be.greaterThan(4545);
   });
 
+  // --port flag with an available port → proxy binds exactly to that port.
   it('should use custom --port when specified and available', async () => {
     const customPort = PROXY_PORT + 5;
 
     const { projectDir } = createProjectWithDevServer(session, 'customPort', 'myApp', DEV_PORT + 3);
 
     handle = await spawnWebappDev(['--name', 'myApp', '--port', String(customPort), '--target-org', targetOrg], {
       cwd: projectDir,
-      timeout: 120_000,
+      timeout: SPAWN_TIMEOUT,
     });
 
     expect(handle.proxyUrl).to.equal(`http://localhost:${customPort}`);
   });
+
+  // dev.port in manifest with an available port (no --port flag) →
+  // proxy binds to the manifest-configured port.
+  it('should use dev.port from manifest when available', async () => {
+    const manifestPort = PROXY_PORT + 6;
+
+    const { projectDir } = createProjectWithDevServer(session, 'manifestPortOk', 'myApp', DEV_PORT + 4, manifestPort);
+
+    handle = await spawnWebappDev(['--name', 'myApp', '--target-org', targetOrg], {
+      cwd: projectDir,
+      timeout: SPAWN_TIMEOUT,
+    });
+
+    expect(handle.proxyUrl).to.equal(`http://localhost:${manifestPort}`);
+  });
 });