hplay-atlas

A beautiful visual test runner with a web UI. Run your Vitest or Jest tests from any directory and view results in an intuitive interface.

Features

• 🎨 Beautiful web UI for running and viewing tests
• 🚀 Works with Vitest and Jest
• 📁 Run tests from any directory
• 🔍 Filter tests by file or test name
• 📊 Visual test results with detailed error messages
• 📜 Test history tracking
• 🌳 View test file structure with suites and individual tests

Installation

Global Installation (Recommended)

npm install -g hplay-atlas

npx (No Installation Required)

npx hplay-atlas

Usage

Basic Usage

Navigate to your project directory and run:

hplay-atlas

This will:

• Start the server on http://localhost:8080
• Look for tests in the current directory
• Open the web UI in your browser

Custom Options

# Custom port
hplay-atlas --port 3000

# Custom host (e.g., to expose on network)
hplay-atlas --host 0.0.0.0

# Custom test directory
hplay-atlas --path /absolute/path/to/tests

# All together
hplay-atlas --port 3000 --host 0.0.0.0 --path /path/to/tests

Command Options

• -p, --port <number> - Port to run the server on (default: 8080)
• --host <string> - Host to bind the server to (default: localhost)
• --path <string> - Absolute path to the directory containing tests (default: current directory)
• -h, --help - Display help information
• -V, --version - Display version number

Requirements

Your project should have either:

• Vitest installed (npm install -D vitest)
• Jest installed (npm install -D jest)

The tool will automatically detect which test runner you're using based on your package.json.

Supported Test Files

hplay-atlas automatically discovers test files matching these patterns:

• *.test.js, *.test.ts, *.test.jsx, *.test.tsx
• *.spec.js, *.spec.ts, *.spec.jsx, *.spec.tsx

How It Works

1. Test Discovery: Scans your project directory for test files
2. Test Parsing: Extracts test structure (suites and individual tests)
3. Execution: Runs tests using your project's installed test runner
4. Results: Displays results in a beautiful web interface

API Endpoints

Full Regression Testing

Run all tests in the background and receive results via webhook:

Endpoint: POST /api/tests/full-regression

Request Body:

{
  "pattern": "integration"  // Optional - filter tests by pattern
}

Note: The rootPath is always set to the configured test path (default: current working directory) and cannot be overridden from the request for security reasons.

Response:

{
  "success": true,
  "message": "Full regression started in background. Results will be sent to webhook",
  "jobId": "regression-1234567890-abc123"
}

Webhook URL: Results are sent to https://n8n.hplay-dev.games/webhook/ba21488b-4949-485e-9329-22f94356a2cf

Webhook Payload:

{
  "jobId": "regression-1234567890-abc123",
  "finishedAt": "2024-01-15T10:30:45.000Z",
  "rootPath": "/path/to/tests",
  "runner": "vitest",
  "results": { /* test results JSON */ },
  "stdout": "console output from test run"
}

Example Usage:

# Run all tests
curl -X POST http://localhost:8080/api/tests/full-regression \
  -H "Content-Type: application/json" \
  -d '{}'

# Run tests matching a pattern
curl -X POST http://localhost:8080/api/tests/full-regression \
  -H "Content-Type: application/json" \
  -d '{"pattern": "integration"}'

This endpoint is perfect for CI/CD pipelines where you want to trigger tests asynchronously and receive results via webhook notification.

Pipeline Test Run

Trigger test runs from CI/CD pipelines with metadata tracking:

Endpoint: POST /api/tests/pipeline-run

Request Body:

{
  "commitId": "abc123def456",    // Optional - Git commit hash
  "group": "range",               // Optional - Test group name (e.g., "range", "frequency")
  "branch": "main",               // Optional - Git branch name
  "projectName": "my-project"     // Optional - Project name
}

All fields are optional. The endpoint will pass these parameters to your reporter.py script.

Response:

{
  "success": true,
  "message": "Pipeline test run started in background. Results will be sent to webhook",
  "jobId": "pipeline-1234567890-xyz789"
}

How it works:

1. Accepts pipeline metadata (commit ID, test group, branch, project name)
2. Locates reporter.py in your configured test directory
3. Spawns the reporter script in background with command-line arguments:

   python3 reporter.py --commit-id abc123 --group range --branch main --project-name my-project

4. Returns immediately with a job ID
5. Your reporter.py script handles test execution and webhook reporting

Example Usage:

# Run tests for specific group with metadata
curl -X POST http://localhost:8080/api/tests/pipeline-run \
  -H "Content-Type: application/json" \
  -d '{
    "commitId": "a1b2c3d4",
    "group": "frequency",
    "branch": "feature/new-tests",
    "projectName": "test-automation"
  }'

# Run with minimal metadata
curl -X POST http://localhost:8080/api/tests/pipeline-run \
  -H "Content-Type: application/json" \
  -d '{"group": "range"}'

Requirements:

• A reporter.py script must exist in your test directory root
• The script should accept these command-line arguments:
  • --commit-id - Git commit hash
  • --group - Test group name
  • --branch - Git branch name
  • --project-name - Project name
• Python 3 must be installed in the Docker container (Alpine: apk add python3)

This endpoint is designed for CI/CD pipelines where you need to:

• Track which commit/branch triggered the tests
• Run specific test groups
• Associate test results with project metadata
• Report results asynchronously via webhook

Development

To develop this tool locally:

# Clone the repository
git clone <your-repo-url>
cd hplay-atlas

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build for production
pnpm build

Available Development Commands

• pnpm dev - Start development server
• pnpm build - Build for production (client + server + CLI)
• pnpm build:client - Build client only
• pnpm build:server - Build server only
• pnpm build:cli - Build CLI only
• pnpm start - Run production server
• pnpm test - Run tests
• pnpm typecheck - Validate TypeScript

Publishing to npm

This package is ready to be published to npm:

# Login to npm (first time only)
npm login

# Publish the package
npm publish

Note: Publishing to npm is completely free for public packages!

Before Publishing

1. Update the author field in package.json
2. Add your git repository URL in package.json
3. Update the version field as needed
4. Ensure the package name is unique on npm (or use a scoped name like @yourname/hplay-atlas)

Tech Stack

• Frontend: React 18 + TypeScript + TailwindCSS 3 + Radix UI
• Backend: Express + Node.js
• Testing: Vitest
• Build: Vite
• CLI: Commander.js

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.