Automation & Monitoring Platform for Modern Applications
Supercheck is an enterprise-grade distributed platform engineered for scalability and reliability at scale. It delivers comprehensive test automation with real-time monitoring, intelligent job orchestration, and parallel execution capabilities, empowering development and SRE teams with a robust solution to accelerate software quality and delivery cycles.
- Docker Desktop (or an alternative like Orbstack)
- At least 4GB of available RAM
- At least 10GB of available disk space
git clone https://github.com/supercheck-io/supercheck.git
cd supercheck
# Start the full application stack
docker-compose up -d
# Main app
http://localhost:3000
# Stop the full application stack
docker-compose down
Key configuration options in docker-compose.yml
:
# Capacity Management
RUNNING_CAPACITY=5 # Max concurrent test/job executions (visible in app header)
QUEUED_CAPACITY=50 # Max queued jobs
TEST_EXECUTION_TIMEOUT_MS=120000 # Test execution timeout in milliseconds (2 mins)
JOB_EXECUTION_TIMEOUT_MS=900000 # Job execution timeout in milliseconds (15 mins)
# Security
SUPER_ADMIN_EMAILS=super.admin@example.com # Comma-separated super admin emails
# Monitor Configuration
RECENT_MONITOR_RESULTS_LIMIT=5000 # Checks limit for 'Recent Check Results' table
# Playwright Configuration
PLAYWRIGHT_RETRIES=1
PLAYWRIGHT_TRACE=on
PLAYWRIGHT_SCREENSHOT=on
PLAYWRIGHT_VIDEO=on
# Browser support (disabled by default for performance)
ENABLE_FIREFOX=false
ENABLE_WEBKIT=false
ENABLE_MOBILE=false
# SMTP Email Configuration
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=test@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM_EMAIL=test@gmail.com
# Notification Channel Limits
NEXT_PUBLIC_MAX_JOB_NOTIFICATION_CHANNELS=10
NEXT_PUBLIC_MAX_MONITOR_NOTIFICATION_CHANNELS=10
Critical Security Variables (Must Change in Production):
REDIS_PASSWORD
BETTER_AUTH_SECRET
VARIABLES_ENCRYPTION_KEY
CREDENTIAL_ENCRYPTION_KEY
SMTP_PASSWORD
- Navigate to the Tests section
- Click "New Test" to create a Playwright test
- Write your test script or use the recorder
- Run the test
- If test passes you will be able to save test
- Go to the Monitors section
- Choose a Monitor type (HTTP Request, Website, Port or Ping) and fill form
- Configure check intervals and alert thresholds
- Set up notification channels (email, webhooks, Slack etc)
- Navigate to the main Dashboard for system overview
- View overall project status and metrics
- Monitor system health and performance indicators
- Track recent activity across tests, jobs, and monitors
- Go to the Jobs section to schedule automated test execution
- Create new jobs with cron-based scheduling (optional)
- Link jobs to existing test/tests
- Monitor job run execution history and status
- Navigate to the Runs section for execution history
- Filter runs by test, status, date range, or execution type
- View detailed run reports with logs and artifacts
- View Playwright report, video and traces
- Analyze performance trends and failure patterns
- Access the Playground for interactive test creation
- Choose test type=Browser Test, API Test, Database Test, or Custom Test
- Write or edit test scripts with real-time syntax highlighting
- Run tests immediately with live feedback
- Save successful tests to your test library or Delete tests
- Access the Organization Admin panel at
/org-admin
- Manage organization members and their roles
- Configure organization-wide settings and preferences
- Monitor organization usage and capacity
- Access the Super Admin Dashboard at
/super-admin
- View system-wide statistics and user activity
- Manage user roles and permissions across all organizations
- Impersonate users for support and testing purposes
# Get API key from the Jobs section by editing a specific job
curl -H "Authorization=Bearer your-api-key" \
-X POST http://localhost:3000/api/jobs/[job-id]/trigger \
-H "Content-Type=application/json"
- SUPER_ADMIN (
super_admin
) - System-wide access - ORG_OWNER (
org_owner
) - Full organization control - ORG_ADMIN (
org_admin
) - Organization management - PROJECT_ADMIN (
project_admin
) - Full project administration within assigned projects - PROJECT_EDITOR (
project_editor
) - Project-specific editing - PROJECT_VIEWER (
project_viewer
) - Read-only access
graph TD
subgraph "System Level"
SA[SUPER_ADMIN<br/>System-wide Control]
SA --> SA1[User Management]
SA --> SA2[System Impersonation]
SA --> SA3[All Org & Project Access]
end
subgraph "Organization Level"
OO[ORG_OWNER<br/>Organization Control]
OA[ORG_ADMIN<br/>Organization Management]
OO --> OO1[Delete Organization]
OO --> OO2[Full Member Management]
OO --> OO3[All Projects Access]
OA --> OA1[Manage Organization]
OA --> OA2[Member Management]
OA --> OA3[All Projects Access]
OA -.->|Cannot| OO1
end
subgraph "Project Level"
PA[PROJECT_ADMIN<br/>Assigned Projects Only]
PE[PROJECT_EDITOR<br/>Assigned Projects Only]
PV[PROJECT_VIEWER<br/>Read Only]
PA --> PA1[Manage Project Members]
PA --> PA2[Full Project Resources]
PA --> PA3[Create/Edit/Delete]
PE --> PE1[Edit Project Resources]
PE --> PE2[Create/Edit Only - No Delete]
PE -.->|Cannot| PA1
PV --> PV1[View All Resources]
PV -.->|Cannot| PE1
PV -.->|Cannot| PA1
end
SA -.-> OO
SA -.-> OA
OO -.-> PA
OA -.-> PA
PA -.-> PE
PE -.-> PV
style SA fill:#ff6b6b,stroke:#d63031,color:#fff
style OO fill:#fd79a8,stroke:#e84393,color:#fff
style OA fill:#fdcb6e,stroke:#e17055,color:#fff
style PA fill:#a29bfe,stroke:#6c5ce7,color:#fff
style PE fill:#55a3ff,stroke:#2d96ff,color:#fff
style PV fill:#74b9ff,stroke:#0984e3,color:#fff
Resource | Super Admin | Org Owner | Org Admin | Project Admin | Project Editor | Project Viewer |
---|---|---|---|---|---|---|
Users (ban/unban) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
Organizations | ✅ | ✅ (own) | ✅ (own) | 👁️ (view) | 👁️ (view) | 👁️ (view) |
Organization Members | ✅ | ✅ | ✅ | 👁️ (view) | 👁️ (view) | 👁️ (view) |
Projects | ✅ | ✅ | ✅ | ✅ (assigned) | 👁️ (assigned) | 👁️ (assigned) |
Project Members | ✅ | ✅ | ✅ | ✅ (assigned projects) | 👁️ (assigned projects) | 👁️ (assigned projects) |
Jobs | ✅ | ✅ | ✅ | ✅ (assigned projects) | ✏️ (assigned projects) | 👁️ (assigned projects) |
Tests | ✅ | ✅ | ✅ | ✅ (assigned projects) | ✏️ (assigned projects) | 👁️ (assigned projects) |
Monitors | ✅ | ✅ | ✅ | ✅ (assigned projects) | ✏️ (assigned projects) | 👁️ (assigned projects) |
Runs | ✅ | ✅ | ✅ | ✅ (assigned projects) | 👁️ (assigned projects) | 👁️ (assigned projects) |
API Keys | ✅ | ✅ | ✅ | ✅ (assigned projects) | ✏️ (assigned projects) | ❌ |
Notifications | ✅ | ✅ | ✅ | ✅ (assigned projects) | ✏️ (assigned projects) | 👁️ (assigned projects) |
Tags | ✅ | ✅ | ✅ | ✅ (assigned projects) | ✏️ (assigned projects) | 👁️ (assigned projects) |
Variables/Secrets | ||||||
Variable Create/Edit | ✅ | ✅ | ✅ | ✅ (assigned projects) | ✅ (assigned projects) | ❌ |
Variable Delete | ✅ | ✅ | ✅ | ✅ (assigned projects) | ❌ | ❌ |
Secret Values View | ✅ | ✅ | ✅ | ✅ (assigned projects) | ❌ | ❌ |
Legend=✅ = Full Access, ✏️ = Create/Edit Only (no delete), 👁️ = View Only, ❌ = No Access
- Database audit logging for all security events
- Rate limiting on admin operations
- Session token hashing and validation
- Comprehensive permission checking
- Secure impersonation with context switching
Supercheck uses a hierarchical multi-tenancy model with organizations containing projects. This provides secure resource isolation and flexible team collaboration while maintaining proper data segregation.
System Level → Organization Level → Project Level
↓ ↓ ↓
Super Admin → Org Owner/Admin → Project Admin/Editor/Viewer
- New User Registration=Automatically creates a default organization and project
- Default Organization=Named after the user or custom name
- Default Project=Named "Default Project" within the organization
- Role Assignment=User becomes the owner of both organization and project
- Multi-Organization Support=Users can belong to multiple organizations
- Organization Switching=Session-based context switching between organizations
- Member Management=Invite, manage, and assign roles to organization members
- Resource Isolation=Complete data separation between organizations
- Admin Oversight=Super admins can view and manage all organizations
- Org Owner (
org_owner
)=Full organization control including deletion - Org Admin (
org_admin
)=Organization management without deletion rights
- Project-Scoped Resources=Tests, jobs, monitors, variables are scoped to projects
- Project Switching=Session-based context switching within the active organization
- Member Assignment=Granular assignment of users to specific projects
- Default Project=Every organization has a default project for immediate use
- Resource Limits=Configurable limits on projects per organization
- Project Admin (
project_admin
)=Full project control and member management - Project Editor (
project_editor
)=Create and edit resources, no delete permissions - Project Viewer (
project_viewer
)=Read-only access to all project resources
- Active Organization=Current organization in user session
- Active Project=Current project within the active organization
- Context Switching=API endpoints for switching between organizations and projects
- Impersonation Support=Admin impersonation preserves organization and project context
- Organization Isolation=Complete data separation between organizations
- Project Scoping=All resources (tests, jobs, monitors, variables) scoped to projects
- Cross-Project Protection=No accidental access to resources across projects
- Audit Trail=Complete tracking of all organization and project activities
- Organization Roles=Higher organization roles inherit project permissions
- Project Assignment=Project-specific roles only apply to assigned projects
- Super Admin Override=System-level access bypasses organization/project restrictions
# Organization & Project Limits (Configurable)
MAX_PROJECTS_PER_ORG=10 # Maximum projects per organization (default=10)
# Default Settings
DEFAULT_PROJECT_NAME="Default Project" # Name for auto-created projects
Supercheck provides a comprehensive variable and secret management system for secure handling of configuration data and sensitive information across your testing and monitoring projects.
- Project-Scoped Variables=Variables are isolated within projects for better organization
- Encrypted Secrets=Sensitive data is encrypted using AES-256-GCM encryption
- Role-Based Access Control=Different permission levels for viewing, creating, editing, and deleting variables
- Audit Trail=Complete tracking of variable creation and modifications
- Test Integration=Easy access to variables in test scripts using helper functions
- Plain text configuration values
- Visible to all project members with appropriate permissions
- Used for non-sensitive configuration like URLs, usernames, timeouts
- Encrypted at rest using AES-256-GCM encryption
- Values masked in the UI for security
- Only visible to users with management permissions
- Used for sensitive data like passwords, API keys, tokens
Role | View Variables | Create/Edit Variables | Delete Variables | View Secret Values |
---|---|---|---|---|
Super Admin | ✅ | ✅ | ✅ | ✅ |
Org Owner | ✅ | ✅ | ✅ | ✅ |
Org Admin | ✅ | ✅ | ✅ | ✅ |
Project Admin | ✅ (assigned projects) | ✅ (assigned projects) | ✅ (assigned projects) | ✅ (assigned projects) |
Project Editor | ✅ (assigned projects) | ✅ (assigned projects) | ❌ | ❌ |
Project Viewer | ✅ (assigned projects) | ❌ | ❌ | ❌ |
Variables can be accessed in Playwright test scripts using built-in helper functions:
// Access regular variables
const apiUrl = await getVariable("API_URL");
const timeout = await getVariable("REQUEST_TIMEOUT");
// Access encrypted secrets
const apiKey = await getSecret("API_KEY");
const password = await getSecret("USER_PASSWORD");
// Use in your tests
await page.goto(apiUrl);
await page.fill('[name="password"]', password);
Supercheck includes a sophisticated multi-channel alerting system that keeps your team informed about job failures, monitor status changes, and system events through various notification providers.
- Configuration: SMTP-based email delivery
- Configuration: Webhook URL and channel configuration
- Configuration: Custom URL, HTTP method, headers, and payload
- Configuration: Bot token and chat ID
- Configuration: Discord webhook URL
- Failure Alerts=Sent when monitors change from 'up' to 'down' status
- Recovery Alerts=Sent when monitors return from 'down' to 'up' status
- SSL Expiration Alerts=Warnings for expiring SSL certificates
- Failure Alerts=Triggered when test jobs fail
- Success Alerts=Confirmation when critical jobs complete successfully
- Timeout Alerts=Notifications for jobs that exceed time limits
- Failure Threshold=Number of consecutive failures before alerting (prevents false positives)
- Recovery Threshold=Number of consecutive successes before recovery alerts
- Configurable Sensitivity=Different thresholds for different monitors/jobs
- Maximum 3 failure alerts per failure sequence to prevent notification spam
- Unlimited recovery alerts to ensure resolution visibility
- Status change detection for intelligent alert triggers
- Complete audit trail of all sent notifications
- Delivery status tracking for each notification provider
- Failed delivery logging with error details and retry information
- Alert frequency analysis to optimize threshold settings
sequenceDiagram
participant U as 👤 User
participant F as 🖥️ Next.js Frontend
participant V as 🔍 Validation API
participant Q as 📨 Redis/BullMQ
participant W as ⚡ NestJS Worker
participant E as ⚙️ Execution Service
participant P as 🎭 Playwright Runner
participant D as 🗄️ PostgreSQL
participant S as 📦 MinIO/S3 Storage
participant R as 🚥 Redis Pub/Sub
Note over U,R: Single Test Execution Flow (Playground)
%% Script Validation Phase
U->>F: Write test code & click "Run Test"
F->>V: POST /api/validate-script
V-->>F: Validation response
alt Script validation fails
F-->>U: Show validation errors
else Script validation passes
%% Test Creation & Queuing
F->>F: Generate unique testId
F->>D: Create test record (status: pending)
F->>Q: Add to 'test-execution' queue
Q-->>F: Job queued successfully
F-->>U: Test started (show loading state)
%% SSE Connection Setup
F->>F: Open SSE /api/test-status/events/[testId]
F->>R: Subscribe to test channels
R-->>F: SSE connection established
%% Worker Processing
Q->>W: TestExecutionProcessor picks up job
activate W
W->>D: Update test status (running)
W->>R: Publish status event
R-->>F: SSE: status='running'
F-->>U: Update UI (running state)
%% Test Execution
W->>E: Call runSingleTest()
activate E
E->>E: Create unique run directory
E->>E: Generate test script file
E->>E: Configure Playwright settings
E->>P: Execute test with Playwright
activate P
P->>P: Run browser automation
P->>P: Generate screenshots/videos
P->>P: Create HTML report
P->>P: Generate trace files
P-->>E: Execution results
deactivate P
%% Result Processing
E->>E: Process test artifacts
E->>S: Upload report & artifacts
S-->>E: Upload complete
E->>D: Create report record
E-->>W: Test execution complete
deactivate E
%% Completion & Cleanup
W->>D: Update test status (completed/failed)
W->>R: Publish completion event
deactivate W
R-->>F: SSE: test complete
F->>F: Close SSE connection
F-->>U: Show completion toast
%% Report Viewing
U->>F: Click "View Report"
F->>F: GET /api/test-results/[...path]
F->>S: Fetch report files
S-->>F: Report content
F-->>U: Display interactive report
end
sequenceDiagram
participant U as 👤 User
participant F as 🖥️ Next.js Frontend
participant A as 🔐 Auth Service
participant V as 🔧 Variable Resolver
participant Q as 📨 Redis/BullMQ
participant W as ⚡ NestJS Worker
participant E as ⚙️ Execution Service
participant P as 🎭 Playwright Runner
participant D as 🗄️ PostgreSQL
participant S as 📦 MinIO/S3 Storage
participant R as 🚥 Redis Pub/Sub
participant N as 📢 Notification Service
Note over U,N: Multi-Test Job Execution Flow
%% Job Initiation
U->>F: Select job & click "Run Job"
F->>A: Validate user session
A-->>F: User authorized
%% Job Setup & Validation
F->>D: Fetch job details & associated tests
D-->>F: Job configuration & test list
F->>V: Resolve project variables/secrets
V->>D: Fetch project variables
D-->>V: Variable data
V-->>F: Resolved variables & secrets
%% Capacity Check & Queuing
F->>Q: Check queue capacity
alt Capacity exceeded
Q-->>F: HTTP 429 - Too Many Requests
F-->>U: Show capacity limit error
else Capacity available
F->>D: Create run record (status: pending)
F->>Q: Add to 'job-execution' queue
Q-->>F: Job queued (runId)
F-->>U: Job started (loading state)
%% SSE Connection
F->>F: Open SSE /api/job-status/events/[runId]
F->>R: Subscribe to job channels
R-->>F: SSE connection established
%% Worker Processing
Q->>W: JobExecutionProcessor picks up job
activate W
W->>D: Update run status (running)
W->>R: Publish job status event
R-->>F: SSE: status='running'
F-->>U: Update UI (running state)
%% Parallel Test Execution
loop For each test in job
W->>E: Execute individual test
activate E
E->>E: Create test run directory
E->>E: Inject resolved variables
E->>E: Apply job configuration
E->>P: Execute test with Playwright
activate P
P->>P: Run browser automation
P->>P: Generate test artifacts
P-->>E: Individual test result
deactivate P
E->>S: Upload test artifacts
E->>D: Save individual test result
E->>R: Publish test progress
R-->>F: SSE: individual test status
F-->>U: Update test progress
deactivate E
end
%% Job Completion Processing
W->>E: Generate consolidated job report
E->>S: Upload job report
E->>D: Update run status (completed/failed)
%% Notification Processing
alt Job has alert configuration
W->>N: Process job notifications
activate N
N->>D: Fetch notification providers
N->>N: Generate alert messages
N->>N: Send notifications (email/slack/webhook)
N->>D: Log notification history
deactivate N
end
W->>R: Publish job completion
deactivate W
R-->>F: SSE: job complete
F->>F: Close SSE connection
F-->>U: Show completion notification
%% Report Access
U->>F: View job results
F->>D: Fetch run details & test results
D-->>F: Consolidated job data
F->>S: Fetch job report files
S-->>F: Report artifacts
F-->>U: Display job results dashboard
end
sequenceDiagram
participant S as ⏰ Job Scheduler
participant Q as 📨 Redis/BullMQ
participant W as ⚡ NestJS Worker
participant M as 👀 Monitor Service
participant H as 🌐 HTTP Client
participant P as 📡 Ping Service
participant T as 🔌 Port Scanner
participant D as 🗄️ PostgreSQL
participant R as 🚥 Redis Pub/Sub
participant A as 📢 Alert Service
participant N as 📧 Notification Providers
Note over S,N: Automated Monitor Execution Flow
%% Scheduled Trigger
S->>S: Cron schedule triggers
S->>Q: Add monitor job to 'monitor-execution' queue
Q->>W: MonitorProcessor picks up job
activate W
W->>D: Fetch monitor configuration
D-->>W: Monitor settings & alert config
%% Check if Monitor is Active
alt Monitor is paused or disabled
W->>W: Skip execution
W-->>Q: Job completed (skipped)
else Monitor is active
W->>M: Execute monitor check
activate M
%% Different Monitor Types
alt Monitor type: HTTP Request
M->>H: Perform advanced HTTP/HTTPS request
activate H
H->>H: Send request with custom headers/auth
H->>H: Support custom methods (GET/POST/PUT/etc)
H->>H: Validate custom status codes
H->>H: Check keyword in response
H->>H: Measure response time
H-->>M: HTTP check results
deactivate H
else Monitor type: Website
M->>H: Perform simplified website check
activate H
H->>H: GET request to URL (default)
H->>H: Check response with 200-299 status
H->>H: Verify SSL certificate (if enabled)
H->>H: Measure response time
H-->>M: Website check results
deactivate H
else Monitor type: Ping Host
M->>P: Perform ICMP ping
activate P
P->>P: Send ping packets
P->>P: Measure response time
P->>P: Calculate packet loss
P-->>M: Ping results
deactivate P
else Monitor type: Port Check
M->>T: Check port accessibility
activate T
T->>T: Attempt TCP/UDP connection
T->>T: Measure connection time
T-->>M: Port check results
deactivate T
end
%% Result Processing
M->>M: Process monitor results
M->>D: Fetch previous monitor status
D-->>M: Historical status data
M->>M: Determine status change (up/down)
M->>D: Save monitor result
M->>D: Update monitor status
deactivate M
%% Alert Processing
alt Status change detected OR Alert conditions met
W->>A: Trigger alert processing
activate A
A->>D: Fetch alert configuration
A->>A: Check failure/recovery thresholds
A->>A: Evaluate alert conditions
alt Alert should be sent
A->>D: Fetch notification providers
D-->>A: Provider configurations
loop For each notification provider
A->>N: Send notification
activate N
N->>N: Format alert message
N->>N: Send via provider (email/slack/webhook)
N-->>A: Delivery status
deactivate N
end
A->>D: Log alert history
A->>D: Update alert counters
end
deactivate A
end
%% Real-time Updates (if applicable)
W->>R: Publish monitor status update
R-->>R: Notify active SSE connections
%% SSL Certificate Alerts (if enabled)
alt SSL certificate expiring soon
W->>A: Trigger SSL expiration alert
A->>N: Send SSL warning notifications
A->>D: Log SSL alert
end
end
deactivate W
Q-->>S: Monitor execution complete
S->>S: Schedule next monitor execution
Special thanks to the exceptional open-source projects that make Supercheck possible:
- Next.js - Full-stack React framework for building fast, scalable web applications
- NestJS - Scalable framework for server-side applications
- Playwright - End-to-end testing framework
- PostgreSQL - Advanced relational database
- Redis - In-memory database
- BullMQ - Robust job/message queue for Node.js
- MinIO - S3-compatible object storage
- Shadcn/ui - UI components
- Better Auth - Authentication system