Run matrix of tasks across services with parallel execution and status reporting
npm install verify-gridRun matrix of tasks across services with parallel execution and live status reporting





Features • Installation • Quick Start • CLI • Configuration
---
- 🚀 Parallel Execution - Run tasks concurrently with configurable limits
- 🎬 Live Updates - Animated spinners and real-time status in your terminal
- 🎯 Priority Control - Execute tasks in specific order or randomize for testing
- ⚡ Fail-Fast Mode - Stop immediately on first error
- 📊 Multiple Formats - Table, minimal, or JSON output
- 🎨 Horizontal Layout - Optimized for terminal space (services × tasks)
- 🔧 Task Overrides - Customize tasks per service
- ✨ Optional Tasks - Skip tasks that don't apply to certain services
- ⏱️ Timeout Support - Set time limits for tasks
- 🌍 Environment Variables - Per-task and per-service configuration
- 🎲 Random Execution - Test robustness with randomized order
- 🔄 CI/CD Ready - Proper exit codes (0=success, 1=errors, 2=config error)
``bash`
npm install verify-grid
1. Create configuration file qa.config.js:
`javascript`
export default {
tasks: {
lint: { command: 'npm', args: ['run', 'lint'], priority: 10 },
test: { command: 'npm', args: ['test'], priority: 5 },
build: { command: 'npm', args: ['run', 'build'] },
},
services: [
{ name: 'api', cwd: './services/api' },
{ name: 'web', cwd: './services/web' },
],
};
2. Run tasks:
`bashRun all tasks on all services
qa run
🎮 CLI Commands
$3
Execute tasks across services with live status updates.
#### Options
| Option | Description | Default |
|--------|-------------|---------|
|
--tasks | Comma-separated tasks or "all" | all |
| --services | Comma-separated services or "all" | all |
| --concurrency | Maximum parallel jobs | CPU count |
| --fail-fast | Stop on first error | false |
| --random | Randomize execution order | false |
| --no-watch | Disable live updates | enabled in TTY |
| --format | Output: table, minimal, json | table |
| --output | Save JSON to file | - |
| --timeout | Timeout per task (milliseconds) | - |
| --no-color | Disable colors | enabled in TTY |
| --config | Custom config file path | qa.config.js |#### Examples
`bash
Run all tasks
qa runRun specific tasks on specific services
qa run --tasks lint,test --services api,webLimit concurrency and stop on error
qa run --concurrency 2 --fail-fastOutput as JSON
qa run --format json --output results.jsonSet timeout (30 seconds)
qa run --timeout 30000Randomize for testing
qa run --random
`⚙️ Configuration
$3
`javascript
{
tasks: {
taskName: {
command: 'npm', // Command to execute (required)
args: ['test'], // Arguments (optional)
shell: false, // Run in shell (optional)
timeout: 30000, // Timeout in ms (optional)
priority: 10, // Higher = earlier (optional)
optional: false, // Skip if not applicable (optional)
env: { // Environment variables (optional)
NODE_ENV: 'test'
}
}
}
}
`Task Properties:
| Property | Type | Required | Description |
|----------|------|----------|-------------|
|
command | string | ✅ | Command to execute |
| args | string[] | ❌ | Command arguments |
| shell | boolean | ❌ | Run in shell (default: false) |
| timeout | number | ❌ | Timeout in milliseconds |
| priority | number | ❌ | Execution priority (higher first, default: 0) |
| optional | boolean | ❌ | Skip task if command not defined (default: false) |
| env | Record | ❌ | Environment variables |$3
`javascript
{
services: [
{
name: 'api', // Service name (required)
cwd: './services/api', // Working directory (required)
tasks: { // Task overrides (optional)
test: {
args: ['test', '--coverage'],
priority: 5
}
},
env: { // Environment variables (optional)
PORT: '3000'
}
}
]
}
`Service Properties:
| Property | Type | Required | Description |
|----------|------|----------|-------------|
|
name | string | ✅ | Service name |
| cwd | string | ✅ | Working directory path |
| tasks | Record | ❌ | Override task properties |
| env | Record | ❌ | Environment variables |$3
`javascript
export default {
tasks: {
lint: {
command: 'npm',
args: ['run', 'lint'],
timeout: 30000,
priority: 10,
},
test: {
command: 'npm',
args: ['test'],
priority: 5,
env: { NODE_ENV: 'test' },
},
build: {
command: 'npm',
args: ['run', 'build'],
timeout: 60000,
},
typecheck: {
command: 'tsc',
args: ['--noEmit'],
},
screenshot: {
command: '',
optional: true, // Only runs if service defines it
},
},
services: [
{
name: 'api',
cwd: './services/api',
env: { PORT: '3000' },
tasks: {
test: {
args: ['test', '--coverage'],
timeout: 45000,
},
},
},
{
name: 'web',
cwd: './services/web',
env: { PORT: '3001' },
tasks: {
screenshot: {
command: 'npm',
args: ['run', 'screenshot'],
},
},
},
{
name: 'shared',
cwd: './packages/shared',
tasks: {
build: { command: 'tsup' },
},
},
],
};
`📊 Output Formats
$3
Horizontal matrix with live updates:
`
Service | lint | test | build
---------|-----------|--------------|-------
api | ✓ done | ⠋ running | ⏳ queued
web | ✓ done | ✓ done | ⏳ queued
shared | ✓ done | ✗ error | - skipped
`$3
Simple text output:
`
lint api done
lint web done
test api running
`$3
Structured output for automation:
`json
{
"startedAt": 1234567890,
"endedAt": 1234567900,
"durationMs": 10000,
"matrix": {
"lint": {
"api": { "status": "done", "exitCode": 0, "durationMs": 1234 }
}
},
"errors": []
}
`🚦 Exit Codes
| Code | Meaning |
|------|---------|
|
0 | All tasks completed successfully ✅ |
| 1 | One or more tasks failed ❌ |
| 2` | Configuration error or invalid arguments ⚠️ |MIT