mbkhealth
v1.0.1
Published
Comprehensive application health testing, route discovery, asset validation, and console error detection for MBKTech Node.js/Express applications
Readme
mbkhealth
Comprehensive application health testing, route discovery, asset validation, and console error detection for MBKTech Node.js/Express applications.
Features
- 🔒 Protected Health Testing: Trigger comprehensive test runs through a protected
POST /api/health/testendpoint secured by an API key or shared secret. - ⚡ Standard Liveness Endpoint: Instant
GET /api/healthandGET /healthresponding with standardized JSON status and uptime. - 🗺️ Automatic Route Discovery: Recursively introspects Express router stacks, sub-routers, dynamic routes, and sitemaps (
/sitemap.xml) to discover all public pages. - 🧪 Deep Functional Verification (Not just HTTP 200!):
- Content Checks: Verifies presence of
<title>,<body>, non-empty DOM, and custom expected content strings. - Backend Error Detection: Identifies 5xx errors, unhandled exceptions, leaked stack traces, and database connection failures.
- Frontend Console Errors: Leverages JSDOM virtual console to catch client-side
console.error, unhandled exceptions, and script syntax errors. - CSS Validation: Verifies that stylesheets return HTTP 200 with
text/cssand that CSS selectors match elements on the page. - Asset Verification: Checks that images (
<img>), icons (<link rel="icon">), and media load successfully with zero 404s.
- Content Checks: Verifies presence of
- 📊 Structured JSON Reports: Detailed overall health status (
healthy,degraded,unhealthy), summary metrics, system diagnostics (memory, uptime), and granular per-route results. - 🧩 Zero-Overhead Integration: Drop into any Express app with just 2 lines of code.
Installation
npm install mbkhealthQuick Start (Express Integration)
In your application's src/app.js:
import express from "express";
import { createHealthRouter } from "mbkhealth";
const app = express();
// ... other middleware and routes ...
// Mount health testing endpoints under /api/health
app.use("/api/health", createHealthRouter({
appName: "my-mbktech-app",
secretKey: process.env.HEALTH_TEST_KEY || "your-secret-key",
}));
// Also alias /health if desired
app.get("/health", (req, res) => res.redirect("/api/health"));Endpoints
1. GET /api/health (Public Liveness Ping)
Fast, lightweight check for monitoring agents and load balancers.
Response (200 OK):
{
"success": true,
"status": "healthy",
"app": "my-mbktech-app",
"uptime": 450.2,
"timestamp": "2026-09-11T18:30:00.000Z",
"version": "1.0.0"
}2. POST /api/health/test (Protected Health Testing Suite)
Runs deep health testing across all discovered application pages.
Authentication: Provide the secret key using any of the following headers:
x-health-key: your-secret-keyAuthorization: Bearer your-secret-keyx-api-key: your-secret-key
Example cURL Request:
curl -X POST http://localhost:4133/api/health/test \
-H "x-health-key: your-secret-key" \
-H "Content-Type: application/json" \
-d '{ "checkAssets": true, "checkCss": true }'Response (200 OK or 503 Service Unavailable if unhealthy):
{
"success": true,
"health": "healthy",
"appName": "mbktech.org",
"timestamp": "2026-09-11T18:35:10.123Z",
"durationMs": 420.5,
"summary": {
"totalRoutesChecked": 14,
"passed": 14,
"failed": 0,
"warnings": 1,
"totalAssetsChecked": 32,
"assetsFailed": 0,
"totalConsoleErrors": 0
},
"system": {
"uptime": 1250.4,
"memoryUsage": {
"heapUsedMb": 42.15,
"heapTotalMb": 85.2,
"rssMb": 110.8
},
"nodeVersion": "v25.2.1",
"environment": "production",
"platform": "win32 (x64)"
},
"routes": [
{
"path": "/",
"method": "GET",
"status": 200,
"durationMs": 35.1,
"health": "healthy",
"contentType": "text/html; charset=utf-8",
"contentChecks": {
"hasTitle": true,
"title": "MBK Tech",
"hasBody": true,
"backendErrorDetected": false
},
"consoleErrors": [],
"cssChecks": {
"stylesheetsFound": 2,
"stylesheetsLoaded": 2,
"stylesApplied": true,
"matchingRulesCount": 18,
"errors": []
},
"assetChecks": {
"totalAssets": 5,
"assetsTested": 5,
"loadedAssets": 5,
"failedAssets": []
},
"errors": [],
"warnings": [],
"logs": [
"Testing /...",
"Received HTTP 200 in 35.1ms",
"CSS: 2/2 loaded, applied=true",
"Assets: 5/5 loaded, failed=0"
]
}
]
}Standalone / Programmatic Usage
You can also run health checks programmatically (for example, in CI/CD pipelines or Vitest/Jest suites):
import { runHealthCheck } from "mbkhealth";
import app from "./src/app.js";
const report = await runHealthCheck(app, {
appName: "my-app",
includeRoutes: ["/", "/about", "/contact"],
checkAssets: true,
checkCss: true,
checkConsole: true,
});
console.log("Overall Health:", report.health);
console.log("Passed:", report.summary.passed, "Failed:", report.summary.failed);Configuration Options
| Option | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| appName | string | process.env.APP_NAME or "mbktech-app" | Application identifier in reports |
| secretKey | string | process.env.HEALTH_TEST_KEY | Secret key for protecting POST /test |
| includeRoutes | string[] | [] | Additional routes to test |
| excludeRoutes | string[] | ["/favicon.ico", "/api/health*"] | Routes to skip |
| routeParams | object | { ":id": "1", ":slug": "test" } | Replacement values for parameterized routes |
| checkAssets | boolean | true | Verify image, icon, and media URLs (HTTP 200) |
| checkCss | boolean | true | Verify stylesheet HTTP 200 and DOM matching |
| checkConsole | boolean | true | Verify zero frontend JS and console errors |
| checkSitemap | boolean | true | Discover routes from /sitemap.xml |
| timeoutMs | number | 15000 | Per-route request timeout |
| maxAssetsPerPage | number | 20 | Maximum assets to check per page |
| expectedContent | object | {} | Map of route path to array of required strings |
License
MIT © Muhammad Bin Khalid & MBKTech.org