kempo-testing-framework 1.1.0

package/src/gui.js

@@ -0,0 +1,249 @@
+import http from 'http';
+import { readFile } from 'fs/promises';
+import { fileURLToPath } from 'url';
+import path from 'path';
+import { exec } from 'child_process';
+import { platform } from 'os';
+import findTests from './findTests.js';
+import runTestFiles from './runTestFiles.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export default async (flags, args) => {
+  const server = http.createServer(async (req, res) => {
+    const basePath = req.url.split('?')[0];
+    
+    /*
+      Custom API Endpoints
+    */
+    
+    /* 
+      Serve essential.css
+    */
+    if(basePath === '/essential.css'){
+      res.writeHead(200, { 'Content-Type': 'text/css' });
+      res.end(await readFile(path.join(__dirname, '../node_modules/essentialcss/dist/essential.min.css'), 'utf8'));
+    } 
+    
+    /*
+      Get list of all test files with their test names
+    */
+    else if(basePath === '/testFiles'){
+      try {
+        const testFiles = await findTests('', '', true, true);
+        
+        // Extract test names from Node test files (safe to import in Node.js)
+        const nodeTestsWithNames = await Promise.all(
+          testFiles.nodeTests.map(async file => {
+            try {
+              // Convert forward slashes back to OS-specific path separators for import
+              const normalizedFile = file.replace(/\//g, path.sep);
+              const module = await import(`file://${path.resolve(process.cwd(), normalizedFile)}`);
+              const testNames = module.default ? Object.keys(module.default) : [];
+              return { file, testNames };
+            } catch (error) {
+              console.error(`Error loading Node test file ${file}:`, error);
+              return { file, testNames: [], error: error.message };
+            }
+          })
+        );
+
+        // Browser tests just return file names (test names will be extracted client-side)
+        const browserTestsWithNames = testFiles.browserTests.map(file => ({ file, testNames: null }));
+
+        const result = {
+          nodeTests: nodeTestsWithNames,
+          browserTests: browserTestsWithNames
+        };
+
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(result));
+      } catch (error) {
+        console.error('Error finding test files:', error);
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Failed to find test files' }));
+      }
+    } 
+    
+    /*
+      Serve test files as ES modules for dynamic imports
+    */
+    else if(basePath.startsWith('/test/')){
+      // URL format: /test/path/to/testfile.js
+      const testPath = basePath.substring(6); // Remove '/test/' prefix
+      
+      try {
+        // Convert forward slashes back to OS-specific path separators for file reading
+        const normalizedFile = testPath.replace(/\//g, path.sep);
+        const filePath = path.resolve(process.cwd(), normalizedFile);
+        
+        // Security check: ensure the file is within the project directory
+        if (!filePath.startsWith(process.cwd())) {
+          res.writeHead(403, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Access denied' }));
+          return;
+        }
+        
+        const fileContent = await readFile(filePath, 'utf8');
+        res.writeHead(200, { 'Content-Type': 'application/javascript' });
+        res.end(fileContent);
+      } catch (error) {
+        console.error(`Error reading test file ${testPath}:`, error);
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Test file not found' }));
+      }
+    } 
+
+    /*
+      Run a testFile
+    */
+    else if(basePath == '/runTest'){
+      const url = new URL(req.url, `http://${req.headers.host}`);
+      const testFile = url.searchParams.get('testFile');
+      const testNamesParam = url.searchParams.get('testNames');
+      const testNames = testNamesParam ? testNamesParam.split(',') : [];
+      const showBrowserParam = url.searchParams.get('showBrowser');
+      const showBrowser = showBrowserParam === 'true';
+     const delayMs = Math.max(0, parseInt(url.searchParams.get('delayMs')||'0', 10) || 0);
+
+      try {
+        // Determine if this is a browser or node test based on file extension
+        const isBrowserTest = testFile.endsWith('.browser-test.js');
+        const isNodeTest = testFile.endsWith('.node-test.js');
+        
+        if (!isBrowserTest && !isNodeTest) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ error: 'Unknown test file type' }));
+          return;
+        }
+
+        // Run the specific test file using the specificFiles parameter
+        const { nodeResults, browserResults } = await runTestFiles({
+          testFilter: (testNames && testNames.length === 1) ? testNames[0] : '',
+          shouldRunBrowser: isBrowserTest,
+          shouldRunNode: isNodeTest,
+          showBrowser, // pass through from query
+          port: 3001,
+          logLevel: 2,
+          delayMs,
+          specificFiles: [testFile]
+        });
+
+        // Return the results for the specific test file
+        const results = isBrowserTest ? browserResults : nodeResults;
+        const fileResults = results[testFile] || { tests: {} };
+        
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          testFile,
+          testNames,
+          results: fileResults
+        }));
+      } catch (error) {
+        console.error(`Error running test file ${testFile}:`, error);
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Failed to run test file', details: error.message }));
+      }
+    }
+
+    /*
+      Return 404 for common browser requests that we don't need to handle
+    */
+    else if(['/favicon.ico', '/.well-known/appspecific/com.chrome.devtools.json'].includes(basePath)){
+      res.writeHead(404);
+      res.end('');
+    } 
+    
+    // Serve static files from the gui directory (HTML, JS, CSS, images, etc.)
+    else {
+      // Serve static files from gui directory
+      try {
+        let filePath;
+        
+        // If requesting root, serve index.html
+        if (basePath === '/') {
+          filePath = path.join(__dirname, '../gui/index.html');
+        } else {
+          // Remove leading slash and serve from gui directory
+          const requestedFile = basePath.substring(1);
+          filePath = path.join(__dirname, '../gui', requestedFile);
+        }
+        
+        // Security check: ensure the resolved path is within the gui directory
+        const guiDir = path.resolve(__dirname, '../gui');
+        const resolvedPath = path.resolve(filePath);
+        if (!resolvedPath.startsWith(guiDir)) {
+          res.writeHead(403, { 'Content-Type': 'text/plain' });
+          res.end('Access denied');
+          return;
+        }
+        
+        /*
+          Static File Content Type Mapping
+        */
+        const ext = path.extname(filePath).toLowerCase();
+        let contentType = 'text/plain';
+        switch (ext) {
+          case '.html': contentType = 'text/html'; break;
+          case '.js': contentType = 'application/javascript'; break;
+          case '.css': contentType = 'text/css'; break;
+          case '.json': contentType = 'application/json'; break;
+          case '.png': contentType = 'image/png'; break;
+          case '.jpg': case '.jpeg': contentType = 'image/jpeg'; break;
+          case '.svg': contentType = 'image/svg+xml'; break;
+        }
+        
+        const fileContent = await readFile(filePath, ext === '.png' || ext === '.jpg' || ext === '.jpeg' ? null : 'utf8');
+        res.writeHead(200, { 'Content-Type': contentType });
+        res.end(fileContent);
+      } catch (error) {
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('File not found');
+      }
+    }
+  });
+  
+  /*
+    Server Startup and Browser Launch
+  */
+  const port = flags['gui-port'] || 4000;
+  server.listen(port);
+  const startUrl = `http://localhost:${port}`;
+  console.log(`Server running at ${startUrl}`);
+  
+  // Show platform-specific instructions for stopping the server
+  const platformName = platform();
+  const stopKey = platformName === 'darwin' ? 'Cmd+C' : 'Ctrl+C';
+  console.log(`Press ${stopKey} to stop the testing ui`);
+  
+  const openBrowser = url => {
+    const platformName = platform();
+    let command;
+    
+    switch(platformName){
+      case 'win32':
+        command = `start ${url}`;
+        break;
+      case 'darwin':
+        command = `open ${url}`;
+        break;
+      case 'linux':
+        command = `xdg-open ${url}`;
+        break;
+      default:
+        console.log(`Unable to open browser automatically on this platform: ${platformName}`);
+        console.log(`Please manually open your browser and navigate to: ${url}`);
+        return;
+    }
+    
+    exec(command, error => {
+      if (error) {
+        console.log(`Failed to open browser: ${error.message}`);
+        console.log(`Please manually open your browser and navigate to: ${url}`);
+      }
+    });
+  };
+  
+  openBrowser(startUrl);
+};

package/src/runBrowserTests.js

@@ -0,0 +1,71 @@
+import { startServer, stopServer } from './browserTestServer.js';
+import puppeteer from 'puppeteer';
+import LOG_LEVELS from './utils/logLevels.js';
+
+export default async ({
+  testFile,
+  filter = false,
+  showBrowser = false,
+  port = 3000,
+  logLevel,
+  delayMs = 0
+}) => {
+  /*
+   * Start Test Server
+   */
+  const url = await startServer(port);
+  
+  if(logLevel >= LOG_LEVELS.VERBOSE){
+    console.log(`\x1b[90m Browser test server started at ${url}\x1b[0m`);
+  }
+  
+  const sleep = (ms) => new Promise(r => setTimeout(r, ms));
+  try {
+    /*
+     * Launch Browser and Execute Tests
+     */
+    const launchOptions = {
+      headless: !showBrowser,
+      args: ['--no-sandbox', '--disable-setuid-sandbox'],
+      defaultViewport: { width: 1600, height: 900 }
+    };
+    if (showBrowser) {
+      launchOptions.devtools = true;
+      launchOptions.args.push('--auto-open-devtools-for-tabs');
+    }
+
+    const browser = await puppeteer.launch(launchOptions);
+    const page = await browser.newPage();
+
+    // Optional pre-delay when a visible browser is requested
+    if (showBrowser && delayMs > 0) {
+      if (logLevel >= LOG_LEVELS.VERBOSE) {
+        console.log(`\x1b[90m Applying pre-test browser delay: ${delayMs}ms\x1b[0m`);
+      }
+      await sleep(delayMs);
+    }
+
+  await page.goto(`${url}?testFile=${testFile}&testFilter=${filter}&delay=${delayMs}`);
+  await page.waitForFunction(() => document.readyState === 'complete' || document.readyState === 'interactive');
+  await page.waitForFunction(() => window.results !== undefined);
+    const results = await page.evaluate(() => window.results);
+
+    // Optional post-delay when a visible browser is requested
+    if (showBrowser && delayMs > 0) {
+      if (logLevel >= LOG_LEVELS.VERBOSE) {
+        console.log(`\x1b[90m Applying post-test browser delay: ${delayMs}ms\x1b[0m`);
+      }
+      await sleep(delayMs);
+    }
+    
+    /*
+     * Cleanup
+     */
+    await browser.close();
+    await stopServer();
+    return results;
+  } catch(error){
+    await stopServer();
+    throw error;
+  }
+};

package/src/runTestFiles.js

@@ -0,0 +1,94 @@
+import findTests from './findTests.js';
+import runNodeTests from './runTests.js';
+import runBrowserTests from './runBrowserTests.js';
+import path from 'path';
+
+/**
+ * Runs test files and returns results without logging
+ * @param {Object} options - Configuration options
+ * @param {string} options.suiteFilter - Filter for test suites
+ * @param {string} options.testFilter - Filter for individual tests
+ * @param {boolean} options.shouldRunBrowser - Whether to run browser tests
+ * @param {boolean} options.shouldRunNode - Whether to run node tests
+ * @param {boolean} options.showBrowser - Whether to show browser during tests
+ * @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 {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)
+ * @returns {Promise<{nodeResults: Object, browserResults: Object}>}
+ */
+export default async ({
+  suiteFilter = '',
+  testFilter = '',
+  shouldRunBrowser = true,
+  shouldRunNode = true,
+  showBrowser = false,
+  port = 3000,
+  logLevel = 2,
+  delayMs = 0,
+  onNodeTestStart,
+  onBrowserTestStart,
+  specificFiles = null
+}) => {
+  let nodeTests = [];
+  let browserTests = [];
+
+  if (specificFiles) {
+    // When specific files are provided, use them directly
+    for (const file of specificFiles) {
+      if (file.endsWith('.node-test.js') && shouldRunNode) {
+        nodeTests.push(file);
+      } else if (file.endsWith('.browser-test.js') && shouldRunBrowser) {
+        browserTests.push(file);
+      } else if (file.endsWith('.test.js')) {
+        // Generic test files can be both
+        if (shouldRunNode) nodeTests.push(file);
+        if (shouldRunBrowser) browserTests.push(file);
+      }
+    }
+  } else {
+    // Use findTests for discovery
+    const result = await findTests(suiteFilter, testFilter, shouldRunBrowser, shouldRunNode);
+    nodeTests = result.nodeTests;
+    browserTests = result.browserTests;
+  }
+
+  /*
+   * Node Test Execution
+   */
+  const nodeResults = {};
+  if(nodeTests.length){
+    for(const file of nodeTests){
+      if(onNodeTestStart) onNodeTestStart(file);
+      // 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);
+    }
+  }
+
+  /*
+   * Browser Test Execution
+   */
+  const browserResults = {};
+  if(browserTests.length){
+    for(const testFile of browserTests){
+      if(onBrowserTestStart) onBrowserTestStart(testFile);
+      browserResults[testFile] = await runBrowserTests({
+        testFile,
+        filter: testFilter, // Changed from testFilter to filter
+        showBrowser,
+        port,
+        logLevel,
+        delayMs
+      });
+    }
+  }
+
+  return {
+    nodeResults,
+    browserResults
+  };
+};

package/src/runTests.js

@@ -0,0 +1,83 @@
+const wait = ms => new Promise(r => setTimeout(r, ms));
+
+export default async ({
+  beforeAll = async () => {},
+  beforeEach = async () => {},
+  afterEach = async () => {},
+  afterAll = async () => {},
+  default: tests
+} = {}, filter = false, delay = 0) => {
+  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');
+  
+  /*
+   * Test Results Structure
+   */
+  const results = {
+    beforeAllLogs: [],
+    tests: {},
+    afterAllLogs: []
+  };
+  
+  /*
+   * Execute beforeAll Hook
+   */
+  await beforeAll(message => {
+    results.beforeAllLogs.push({
+      message,
+      type: 'log',
+      level: 3
+    });
+  });
+  
+  /*
+   * Execute Individual Tests
+   */
+  for (const name of testsToRun) {
+    const result = {
+      logs: [],
+      passed: null
+    };
+    const log = (message, type = 'log', level = 3) => {
+      result.logs.push({
+        message,
+        type,
+        level
+      });
+    };
+    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);
+      }
+    });
+    await afterEach(log);
+    log('== After Each ==', 'progress', 3);
+    if(!result.passed){ // If the test failed, elevate all logs to a level 2
+      result.logs.forEach(log => log.level = 2);
+    }
+    results.tests[name] = result;
+    await wait(delay);
+  }
+  
+  /*
+   * Execute afterAll Hook
+   */
+  await afterAll(message => {
+    results.afterAllLogs.push({
+      message,
+      type: 'log',
+      level: 3
+    });
+  });
+  
+  return results;
+};

package/src/utils/logLevels.js

@@ -0,0 +1,7 @@
+export default {
+  SILENT: 0,    // No output except final summary
+  MINIMAL: 1,   // Only test names and pass/fail status
+  NORMAL: 2,    // Test names, status, and logs from failed tests
+  VERBOSE: 3,   // All test output including logs from passing tests
+  DEBUG: 4      // Everything including framework internals
+};

package/test.html

@@ -0,0 +1,23 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Test</title>
+</head>
+<body>
+  <script type="module">
+    import runTests from './runTests.js';
+    const urlParams = new URLSearchParams(window.location.search);
+    const testFile = urlParams.get('testFile');
+    const testFilter = urlParams.get('testFilter');
+    const delay = parseInt(urlParams.get('delay') || '0', 10) || 0;
+    if(!testFile){
+      throw new Error('No test file provided');
+    }
+    const testsModule = await import(`/${testFile}`);
+    const results = await runTests(testsModule, testFilter, delay);
+    window.results = results;
+  </script>
+</body>
+</html>

package/tests/Counter.js

@@ -0,0 +1,34 @@
+class Counter extends HTMLElement {
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    this.count = 0;
+  }
+
+  connectedCallback() {
+    this.render();
+    this.shadowRoot.querySelector('button').addEventListener('click', this.increment);
+  }
+
+  disconnectedCallback() {
+    const button = this.shadowRoot.querySelector('button');
+    if (button) {
+      button.removeEventListener('click', this.increment);
+    }
+  }
+
+  increment = () => {
+    this.count++;
+    this.render();
+  }
+
+  render() {
+    this.shadowRoot.innerHTML = `
+      <button>Increment</button>
+      <div>Count: ${this.count}</div>
+    `;
+    this.shadowRoot.querySelector('button').addEventListener('click', this.increment);
+  }
+}
+
+customElements.define('my-counter', Counter);

package/tests/cli-flags.node-test.js

@@ -0,0 +1,54 @@
+import { spawn } from 'child_process';
+
+const runWithArgs = (args, timeoutMs = 3000) => new Promise((resolve) => {
+  const child = spawn(process.execPath, ['index.js', ...args], {
+    cwd: process.cwd(),
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+  let out = '';
+  let resolved = false;
+
+  const finish = () => {
+    if (resolved) return;
+    resolved = true;
+    try { child.kill('SIGTERM'); } catch {}
+    resolve(out);
+  };
+
+  child.stdout.on('data', (chunk) => {
+    out += chunk.toString();
+    if (out.includes('kempo-test flags:')) {
+      // We only need to see the flags echo. Short delay to capture the full line, then stop.
+      setTimeout(finish, 50);
+    }
+  });
+  child.stderr.on('data', (chunk) => { out += chunk.toString(); });
+  child.on('error', () => finish());
+  child.on('exit', () => finish());
+
+  setTimeout(finish, timeoutMs);
+});
+
+export default {
+  'maps -l 3 to logLevel 3': async ({ pass, fail }) => {
+    const out = await runWithArgs(['-l', '3']);
+  out.includes('logLevel: 3') ? pass('Parsed -l 3 to logLevel 3') : fail(`Output did not include expected logLevel=3:\n${out}`);
+  },
+  'maps -l debug to logLevel 4': async ({ pass, fail }) => {
+    const out = await runWithArgs(['-l', 'debug']);
+  out.includes('logLevel: 4') ? pass('Parsed -l debug to logLevel 4') : fail(`Output did not include expected logLevel=4:\n${out}`);
+  },
+  'maps -l v to logLevel 3': async ({ pass, fail }) => {
+    const out = await runWithArgs(['-l', 'v']);
+  out.includes('logLevel: 3') ? pass('Parsed -l v to logLevel 3') : fail(`Output did not include expected logLevel=3:\n${out}`);
+  },
+  'passes --delay value as delay flag': async ({ pass, fail }) => {
+    const out = await runWithArgs(['--delay', '2000']);
+  (out.includes("delay: '2000'") || out.includes('delay: 2000')) ? pass('Parsed --delay 2000 into flags output') : fail(`Output did not include expected delay:\n${out}`);
+  },
+  'combines log-level and delay flags': async ({ pass, fail }) => {
+    const out = await runWithArgs(['-l', 'minimal', '--delay', '250']);
+    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}`);
+  },
+};

package/tests/cli-loglevel.node-test.js

@@ -0,0 +1,40 @@
+import { spawn } from 'child_process';
+
+const stripAnsi = (s) => s.replace(/\x1b\[[0-9;]*m/g, '');
+
+const run = (args, timeoutMs = 8000) => new Promise((resolve) => {
+  const child = spawn(process.execPath, ['index.js', ...args], {
+    cwd: process.cwd(),
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+  let out = '';
+  let resolved = false;
+  const done = () => { if (!resolved) { resolved = true; try { child.kill('SIGTERM'); } catch {} resolve(out); } };
+  child.stdout.on('data', c => { out += c.toString(); });
+  child.stderr.on('data', c => { out += c.toString(); });
+  child.on('exit', done);
+  child.on('error', done);
+  setTimeout(done, timeoutMs);
+});
+
+export default {
+  'debug level prints debug preamble': async ({ pass, fail }) => {
+    // Pass suite filter as positional arg so it isn't consumed as a value for -n
+    const out = await run(['-l', 'debug', 'example']);
+    const txt = stripAnsi(out);
+    const ok = txt.includes('[Debug] Flags:') && txt.includes('[Debug] Args:') && txt.includes('[Debug] Log level: 4');
+  ok ? pass('CLI debug level printed expected debug preamble') : fail(`CLI output missing debug preamble:\n${out}`);
+  },
+  'minimal level omits beforeAll sections': async ({ pass, fail }) => {
+    const out = await run(['-l', 'minimal', 'example']);
+    const txt = stripAnsi(out);
+    const ok = !/beforeAll/.test(txt);
+  ok ? pass('Minimal log level omitted beforeAll sections') : fail(`Output contained beforeAll unexpectedly:\n${out}`);
+  },
+  'verbose shows pass lines for passing tests': async ({ pass, fail }) => {
+    const out = await run(['-l', 'verbose', 'example']);
+    const txt = stripAnsi(out);
+    const ok = /PASS\s+should handle basic string operations/.test(txt);
+  ok ? pass('Verbose level printed PASS lines for passing tests') : fail(`Verbose output missing PASS lines:\n${out}`);
+  }
+};