cursor-rules-java/.cursor/rules/151-java-performance-jmeter.mdc at b403b34f3c1ee39ea30bf6e1ea95392a04bcfab7 · jabrena/cursor-rules-java · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
---
description:
globs:
alwaysApply: false
---
# Run performance tests based on JMeter

## ⚠️ CRITICAL INSTRUCTION FOR AI ASSISTANTS ⚠️

**WHEN USING THE PERFORMANCE SCRIPT TEMPLATE:**
- **COPY THE BASH SCRIPT EXACTLY** from `java-performance-script-template.md`
- **NO MODIFICATIONS, INTERPRETATIONS, OR ENHANCEMENTS** allowed
- **USE EVERY LINE VERBATIM** - do not change logic, structure, or features
- **DO NOT CREATE YOUR OWN VERSION** - use the provided template only
- The template script is complete, tested, and production-ready

---

## 📋 How to Copy the Performance Script Template

### Step 1: Create the Script File
When a user requests JMeter performance testing setup:

1. **Copy the entire script** from `.cursor/rules/templates/java-performance-script-template.md`
2. **Create the file** as `run-jmeter.sh` in the project root
3. **Make it executable**: `chmod +x run-jmeter.sh`

### Step 2: Template Location
- **Source**: `.cursor/rules/templates/java-performance-script-template.md`
- **Destination**: `run-jmeter.sh` (project root)
- **Copy Method**: Exact verbatim copy - no changes allowed

---

## 🚀 Script Usage Instructions

### Basic Usage
```bash
# Run with default settings (1000 loops, 1 thread, 1s ramp-up)
./run-jmeter.sh

# Custom configuration
./run-jmeter.sh -l 500 -t 10 -r 30

# Open JMeter GUI
./run-jmeter.sh -g
```

### Available Options
- `-l, --loops LOOPS`: Number of loops per thread (default: 1000)
- `-t, --threads THREADS`: Number of concurrent threads (default: 1)
- `-r, --ramp-up SECONDS`: Ramp-up period in seconds (default: 1)
- `-g, --gui`: Open JMeter GUI instead of running in non-GUI mode
- `-h, --help`: Show detailed help message

### Environment Variables
```bash
# Override defaults using environment variables
JMETER_LOOPS=500 JMETER_THREADS=5 ./run-jmeter.sh

# Or export them
export JMETER_LOOPS=1000
export JMETER_THREADS=10
export JMETER_RAMP_UP=30
./run-jmeter.sh
```

### Example Scenarios
```bash
# Light load test
./run-jmeter.sh -l 100 -t 1 -r 1

# Medium load test
./run-jmeter.sh -l 500 -t 5 -r 10

# Heavy load test
./run-jmeter.sh -l 1000 -t 20 -r 60

# Quick GUI setup
./run-jmeter.sh -g
```

---

## 📁 Required Project Structure

The script expects this structure:
```
project-root/
├── run-jmeter.sh                          # The performance script
├── src/test/resources/jmeter/
│   └── load-test.jmx                      # JMeter test plan
└── target/                                # Generated reports (auto-created)
    ├── jmeter-results.jtl                 # Raw results
    ├── jmeter-report/                     # HTML dashboard
    │   └── index.html                     # Main report
    └── jmeter.log                         # Execution log
```

---

## 🔧 Prerequisites

1. **JMeter Installation**: Must be installed and available in PATH
2. **Test Plan**: Must exist at `src/test/resources/jmeter/load-test.jmx`
3. **Executable Permissions**: Script must be executable (`chmod +x run-jmeter.sh`)

---

## 📊 Output Files

After running the script, you'll get:

1. **Raw Results**: `target/jmeter-results.jtl` (JTL format)
2. **HTML Dashboard**: `target/jmeter-report/index.html` (automatically opens in browser)
3. **Execution Log**: `jmeter.log` (debugging information)

---

## 💡 Best Practices

### For Load Testing
- Start with low thread counts and gradually increase
- Monitor system resources during tests
- Use realistic ramp-up periods (don't slam the server)

### For Test Plan Development
- Use GUI mode (`-g`) for initial test plan creation
- Test with low load first (`-l 10 -t 1`)
- Validate test plan logic before heavy load testing

### For CI/CD Integration
```bash
# Example CI/CD usage
./run-jmeter.sh -l 100 -t 5 -r 10
# Check exit code for pass/fail status
```

---

## 🚨 Important Notes

- The script automatically cleans previous results
- HTML reports open automatically in your default browser
- All configuration is parameterized - no hardcoded values
- The script provides colored output for better visibility
- Comprehensive error handling and validation included

---