@matware/e2e-runner 1.1.1 → 1.2.1

package/src/ai-generate.js

@@ -27,23 +27,74 @@ The test format is:
       { "type": "wait", "text": "Expected text" },
       { "type": "wait", "value": "2000" },
       { "type": "assert_text", "text": "Expected text on page" },
+      { "type": "assert_element_text", "selector": "#title", "text": "Dashboard" },
+      { "type": "assert_element_text", "selector": "#title", "text": "Dashboard", "value": "exact" },
+      { "type": "assert_attribute", "selector": "input#email", "value": "type=email" },
+      { "type": "assert_attribute", "selector": "button", "value": "disabled" },
+      { "type": "assert_class", "selector": ".nav-item", "value": "active" },
+      { "type": "assert_not_visible", "selector": ".error-banner" },
+      { "type": "assert_input_value", "selector": "#email", "value": "user@example.com" },
+      { "type": "assert_matches", "selector": ".phone", "value": "\\\\d{3}-\\\\d{3}-\\\\d{4}" },
       { "type": "assert_url", "value": "/expected-path" },
       { "type": "assert_visible", "selector": ".element" },
       { "type": "assert_count", "selector": ".items", "value": "5" },
+      { "type": "assert_count", "selector": ".rows", "value": ">3" },
+      { "type": "assert_count", "selector": ".errors", "value": "0" },
+      { "type": "get_text", "selector": "#patient-name" },
       { "type": "screenshot", "value": "step-name.png" },
       { "type": "select", "selector": "select#role", "value": "admin" },
       { "type": "clear", "selector": "input" },
       { "type": "press", "value": "Enter" },
       { "type": "scroll", "selector": ".target" },
       { "type": "hover", "selector": ".menu" },
-      { "type": "evaluate", "value": "document.title" }
+      { "type": "evaluate", "value": "document.title" },
+      { "type": "type_react", "selector": "input#search", "value": "search term" },
+      { "type": "click_regex", "text": "submit order", "selector": "button", "value": "last" },
+      { "type": "click_option", "text": "Option Label" },
+      { "type": "focus_autocomplete", "text": "Search by label" },
+      { "type": "click_chip", "text": "Tag Name" }
     ]
   }
 ]
 
+Framework-aware action reference (prefer these over evaluate for React/MUI apps):
+- type_react: types into React controlled inputs using native value setter + input/change events (works with both input and textarea)
+- click_regex: click element by regex text match (case-insensitive). Use "value": "last" for last match. Optional "selector" scopes the search
+- click_option: click a [role="option"] element by text — for autocomplete/select dropdowns
+- focus_autocomplete: focus an autocomplete input by its label text (supports MUI .MuiAutocomplete-root and [role="combobox"])
+- click_chip: click a chip/tag element by text (searches [class*="Chip"], [data-chip])
+
+Assertion action reference:
+- assert_text: checks if text appears anywhere in the page body
+- assert_element_text: checks textContent of a specific element (use "value": "exact" for strict match)
+- assert_attribute: checks HTML attributes — "attr=value" for value check, "attr" alone for existence
+- assert_class: checks if element has a CSS class via classList.contains
+- assert_visible / assert_not_visible: checks element visibility (display, visibility, opacity)
+- assert_input_value: checks the .value of input/select/textarea elements
+- assert_matches: checks element textContent against a regex pattern
+- assert_count: counts matching elements — exact number or operators (">3", ">=1", "<10", "<=5")
+- assert_url: checks if current URL contains the value
+- get_text: extracts element text (non-assertion, returns { value })
+
+Reusable modules:
+- Tests can reference shared action sequences: { "$use": "module-name", "params": { "key": "value" } }
+- Use modules for repeated flows like login, navigation, or setup
+
 Rules:
 - Output a JSON array of test objects
-- Use only the action types listed above
+- NEVER use evaluate with inline JS for assertions that can be done with native action types:
+  * Use assert_element_text instead of evaluate to check element textContent
+  * Use assert_attribute instead of evaluate to check HTML attributes
+  * Use assert_class instead of evaluate to check CSS classes
+  * Use assert_input_value instead of evaluate to check input/select/textarea values
+  * Use assert_matches instead of evaluate for regex text matching
+  * Use assert_not_visible instead of evaluate to verify elements are hidden
+  * Use type_react instead of evaluate with native value setter for React controlled inputs
+  * Use click_regex instead of evaluate with Array.from(querySelectorAll).filter(regex) patterns
+  * Use click_option instead of evaluate with querySelectorAll('[role="option"]') patterns
+  * Use focus_autocomplete instead of evaluate with MuiAutocomplete-root label search patterns
+  * Use click_chip instead of evaluate with querySelectorAll('[class*="Chip"]') patterns
+  * Reserve evaluate ONLY for complex logic that cannot be expressed with existing action types
 - "click" with "text" (no selector) finds buttons/links by visible text
 - "goto" values starting with "/" are relative to the app's base URL
 - Include a screenshot action before key assertions for debugging
@@ -53,6 +104,27 @@ Rules:
 - If the issue description is vague, create a reasonable test that covers the described scenario
 - If project context is provided (from CLAUDE.md), use the REAL routes, selectors, and UI patterns described there — never invent routes or selectors`;
 
+const E2E_RULES = `
+CRITICAL — UI-first testing rules:
+- Every test MUST start with a "goto" action to navigate to a real page
+- Tests MUST interact with UI elements: click, type, select, hover, scroll
+- Verify results through visible page state: assert_text, assert_visible, assert_element_text, assert_url
+- NEVER use evaluate to call APIs directly (no fetch, no GraphQL, no XHR, no window.__e2e.gql)
+- NEVER use evaluate to set up or verify data — use the UI workflow instead
+- Test the user journey as a real person would use the application
+- Include screenshot actions before key assertions for debugging
+`;
+
+const API_RULES = `
+API testing rules:
+- Tests verify backend API behavior directly via evaluate actions
+- Each test should: set up context → call API → assert response shape and values
+- Use evaluate for GraphQL mutations, queries, and REST calls
+- Name tests clearly describing the API operation (e.g. "createUser-returns-new-user")
+- Include error case tests (invalid input, missing fields, auth failures)
+- No need for goto/click/type — this is not UI testing
+`;
+
 /**
  * Reads the project's CLAUDE.md for app context (routes, selectors, UI structure).
  * Returns the content or empty string if not found.
@@ -77,7 +149,7 @@ function loadProjectContext(cwd) {
  * @param {object} config - Loaded config
  * @returns {object}
  */
-export function buildPrompt(issue, config) {
+export function buildPrompt(issue, config, testType = 'e2e') {
   let existingSuites = [];
   try {
     existingSuites = listSuites(config.testsDir).map(s => s.name);
@@ -88,7 +160,9 @@ export function buildPrompt(issue, config) {
     ? `\n## Project Context (from CLAUDE.md)\nUse these REAL routes, selectors, and UI patterns — do NOT invent your own.\n\n${projectContext}\n`
     : '';
 
-  const prompt = `Based on the following issue, generate E2E test actions using the e2e_create_test tool.
+  const categoryRules = testType === 'api' ? API_RULES : E2E_RULES;
+
+  const prompt = `Based on the following issue, generate ${testType === 'api' ? 'API' : 'E2E'} test actions using the e2e_create_test tool.
 
 ## Issue: ${issue.title}
 **Repo:** ${issue.repo}
@@ -99,8 +173,10 @@ export function buildPrompt(issue, config) {
 ### Description
 ${issue.body || 'No description provided.'}
 ${contextBlock}
+## Test Category: ${testType}
+${categoryRules}
 ## Instructions
-1. Analyze the issue and determine what user flows to test
+1. Analyze the issue and determine what ${testType === 'api' ? 'API operations' : 'user flows'} to test
 2. Create one or more tests that verify the expected behavior
 3. For bug reports: assert the CORRECT behavior (test failure = bug confirmed)
 4. Use the \`e2e_create_test\` tool with suite name \`issue-${issue.number}\`
@@ -141,7 +217,7 @@ export function hasApiKey(config = {}) {
  * @param {object} config - Loaded config
  * @returns {Promise<{ tests: object[], suiteName: string }>}
  */
-export async function generateTests(issue, config) {
+export async function generateTests(issue, config, testType = 'e2e') {
   const apiKey = config.anthropicApiKey || process.env.ANTHROPIC_API_KEY;
   if (!apiKey) {
     throw new Error('ANTHROPIC_API_KEY is required for test generation. Set it as an environment variable or in config.');
@@ -155,7 +231,9 @@ export async function generateTests(issue, config) {
     ? `\n## Project Context (from CLAUDE.md)\nIMPORTANT: Use these REAL routes, selectors, and UI patterns — do NOT invent your own.\n\n${projectContext}\n`
     : '';
 
-  const userMessage = `Generate E2E tests for this issue:
+  const categoryRules = testType === 'api' ? API_RULES : E2E_RULES;
+
+  const userMessage = `Generate ${testType === 'api' ? 'API' : 'E2E'} tests for this issue:
 
 Title: ${issue.title}
 Repo: ${issue.repo}
@@ -165,6 +243,8 @@ State: ${issue.state}
 Description:
 ${issue.body || 'No description provided.'}
 ${contextBlock}
+Test Category: ${testType}
+${categoryRules}
 Base URL: ${config.baseUrl}
 
 Output a JSON array of test objects. Nothing else.`;

package/src/config.js

@@ -16,6 +16,7 @@ const DEFAULTS = {
   baseUrl: 'http://host.docker.internal:3000',
   poolUrl: 'ws://localhost:3333',
   testsDir: 'e2e/tests',
+  modulesDir: 'e2e/modules',
   screenshotsDir: 'e2e/screenshots',
   concurrency: 3,
   viewport: { width: 1280, height: 720 },
@@ -33,11 +34,23 @@ const DEFAULTS = {
   dashboardPort: 8484,
   maxHistoryRuns: 100,
   projectName: null,
+  exclude: [],
   failOnNetworkError: false,
+  actionRetries: 0,
+  actionRetryDelay: 500,
   anthropicApiKey: null,
   anthropicModel: 'claude-sonnet-4-5-20250929',
   authToken: null,
   authStorageKey: 'accessToken',
+  learningsEnabled: true,
+  learningsMarkdown: true,
+  learningsNeo4j: false,
+  learningsDays: 30,
+  neo4jBoltUrl: 'bolt://localhost:7687',
+  neo4jUser: 'neo4j',
+  neo4jPassword: 'e2erunner',
+  neo4jBoltPort: 7687,
+  neo4jHttpPort: 7474,
 };
 
 function loadEnvVars() {
@@ -45,6 +58,7 @@ function loadEnvVars() {
   if (process.env.BASE_URL) env.baseUrl = process.env.BASE_URL;
   if (process.env.CHROME_POOL_URL) env.poolUrl = process.env.CHROME_POOL_URL;
   if (process.env.TESTS_DIR) env.testsDir = process.env.TESTS_DIR;
+  if (process.env.MODULES_DIR) env.modulesDir = process.env.MODULES_DIR;
   if (process.env.SCREENSHOTS_DIR) env.screenshotsDir = process.env.SCREENSHOTS_DIR;
   if (process.env.CONCURRENCY) env.concurrency = parseInt(process.env.CONCURRENCY);
   if (process.env.DEFAULT_TIMEOUT) env.defaultTimeout = parseInt(process.env.DEFAULT_TIMEOUT);
@@ -57,10 +71,21 @@ function loadEnvVars() {
   if (process.env.E2E_ENV) env.env = process.env.E2E_ENV;
   if (process.env.PROJECT_NAME) env.projectName = process.env.PROJECT_NAME;
   if (process.env.FAIL_ON_NETWORK_ERROR) env.failOnNetworkError = process.env.FAIL_ON_NETWORK_ERROR === 'true' || process.env.FAIL_ON_NETWORK_ERROR === '1';
+  if (process.env.ACTION_RETRIES) env.actionRetries = parseInt(process.env.ACTION_RETRIES);
+  if (process.env.ACTION_RETRY_DELAY) env.actionRetryDelay = parseInt(process.env.ACTION_RETRY_DELAY);
   if (process.env.ANTHROPIC_API_KEY) env.anthropicApiKey = process.env.ANTHROPIC_API_KEY;
   if (process.env.ANTHROPIC_MODEL) env.anthropicModel = process.env.ANTHROPIC_MODEL;
   if (process.env.AUTH_TOKEN) env.authToken = process.env.AUTH_TOKEN;
   if (process.env.AUTH_STORAGE_KEY) env.authStorageKey = process.env.AUTH_STORAGE_KEY;
+  if (process.env.LEARNINGS_ENABLED) env.learningsEnabled = process.env.LEARNINGS_ENABLED !== 'false' && process.env.LEARNINGS_ENABLED !== '0';
+  if (process.env.LEARNINGS_MARKDOWN) env.learningsMarkdown = process.env.LEARNINGS_MARKDOWN !== 'false' && process.env.LEARNINGS_MARKDOWN !== '0';
+  if (process.env.LEARNINGS_NEO4J) env.learningsNeo4j = process.env.LEARNINGS_NEO4J === 'true' || process.env.LEARNINGS_NEO4J === '1';
+  if (process.env.LEARNINGS_DAYS) env.learningsDays = parseInt(process.env.LEARNINGS_DAYS);
+  if (process.env.NEO4J_BOLT_URL) env.neo4jBoltUrl = process.env.NEO4J_BOLT_URL;
+  if (process.env.NEO4J_USER) env.neo4jUser = process.env.NEO4J_USER;
+  if (process.env.NEO4J_PASSWORD) env.neo4jPassword = process.env.NEO4J_PASSWORD;
+  if (process.env.NEO4J_BOLT_PORT) env.neo4jBoltPort = parseInt(process.env.NEO4J_BOLT_PORT);
+  if (process.env.NEO4J_HTTP_PORT) env.neo4jHttpPort = parseInt(process.env.NEO4J_HTTP_PORT);
   return env;
 }
 
@@ -129,6 +154,9 @@ export async function loadConfig(cliArgs = {}, cwd = null) {
   if (!path.isAbsolute(config.testsDir)) {
     config.testsDir = path.join(cwd, config.testsDir);
   }
+  if (config.modulesDir && !path.isAbsolute(config.modulesDir)) {
+    config.modulesDir = path.join(cwd, config.modulesDir);
+  }
   if (!path.isAbsolute(config.screenshotsDir)) {
     config.screenshotsDir = path.join(cwd, config.screenshotsDir);
   }

package/src/dashboard.js

@@ -17,9 +17,10 @@ import { createWebSocketServer } from './websocket.js';
 import { getPoolStatus, waitForPool } from './pool.js';
 import { runTestsParallel, loadAllSuites, loadTestSuite, listSuites } from './runner.js';
 import { generateReport, generateJUnitXML, saveReport, persistRun, loadHistory, loadHistoryRun } from './reporter.js';
-import { listProjects as dbListProjects, getProjectRuns as dbGetProjectRuns, getRunDetail as dbGetRunDetail, getAllRuns as dbGetAllRuns, getRunCount as dbGetRunCount, getProjectScreenshotsDir as dbGetProjectScreenshotsDir, getProjectTestsDir as dbGetProjectTestsDir, getProjectCwd as dbGetProjectCwd, lookupScreenshotHash as dbLookupScreenshotHash, closeDb } from './db.js';
+import { listProjects as dbListProjects, getProjectRuns as dbGetProjectRuns, getRunDetail as dbGetRunDetail, getAllRuns as dbGetAllRuns, getRunCount as dbGetRunCount, getProjectScreenshotsDir as dbGetProjectScreenshotsDir, getProjectTestsDir as dbGetProjectTestsDir, getProjectCwd as dbGetProjectCwd, lookupScreenshotHash as dbLookupScreenshotHash, ensureProject as dbEnsureProject, getNetworkLogs as dbGetNetworkLogs, closeDb } from './db.js';
 import { loadConfig } from './config.js';
 import { log, colors as C } from './logger.js';
+import { getLearningsSummary, getFlakySummary, getSelectorStability, getPageHealth, getApiHealth, getErrorPatterns, getTestTrends } from './learner-sqlite.js';
 
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
@@ -204,6 +205,27 @@ export async function startDashboard(config) {
         return;
       }
 
+      // API: DB — network logs for a run (filterable)
+      const networkLogsMatch = pathname.match(/^\/api\/db\/runs\/(\d+)\/network-logs$/);
+      if (networkLogsMatch) {
+        try {
+          const runDbId = parseInt(networkLogsMatch[1], 10);
+          const filters = {};
+          if (url.searchParams.has('testName')) filters.testName = url.searchParams.get('testName');
+          if (url.searchParams.has('method')) filters.method = url.searchParams.get('method');
+          if (url.searchParams.has('statusMin')) filters.statusMin = parseInt(url.searchParams.get('statusMin'), 10);
+          if (url.searchParams.has('statusMax')) filters.statusMax = parseInt(url.searchParams.get('statusMax'), 10);
+          if (url.searchParams.has('urlPattern')) filters.urlPattern = url.searchParams.get('urlPattern');
+          if (url.searchParams.get('errorsOnly') === 'true') filters.errorsOnly = true;
+          if (url.searchParams.get('includeHeaders') === 'true') filters.includeHeaders = true;
+          if (url.searchParams.get('includeBodies') === 'true') filters.includeBodies = true;
+          jsonResponse(res, dbGetNetworkLogs(runDbId, filters));
+        } catch (error) {
+          jsonResponse(res, { error: error.message }, 500);
+        }
+        return;
+      }
+
       // API: DB — project screenshots list
       const projectScreenshotsMatch = pathname.match(/^\/api\/db\/projects\/(\d+)\/screenshots$/);
       if (projectScreenshotsMatch) {
@@ -239,6 +261,124 @@ export async function startDashboard(config) {
         return;
       }
 
+      // API: DB — suite detail (tests + actions)
+      const suiteDetailMatch = pathname.match(/^\/api\/db\/projects\/(\d+)\/suites\/(.+)$/);
+      if (suiteDetailMatch) {
+        try {
+          const projectId = parseInt(suiteDetailMatch[1], 10);
+          const suiteName = decodeURIComponent(suiteDetailMatch[2]);
+          const dir = dbGetProjectTestsDir(projectId);
+          if (!dir || !fs.existsSync(dir)) {
+            jsonResponse(res, { error: 'Tests directory not found' }, 404);
+            return;
+          }
+          const { tests, hooks } = loadTestSuite(suiteName, dir);
+          jsonResponse(res, { name: suiteName, tests, hooks });
+        } catch (error) {
+          jsonResponse(res, { error: error.message }, 500);
+        }
+        return;
+      }
+
+      // API: DB — cross-project learnings (when no project selected)
+      const crossLearningsMatch = pathname.match(/^\/api\/db\/learnings(?:\/(\w+))?$/);
+      if (crossLearningsMatch) {
+        try {
+          const category = crossLearningsMatch[1] || 'summary';
+          const days = parseInt(url.searchParams.get('days') || '30', 10);
+          let data;
+          switch (category) {
+            case 'summary': {
+              const summary = getLearningsSummary(null);
+              const trends = getTestTrends(null, 7);
+              data = { ...summary, recentTrend: trends };
+              break;
+            }
+            default:
+              jsonResponse(res, { error: `Unknown learnings category: ${category}` }, 400);
+              return;
+          }
+          jsonResponse(res, data);
+        } catch (error) {
+          jsonResponse(res, { error: error.message }, 500);
+        }
+        return;
+      }
+
+      // API: DB — project modules list
+      const projectModulesMatch = pathname.match(/^\/api\/db\/projects\/(\d+)\/modules$/);
+      if (projectModulesMatch) {
+        try {
+          const projectId = parseInt(projectModulesMatch[1], 10);
+          const projectCwd = dbGetProjectCwd(projectId);
+          if (!projectCwd) { jsonResponse(res, []); return; }
+          const modulesDir = path.join(projectCwd, 'e2e', 'modules');
+          if (!fs.existsSync(modulesDir)) { jsonResponse(res, []); return; }
+          const files = fs.readdirSync(modulesDir).filter(f => f.endsWith('.json')).sort();
+          const modules = files.map(f => {
+            try {
+              const data = JSON.parse(fs.readFileSync(path.join(modulesDir, f), 'utf-8'));
+              return {
+                name: f.replace('.json', ''),
+                file: f,
+                description: data.description || null,
+                params: data.params || [],
+                actionCount: Array.isArray(data.actions) ? data.actions.length : 0,
+              };
+            } catch { return { name: f.replace('.json', ''), file: f, description: null, params: [], actionCount: 0 }; }
+          });
+          jsonResponse(res, modules);
+        } catch (error) {
+          jsonResponse(res, { error: error.message }, 500);
+        }
+        return;
+      }
+
+      // API: DB — project learnings (summary or specific category)
+      const learningsMatch = pathname.match(/^\/api\/db\/projects\/(\d+)\/learnings(?:\/(\w+))?$/);
+      if (learningsMatch) {
+        try {
+          const projectId = parseInt(learningsMatch[1], 10);
+          const category = learningsMatch[2] || 'summary';
+          const days = parseInt(url.searchParams.get('days') || '30', 10);
+
+          let data;
+          switch (category) {
+            case 'summary': {
+              const summary = getLearningsSummary(projectId);
+              const trends = getTestTrends(projectId, 7);
+              data = { ...summary, recentTrend: trends };
+              break;
+            }
+            case 'flaky':
+              data = getFlakySummary(projectId, days);
+              break;
+            case 'selectors':
+              data = getSelectorStability(projectId, days);
+              break;
+            case 'pages':
+              data = getPageHealth(projectId, days);
+              break;
+            case 'apis':
+              data = getApiHealth(projectId, days);
+              break;
+            case 'errors':
+              data = getErrorPatterns(projectId);
+              break;
+            case 'trends':
+              data = getTestTrends(projectId, days);
+              break;
+            default:
+              jsonResponse(res, { error: `Unknown learnings category: ${category}` }, 400);
+              return;
+          }
+          jsonResponse(res, data);
+        } catch (error) {
+          jsonResponse(res, { error: error.message }, 500);
+        }
+        return;
+      }
+
       // API: serve screenshot by hash (e.g. /api/screenshot-hash/a3f2b1c9)
       const ssHashMatch = pathname.match(/^\/api\/screenshot-hash\/([a-f0-9]{8})$/);
       if (ssHashMatch) {
@@ -262,7 +402,7 @@ export async function startDashboard(config) {
           const ext = path.extname(realPath).toLowerCase();
           const mimeTypes = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp' };
           if (!mimeTypes[ext]) { jsonResponse(res, { error: 'Not an image' }, 400); return; }
-          res.writeHead(200, { 'Content-Type': mimeTypes[ext] });
+          res.writeHead(200, { 'Content-Type': mimeTypes[ext], 'Cache-Control': 'no-store' });
           fs.createReadStream(realPath).pipe(res);
         } catch (error) {
           jsonResponse(res, { error: error.message }, 500);
@@ -302,7 +442,7 @@ export async function startDashboard(config) {
           jsonResponse(res, { error: 'Not an image' }, 400);
           return;
         }
-        res.writeHead(200, { 'Content-Type': mimeTypes[ext] });
+        res.writeHead(200, { 'Content-Type': mimeTypes[ext], 'Cache-Control': 'no-store' });
         fs.createReadStream(realPath).pipe(res);
         return;
       }
@@ -347,7 +487,7 @@ export async function startDashboard(config) {
           return;
         }
         if (fs.existsSync(resolvedPath)) {
-          res.writeHead(200, { 'Content-Type': imageMimeTypes[ext] });
+          res.writeHead(200, { 'Content-Type': imageMimeTypes[ext], 'Cache-Control': 'no-store' });
           fs.createReadStream(resolvedPath).pipe(res);
         } else {
           jsonResponse(res, { error: 'Not found' }, 404);
@@ -504,7 +644,7 @@ export async function startDashboard(config) {
       if (params.suite) {
         ({ tests, hooks } = loadTestSuite(params.suite, runConfig.testsDir));
       } else {
-        ({ tests, hooks } = loadAllSuites(runConfig.testsDir));
+        ({ tests, hooks } = loadAllSuites(runConfig.testsDir, runConfig.modulesDir, runConfig.exclude));
       }
 
       await waitForPool(runConfig.poolUrl);
@@ -521,8 +661,18 @@ export async function startDashboard(config) {
     }
   }
 
-  return new Promise((resolve) => {
+  return new Promise((resolve, reject) => {
     const host = config.dashboardHost || '127.0.0.1';
+
+    server.on('error', (err) => {
+      if (err.code === 'EADDRINUSE') {
+        log('❌', `${C.red}Port ${port} is already in use. Try a different port with --port <number>.${C.reset}`);
+        reject(new Error(`Port ${port} is already in use`));
+      } else {
+        reject(err);
+      }
+    });
+
     server.listen(port, host, () => {
       log('🖥️', `${C.bold}Dashboard${C.reset} running at ${C.cyan}http://${host}:${port}${C.reset}`);