kempo-testing-framework 1.3.8 → 1.3.9

package/README.md

@@ -56,6 +56,26 @@ Kempo supports three types of test files:
 
 If your code is intended to run in both Node and the browser, you should write a single test file named `[name].test.js.`, otherwise use the environment specific file names `[name].browser-test.js` and/or `[name]node-test.js`.
 
+## Test Organization
+
+Kempo automatically discovers tests in the `tests` directory and supports organizing tests in subdirectories for better project structure. You can organize your tests however makes sense for your project:
+
+```
+tests/
+├── components/           # UI component tests
+│   ├── button.browser-test.js
+│   └── modal.browser-test.js
+├── api/                  # API-related tests  
+│   ├── auth.node-test.js
+│   └── users.node-test.js
+├── integration/          # Integration tests
+│   └── workflow.test.js
+└── utils/               # Utility function tests
+    └── helpers.test.js
+```
+
+The framework will recursively search all subdirectories within `tests/` to find test files, so you can nest directories as deeply as needed to match your project structure.
+
 ## Writing Tests
 
 ### Lifecycle Callbacks
@@ -272,6 +292,13 @@ Set the verbosity of output:
 - Specify a browser pause delay in milliseconds (applies before and after browser tests when the browser window is shown)
 - Example: `npx kempo-test -b --show-browser --delay 2000`
 
+**`--timeout` or `-t`**
+- Set the timeout for individual tests in milliseconds (default: 30000ms)
+- Tests that run longer than this timeout will be terminated and marked as failed
+- Minimum value: 1000ms (1 second)
+- Example: `npx kempo-test --timeout 60000` (60 second timeout)
+- Example: `npx kempo-test -t 10000` (10 second timeout)
+
 ### Combining Flags
 
 You can combine multiple flags for precise control:
@@ -288,6 +315,12 @@ npx kempo-test -l silent payment
 
 # Run browser tests with visible browser window, custom port and delay
 npx kempo-test -b --show-browser --port 8080 --delay 2000
+
+# Run tests with a custom timeout for slow-running tests
+npx kempo-test --timeout 60000
+
+# Run browser tests with custom timeout and visible browser
+npx kempo-test -b --show-browser --timeout 10000
 ```
 
 ## Running Specific or Filtered Tests

package/gui/components/TestFramework.js

@@ -100,8 +100,8 @@ class TestFrameworkEl extends LitElement {
       const logsEl = el.renderRoot?.getElementById('logs');
       if (logsEl) logsEl.clear();
     } catch {}
-    const { showBrowser, delayMs } = getSettings();
-    const resp = await fetch(`/runTest?testFile=${encodeURIComponent(file)}&testNames=${encodeURIComponent(name)}&showBrowser=${!!showBrowser}&delayMs=${Number(delayMs||0)}`);
+    const { showBrowser, delayMs, timeoutMs } = getSettings();
+    const resp = await fetch(`/runTest?testFile=${encodeURIComponent(file)}&testNames=${encodeURIComponent(name)}&showBrowser=${!!showBrowser}&delayMs=${Number(delayMs||0)}&timeoutMs=${Number(timeoutMs||30000)}`);
     let data = null;
     try { data = await resp.json(); } catch {}
     if(!resp.ok || (data && data.error)){
@@ -165,15 +165,15 @@ class TestFrameworkEl extends LitElement {
       if(fileLogsEl) fileLogsEl.clear();
     } catch {}
     
-    const { showBrowser, delayMs } = getSettings();
+    const { showBrowser, delayMs, timeoutMs } = getSettings();
     
     // For universal tests, run both environments
     if (isUniversal && file.endsWith('.test.js')) {
       try {
         // Run both Node and Browser tests
         const [nodeResp, browserResp] = await Promise.all([
-          fetch(`/runTest?testFile=${encodeURIComponent(file)}&environment=node&showBrowser=false&delayMs=${Number(delayMs||0)}`),
-          fetch(`/runTest?testFile=${encodeURIComponent(file)}&environment=browser&showBrowser=${!!showBrowser}&delayMs=${Number(delayMs||0)}`)
+          fetch(`/runTest?testFile=${encodeURIComponent(file)}&environment=node&showBrowser=false&delayMs=${Number(delayMs||0)}&timeoutMs=${Number(timeoutMs||30000)}`),
+          fetch(`/runTest?testFile=${encodeURIComponent(file)}&environment=browser&showBrowser=${!!showBrowser}&delayMs=${Number(delayMs||0)}&timeoutMs=${Number(timeoutMs||30000)}`)
         ]);
         
         let nodeData = null, browserData = null;
@@ -305,7 +305,7 @@ class TestFrameworkEl extends LitElement {
     }
     
     // Original single-environment logic for non-universal tests
-    const resp = await fetch(`/runTest?testFile=${encodeURIComponent(file)}&showBrowser=${!!showBrowser}&delayMs=${Number(delayMs||0)}`);
+    const resp = await fetch(`/runTest?testFile=${encodeURIComponent(file)}&showBrowser=${!!showBrowser}&delayMs=${Number(delayMs||0)}&timeoutMs=${Number(timeoutMs||30000)}`);
     let data = null;
     try { data = await resp.json(); } catch {}
     if(!resp.ok || (data && data.error)){

package/gui/components/settingsStore.js

@@ -5,6 +5,7 @@ const DEFAULTS = {
   logLevel: 3,
   theme: 'auto',
   delayMs: 0,
+  timeoutMs: 30000,
 };
 
 let state = (() => {

package/gui/index.html

@@ -17,6 +17,7 @@
       <div id="delaySettingRow">
         <ktf-setting-number name="delayMs" label="Delay (ms) between tests and around browser runs" step="100" min="0" max="600000" suffix="ms"></ktf-setting-number>
       </div>
+      <ktf-setting-number name="timeoutMs" label="Test timeout (ms)" step="1000" min="1000" max="300000" suffix="ms"></ktf-setting-number>
 
       <ktf-setting-select name="logLevel" label="Log Level"></ktf-setting-select>
 

package/index.js

@@ -11,6 +11,7 @@ const shortFlagMap = {
     'p': 'port',
     'g': 'gui',
     'w': 'show-browser',
+    't': 'timeout',
     'h': 'help'
 };
 
@@ -22,7 +23,7 @@ const flags = {};
 const remainingArgs = [];
 
 // Define which flags take values vs booleans
-const valueFlags = new Set(['log-level', 'delay', 'port']);
+const valueFlags = new Set(['log-level', 'delay', 'port', 'timeout', 'gui-port']);
 const booleanFlags = new Set(['browser', 'node', 'gui', 'show-browser', 'help', 'debug-flags']);
 
 for (let i = 0; i < args.length; i++) {
@@ -125,6 +126,7 @@ OPTIONS:
   -n, --node              Run only node tests
   -l, --log-level LEVEL   Set log level (0-4 or silent/minimal/normal/verbose/debug)
   -d, --delay MS          Add delay between tests in milliseconds
+  -t, --timeout MS        Set timeout for individual tests in milliseconds (default: 30000)
   -p, --port PORT         Set port for test server (default: 3000)
   -g, --gui               Launch GUI mode
   -w, --show-browser      Show browser window during tests
@@ -137,6 +139,7 @@ EXAMPLES:
   kempo-test                    # Run all tests
   kempo-test --browser          # Run only browser tests
   kempo-test -l verbose         # Run with verbose logging
+  kempo-test -t 60000           # Set 60-second timeout for tests
   kempo-test --gui              # Launch GUI mode
   kempo-test myComponent        # Run tests for 'myComponent' suite
   kempo-test myComponent myTest # Run specific test in specific suite

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kempo-testing-framework",
-  "version": "1.3.8",
+  "version": "1.3.9",
   "description": "The Kempo Testing Framework is a simple testing framework built on the principle that code intended to be ran in the browser should be tested in the browser, code intended to be ran in Node should be tested in Node, and code intended to be ran in both should be tested in both. No mocking, no complexity—just testing.",
   "main": "index.js",
   "bin": {

package/src/browserTestServer.js

@@ -109,7 +109,13 @@ export const startServer = async (_port = 3000) => {
 
 export const stopServer = async () => {
   if(server){
-  await new Promise(resolve => server.close(resolve));
-    server = null;
+    // Close all connections and stop accepting new ones
+    await new Promise((resolve) => {
+      server.closeAllConnections?.(); // Close keep-alive connections if method exists
+      server.close(() => {
+        server = null;
+        resolve();
+      });
+    });
   }
 };

package/src/cli.js

@@ -30,6 +30,8 @@ export default async (flags, args) => {
   const port = flags.port ? parseInt(flags.port, 10) : 3000;
   // Parse delay (milliseconds). Non-numeric or missing => 0
   const delayMs = Number.isFinite(parseInt(flags.delay, 10)) ? Math.max(0, parseInt(flags.delay, 10)) : 0;
+  // Parse timeout (milliseconds). Non-numeric or missing => 30000 (30 seconds)
+  const timeoutMs = Number.isFinite(parseInt(flags.timeout, 10)) ? Math.max(1000, parseInt(flags.timeout, 10)) : 30000;
 
   /*
    * Color Configuration
@@ -57,6 +59,7 @@ export default async (flags, args) => {
     port,
     logLevel,
     delayMs,
+    timeoutMs,
     onNodeTestStart: logLevel > LOG_LEVELS.MINIMAL ? (file) => {
       console.log(`${colors.cyan}Running Node test: ${file}${colors.reset}`);
     } : undefined,
@@ -192,7 +195,9 @@ const displaySummary = (nodeResults, browserResults, colors) => {
   console.log(`${colors.red}Failed:${colors.reset} ${failedTests}`);
   if(failedTests === 0){
     console.log(`\n${colors.green}${colors.bright}All tests passed!${colors.reset}`);
+    process.exit(0);
   } else {
     console.log(`\n${colors.red}${colors.bright}Some tests failed. See details above.${colors.reset}`);
+    process.exit(1);
   }
 };

package/src/findTests.js

@@ -4,24 +4,32 @@ import path from 'path';
 const findFiles = async (testDirs, filter = '') => {
   const results = [];
   
-  for (const dir of testDirs) {
+  const searchDirectory = async (dir) => {
     try {
       await fs.access(dir);
       const entries = await fs.readdir(dir, { withFileTypes: true });
       
       for (const entry of entries) {
+        const entryPath = path.join(dir, entry.name);
+        
         if (entry.isFile() && 
             entry.name.endsWith('test.js') &&
             entry.name.includes(filter)) {
-          const entryPath = path.join(dir, entry.name);
           // Normalize path to always use forward slashes for consistency across platforms
           const relativePath = path.relative(process.cwd(), entryPath).replace(/\\/g, '/');
           results.push(relativePath);
+        } else if (entry.isDirectory()) {
+          // Recursively search subdirectories
+          await searchDirectory(entryPath);
         }
       }
     } catch (error) {
-      // Directory doesn't exist, skip it
+      // Directory doesn't exist or access denied, skip it
     }
+  };
+  
+  for (const dir of testDirs) {
+    await searchDirectory(dir);
   }
   return results;
 };

package/src/gui.js

@@ -143,6 +143,7 @@ export default async (flags, args) => {
       const showBrowserParam = url.searchParams.get('showBrowser');
       const showBrowser = showBrowserParam === 'true';
       const delayMs = Math.max(0, parseInt(url.searchParams.get('delayMs')||'0', 10) || 0);
+      const timeoutMs = Math.max(1000, parseInt(url.searchParams.get('timeoutMs')||'30000', 10) || 30000);
       const environment = url.searchParams.get('environment'); // 'node', 'browser', or null for auto-detect
 
       try {
@@ -177,6 +178,7 @@ export default async (flags, args) => {
           port: 3001,
           logLevel: 2,
           delayMs,
+          timeoutMs,
           specificFiles: [testFile]
         });
 
@@ -246,8 +248,36 @@ export default async (flags, args) => {
         }
         
         const fileContent = await readFile(filePath, ext === '.png' || ext === '.jpg' || ext === '.jpeg' ? null : 'utf8');
-        res.writeHead(200, { 'Content-Type': contentType });
-        res.end(fileContent);
+        
+        // For index.html, inject initial settings from CLI flags
+        if (basePath === '/' && ext === '.html') {
+          const timeoutMs = Number.isFinite(parseInt(flags.timeout, 10)) ? Math.max(1000, parseInt(flags.timeout, 10)) : 30000;
+          const initialSettings = {
+            timeoutMs: timeoutMs
+          };
+          
+          // Inject settings into the HTML
+          const settingsScript = `<script>
+            // Apply initial CLI settings
+            if (typeof Storage !== "undefined") {
+              try {
+                const currentSettings = JSON.parse(localStorage.getItem('ktf_settings') || '{}');
+                const initialSettings = ${JSON.stringify(initialSettings)};
+                const mergedSettings = { ...currentSettings, ...initialSettings };
+                localStorage.setItem('ktf_settings', JSON.stringify(mergedSettings));
+              } catch (e) {
+                console.warn('Failed to set initial settings:', e);
+              }
+            }
+          </script>`;
+          
+          const modifiedContent = fileContent.replace('</head>', `${settingsScript}\n</head>`);
+          res.writeHead(200, { 'Content-Type': contentType });
+          res.end(modifiedContent);
+        } else {
+          res.writeHead(200, { 'Content-Type': contentType });
+          res.end(fileContent);
+        }
       } catch (error) {
         res.writeHead(404, { 'Content-Type': 'text/plain' });
         res.end('File not found');

package/src/runBrowserTests.js

@@ -10,7 +10,8 @@ export default async ({
   showBrowser = false,
   port = 3000,
   logLevel,
-  delayMs = 0
+  delayMs = 0,
+  timeoutMs = 30000
 }) => {
   /*
    * Start Test Server
@@ -120,7 +121,7 @@ export default async ({
       throw new Error(`Browser test error: ${error}`);
     }
     
-    await page.waitForFunction(() => window.results !== undefined, { timeout: 20000 });
+    await page.waitForFunction(() => window.results !== undefined, { timeout: timeoutMs });
     const results = await page.evaluate(() => window.results);
 
     // Optional post-delay when a visible browser is requested

package/src/runTestFiles.js

@@ -14,6 +14,7 @@ import path from 'path';
  * @param {number} options.port - Port for browser tests
  * @param {number} options.logLevel - Log level for browser tests
  * @param {number} options.delayMs - Optional delay in ms to apply for browser runs
+ * @param {number} options.timeoutMs - Timeout in ms for individual tests (default: 30000)
  * @param {Function} options.onNodeTestStart - Callback when a node test starts
  * @param {Function} options.onBrowserTestStart - Callback when a browser test starts
  * @param {string[]} options.specificFiles - Array of specific test files to run (overrides findTests)
@@ -28,6 +29,7 @@ export default async ({
   port = 3000,
   logLevel = 2,
   delayMs = 0,
+  timeoutMs = 30000,
   onNodeTestStart,
   onBrowserTestStart,
   specificFiles = null
@@ -65,7 +67,7 @@ export default async ({
       // Convert forward slashes back to OS-specific path separators for file system operations
       const normalizedFile = file.replace(/\//g, path.sep);
       const module = await import(`file://${path.resolve(process.cwd(), normalizedFile)}`);
-      nodeResults[file] = await runNodeTests(module, testFilter);
+      nodeResults[file] = await runNodeTests(module, testFilter, 0, timeoutMs);
     }
   }
 
@@ -82,7 +84,8 @@ export default async ({
         showBrowser,
         port,
         logLevel,
-        delayMs
+        delayMs,
+        timeoutMs
       });
     }
   }

package/src/runTests.js

@@ -1,12 +1,21 @@
 const wait = ms => new Promise(r => setTimeout(r, ms));
 
+const withTimeout = (promise, timeoutMs, testName) => {
+  return Promise.race([
+    promise,
+    new Promise((_, reject) => 
+      setTimeout(() => reject(new Error(`Test "${testName}" timed out after ${timeoutMs}ms`)), timeoutMs)
+    )
+  ]);
+};
+
 export default async ({
   beforeAll = async () => {},
   beforeEach = async () => {},
   afterEach = async () => {},
   afterAll = async () => {},
   default: tests
-} = {}, filter = false, delay = 0) => {
+} = {}, filter = false, delay = 0, timeoutMs = 30000) => {
   const testsToRun = filter ? Object.keys(tests).filter(name => name.trim().toLowerCase().includes(filter.trim().toLowerCase())) : Object.keys(tests);
   if(!testsToRun.length) throw new Error('No tests found matching the filter');
   
@@ -48,17 +57,28 @@ export default async ({
     log(`== Starting Test "${name}" ==`, 'progress', 3);
     log('== Before Each ==', 'progress', 3);
     await beforeEach(log);
-    await tests[name]({
-      log,
-      pass: message => {
-        result.passed = true;
-        log(message, 'pass', 2); // was 3; make visible at NORMAL
-      },
-      fail: message => {
-        result.passed = false;
-        log(message, 'fail', 2);
-      }
-    });
+    
+    try {
+      await withTimeout(
+        tests[name]({
+          log,
+          pass: message => {
+            result.passed = true;
+            log(message, 'pass', 2); // was 3; make visible at NORMAL
+          },
+          fail: message => {
+            result.passed = false;
+            log(message, 'fail', 2);
+          }
+        }),
+        timeoutMs,
+        name
+      );
+    } catch (error) {
+      result.passed = false;
+      log(error.message, 'fail', 2);
+    }
+    
     await afterEach(log);
     log('== After Each ==', 'progress', 3);
     if(!result.passed){ // If the test failed, elevate all logs to a level 2

package/tests/{cli-flags.node-test.js → cli/flags.node-test.js}

@@ -51,4 +51,12 @@ export default {
     const ok = out.includes('logLevel: 1') && (out.includes("delay: '250'") || out.includes('delay: 250'));
   ok ? pass('Parsed and combined -l minimal with --delay 250') : fail(`Output missing expected flags:\n${out}`);
   },
+  'passes --timeout value as timeout flag': async ({ pass, fail }) => {
+    const out = await runWithArgs(['--timeout', '5000']);
+    (out.includes("timeout: '5000'") || out.includes('timeout: 5000')) ? pass('Parsed --timeout 5000 into flags output') : fail(`Output did not include expected timeout:\n${out}`);
+  },
+  'passes -t as short form of timeout flag': async ({ pass, fail }) => {
+    const out = await runWithArgs(['-t', '15000']);
+    (out.includes("timeout: '15000'") || out.includes('timeout: 15000')) ? pass('Parsed -t 15000 into flags output') : fail(`Output did not include expected timeout:\n${out}`);
+  }
 };

package/tests/{counter.browser-test.js → components/counter.browser-test.js}

@@ -1,4 +1,4 @@
-import './Counter.js';
+import '../fixtures/Counter.js';
 
 const wait = ms => new Promise(r=>setTimeout(r,ms));
 

package/tests/{custom-page.browser-test.js → examples/custom-page.browser-test.js}

@@ -1,4 +1,4 @@
-export const page = './custom-test-page.html';
+export const page = '../fixtures/custom-test-page.html';
 
 export default {
   'should find custom element in custom page': ({ pass, fail }) => {

package/tests/{fibonacci.test.js → examples/fibonacci.test.js}

@@ -1,5 +1,5 @@
 // Import the fibonacci utility functions
-import fibonacciUtils from './fibonacci.js';
+import fibonacciUtils from '../fixtures/fibonacci.js';
 
 const { fibonacci, fibonacciSequence, isFibonacci } = fibonacciUtils;
 

package/tests/nested/deep/deep.node-test.js

@@ -0,0 +1,9 @@
+export default {
+  'deeply nested test should be found': ({ pass, fail }) => {
+		if(1 == true){
+			pass('This test is in a deeply nested subdirectory');
+		} else {
+			fail('How did this happen?');
+		}
+  }
+};

package/tests/nested/nested.browser-test.js

@@ -0,0 +1,9 @@
+export default {
+  'nested test should be found': ({ pass, fail }) => {
+    if(1 == true){
+			pass('This test is in a subdirectory');
+		} else {
+			fail('How did this happen?');
+		}
+  }
+};

package/tests/{src-browserTestServer.node-test.js → src/browserTestServer.node-test.js}

@@ -1,5 +1,5 @@
 import http from 'http';
-import { startServer, stopServer } from '../src/browserTestServer.js';
+import { startServer, stopServer } from '../../src/browserTestServer.js';
 
 const get = (port, path) => new Promise((resolve, reject) => {
   const req = http.request({ hostname: 'localhost', port, path, method: 'GET' }, (res) => {
@@ -31,9 +31,9 @@ export default {
     try {
       await startServer(port);
       const a = await get(port, '/runTests.js');
-      const b = await get(port, '/tests/counter.browser-test.js');
+      const b = await get(port, '/tests/components/counter.browser-test.js');
       const c = await get(port, '/does-not-exist.js');
-    log(`Statuses: /runTests.js=${a.status} /tests/counter.browser-test.js=${b.status} /does-not-exist.js=${c.status}`);
+    log(`Statuses: /runTests.js=${a.status} /tests/components/counter.browser-test.js=${b.status} /does-not-exist.js=${c.status}`);
       const ok = a.status === 200 && /export default|const wait/.test(a.body)
         && b.status === 200 && /Counter component/.test(b.body)
         && c.status === 404;

package/tests/{src-findTests.node-test.js → src/findTests.node-test.js}

@@ -1,12 +1,12 @@
-import findTests from '../src/findTests.js';
+import findTests from '../../src/findTests.js';
 
 export default {
   'finds node and browser test files with no filters': async ({ pass, fail, log }) => {
     try {
       const { nodeTests, browserTests } = await findTests('', '', true, true);
     log(`Found node tests: ${nodeTests.length}, browser tests: ${browserTests.length}`);
-      const hasCounter = browserTests.some(f => f.endsWith('tests/counter.browser-test.js'));
-      const hasExample = nodeTests.some(f => f.endsWith('tests/example.node-test.js'));
+      const hasCounter = browserTests.some(f => f.endsWith('tests/components/counter.browser-test.js'));
+      const hasExample = nodeTests.some(f => f.endsWith('tests/examples/example.node-test.js'));
     if (hasCounter && hasExample) pass('Discovered expected canonical files (counter + example)');
     else fail(`Missing expected files. node: ${JSON.stringify(nodeTests)}, browser: ${JSON.stringify(browserTests)}`);
     } catch (e) {
@@ -37,5 +37,22 @@ export default {
     } catch (e) {
       fail(e.stack || String(e));
     }
+  },
+  'finds tests in nested subdirectories': async ({ pass, fail, log }) => {
+    try {
+      const { nodeTests, browserTests } = await findTests('', '', true, true);
+      log(`All node tests: ${nodeTests.length}, browser tests: ${browserTests.length}`);
+      
+      const hasNestedBrowser = browserTests.some(f => f.includes('tests/nested/nested.browser-test.js'));
+      const hasDeepNode = nodeTests.some(f => f.includes('tests/nested/deep/deep.node-test.js'));
+      
+      if (hasNestedBrowser && hasDeepNode) {
+        pass('Found tests in nested subdirectories');
+      } else {
+        fail(`Missing nested tests. hasNestedBrowser: ${hasNestedBrowser}, hasDeepNode: ${hasDeepNode}`);
+      }
+    } catch (e) {
+      fail(e.stack || String(e));
+    }
   }
 };

package/tests/{src-logLevels.node-test.js → src/logLevels.node-test.js}

@@ -1,4 +1,4 @@
-import LOG_LEVELS from '../src/utils/logLevels.js';
+import LOG_LEVELS from '../../src/utils/logLevels.js';
 
 export default {
   'defines expected numeric levels': async ({ pass, fail, log }) => {

package/tests/{src-runBrowserTests.node-test.js → src/runBrowserTests.node-test.js}

@@ -1,10 +1,10 @@
-import runBrowserTests from '../src/runBrowserTests.js';
+import runBrowserTests from '../../src/runBrowserTests.js';
 
 export default {
   'runs a specific browser test headless and returns results': async ({ pass, fail, log }) => {
     try {
       const res = await runBrowserTests({
-        testFile: 'tests/counter.browser-test.js',
+        testFile: 'tests/components/counter.browser-test.js',
         filter: '',
         showBrowser: false,
         port: 3111,
@@ -25,10 +25,10 @@ export default {
       const filter = 'Counter component should be defined';
       const delay = 500; // Reduced from 1000ms to avoid timeouts
       const start1 = Date.now();
-      await runBrowserTests({ testFile: 'tests/counter.browser-test.js', filter, showBrowser: false, port: 3112, logLevel: 2, delayMs: delay });
+      await runBrowserTests({ testFile: 'tests/components/counter.browser-test.js', filter, showBrowser: false, port: 3112, logLevel: 2, delayMs: delay });
       const t1 = Date.now() - start1;
       const start2 = Date.now();
-      await runBrowserTests({ testFile: 'tests/counter.browser-test.js', filter, showBrowser: true, port: 3113, logLevel: 2, delayMs: delay });
+      await runBrowserTests({ testFile: 'tests/components/counter.browser-test.js', filter, showBrowser: true, port: 3113, logLevel: 2, delayMs: delay });
       const t2 = Date.now() - start2;
       // Headful should incur roughly +1000ms (pre+post). Allow slack for env variance.
       log(`Timing — headless=${t1}ms, headful=${t2}ms, delta=${t2 - t1}ms`);

package/tests/{src-runTestFiles.node-test.js → src/runTestFiles.node-test.js}

@@ -1,4 +1,4 @@
-import runTestFiles from '../src/runTestFiles.js';
+import runTestFiles from '../../src/runTestFiles.js';
 
 export default {
   'discovers and runs node tests only when requested': async ({ pass, fail, log }) => {

package/tests/{src-runTests.node-test.js → src/runTests.node-test.js}

@@ -1,4 +1,4 @@
-import runTests from '../src/runTests.js';
+import runTests from '../../src/runTests.js';
 
 const mkSuite = () => ({
   beforeAll: async (log) => { log('before all'); },

package/tests/src/timeout.node-test.js

@@ -0,0 +1,66 @@
+import runTests from '../../src/runTests.js';
+
+export default {
+  'should timeout hanging test with custom timeout': async ({ pass, fail, log }) => {
+    try {
+      const hangingTest = {
+        default: {
+          'hanging test': () => {
+            // Return a promise that never resolves
+            return new Promise(() => {});
+          }
+        }
+      };
+      
+      const start = Date.now();
+      const results = await runTests(hangingTest, false, 0, 2000); // 2 second timeout for faster testing
+      const duration = Date.now() - start;
+      
+      log(`Test completed in ${duration}ms`);
+      
+      // Should have timed out and marked as failed
+      const testResult = results.tests['hanging test'];
+      if (testResult && !testResult.passed && duration >= 1900 && duration <= 3000) {
+        // Check if the failure message mentions timeout
+        const hasTimeoutMessage = testResult.logs.some(log => log.message.includes('timed out'));
+        if (hasTimeoutMessage) {
+          pass('Test correctly timed out and reported timeout error');
+        } else {
+          fail('Test failed but timeout message not found in logs');
+        }
+      } else {
+        fail(`Test should have timed out. passed: ${testResult?.passed}, duration: ${duration}ms`);
+      }
+    } catch (e) {
+      fail(e.stack || String(e));
+    }
+  },
+  
+  'should complete normal test within timeout': async ({ pass, fail, log }) => {
+    try {
+      const normalTest = {
+        default: {
+          'quick test': ({ pass }) => {
+            pass('This test completes quickly');
+          }
+        }
+      };
+      
+      const start = Date.now();
+      const results = await runTests(normalTest, false, 0, 2000); // 2 second timeout
+      const duration = Date.now() - start;
+      
+      log(`Test completed in ${duration}ms`);
+      
+      // Should complete quickly and pass
+      const testResult = results.tests['quick test'];
+      if (testResult && testResult.passed && duration < 1000) {
+        pass('Normal test completed successfully within timeout');
+      } else {
+        fail(`Normal test should have passed quickly. passed: ${testResult?.passed}, duration: ${duration}ms`);
+      }
+    } catch (e) {
+      fail(e.stack || String(e));
+    }
+  }
+};