Spring Test Control Center (STCC)

A smart, standalone test management system for Spring Boot projects. Zero configuration, zero cognitive overhead.

What is STCC?

STCC is a local developer tool that understands your Spring Boot project, indexes every test, runs them through a rich web interface, analyzes failures intelligently, and tracks execution history over time.

Launch it in any Spring Boot repository and get a professional test dashboard instantly.

Features

• Automatic Project Discovery — Detects Maven/Gradle, multi-module structure, Spring Boot version, Java version, and test frameworks
• Complete Test Indexing — Parses all test classes with a proper Java AST parser, building a hierarchical test tree
• Smart Execution — Run all, by module, by class, by method, rerun failed, clean+run, debug mode
• Live Streaming Console — Real-time WebSocket output with color-coded lines and collapsible stack traces
• Intelligent Failure Classification — 17 built-in rules that identify root causes (context failures, bean issues, Mockito problems, Testcontainers, etc.) and provide actionable suggestions
• Execution History — SQLite-backed history with flaky test detection, slow test ranking, and duration trends
• Git Operations Panel — Full git workflow: fetch, pull, push, force-push (with lease), rebase, sync fork, stash, cherry-pick, branch management, staging/unstaging, and commit — all with confirmation dialogs
• Git Impact Analysis — Detects changed files from upstream and maps them to affected test classes via import-based, name-based, and package-based strategies
• Smart Terminal — Integrated shell with command history, autocomplete, pinned commands, and executable multi-command blocks with sequential execution and failure handling
• Dependency View — Visual graph and tree of Test ↔ Production class relationships with force-directed layout, zoom/pan, and detail side-panel
• Maven Tool Panel — Execute arbitrary Maven commands with real-time streaming output, presets, and module selection
• API Explorer — Built-in Swagger-like panel to browse, test, and validate all 70+ REST API endpoints directly from the dashboard
• Performance Analytics — Test duration trends, slowest tests, and execution performance insights
• Watch Mode — Auto-run tests on file changes
• Settings Panel — Configure JVM args, Java home, Maven options, reset history, and clear execution queue
• Session Persistence — Navigate to Git, Terminal, or any panel during a test run and return to live progress without losing state
• Dark Mode Web UI — Professional dashboard with test tree explorer, live console, suggestion panel, and history view

Quick Start

Prerequisites

• Node.js 18+ (LTS recommended)
• JDK 17+ with JAVA_HOME set
• Maven or Gradle (wrapper scripts work too)
• A Spring Boot project with pom.xml or build.gradle

Note: better-sqlite3 is a native addon that compiles during install. On most systems this works automatically. If you hit errors, ensure you have C++ build tools installed (node-gyp prerequisites).

Install & Run

# Option 1: Run directly (no install needed)
cd /path/to/your/spring-boot-project
npx spring-test-control-center

# Option 2: Install globally
npm install -g spring-test-control-center
cd /path/to/your/spring-boot-project
stcc

# Option 3: Install as a project dev dependency
npm install --save-dev spring-test-control-center
npx stcc

The dashboard opens automatically at http://localhost:3000.

CLI Options

stcc [project-path] [options]

Arguments:
  project-path          Path to Spring Boot project root (default: current directory)

Options:
  -p, --port <port>     Server port (default: 3000)
  -h, --help            Show help
  -v, --version         Show version
  --debug               Enable debug logging
  -q, --quiet           Suppress info logging
  --no-open             Don't open browser automatically

Examples

# Launch in current directory with defaults (port 3000)
stcc

# Point to a specific project
stcc /home/dev/my-spring-app

# Custom port, no auto-open browser
stcc --port 8080 --no-open

# Debug logging
stcc --debug

Architecture

┌────────────────────────────────────────────────────────────────────────┐
│                           Web UI Layer                                 │
│  Dashboard │ Test Tree │ Console │ History │ Git Changes │ Git Panel   │
│  Smart Terminal │ Dependency View │ Maven Panel │ API Explorer         │
│  Performance Analytics │ Settings                                      │
├────────────────────────────────────────────────────────────────────────┤
│                    REST API (70+ endpoints) + WebSocket                │
├────────────────────────────────────────────────────────────────────────┤
│                         Core Engine Layer                              │
│                                                                        │
│  ┌─────────────────┐  ┌──────────────────────┐  ┌──────────────────┐  │
│  │  Discovery       │  │  Test Indexer         │  │  Git Service     │  │
│  │  Engine          │  │  (Java AST Parser)    │  │  (Full Workflow) │  │
│  └─────────────────┘  └──────────────────────┘  └──────────────────┘  │
│                                                                        │
│  ┌─────────────────┐  ┌──────────────────────┐  ┌──────────────────┐  │
│  │  Execution       │  │  Output Parser        │  │  Terminal        │  │
│  │  Engine          │  │  (Console + XML)      │  │  Service         │  │
│  └─────────────────┘  └──────────────────────┘  └──────────────────┘  │
│                                                                        │
│  ┌─────────────────┐  ┌──────────────────────┐  ┌──────────────────┐  │
│  │  Failure         │  │  History Store        │  │  Watch           │  │
│  │  Classifier      │  │  (SQLite)             │  │  Service         │  │
│  └─────────────────┘  └──────────────────────┘  └──────────────────┘  │
│                                                                        │
│  ┌─────────────────┐  ┌──────────────────────┐  ┌──────────────────┐  │
│  │  Git Impact      │  │  Dependency Graph     │  │  JDK             │  │
│  │  Analyzer        │  │  Service              │  │  Resolver        │  │
│  └─────────────────┘  └──────────────────────┘  └──────────────────┘  │
│                                                                        │
│  ┌─────────────────┐  ┌──────────────────────┐  ┌──────────────────┐  │
│  │  Maven Tool      │  │  Preset               │  │  Config          │  │
│  │  Service         │  │  Repository            │  │  Manager         │  │
│  └─────────────────┘  └──────────────────────┘  └──────────────────┘  │
└────────────────────────────────────────────────────────────────────────┘

Project Structure

stcc/
├── src/
│   ├── index.ts                        # CLI entry point
│   ├── server.ts                       # Express + WebSocket server wiring
│   ├── core/
│   │   ├── types.ts                    # TypeScript type definitions
│   │   ├── config.ts                   # Configuration manager
│   │   ├── project-discovery.ts        # Maven/Gradle detection & parsing
│   │   ├── test-indexer.ts             # Test file scanning & tree building
│   │   ├── execution-engine.ts         # Process spawning & management
│   │   ├── output-parser.ts            # Console + XML result parsing
│   │   ├── streaming-parser.ts         # Real-time build phase parsing
│   │   ├── failure-classifier.ts       # 17-rule failure analysis engine
│   │   ├── history-store.ts            # SQLite persistence layer
│   │   ├── git-service.ts              # Full git operations (push, pull, rebase, stash, branch, etc.)
│   │   ├── git-change-detector.ts      # Git diff detection (upstream, staged, untracked)
│   │   ├── terminal-service.ts         # Shell command execution & management
│   │   ├── watch-service.ts            # File change watcher for auto-run
│   │   ├── jdk-resolver.ts             # JDK detection & version resolution
│   │   ├── maven-module-resolver.ts    # File-to-module mapping
│   │   ├── test-impact-index.ts        # Production → Test reverse index
│   │   ├── test-impact-analyzer.ts     # Git + index for impact analysis
│   │   ├── dependency-graph-service.ts # Bidirectional Test ↔ Production graph
│   │   └── maven-tool-service.ts       # Maven execution, resolver, presets
│   ├── api/
│   │   ├── routes.ts                   # REST API endpoints (70+)
│   │   └── websocket.ts               # Real-time WebSocket handler
│   └── utils/
│       ├── logger.ts                   # Colored logging utility
│       ├── platform.ts                 # Cross-platform helpers
│       └── java-parser.ts             # Character-level Java file parser
├── public/
│   ├── index.html                      # SPA shell
│   ├── css/
│   │   ├── styles.css                  # Core dark mode stylesheet
│   │   ├── sidebar.css                 # Sidebar & test tree styles
│   │   ├── failures.css                # Failure classification styles
│   │   ├── maven-panel.css             # Maven panel styles
│   │   ├── insights.css                # Insights & analytics styles
│   │   ├── perf-analytics.css          # Performance analytics styles
│   │   ├── command-palette.css         # Command palette styles
│   │   ├── git-panel.css               # Git operations panel styles
│   │   ├── settings-panel.css          # Settings panel styles
│   │   ├── smart-terminal.css          # Smart terminal styles
│   │   └── api-explorer.css            # API explorer / Swagger styles
│   └── js/
│       ├── app.js                      # Application orchestrator
│       ├── services/
│       │   ├── api.js                  # REST API client
│       │   └── websocket.js            # WebSocket client
│       └── components/
│           ├── test-tree.js            # Hierarchical test explorer
│           ├── execution-panel.js      # Test run dashboard & results
│           ├── console.js              # Live streaming console
│           ├── toast.js                # Notification toasts
│           ├── git-changes.js          # Git impact analysis panel
│           ├── git-panel.js            # Full git operations panel
│           ├── smart-terminal.js       # Integrated smart terminal
│           ├── dependency-view.js      # Graph + tree dependency viewer
│           ├── maven-panel.js          # Maven tool execution panel
│           ├── api-explorer.js         # Swagger-like API explorer
│           ├── perf-analytics.js       # Performance analytics view
│           ├── settings-panel.js       # Settings & data management
│           ├── suggestions.js          # AI-powered failure suggestions
│           └── command-palette.js      # Keyboard command palette
├── package.json
├── tsconfig.json
└── README.md

Core Capabilities

Project Discovery

Automatically detects:

• Maven (pom.xml) or Gradle (build.gradle / build.gradle.kts)
• Multi-module structure
• Spring Boot version
• Java version
• JUnit 4 vs JUnit 5
• Test frameworks (Mockito, Testcontainers, AssertJ, WireMock, REST Assured, etc.)

Test Indexer

Scans src/test/java across all modules using a character-by-character Java parser that handles:

• Package declarations and imports
• Class and nested class declarations
• @Test, @ParameterizedTest, @Disabled, @DisplayName, @Nested annotations
• Comment and string literal skipping
• Brace-counting for accurate nesting

Produces a hierarchical tree: Project → Module → Package → Class → Method

Execution Engine

Builds correct Maven/Gradle commands for any scope:

• Run all tests
• Run specific module (-pl module)
• Run specific class (-Dtest=Class / --tests Class)
• Run specific method (-Dtest=Class#method)
• Rerun failed tests
• Clean + run
• Debug mode (JVM debug port 5005)

Streams output in real-time via WebSocket. Supports cancellation with proper process tree cleanup. Navigating away from the execution view preserves state — return at any time to see live progress.

Output Parser

Parses test results from two sources (XML reports are preferred):

1. XML reports — target/surefire-reports/TEST-*.xml (Maven) or build/test-results/test/TEST-*.xml (Gradle)
2. Console output — Regex-based parsing of Maven Surefire / Gradle test output

Extracts: test counts, pass/fail/skip status, durations, stack traces, assertion diffs, compilation errors.

Failure Classifier

17 built-in rules covering:

| Category | Rules | |---|---| | Spring Context | ApplicationContext load failure, BeanCreationException, NoSuchBeanDefinition, UnsatisfiedDependency, Circular dependency | | Database | Flyway migration, Liquibase migration, Transaction rollback | | Network | Port already in use | | Mockito | Strict stubbing, Verification failures | | Testcontainers | Container startup failure | | Assertion | Assertion failures, NullPointerException | | Context Caching | Context invalidation conflicts | | Connection/Timeout | Connection refused, Test timeout |

Each rule provides: root cause, human-readable explanation, actionable suggestions, severity level, and documentation links.

History Store

SQLite-backed persistence tracking:

• Full execution history with test-level results
• Flaky test detection — identifies tests that alternate between pass and fail
• Slow test ranking — average and max duration per test
• Duration trends — charted over time
• Automatic cleanup of old data (configurable retention)

Data is stored in .stcc/history.db within the project directory.

Git Service

Complete git workflow support with confirmation dialogs for destructive operations:

| Operation | Description | |---|---| | Status | Staged, unstaged, untracked files with robust porcelain parsing | | Fetch/Pull | From any remote with branch selection | | Push | Regular push and force push with --force-with-lease (safe) | | Sync Fork | Fetch upstream + fast-forward merge + push to origin | | Rebase | Interactive rebase on upstream with abort support | | Stash | Save, pop, drop with custom messages | | Branch | Create, switch, delete, rename branches | | Commit | Stage, unstage, discard, commit, amend | | Cherry-pick | Apply specific commits to current branch | | Reset | Soft reset (keep changes) and hard reset (destructive) | | Clean | Remove untracked files |

Git Impact Analysis

Detects changes from the upstream branch and maps them to affected tests:

• Computes merge-base with upstream branch
• Parses git diff --name-status for staged, unstaged, and committed changes
• Maps production class changes to test classes via three strategies:
  • Import-based — scans test file imports to find which tests reference a changed class
  • Name-based — matches UserServiceTest → UserService naming conventions
  • Package-based — tests in the same package as a changed class
• Falls back to module-level test runs for large changesets (500+ files)

Smart Terminal

Integrated shell with developer-focused features:

• Command history with arrow-key navigation and persistent storage
• Autocomplete with context-aware suggestions (git, maven, system commands)
• Pinned commands for quick access to frequently used commands
• Smart blocks — multi-command sequences that execute sequentially with:
  • Confirmation modal showing all commands before execution
  • Automatic stop on failure with clear error reporting
  • Commands displayed with arrow (→) flow notation
• Command reference organized by category (Git, Maven, System)
• Working directory tracking with branch display

Dependency Graph

Visualizes Test ↔ Production class relationships:

• Builds bidirectional mapping on-demand (lazy, filtered)
• Supports module, package, and search filtering
• Two visual modes:
  • Graph Mode — Canvas force-directed layout with zoom/pan/drag
  • Tree Mode — Hierarchical DOM view with lazy expansion

Maven Tool Panel

Execute arbitrary Maven commands from the UI:

• Command Builder — goals, options, profiles, properties, env vars, module, parallel threads
• Lifecycle Phases — clickable buttons for standard Maven phases plus common plugin goals
• Presets — save, load, delete user-defined command presets (persisted to .stcc/maven-presets.json)
• Streaming Output — real-time console with ANSI color support, line filtering, debug collapse
• Cancellation — graceful process tree kill on Windows and Unix

API Explorer

Built-in Swagger-like interface for API validation:

• Browse all 70+ endpoints organized in 13 groups
• Color-coded method tags (GET, POST, PUT, DELETE)
• Expandable endpoint details with parameter editors
• Try It button to execute requests and see live responses
• Copy as cURL for use in external tools
• Search/filter to quickly find endpoints
• Response display with status codes, timing, and JSON formatting
• Accessible from dashboard quick actions and Tools menu

Web UI Panels

| Panel | Access | Description | |---|---|---| | Dashboard | Home button / STCC logo | Stats cards, quick actions, last run summary, flaky test alerts | | Test Tree | Left sidebar | Expandable tree with search and filters (failed, slow, flaky, pinned) | | Execution View | Runs automatically on test execution | Live pipeline, progress ring, tabbed results, failure triage | | Git Panel | Header → Git button | Full git operations with status, branches, log, stash management | | Smart Terminal | Header → Terminal button | Integrated shell with blocks, history, and autocomplete | | Watch Mode | Header → Watch button | Auto-run tests on file changes | | Maven Panel | Tools → Maven | Command builder with presets and streaming output | | Dependencies | Tools → Dependencies | Force-directed graph of test/production relationships | | Performance | Tools → Performance | Test duration trends and slowest test analysis | | API Explorer | Tools → API Explorer | Interactive Swagger-like API testing interface | | Settings | Tools → Settings | JVM args, Java home, data management | | Console | Bottom drawer (Ctrl+`) | Live build output with failure filtering | | Command Palette | Ctrl+Shift+P | Quick access to any action |

API Reference

All endpoints are documented and testable via the built-in API Explorer (Tools → API Explorer).

Endpoint Groups

| Group | Endpoints | Description | |---|---|---| | Health & Project | 2 | Health check, project model | | Tests | 3 | Test tree, search, reindex | | Execution | 6 | Execute, cancel, status, rerun, queue | | Results | 3 | Latest results, by ID, JUnit XML export | | History & Analytics | 7 | History list, flaky tests, slow tests, trends, failure classification | | Git Impact | 4 | Impact analysis, run impacted tests | | Git Operations | 26 | Full git workflow (status, fetch, push, rebase, branch, stash, commit, etc.) | | Maven | 9 | Execute, cancel, status, presets, modules | | Dependency Graph | 4 | Graph, tree, node details, modules | | Watch Mode | 3 | Start, stop, status | | Terminal | 4 | Execute command, kill, suggest, history | | Configuration | 2 | Get/update config | | JDK Management | 2 | Detected JDKs, refresh |

Total: 75 endpoints

Keyboard Shortcuts

| Shortcut | Action | |---|---| | Ctrl+Shift+P | Open command palette | | Ctrl+K | Focus test search | | Ctrl+`` | Toggle console drawer | | Ctrl+Enter | Run selected tests | | Escape | Close modal / panel |

Cross-Platform Support

Works on Windows, macOS, and Linux. Handles:

• Maven wrapper (mvnw / mvnw.cmd)
• Gradle wrapper (gradlew / gradlew.bat)
• Path separators and normalization
• Process tree killing (taskkill on Windows, SIGTERM/SIGKILL on Unix)
• Git porcelain format variations across platforms

Tech Stack

• Backend: Node.js, TypeScript, Express, WebSocket (ws)
• Frontend: Vanilla JavaScript (no framework), CSS custom properties
• Storage: SQLite via better-sqlite3
• Parsing: fast-xml-parser (XML), custom character-level parser (Java)

Configuration

STCC stores its data in a .stcc/ directory within the project root:

| File | Purpose | |---|---| | .stcc/history.db | SQLite execution history, flaky/slow test data | | .stcc/maven-presets.json | Saved Maven command presets | | .stcc/config.json | User configuration (JVM args, paths, etc.) |

Publishing

STCC is published to the public npm registry. Releases are automated via GitHub Actions.

Manual Publish

# Login to npm (one-time)
npm login

# Bump version (patch / minor / major)
npm version patch

# Publish (prepublishOnly runs clean + build automatically)
npm publish

Automated Publish (CI/CD)

1. Add your npm access token as a GitHub repository secret named NPM_TOKEN
2. Create a GitHub Release — the workflow at .github/workflows/publish.yml will build and publish automatically

Verifying the Package

# Check what will be included in the tarball
npm pack --dry-run

# Test the package locally before publishing
npm pack
npm install -g spring-test-control-center-1.0.0.tgz
stcc --version

License

MIT