test: integration test for the local cmp preview @W-18852148

Author: lesya7

.env.template

@@ -0,0 +1,19 @@
+# JWT private key 
+TESTKIT_JWT_KEY="-----BEGIN RSA PRIVATE KEY-----
+FAKEPRIVATEKEY1234567890abcdefg==
+-----END RSA PRIVATE KEY-----"
+
+# Connected App Client ID for JWT auth
+TESTKIT_JWT_CLIENT_ID=FAKE_CLIENT_ID_123456
+
+# Username of your Dev Hub org
+TESTKIT_HUB_USERNAME=test-user@example.com
+
+# Path to the Salesforce CLI executable
+TESTKIT_EXECUTABLE_PATH=./node_modules/.bin/sf
+
+# Instance URL of your Dev Hub org
+TESTKIT_HUB_INSTANCE=https://fake-devhub-instance.salesforce.com
+
+# Prevent the dev server from opening the browser during tests
+OPEN_BROWSER=false

.gitignore

@@ -56,4 +56,9 @@ bld
 
 # sf cli
 .sf
-.sfdx
+.sfdx
+
+stdout*
+stderr*
+
+.env

README.md

@@ -304,4 +304,68 @@ EXAMPLES
 
 _See code: [src/commands/lightning/dev/site.ts](https://github.com/salesforcecli/plugin-lightning-dev/blob/4.0.4/src/commands/lightning/dev/site.ts)_
 
+## Integration Testing
+
+This plugin includes integration (NUT) tests for verifying the Lightning Dev Server functionality using SFDX projects and components. Test data like SFDX projects are created at runtime by the testkit.
+
+### Prerequisites
+
+**Connected App Setup**
+Follow the [Connected App Setup Guide](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth_connected_app.htm) to:
+
+- Create a connected app
+- Enable JWT OAuth
+- Configure callback URL and OAuth scopes
+
+**JWT Credentials**
+Follow the [Private Key and Certificate Setup Guide](https://developer.salesforce.com/docs/atlas.en-us.sfdx_dev.meta/sfdx_dev/sfdx_dev_auth_key_and_cert.htm) to:
+
+- Generate a private key and certificate
+- Upload certificate to the connected app
+
+Set the environment variables (copy from `.env.template` to `.env`):
+
+- `TESTKIT_JWT_CLIENT_ID` - Your connected app client ID
+- `TESTKIT_JWT_KEY` - Your private key contents
+- `TESTKIT_HUB_INSTANCE` - Salesforce instance URL
+- `TESTKIT_ORG_USERNAME` - Your org username for testing
+- `OPEN_BROWSER` - Control browser opening (true/false)
+
+### Running Tests
+
+Run all or specific integration tests (NUTs) via:
+
+```bash
+# Run all integration tests
+yarn test:nuts
+
+# Run by category
+yarn test:nuts "test/commands/lightning/dev/component*.nut.ts"
+
+# Run with environment variables
+OPEN_BROWSER=false NODE_ENV=production yarn test:nuts
+```
+
+### Test Data Structure
+
+The testkit creates SFDX projects and test data at runtime:
+
+```
+test/
+├── testdata/
+│   ├── lwc/
+│   │   └── helloWorld/
+│   └── project-definition.json
+```
+
+### Automation with TestKit
+
+Tests use [@salesforce/cli-plugins-testkit](https://github.com/salesforcecli/cli-plugins-testkit) for:
+
+- Temporary project creation at runtime
+- JWT-based org login
+- Cleanup after each run
+
+No manual authentication is needed. Set the required environment variables once and run tests headlessly.
+
 <!-- commandsstop -->

package.json

@@ -24,12 +24,14 @@
   },
   "devDependencies": {
     "@oclif/plugin-command-snapshot": "^5.3.2",
+    "@salesforce/cli": "^2.93.7",
     "@salesforce/cli-plugins-testkit": "^5.3.39",
     "@salesforce/dev-scripts": "^11.0.2",
     "@salesforce/plugin-command-reference": "^3.1.56",
     "@types/node-fetch": "^2.6.12",
     "@types/xml2js": "^0.4.14",
     "@typescript-eslint/eslint-plugin": "^6.21.0",
+    "dotenv": "^16.5.0",
     "eslint": "^8.57.0",
     "eslint-config-prettier": "^9.1.0",
     "eslint-plugin-header": "^3.1.1",
@@ -257,7 +259,7 @@
   "exports": "./lib/index.js",
   "type": "module",
   "volta": {
-    "node": "20.11.0",
+    "node": "20.19.3",
     "yarn": "1.22.22"
   }
 }

src/commands/lightning/dev/component.ts

@@ -32,6 +32,11 @@ export default class LightningDevComponent extends SfCommand<void> {
       char: 'c',
       default: false,
     }),
+    port: Flags.integer({
+      summary: 'Port number for the development server',
+      char: 'p',
+      default: 3000,
+    }),
     // TODO should this be required or optional?
     // We don't technically need this if your components are simple / don't need any data from your org
     'target-org': Flags.optionalOrg(),
@@ -96,14 +101,15 @@ export default class LightningDevComponent extends SfCommand<void> {
 
     const dirname = path.dirname(url.fileURLToPath(import.meta.url));
     const rootDir = path.resolve(dirname, '../../../..');
-    const port = parseInt(process.env.PORT ?? '3000', 10);
+    const port = flags.port;
 
     await cmpDev({
       rootDir,
       mode: 'dev',
       port,
       name: name ? `c/${name}` : undefined,
       namespacePaths,
+      open: process.env.OPEN_BROWSER ? process.env.OPEN_BROWSER === 'true' : false,
     });
   }
 }

src/shared/componentUtils.ts

@@ -26,6 +26,12 @@ export class ComponentUtils {
     return componentName.replace(/([A-Z])/g, ' $1').replace(/^./, (str) => str.toUpperCase());
   }
 
+  public static toKebabCase(str: string): string {
+    return str
+      .replace(/([a-z0-9])([A-Z])/g, '$1-$2') // insert dash between camelCase boundaries
+      .toLowerCase();
+  }
+
   public static async getNamespacePaths(project: SfProject): Promise<string[]> {
     const packageDirs = project.getPackageDirectories();
 

src/shared/experience/expSite.ts

@@ -258,8 +258,8 @@ export class ExperienceSite {
       // eslint-disable-next-line @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-member-access
       response.data.pipe(fileStream);
 
-      await new Promise((resolve, reject) => {
-        fileStream.on('finish', resolve);
+      await new Promise<void>((resolve, reject) => {
+        fileStream.on('finish', () => resolve());
         fileStream.on('error', reject);
       });
       this.saveMetadata(metadata);

test/commands/lightning/dev/componentLocalPreview.nut.ts

@@ -0,0 +1,124 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import { expect } from 'chai';
+import { TestSession } from '@salesforce/cli-plugins-testkit';
+import dotenv from 'dotenv';
+import axios from 'axios';
+import { ComponentUtils } from '../../../../src/shared/componentUtils.js';
+import { createSfdxProject, createLwcComponent } from './helpers/projectSetup.js';
+import { startLightningDevServer } from './helpers/devServerUtils.js';
+
+dotenv.config();
+
+const INSTANCE_URL = process.env.TESTKIT_HUB_INSTANCE;
+const TEST_TIMEOUT_MS = 60_000;
+const STARTUP_DELAY_MS = 5000;
+const DEV_SERVER_PORT = 3000;
+
+describe('LWC Local Preview Integration', () => {
+  let session: TestSession;
+  let componentName: string;
+  let projectDir: string;
+
+  before(async () => {
+    componentName = 'helloWorld';
+
+    session = await TestSession.create({ devhubAuthStrategy: 'JWT' });
+
+    const timestamp = Date.now();
+    projectDir = path.join(session.dir, `lwc-project-${timestamp}`);
+    fs.mkdirSync(projectDir, { recursive: true });
+
+    await Promise.all([
+      createSfdxProject(projectDir, INSTANCE_URL ?? ''),
+      createLwcComponent(projectDir, componentName),
+    ]);
+  });
+
+  after(async () => {
+    await session?.clean();
+  });
+
+  it('should start lightning dev server and respond to /c-hello-world/ URL', async function () {
+    this.timeout(TEST_TIMEOUT_MS);
+
+    let stderrOutput = '';
+    let stdoutOutput = '';
+    let exitedEarly = false;
+    let exitCode: number | null = null;
+
+    const serverProcess = startLightningDevServer(projectDir, componentName);
+
+    serverProcess.stderr?.on('data', (data: Buffer) => {
+      stderrOutput += data.toString();
+    });
+
+    serverProcess.stdout?.on('data', (data: Buffer) => {
+      stdoutOutput += data.toString();
+    });
+
+    serverProcess.on('exit', (code: number) => {
+      exitedEarly = true;
+      exitCode = code;
+    });
+
+    serverProcess.on('error', (error) => {
+      exitedEarly = true;
+      stderrOutput += `Process error: ${String(error)}\n`;
+    });
+
+    // Wait for server startup
+    await new Promise((r) => setTimeout(r, STARTUP_DELAY_MS));
+
+    // Test the kebab-case component URL with /c- prefix
+    const componentKebabName = ComponentUtils.toKebabCase(componentName);
+    const componentUrl = `http://localhost:${DEV_SERVER_PORT}/c-${componentKebabName}/`;
+    let componentHttpSuccess = false;
+
+    try {
+      const componentResponse = await axios.get(componentUrl, { timeout: 2000 });
+      componentHttpSuccess = componentResponse.status === 200;
+    } catch (error) {
+      const err = error as { message?: string };
+      stderrOutput += `Component URL HTTP request failed: ${err.message ?? 'Unknown error'}\n`;
+      componentHttpSuccess = false;
+    }
+
+    // Clean up
+    try {
+      if (serverProcess.pid && process.kill(serverProcess.pid, 0)) {
+        process.kill(serverProcess.pid, 'SIGKILL');
+      }
+    } catch (error) {
+      const err = error as NodeJS.ErrnoException;
+      if (err.code !== 'ESRCH') throw error;
+    }
+
+    // Stderr error check
+    const criticalPatterns = [
+      'FATAL',
+      'Cannot find module',
+      'ENOENT',
+      'Unable to find component',
+      'command lightning:dev:component not found',
+    ];
+    const hasCriticalError = criticalPatterns.some((pattern) => stderrOutput.includes(pattern));
+
+    expect(
+      exitedEarly,
+      `Dev server exited early with code ${exitCode}. Full stderr: ${stderrOutput}. Full stdout: ${stdoutOutput}`
+    ).to.be.false;
+    expect(hasCriticalError, `Critical stderr output detected:\n${stderrOutput}`).to.be.false;
+    expect(
+      componentHttpSuccess,
+      `Dev server did not respond with HTTP 200 for component URL. Tried URL: ${componentUrl}`
+    ).to.be.true;
+  });
+});

test/commands/lightning/dev/helpers/devServerUtils.ts

@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+import path from 'node:path';
+import { spawn, ChildProcess } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const currentFile = fileURLToPath(import.meta.url);
+const currentDir = path.dirname(currentFile);
+const pluginRoot = path.resolve(currentDir, '../../../../..');
+
+export const startLightningDevServer = (projectDir: string, componentName: string): ChildProcess => {
+  const devScriptPath = path.join(pluginRoot, 'bin', 'run.js');
+
+  return spawn('node', [devScriptPath, 'lightning', 'dev', 'component', '--name', componentName], {
+    cwd: projectDir,
+    env: { ...process.env, NODE_ENV: 'production', PORT: '3000', OPEN_BROWSER: process.env.OPEN_BROWSER ?? 'false' },
+  });
+};

test/commands/lightning/dev/helpers/projectSetup.ts

@@ -0,0 +1,70 @@
+/*
+ * Copyright (c) 2025, salesforce.com, inc.
+ * All rights reserved.
+ * Licensed under the BSD 3-Clause license.
+ * For full license text, see LICENSE.txt file in the repo root or https://opensource.org/licenses/BSD-3-Clause
+ */
+
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const currentFile = fileURLToPath(import.meta.url);
+const currentDir = path.dirname(currentFile);
+
+const TEMPLATE_DIR = path.resolve(currentDir, '../testdata/lwc/helloWorld');
+const SCRATCH_DEF_PATH = path.resolve(currentDir, '../testdata/project-definition.json');
+
+let templateCache: { js: string; html: string; meta: string } | null = null;
+
+const loadTemplateContent = async (): Promise<{ js: string; html: string; meta: string }> => {
+  if (!templateCache) {
+    const [js, html, meta] = await Promise.all([
+      fs.promises.readFile(path.join(TEMPLATE_DIR, 'helloWorld.js'), 'utf8'),
+      fs.promises.readFile(path.join(TEMPLATE_DIR, 'helloWorld.html'), 'utf8'),
+      fs.promises.readFile(path.join(TEMPLATE_DIR, 'helloWorld.js-meta.xml'), 'utf8'),
+    ]);
+    templateCache = { js, html, meta };
+  }
+  return templateCache;
+};
+
+export const createSfdxProject = async (projectDir: string, customInstanceUrl: string): Promise<void> => {
+  const sfdxProject = {
+    packageDirectories: [{ path: 'force-app', default: true }],
+    name: 'temp-project',
+    namespace: '',
+    instanceUrl: customInstanceUrl,
+    sourceApiVersion: '60.0',
+  };
+
+  // Parallel operations: create directories and read scratch def
+  const [, scratchDefContent] = await Promise.all([
+    Promise.all([
+      fs.promises.mkdir(path.join(projectDir, 'force-app', 'main', 'default', 'lwc'), { recursive: true }),
+      fs.promises.mkdir(path.join(projectDir, 'config'), { recursive: true }),
+    ]),
+    fs.promises.readFile(SCRATCH_DEF_PATH, 'utf8'),
+  ]);
+
+  await Promise.all([
+    fs.promises.writeFile(path.join(projectDir, 'sfdx-project.json'), JSON.stringify(sfdxProject, null, 2)),
+    fs.promises.writeFile(path.join(projectDir, 'config', 'project-scratch-def.json'), scratchDefContent),
+  ]);
+};
+
+export const createLwcComponent = async (projectDir: string, name: string): Promise<void> => {
+  const lwcPath = path.join(projectDir, 'force-app', 'main', 'default', 'lwc', name);
+
+  const [, templates] = await Promise.all([fs.promises.mkdir(lwcPath, { recursive: true }), loadTemplateContent()]);
+
+  await Promise.all([
+    fs.promises.writeFile(path.join(lwcPath, `${name}.js`), templates.js.replace(/helloWorld/g, name)),
+    fs.promises.writeFile(path.join(lwcPath, `${name}.html`), templates.html),
+    fs.promises.writeFile(path.join(lwcPath, `${name}.js-meta.xml`), templates.meta),
+  ]);
+};
+
+export const clearTemplateCache = (): void => {
+  templateCache = null;
+};