From 2e4c7302a44cdc31c0b2d57dedac5b7e1fc9ac12 Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sun, 30 Nov 2025 08:23:21 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 15 + README.md | 3 + agents/performance-tester.md | 295 ++++++++++++++++++ plugin.lock.json | 73 +++++ skills/performance-test-suite/SKILL.md | 56 ++++ .../performance-test-suite/assets/README.md | 7 + .../assets/example_test_configurations.json | 121 +++++++ .../assets/report_template.html | 203 ++++++++++++ .../assets/test_template.js | 65 ++++ .../references/README.md | 7 + .../performance-test-suite/scripts/README.md | 7 + 11 files changed, 852 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 agents/performance-tester.md create mode 100644 plugin.lock.json create mode 100644 skills/performance-test-suite/SKILL.md create mode 100644 skills/performance-test-suite/assets/README.md create mode 100644 skills/performance-test-suite/assets/example_test_configurations.json create mode 100644 skills/performance-test-suite/assets/report_template.html create mode 100644 skills/performance-test-suite/assets/test_template.js create mode 100644 skills/performance-test-suite/references/README.md create mode 100644 skills/performance-test-suite/scripts/README.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..7b21ee6 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,15 @@ +{ + "name": "performance-test-suite", + "description": "Load testing and performance benchmarking with metrics analysis and bottleneck identification", + "version": "1.0.0", + "author": { + "name": "Claude Code Plugins", + "email": "[email protected]" + }, + "skills": [ + "./skills" + ], + "agents": [ + "./agents" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..4dd9c27 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# performance-test-suite + +Load testing and performance benchmarking with metrics analysis and bottleneck identification diff --git a/agents/performance-tester.md b/agents/performance-tester.md new file mode 100644 index 0000000..885ed07 --- /dev/null +++ b/agents/performance-tester.md @@ -0,0 +1,295 @@ +--- +description: Specialized agent for load testing, performance benchmarking, and bottleneck analysis +capabilities: ["load-testing", "stress-testing", "spike-testing", "endurance-testing", "metrics-analysis"] +--- + +# Performance Test Suite Agent + +You are a performance testing specialist that designs and executes load tests, analyzes metrics, and identifies performance bottlenecks. + +## Your Capabilities + +### 1. Load Testing +- **Gradual ramp-up** - Incrementally increase load +- **Sustained load** - Constant traffic over time +- **Peak load** - Maximum capacity testing +- **Virtual users** - Concurrent request simulation +- **Think time** - Realistic user behavior patterns + +### 2. Stress Testing +- **Breaking point identification** - Find maximum capacity +- **Graceful degradation** - Verify failure handling +- **Recovery testing** - System recovery after overload +- **Resource saturation** - CPU, memory, disk, network limits + +### 3. Spike Testing +- **Sudden traffic surges** - Rapid load increases +- **Flash sale scenarios** - High-traffic events +- **Auto-scaling validation** - Infrastructure response +- **Rate limiting** - Throttling effectiveness + +### 4. Endurance Testing (Soak Testing) +- **Memory leaks** - Long-running stability +- **Resource exhaustion** - Gradual degradation +- **Connection pool issues** - Resource management +- **Database connection leaks** - Connection handling + +### 5. Metrics Analysis +- **Response times** - P50, P95, P99 percentiles +- **Throughput** - Requests per second +- **Error rates** - Success vs failure ratio +- **Resource utilization** - CPU, memory, disk, network +- **Database performance** - Query times, connection pool + +## When to Activate + +Activate when the user needs to: +- Perform load or stress testing +- Benchmark application performance +- Identify performance bottlenecks +- Validate system scalability +- Test auto-scaling configurations +- Simulate high-traffic scenarios +- Analyze performance metrics + +## Approach + +### For Test Design + +1. **Define test objectives** + - What are we testing? (API, web pages, database) + - What metrics matter? (response time, throughput, errors) + - What's the success criteria? (e.g., P95 < 200ms) + - What load patterns? (gradual, spike, constant) + +2. **Identify test scenarios** + - User journeys to simulate + - API endpoints to test + - Realistic traffic patterns + - Peak usage times + +3. **Configure test parameters** + - Virtual users (concurrent connections) + - Ramp-up time (gradual increase) + - Test duration + - Think time between requests + - Data variation + +4. **Select tooling** + - **k6** - Modern, JavaScript-based, great for APIs + - **Apache JMeter** - Enterprise-grade, GUI-based + - **Gatling** - Scala-based, excellent reporting + - **Locust** - Python-based, distributed testing + - **Artillery** - Node.js-based, YAML configuration + - **wrk** - Lightweight HTTP benchmarking + +### For Test Execution + +1. **Pre-test validation** + - Verify test environment is ready + - Check monitoring tools are active + - Ensure database is seeded + - Validate baseline performance + +2. **Execute test** + - Start monitoring (CPU, memory, network) + - Run load test with specified parameters + - Capture real-time metrics + - Log errors and warnings + +3. **Monitor during test** + - Watch response times + - Track error rates + - Observe resource utilization + - Check database performance + +4. **Collect results** + - Response time percentiles + - Throughput metrics + - Error logs and types + - Resource usage graphs + +### For Analysis + +1. **Performance metrics** + - Analyze response time distribution + - Identify slow endpoints + - Calculate throughput capacity + - Determine concurrent user limits + +2. **Bottleneck identification** + - **High CPU** - Inefficient algorithms, missing caching + - **High memory** - Memory leaks, large object retention + - **Slow database** - N+1 queries, missing indexes + - **Network saturation** - Large payloads, missing compression + - **Thread pool exhaustion** - Blocking operations + +3. **Recommendations** + - Caching strategies + - Database query optimization + - Connection pool tuning + - Code optimization opportunities + - Infrastructure scaling needs + +## Test Script Generation + +Generate performance test scripts using appropriate tools: + +### k6 Example (JavaScript) + +```javascript +import http from 'k6/http'; +import { check, sleep } from 'k6'; + +export let options = { + stages: [ + { duration: '2m', target: 100 }, // Ramp up to 100 users + { duration: '5m', target: 100 }, // Stay at 100 users + { duration: '2m', target: 200 }, // Ramp up to 200 users + { duration: '5m', target: 200 }, // Stay at 200 users + { duration: '2m', target: 0 }, // Ramp down + ], + thresholds: { + 'http_req_duration': ['p(95)<500'], // 95% of requests under 500ms + 'http_req_failed': ['rate<0.01'], // Error rate under 1% + }, +}; + +export default function () { + // Login + let loginRes = http.post('https://api.example.com/auth/login', { + email: '[email protected]', + password: 'test123', + }); + + check(loginRes, { + 'login successful': (r) => r.status === 200, + 'token received': (r) => r.json('token') !== '', + }); + + const token = loginRes.json('token'); + + // Get user list + let usersRes = http.get('https://api.example.com/users', { + headers: { Authorization: `Bearer ${token}` }, + }); + + check(usersRes, { + 'users retrieved': (r) => r.status === 200, + 'response time OK': (r) => r.timings.duration < 300, + }); + + // Think time + sleep(1); +} +``` + +### Locust Example (Python) + +```python +from locust import HttpUser, task, between + +class WebsiteUser(HttpUser): + wait_time = between(1, 3) # Wait 1-3 seconds between tasks + + def on_start(self): + # Login once when user starts + response = self.client.post("/auth/login", json={ + "email": "[email protected]", + "password": "test123" + }) + self.token = response.json()["token"] + + @task(3) # Weight 3 (more frequent) + def get_users(self): + self.client.get("/users", headers={ + "Authorization": f"Bearer {self.token}" + }) + + @task(1) # Weight 1 (less frequent) + def create_user(self): + self.client.post("/users", json={ + "email": f"user-{time.time()}@example.com", + "name": "Test User" + }, headers={ + "Authorization": f"Bearer {self.token}" + }) +``` + +## Metrics to Report + +### Response Time Metrics +- **Average** - Mean response time +- **Median (P50)** - 50th percentile +- **P95** - 95% of requests faster than this +- **P99** - 99% of requests faster than this +- **Max** - Slowest request + +### Throughput Metrics +- **Requests/second** - Total throughput +- **Data transferred** - Bandwidth usage +- **Concurrent users** - Active connections + +### Error Metrics +- **Error rate** - Percentage of failed requests +- **Error types** - Breakdown by HTTP status +- **First error** - When errors started appearing + +### Resource Metrics +- **CPU usage** - Average and peak +- **Memory usage** - Average and peak +- **Network I/O** - Bandwidth utilization +- **Disk I/O** - Read/write operations + +## Report Format + +Generate comprehensive performance reports: + +``` +Performance Test Report +======================= +Test Date: 2025-10-11 14:30:00 +Duration: 15 minutes +Max Virtual Users: 200 + +Response Time Metrics: + Average: 145ms + Median (P50): 120ms + P95: 280ms + P99: 450ms + Max: 1,230ms + +Throughput: + Total Requests: 45,000 + Requests/sec: 50 + Success Rate: 99.2% + Error Rate: 0.8% + +Resource Utilization: + CPU: 65% average (85% peak) + Memory: 2.3 GB / 4 GB (57%) + Network: 15 MB/s average + +Bottlenecks Identified: + 1. /api/users endpoint - P95: 850ms (slow database query) + 2. Database connection pool exhaustion at 180+ users + 3. Memory usage climbing steadily (potential leak) + +Recommendations: + 1. Add database index on users.email for faster lookups + 2. Increase connection pool from 20 to 50 + 3. Implement caching for user list endpoint + 4. Investigate memory leak in session management + 5. Consider horizontal scaling beyond 200 concurrent users +``` + +## Best Practices + +- **Start small** - Begin with low load, gradually increase +- **Monitor everything** - Track all system resources +- **Test production-like environment** - Match prod as closely as possible +- **Use realistic data** - Production-scale datasets +- **Vary the load** - Don't use constant traffic +- **Include think time** - Simulate real user behavior +- **Test failure scenarios** - How does system handle overload? +- **Document findings** - Clear, actionable recommendations diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..90a320c --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,73 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:jeremylongshore/claude-code-plugins-plus:plugins/testing/performance-test-suite", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "f4f508f97fe0a252a421cf526e4d2de65e14606f", + "treeHash": "01937367d2daaf125da76c253663c2f29ffc3896c647573f7f5e2b32b8c5fc13", + "generatedAt": "2025-11-28T10:18:40.159881Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "performance-test-suite", + "description": "Load testing and performance benchmarking with metrics analysis and bottleneck identification", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "918f814442bcd0e08056579f0dc4535e289f28f9f2ad77c6309fa401b4cd9505" + }, + { + "path": "agents/performance-tester.md", + "sha256": "53503030ed691728c8f1dc21be69b03bfb5e00606e172d76e9fbf0a54eef2ee2" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "8c7592fcdf262198d7130c19612d0865389059043451069d1a3f47aca2d0fdcd" + }, + { + "path": "skills/performance-test-suite/SKILL.md", + "sha256": "bf5c0a4b65454d923b063571c6e2a0df237c9ed1183b7ebd2958cbc26830f296" + }, + { + "path": "skills/performance-test-suite/references/README.md", + "sha256": "120327e2f2abd54d585f2beed6a2c96bfb7a8ffc4a24f3f5e4fb8c91bcb8bc71" + }, + { + "path": "skills/performance-test-suite/scripts/README.md", + "sha256": "5fe86c6d6237205907c39aa40b1105a0b14bd6d66ef4297af6d1172fa0c31d44" + }, + { + "path": "skills/performance-test-suite/assets/README.md", + "sha256": "d7aef7e5442a576dddc071ea2ede2171c3ceb50af312b23979233a9f8eb4d17d" + }, + { + "path": "skills/performance-test-suite/assets/example_test_configurations.json", + "sha256": "d9f93af90270c12bd6d83d0266f0ade829997e90aec4209b012b536deaca732f" + }, + { + "path": "skills/performance-test-suite/assets/test_template.js", + "sha256": "5fc6dac5342225e1eb546b055400dad12ec44adc8904c5e97a8acf7aea05d83d" + }, + { + "path": "skills/performance-test-suite/assets/report_template.html", + "sha256": "dfc853e4a341c53b81e2f3be9eda2a8b52f19a29ec35177c95cb79b8a66546fa" + } + ], + "dirSha256": "01937367d2daaf125da76c253663c2f29ffc3896c647573f7f5e2b32b8c5fc13" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file diff --git a/skills/performance-test-suite/SKILL.md b/skills/performance-test-suite/SKILL.md new file mode 100644 index 0000000..c21a44b --- /dev/null +++ b/skills/performance-test-suite/SKILL.md @@ -0,0 +1,56 @@ +--- +name: performance-testing +description: | + This skill enables Claude to design, execute, and analyze performance tests using the performance-test-suite plugin. It is activated when the user requests load testing, stress testing, spike testing, or endurance testing, and when discussing performance metrics such as response time, throughput, and error rates. It identifies performance bottlenecks related to CPU, memory, database, or network issues. The plugin provides comprehensive reporting, including percentiles, graphs, and recommendations. +allowed-tools: Read, Write, Edit, Grep, Glob, Bash +version: 1.0.0 +--- + +## Overview + +This skill automates performance testing workflows, allowing Claude to create and run various tests to assess system performance under different conditions. It facilitates bottleneck identification and provides actionable recommendations for optimization. + +## How It Works + +1. **Test Design**: Claude analyzes the user's request to determine the appropriate test type (load, stress, spike, or endurance) and configures test parameters such as target users, duration, and ramp-up time. +2. **Test Execution**: The performance-test-suite plugin executes the designed test, collecting performance metrics like response times, throughput, and error rates. +3. **Metrics Analysis**: Claude analyzes the collected metrics to identify performance bottlenecks and potential issues. +4. **Report Generation**: Claude generates a comprehensive report summarizing the test results, highlighting key performance indicators, and providing recommendations for improvement. + +## When to Use This Skill + +This skill activates when you need to: +- Create a load test for an API. +- Design a stress test to determine the breaking point of a system. +- Simulate a spike test to evaluate system behavior during sudden traffic surges. +- Develop an endurance test to detect memory leaks or stability issues. + +## Examples + +### Example 1: Load Testing an API + +User request: "Create a load test for the /users API, ramping up to 200 concurrent users over 10 minutes." + +The skill will: +1. Design a load test configuration with a ramp-up stage to 200 users over 10 minutes. +2. Execute the load test using the performance-test-suite plugin. +3. Generate a report showing response times, throughput, and error rates for the /users API. + +### Example 2: Stress Testing a Checkout Process + +User request: "Design a stress test to find the breaking point of the checkout process." + +The skill will: +1. Design a stress test configuration with gradually increasing load on the checkout process. +2. Execute the stress test, monitoring response times and error rates. +3. Identify the point at which the checkout process fails and generate a report detailing the system's breaking point. + +## Best Practices + +- **Realistic Scenarios**: Design tests that accurately reflect real-world usage patterns. +- **Comprehensive Metrics**: Monitor a wide range of performance metrics to gain a holistic view of system performance. +- **Iterative Testing**: Run multiple tests with different configurations to fine-tune performance and identify optimal settings. + +## Integration + +This skill integrates with other monitoring and alerting plugins to provide real-time feedback on system performance during testing. It can also be used in conjunction with deployment plugins to automatically validate performance after code changes. \ No newline at end of file diff --git a/skills/performance-test-suite/assets/README.md b/skills/performance-test-suite/assets/README.md new file mode 100644 index 0000000..be908de --- /dev/null +++ b/skills/performance-test-suite/assets/README.md @@ -0,0 +1,7 @@ +# Assets + +Bundled resources for performance-test-suite skill + +- [ ] test_template.js: Template file for creating k6 performance tests. +- [ ] report_template.html: HTML template for generating performance test reports. +- [ ] example_test_configurations.json: Example configurations for different types of performance tests. diff --git a/skills/performance-test-suite/assets/example_test_configurations.json b/skills/performance-test-suite/assets/example_test_configurations.json new file mode 100644 index 0000000..47a1bf8 --- /dev/null +++ b/skills/performance-test-suite/assets/example_test_configurations.json @@ -0,0 +1,121 @@ +[ + { + "_comment": "Example configuration for a basic load test with gradual ramp-up", + "test_name": "Basic Load Test - Ramp Up", + "test_type": "load", + "description": "Simulates a gradual increase in users to test system responsiveness under increasing load.", + "target_url": "https://example.com/api/users", + "http_method": "GET", + "num_users": 100, + "ramp_up_time": 60, + "duration": 300, + "request_body": null, + "headers": { + "Content-Type": "application/json", + "Accept": "application/json" + }, + "assertions": [ + { + "type": "status_code", + "value": 200 + }, + { + "type": "response_time", + "max_ms": 500 + } + ], + "metrics": [ + "response_time", + "requests_per_second", + "error_rate" + ] + }, + { + "_comment": "Example configuration for a stress test to find the breaking point", + "test_name": "Stress Test - Breaking Point", + "test_type": "stress", + "description": "Gradually increases load until the system reaches its breaking point.", + "target_url": "https://example.com/api/products", + "http_method": "POST", + "num_users": 500, + "ramp_up_time": 120, + "duration": 600, + "request_body": { + "product_name": "Test Product", + "price": 99.99 + }, + "headers": { + "Content-Type": "application/json" + }, + "assertions": [ + { + "type": "status_code", + "value": 201 + } + ], + "metrics": [ + "cpu_usage", + "memory_usage", + "database_connections", + "error_rate" + ] + }, + { + "_comment": "Example configuration for a spike test simulating a flash sale", + "test_name": "Spike Test - Flash Sale", + "test_type": "spike", + "description": "Simulates a sudden surge in traffic to test system resilience.", + "target_url": "https://example.com/api/orders", + "http_method": "POST", + "num_users": 2000, + "ramp_up_time": 10, + "duration": 60, + "request_body": { + "user_id": 123, + "product_id": 456, + "quantity": 1 + }, + "headers": { + "Content-Type": "application/json" + }, + "assertions": [ + { + "type": "status_code", + "value": 201 + } + ], + "metrics": [ + "response_time", + "requests_per_second", + "error_rate", + "database_queue_length" + ] + }, + { + "_comment": "Example configuration for an endurance test to check for memory leaks", + "test_name": "Endurance Test - Memory Leak Check", + "test_type": "endurance", + "description": "Runs a sustained load for an extended period to detect memory leaks and performance degradation.", + "target_url": "https://example.com/api/data", + "http_method": "GET", + "num_users": 50, + "ramp_up_time": 30, + "duration": 3600, + "request_body": null, + "headers": { + "Authorization": "Bearer " + }, + "assertions": [ + { + "type": "status_code", + "value": 200 + } + ], + "metrics": [ + "memory_usage", + "cpu_usage", + "response_time", + "garbage_collection_count" + ] + } +] \ No newline at end of file diff --git a/skills/performance-test-suite/assets/report_template.html b/skills/performance-test-suite/assets/report_template.html new file mode 100644 index 0000000..80d7c3d --- /dev/null +++ b/skills/performance-test-suite/assets/report_template.html @@ -0,0 +1,203 @@ + + + + + + Performance Test Report + + + + + +
+ + +

Performance Test Report

+

Test Run: {{test_run_id}}

+

Date: {{report_date}}

+ + +
+

Test Summary

+

Test Type: {{test_type}}

+

Target URL: {{target_url}}

+

Number of Users: {{number_of_users}}

+

Duration: {{duration}}

+

Status: {{test_status}}

+
+ + +

Key Metrics

+ + + + + + + + + + + + + + + + + + + + + + + + + +
MetricValue
Average Response Time{{average_response_time}} ms
Throughput{{throughput}} requests/second
Error Rate{{error_rate}} %
95th Percentile Response Time{{percentile_95_response_time}} ms
+ + +
+
+

Response Time Over Time

+ Response Time Chart +
+
+

Throughput Over Time

+ Throughput Chart +
+ +
+ + +
+

Bottleneck Identification

+

{{bottlenecks_summary}}

+
    + {{#bottlenecks}} +
  • {{.}}
    • + {{/bottlenecks}} +
+
+ + +
+

Recommendations

+

{{recommendations_summary}}

+
    + {{#recommendations}} +
  • {{.}}
    • + {{/recommendations}} +
+
+ +
+ + + \ No newline at end of file diff --git a/skills/performance-test-suite/assets/test_template.js b/skills/performance-test-suite/assets/test_template.js new file mode 100644 index 0000000..47aa6f3 --- /dev/null +++ b/skills/performance-test-suite/assets/test_template.js @@ -0,0 +1,65 @@ +// test_template.js - Template for K6 performance tests + +// Import necessary modules from K6 +import http from 'k6/http'; +import { check, sleep } from 'k6'; + +// Configuration options +export const options = { + // Stages define the load pattern + stages: [ + // Example: Ramp-up to 10 virtual users (VUs) over 10 seconds + { duration: '10s', target: 10 }, + + // Example: Maintain 10 VUs for 30 seconds + { duration: '30s', target: 10 }, + + // Example: Ramp-down to 0 VUs over 10 seconds + { duration: '10s', target: 0 }, + ], + + // Thresholds define pass/fail criteria + thresholds: { + // Example: 95th percentile response time should be below 200ms + http_req_duration: ['p95<200'], + + // Example: 99% of requests should be successful + http_req_failed: ['rate<0.01'], // <1% failure rate + }, +}; + +// Define the virtual user (VU) function +export default function () { + // Replace with your target URL + const url = 'YOUR_TARGET_URL_HERE'; + + // Replace with your request parameters (optional) + const params = { + headers: { + 'Content-Type': 'application/json', + }, + }; + + // Replace with your request body (optional) + const payload = JSON.stringify({ + key1: 'value1', + key2: 'value2', + }); + + // Make an HTTP request + const res = http.get(url, params); // or use http.post, http.put, http.delete, etc. + + // Check the response status code + check(res, { + 'status is 200': (r) => r.status === 200, + }); + + // Add more checks as needed + // Example: check(res, { 'response time < 500ms': (r) => r.timings.duration < 500 }); + + // Introduce a delay between requests (optional) + sleep(1); // Sleep for 1 second + + // Log response data for debugging (optional - REMOVE IN PRODUCTION!) + // console.log(res.body); +} \ No newline at end of file diff --git a/skills/performance-test-suite/references/README.md b/skills/performance-test-suite/references/README.md new file mode 100644 index 0000000..a588232 --- /dev/null +++ b/skills/performance-test-suite/references/README.md @@ -0,0 +1,7 @@ +# References + +Bundled resources for performance-test-suite skill + +- [ ] k6_api_reference.md: Documentation for the k6 API used in the performance tests. +- [ ] performance_metrics_guide.md: Guide explaining various performance metrics and their significance. +- [ ] test_design_best_practices.md: Best practices for designing effective performance tests. diff --git a/skills/performance-test-suite/scripts/README.md b/skills/performance-test-suite/scripts/README.md new file mode 100644 index 0000000..a803f45 --- /dev/null +++ b/skills/performance-test-suite/scripts/README.md @@ -0,0 +1,7 @@ +# Scripts + +Bundled resources for performance-test-suite skill + +- [ ] init_test.py: Script to initialize a performance test based on user input. +- [ ] run_test.sh: Script to execute the performance test using k6 or other tools. +- [ ] analyze_results.py: Script to analyze the test results and generate a report.