super-api-tester-dashboard-wrapper 1.0.0

package/bin/cli.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+/**
+ * super-api-tester-dashboard-wrapper
+ * Executable CLI Entry Point
+ */
+
+// Bypasses argument filtering to execute the live streaming runner instantly
+require('../src/runner.js');

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "super-api-tester-dashboard-wrapper",
+  "version": "1.0.0",
+  "description": "The official real-time SSE live-streaming dashboard UI wrapper for super-api-tester suites",
+  "main": "src/runner.js",
+  "bin": {
+    "super-api-dashboard": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "keywords": [
+    "super-api-tester",
+    "dashboard",
+    "realtime",
+    "sse",
+    "automation",
+    "qa",
+    "contract-testing"
+  ],
+  "author": "Kushan Shalindra Amarasiri",
+  "license": "ISC",
+  "dependencies": {
+    "express": "^4.19.2"
+  },
+  "peerDependencies": {
+    "super-api-tester": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/readme.md

@@ -0,0 +1,65 @@
+# super-api-tester-dashboard-wrapper
+
+A real-time, hands-free automation streaming pipeline and interactive visual dashboard wrapper for the `super-api-tester` contract framework. 
+
+This wrapper monitors your Vitest contract automation metrics, maintains an in-memory execution history ledger, and handles real-time Server-Sent Events (SSE) data streams to populate a beautiful, zero-lag browser interface complete with interactive telemetry metrics and individual endpoint latency profiling.
+
+---
+
+## 🚀 Features
+
+* **⚡ Zero-Lag Live Streaming:** Utilizes Server-Sent Events (SSE) to push test metrics instantly from your runtime compiler loop straight to your browser.
+* **📊 Interactive Trend Charts:** Integrated Chart.js dashboards showing overall execution trends (Passed vs. Contract Breaches) over structural interval cycles.
+* **⏱️ Performance Profiling:** Automatically highlights your Top 5 slowest routing endpoints in a responsive bar graph matrix.
+* **🔍 Click-to-Drilldown History:** Click any specific API route row in the log console to instantly pull up its isolated, historical latency tracking profile over past runs.
+* **💾 Refresh Persistence:** The backend keeps an active internal snapshot ledger. Refreshing your browser will **never** wipe your charts or show blank metrics placeholders.
+* **⏰ Embedded Automation Scheduler:** Operates background cron intervals (defaulted to 5 minutes) to execute checks hands-free from a single terminal window.
+
+---
+
+## 🛠️ Installation
+
+Navigate to your active `super-api-tester` project directory and install the wrapper as a development dependency:
+
+```bash
+npm install -D super-api-tester-dashboard-wrapper
+⚙️ Project Setup Configuration
+1. Update package.json Scripts
+Open your main testing repository's package.json file and merge these scripts into your existing configuration:
+
+JSON
+{
+  "name": "your-testing-project",
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest --reporter=default --reporter=json --outputFile=./test-results.json",
+    "dashboard": "super-api-dashboard"
+  },
+  "dependencies": {
+    "super-api-tester": "^1.0.3"
+  },
+  "devDependencies": {
+    "super-api-tester-dashboard-wrapper": "^1.1.0"
+  }
+}
+2. Verify Your Test Base URL Alignment
+To avoid encountering HTTP 405 Method Not Allowed errors during execution loops, ensure your super-api-tester instance points directly to the active API routing gateway subdomain, rather than a landing documentation URL layer:
+
+JavaScript
+// ✅ Correct Target Configuration Structure
+const api = new ApiTester({
+  baseUrl: '[https://api.restful-api.dev](https://api.restful-api.dev)' 
+});
+💻 Usage
+You no longer need to manage multiple terminal windows to run your dashboard and watch files simultaneously! Simply run the unified dashboard boot command:
+
+Bash
+npm run dashboard
+This launches the internal monitoring engine and outputs your confirmation hook:
+
+Plaintext
+🖥️  super-api-tester Live Console: http://localhost:3000
+🚀 Automated scheduling sequence armed.
+🕒 Triggering automated contract check...
+Open your browser and navigate to http://localhost:3000 to view your live telemetry suite streaming in real time.

package/src/index.html

@@ -0,0 +1,227 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>super-api-tester Live Console</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
+    <style>
+        body { background-color: #0b0f19; }
+        .neon-glow-pass { text-shadow: 0 0 15px rgba(16, 185, 129, 0.3); }
+        .neon-glow-fail { text-shadow: 0 0 15px rgba(244, 63, 94, 0.3); }
+    </style>
+</head>
+<body class="text-slate-300 font-sans antialiased min-h-screen p-4 sm:p-8">
+
+    <div class="max-w-6xl mx-auto space-y-8">
+        
+        <header class="flex flex-col sm:flex-row sm:items-center sm:justify-between gap-4 border-b border-slate-800 pb-6">
+            <div>
+                <div class="flex items-center gap-3">
+                    <h1 class="text-2xl font-extrabold tracking-tight text-white flex items-center gap-2">
+                        <svg class="w-6 h-6 text-emerald-500" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M9 3v2m6-2v2M9 19v2m6-2v2M5 9H3m2 6H3m18-6h-2m2 6h-2M7 19h10a2 2 0 002-2V7a2 2 0 00-2-2H7a2 2 0 00-2 2v10a2 2 0 002 2z"></path></svg>
+                        super-api-tester
+                    </h1>
+                    <span class="bg-slate-800 text-slate-400 text-xs px-2 py-0.5 rounded font-mono border border-slate-700">Live Console</span>
+                </div>
+                <p class="text-sm text-slate-400 mt-1">Real-time contract automation streaming dashboard wrapper pipeline</p>
+            </div>
+            <div class="flex items-center gap-2 bg-slate-900 border border-slate-800 px-3 py-1.5 rounded-lg w-fit">
+                <span id="status-dot" class="w-2.5 h-2.5 rounded-full bg-yellow-500 animate-pulse"></span>
+                <span id="status-text" class="text-xs font-mono font-bold uppercase tracking-wider text-yellow-500">Connecting</span>
+            </div>
+        </header>
+
+        <section class="grid grid-cols-1 sm:grid-cols-3 gap-6">
+            <div class="bg-[#0f1422] border border-slate-800 p-6 rounded-xl relative overflow-hidden">
+                <div class="text-xs font-bold text-slate-500 uppercase tracking-wider">Total Executed Suites</div>
+                <div id="total-suites" class="text-4xl font-black text-white mt-2 font-mono">--</div>
+            </div>
+            <div class="bg-[#0f1422] border border-slate-800 p-6 rounded-xl border-l-4 border-l-emerald-500 relative overflow-hidden">
+                <div class="text-xs font-bold text-slate-500 uppercase tracking-wider">Passed Metrics</div>
+                <div id="passed-tests" class="text-4xl font-black text-emerald-400 mt-2 font-mono neon-glow-pass">--</div>
+            </div>
+            <div class="bg-[#0f1422] border border-slate-800 p-6 rounded-xl border-l-4 border-l-rose-500 relative overflow-hidden">
+                <div class="text-xs font-bold text-slate-500 uppercase tracking-wider">Contract Breaches</div>
+                <div id="failed-tests" class="text-4xl font-black text-rose-500 mt-2 font-mono neon-glow-fail">--</div>
+            </div>
+        </section>
+
+        <section class="grid grid-cols-1 md:grid-cols-2 gap-6">
+            <div class="bg-[#0f1422] border border-slate-800 p-5 rounded-xl space-y-3">
+                <h4 class="text-xs font-bold text-slate-400 uppercase tracking-wider">Suite Execution Trends History</h4>
+                <div class="h-56 w-full relative"><canvas id="lineChart"></canvas></div>
+            </div>
+            <div class="bg-[#0f1422] border border-slate-800 p-5 rounded-xl space-y-3">
+                <h4 class="text-xs font-bold text-slate-400 uppercase tracking-wider">Slowest Endpoints Response Speed (Top 5)</h4>
+                <div class="h-56 w-full relative"><canvas id="barChart"></canvas></div>
+            </div>
+        </section>
+
+        <main class="bg-[#0f1422] border border-slate-800 rounded-xl overflow-hidden shadow-2xl">
+            <div class="px-6 py-4 bg-slate-900/40 border-b border-slate-800 flex items-center justify-between">
+                <h3 class="font-bold text-white text-sm tracking-wide uppercase">Active Spec Target Suite Telemetry (Click Row to View History)</h3>
+                <span id="runtime-clock" class="text-xs font-mono text-slate-500">Last updated: Never</span>
+            </div>
+            <div id="log-container" class="p-6 divide-y divide-slate-800/60 font-mono text-sm space-y-4"></div>
+        </main>
+
+        <section id="drilldown-panel" class="hidden bg-[#0f1422] border border-slate-700 rounded-xl p-6 space-y-4 shadow-2xl border-t-4 border-t-blue-500">
+            <div class="flex items-center justify-between">
+                <div>
+                    <h4 id="drilldown-title" class="text-white font-bold font-sans text-base">Endpoint Performance Profile</h4>
+                    <p id="drilldown-subtitle" class="text-xs text-slate-500 mt-0.5 font-mono"></p>
+                </div>
+                <button onclick="document.getElementById('drilldown-panel').classList.add('hidden')" class="text-xs tracking-wider border border-slate-800 bg-slate-900 text-slate-400 hover:text-white px-3 py-1 rounded">Close</button>
+            </div>
+            <div class="h-48 w-full relative">
+                <canvas id="endpointHistoryChart"></canvas>
+            </div>
+        </section>
+    </div>
+
+    <script>
+        const logContainer = document.getElementById('log-container');
+        let lineChartInstance = null, barChartInstance = null, endpointChartInstance = null;
+        let globalHistoryLedger = [];
+
+        function renderInterface(payload) {
+            if (!payload || !payload.latest) return;
+            const metrics = payload.latest;
+            globalHistoryLedger = payload.history || [];
+
+            document.getElementById('runtime-clock').innerText = `Last updated: ${new Date().toLocaleTimeString()}`;
+            document.getElementById('total-suites').innerText = metrics.numTotalTestSuites || 0;
+            document.getElementById('passed-tests').innerText = metrics.numPassedTests || 0;
+            document.getElementById('failed-tests').innerText = metrics.numFailedTests || 0;
+
+            // 1. Refresh System Line Trends Charts
+            if (lineChartInstance) {
+                lineChartInstance.data.labels = globalHistoryLedger.map(r => r.timestamp);
+                lineChartInstance.data.datasets[0].data = globalHistoryLedger.map(r => r.numPassedTests);
+                lineChartInstance.data.datasets[1].data = globalHistoryLedger.map(r => r.numFailedTests);
+                lineChartInstance.update();
+            }
+
+            // 2. Map Rows Log Console Matrix
+            logContainer.innerHTML = '';
+            let speedMetricsList = [];
+
+            metrics.testResults?.forEach(suite => {
+                suite.assertionResults?.forEach(assertion => {
+                    const isPassed = assertion.status === 'passed';
+                    const statusColor = isPassed ? 'text-emerald-400' : 'text-rose-500';
+                    const row = document.createElement('div');
+                    
+                    row.className = "pt-4 pb-3 flex flex-col sm:flex-row sm:items-center sm:justify-between gap-2 border-b border-slate-800/40 last:border-0 hover:bg-slate-900/30 px-3 rounded-lg cursor-pointer transition";
+                    
+                    // Click execution engine binder
+                    row.onclick = () => showEndpointDrilldown(assertion.fullName);
+
+                    speedMetricsList.push({
+                        label: assertion.fullName.length > 15 ? assertion.fullName.substring(0, 14) + '..' : assertion.fullName,
+                        duration: assertion.duration || 0
+                    });
+
+                    row.innerHTML = `
+                        <div class="flex-1 min-w-0">
+                            <span class="text-slate-200 font-sans font-medium block truncate">${assertion.fullName}</span>
+                            <span class="text-xs text-slate-500 block mt-0.5 truncate">${suite.name}</span>
+                        </div>
+                        <span class="text-xs font-mono font-bold px-2 py-1 bg-slate-900 border border-slate-800 rounded ${statusColor}">
+                            ${assertion.duration || 0}ms
+                        </span>
+                    `;
+                    logContainer.appendChild(row);
+                });
+            });
+
+            // 3. Sync System Bar Performance Profile
+            speedMetricsList.sort((a, b) => b.duration - a.duration);
+            if (barChartInstance) {
+                barChartInstance.data.labels = speedMetricsList.slice(0, 5).map(i => i.label);
+                barChartInstance.data.datasets[0].data = speedMetricsList.slice(0, 5).map(i => i.duration);
+                barChartInstance.update();
+            }
+        }
+
+        // Extracts all matching historical latency targets for an item when clicked
+        function showEndpointDrilldown(fullName) {
+            const container = document.getElementById('drilldown-panel');
+            document.getElementById('drilldown-title').innerText = fullName;
+            document.getElementById('drilldown-subtitle').innerText = `Historical Latency Over Last ${globalHistoryLedger.length} Runs`;
+            container.classList.remove('hidden');
+
+            const historyPoints = globalHistoryLedger.map(run => {
+                let matchingAssertion = null;
+                run.testResults.forEach(s => {
+                    s.assertionResults.forEach(a => {
+                        if (a.fullName === fullName) matchingAssertion = a;
+                    });
+                });
+                return {
+                    timestamp: run.timestamp,
+                    duration: matchingAssertion ? matchingAssertion.duration : 0
+                };
+            });
+
+            if (endpointChartInstance) endpointChartInstance.destroy();
+
+            const ctx = document.getElementById('endpointHistoryChart').getContext('2d');
+            endpointChartInstance = new Chart(ctx, {
+                type: 'line',
+                data: {
+                    labels: historyPoints.map(p => p.timestamp),
+                    datasets: [{
+                        label: 'Duration (ms)',
+                        data: historyPoints.map(p => p.duration),
+                        borderColor: '#3b82f6',
+                        backgroundColor: 'rgba(59, 130, 246, 0.1)',
+                        fill: true,
+                        tension: 0.1
+                    }]
+                },
+                options: {
+                    responsive: true,
+                    maintainAspectRatio: false,
+                    plugins: { legend: { display: false } },
+                    scales: {
+                        x: { grid: { color: '#1e293b' }, ticks: { color: '#64748b' } },
+                        y: { grid: { color: '#1e293b' }, ticks: { color: '#64748b' }, beginAtZero: true }
+                    }
+                }
+            });
+            container.scrollIntoView({ behavior: 'smooth' });
+        }
+
+        // Chart Initialization Setup Loops
+        function initCharts() {
+            lineChartInstance = new Chart(document.getElementById('lineChart').getContext('2d'), {
+                type: 'line',
+                data: { labels: [], datasets: [{ label: 'Pass', data: [], borderColor: '#10b981', tension: 0.2 }, { label: 'Fail', data: [], borderColor: '#f43f5e', tension: 0.2 }] },
+                options: { responsive: true, maintainAspectRatio: false, scales: { x: { ticks: { color: '#64748b' } }, y: { beginAtZero: true, ticks: { color: '#64748b' } } } }
+            });
+
+            barChartInstance = new Chart(document.getElementById('barChart').getContext('2d'), {
+                type: 'bar',
+                data: { labels: [], datasets: [{ data: [], backgroundColor: '#3b82f6' }] },
+                options: { responsive: true, maintainAspectRatio: false, plugins: { legend: { display: false } }, scales: { y: { beginAtZero: true } } }
+            });
+        }
+
+        // Fetch snapshot directly on page layout render to completely prevent visual lag or empty states
+        initCharts();
+        fetch('/api/snapshot').then(r => r.json()).then(renderInterface);
+
+        // Connect the continuous stream pipeline
+        const eventSource = new EventSource('/stream');
+        eventSource.onopen = () => {
+            document.getElementById('status-dot').className = "w-2.5 h-2.5 rounded-full bg-emerald-500 animate-pulse";
+            document.getElementById('status-text').className = "text-xs font-mono font-bold text-emerald-400";
+            document.getElementById('status-text').innerText = "Live Streaming";
+        };
+        eventSource.onmessage = (e) => renderInterface(JSON.parse(e.data));
+    </script>
+</body>
+</html>

package/src/runner.js

@@ -0,0 +1,98 @@
+const express = require('express');
+const { exec } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const app = express();
+const PORT = process.env.PORT || 3000;
+const RESULTS_PATH = path.join(process.cwd(), 'test-results.json');
+
+// Global Backend Memory Stores to persist data through browser refreshes
+let currentTelemetryData = null;
+let historicalRunsLedger = []; 
+const MAX_HISTORICAL_RUNS = 20;
+
+// Helper to safely fetch, clean, and digest local metrics data
+function loadTelemetryFromDisk() {
+  if (fs.existsSync(RESULTS_PATH)) {
+    try {
+      const rawData = fs.readFileSync(RESULTS_PATH, 'utf-8');
+      if (!rawData.trim()) return null;
+      
+      const parsed = JSON.parse(rawData);
+      currentTelemetryData = parsed;
+      
+      // Append runtime data into historical tracks matrix
+      const timestamp = new Date().toLocaleTimeString();
+      historicalRunsLedger.push({
+        timestamp,
+        numPassedTests: parsed.numPassedTests || 0,
+        numFailedTests: parsed.numFailedTests || 0,
+        testResults: parsed.testResults || []
+      });
+
+      // Bound size bounds
+      if (historicalRunsLedger.length > MAX_HISTORICAL_RUNS) {
+        historicalRunsLedger.shift();
+      }
+      return parsed;
+    } catch (e) {
+      return null;
+    }
+  }
+  return null;
+}
+
+// Bootstrap raw baseline load instantly on process boot
+loadTelemetryFromDisk();
+
+app.get('/', (req, res) => {
+  res.sendFile(path.join(__dirname, 'index.html'));
+});
+
+// REST API endpoint to pull absolute system memory instantly on reload
+app.get('/api/snapshot', (req, res) => {
+  res.json({
+    latest: currentTelemetryData,
+    history: historicalRunsLedger
+  });
+});
+
+// Real-Time SSE Live Gate
+app.get('/stream', (req, res) => {
+  res.setHeader('Content-Type', 'text/event-stream');
+  res.setHeader('Cache-Control', 'no-cache');
+  res.setHeader('Connection', 'keep-alive');
+
+  // Immediately stream back current cache frames so it isn't blank on connection hook
+  if (currentTelemetryData) {
+    res.write(`data: ${JSON.stringify({ latest: currentTelemetryData, history: historicalRunsLedger })}\n\n`);
+  }
+
+  const watcher = fs.watch(RESULTS_PATH, (eventType) => {
+    if (eventType === 'change') {
+      // Small timeout delay to let file write streams unlock safely
+      setTimeout(() => {
+        const freshlyLoaded = loadTelemetryFromDisk();
+        if (freshlyLoaded && !res.writableEnded) {
+          res.write(`data: ${JSON.stringify({ latest: freshlyLoaded, history: historicalRunsLedger })}\n\n`);
+        }
+      }, 150);
+    }
+  });
+
+  req.on('close', () => watcher.close());
+});
+
+function runTestPipeline() {
+  console.log(`\n🕒 [${new Date().toLocaleTimeString()}] Triggering automated contract check...`);
+  const testExecution = exec('npx vitest run --reporter=default --reporter=json --outputFile=./test-results.json');
+  testExecution.stdout.on('data', (data) => process.stdout.write(data));
+  testExecution.stderr.on('data', (data) => process.stderr.write(data));
+}
+
+app.listen(PORT, () => {
+  console.log(`🖥️  super-api-tester Live Console: http://localhost:${PORT}`);
+  runTestPipeline();
+  setInterval(runTestPipeline, 120000); // Trigger every 5 minutes
+});