JAWA 🚀

JavaScript Apache Wrapper for JMeter

A modern CLI tool to simplify JMeter performance testing. Initialize projects, run tests, and view reports with simple commands.

📦 Installation

npm install -g jawa-framework

Verify installation:

jawa --version

⚡ Prerequisites

JMeter must be installed on your system:

# macOS
brew install jmeter

# Linux/Windows
# Download from: https://jmeter.apache.org

Verify JMeter:

jmeter --version

🚀 Quick Start

1️⃣ Create New Project

jawa init my-project
cd my-project

Generated structure:

my-project/
├── .env                     # Environment configuration
├── plan/
│   └── main.jmx            # JMeter test plan
├── prop/
│   ├── dev/                # Dev environment properties
│   │   ├── user.properties
│   │   └── jmeter.properties
│   ├── prod/               # Production environment properties
│   │   ├── user.properties
│   │   └── jmeter.properties
│   └── uat/                # UAT environment properties
│       ├── user.properties
│       └── jmeter.properties
├── data/
│   ├── dev/                # Dev test data (CSV files)
│   ├── prod/               # Prod test data (CSV files)
│   └── uat/                # UAT test data (CSV files)
├── reports/                # HTML reports (timestamped)
├── results/                # Test results (timestamped)
└── lib/                    # Custom JMeter plugins

2️⃣ Configure Environment

Edit .env file to set target environment:

TARGET_ENV=dev
BASE_URL=http://localhost:8080
THREADS=1
RAMPUP=1
LOOP=1

Or customize properties per environment in prop/dev/, prop/prod/, etc.

3️⃣ Run Test

# Use environment from .env file
jawa run --loop=1 --user=1 --ramp=1

# Override environment via command line
jawa run --env=prod --loop=10 --user=50 --ramp=10

4️⃣ View Report

jawa report

Opens the latest HTML report in your browser.

📖 Commands

jawa init

Initialize a new JAWA project with environment-based structure.

jawa init my-load-test

Creates project with plan/, prop/[env]/, and data/[env]/ folders.

jawa run

Run JMeter performance test.

Options:

| Option | Description | Default | |--------|-------------|---------| | -e, --env | Target environment (dev/prod/uat) | dev | | -l, --loop | Loop count per user | 1 | | -u, --user | Number of concurrent users | 1 | | -r, --ramp | Ramp-up period in seconds | 1 | | -d, --duration | Test duration (0 = loop-based) | 0 | | --heap | JVM heap memory | 3g | | --base-url | Override base URL | - | | -g, --gui | Open JMeter GUI | false | | -f, --file | Test file path | plan/main.jmx | | --web | Launch interactive web UI | false | | -p, --port | Web UI port | 7247 or .env |

Examples:

# Quick test on dev
jawa run --loop=1 --user=1 --ramp=1

# Load test on production
jawa run --env=prod --loop=10 --user=50 --ramp=5

# Stress test on UAT with more memory
jawa run --env=uat --loop=20 --user=100 --ramp=10 --heap=4g

# Use environment from .env file
jawa run --loop=5 --user=10

# Time-based test (run for 5 minutes)
jawa run --user=20 --ramp=5 --duration=300

# Custom base URL
jawa run --loop=5 --user=10 --base-url=https://api.example.com

# 🌐 Launch Web UI (Locust-style interface)
jawa run --web

# Web UI on custom port
jawa run --web --port=8080

🌐 Web UI Mode (--web)

Launch an interactive web interface for test configuration and real-time monitoring.

Features:

• 🎯 Thread Group Selection - Choose which thread groups to run
• 📊 Real-time Statistics - Live monitoring with 2-second polling
• 📈 Charts - RPS, Response Time, Active Users visualization
• 💾 Download Reports - ZIP, CSV, HTML report, JMeter logs
• 🔄 State Persistence - Resume monitoring after page refresh
• 🎨 Modern UI - Clean, responsive interface inspired by Locust

Usage:

# Start web UI (opens browser automatically)
jawa run --web

# Access at: http://localhost:7247

Tabs:

• Statistics: Real-time request metrics (requests, failures, response times, percentiles)
• Charts: Visual graphs for RPS, response time trends, and user load
• Failures: Track failed requests with error details
• Exceptions: Monitor test exceptions and errors
• Download Data: Export results in multiple formats

Configuration:

# Set port in .env file
PORT=8080

# Or via command line
jawa run --web --port=8080

jawa report

Open the latest HTML report in your browser.

jawa report

jawa stop

Stop all running JAWA processes (JMeter tests and web servers).

jawa stop

Forcefully terminates:

• All running JMeter test processes
• JAWA web UI servers
• Background test executions

Cross-platform support:

• macOS/Linux: Uses pkill to find and stop processes
• Windows: Uses taskkill to terminate processes

When to use:

• Tests are stuck or not responding
• Need to kill background web servers
• Clean up before starting new tests
• Emergency stop during runaway tests

🎯 Features

• ✅ Timestamped Reports - Every run creates a separate report folder
• ✅ Auto ZIP Archives - Results automatically compressed for sharing
• ✅ Integrated Report Generation - No separate steps, no hanging
• ✅ Cross-Platform - Works on macOS, Windows, Linux
• ✅ Dynamic Memory - Configurable heap size for large tests
• ✅ Professional Output - Clean console logs with progress tracking

📁 Output Structure

After running tests, your project will have:

my-project/
├── reports/
│   ├── report-20241209-143022/
│   └── report-20241209-145530/
├── results/
│   ├── result-20241209-143022/
│   └── result-20241209-145530/
├── jmeter_logs/
│   └── jmeter-20241209-143022.log
├── report-zips/
│   └── report-20241209-143022.zip
└── result-zips/
    └── result-20241209-143022.zip

Benefits:

• All reports are preserved (no overwriting)
• ZIP files ready for sharing
• Timestamped for easy tracking

🔧 Configuration

Memory Sizing Guide

| Users | Recommended Heap | |-------|------------------| | 1-10 | --heap=1g | | 10-50 | --heap=2g | | 50-100 | --heap=3g (default) | | 100+ | --heap=4g or higher |

Loop vs Duration

Loop-based (recommended for API tests):

jawa run --loop=10 --user=5

Time-based (recommended for endurance tests):

jawa run --duration=300 --user=10

Edit Test Plan

Open JMeter GUI to customize your test:

jawa run --gui

🛠️ Workflow

# 1. Create project
jawa init load-test
cd load-test

# 2. Edit test plan (optional)
jawa run --gui

# 3. Run test
jawa run --loop=5 --user=10 --ramp=2

# 4. View results
jawa report

# 5. Share results
# Send: report-zips/report-TIMESTAMP.zip

🐛 Troubleshooting

JMeter Not Found

# Install JMeter first
brew install jmeter

Out of Memory

# Increase heap size
jawa run --heap=4g --loop=10 --user=50

Report Not Generated

Check the log file:

cat jmeter_logs/jmeter-TIMESTAMP.log

Test Fails to Start

Ensure main.jmx is valid:

jawa run --gui

📚 Documentation

• Workflow Guide: NEW_WORKFLOW.md
• GitHub Issues: Report a bug
• GitHub Discussions: Ask questions

🤝 Contributing

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

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

📄 License

MIT © badrusalam11

⭐ Support

If you find JAWA helpful, please give it a star on GitHub!

Made with ❤️ for performance testers