# K6TestSystem

**Repository Path**: smooth00/K6TestSystem

## Basic Information

- **Project Name**: K6TestSystem
- **Description**: 本项目通过AI辅助开发，主要是用来管理grafana k6性能测试，支持k6脚本上传编辑，测试计划创建编辑（支持压测策略定制和多机器负载分割），计划执行（支持代理远程机器执行），报告生成和查看，同时支持grafana报告集成查看；目前支持本地和远程代理端k6的测试和管理，后期会扩展第三方接口工具导入k6脚本，以及AI辅助编写k6测试脚本
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: https://smooth.blog.csdn.net
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 1
- **Created**: 2026-04-09
- **Last Updated**: 2026-06-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# K6 Test Management System

A comprehensive web system for managing Grafana k6 performance tests, including script management, test plan creation, remote execution, and result visualization through InfluxDB and Grafana.

## Features

- **User Authentication**: Secure login and registration with role-based access control
- **Script Management**: Upload, edit, and manage k6 test scripts
- **Test Plan Management**: Create and configure test plans with custom parameters, supporting multiple machine selection
- **Multi-machine Parallel Execution**: Execute test plans on multiple machines simultaneously
- **Agent Execution**: Execute tests on remote machines via WebSocket proxy
- **Report Auto-retrieval**: Automatically download HTML reports from remote agents after execution
- **Data Collection**: Collect performance data using InfluxDB with machine tag differentiation
- **Result Visualization**: Embed Grafana dashboards for visualizing test results
- **Responsive UI**: Modern, user-friendly interface built with React and Material UI
- **Internationalization**: Support for Chinese and English interface switching

## Prerequisites

- Node.js (v14+)
- SQLite
- k6
- InfluxDB
- Grafana

## Installation

### Backend Setup

1. **Clone the repository**
   ```bash
   git clone <repository-url>
   cd K6TestSystem
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Configure environment variables**
   Edit the `.env` file and configure:
   ```env
   # Server Configuration
   PORT=5000
   NODE_ENV=development

   # Database Configuration
   # System uses SQLite, no additional configuration needed

   # JWT Configuration
   JWT_SECRET=your_jwt_secret_key
   JWT_EXPIRE=7d

   # K6 Configuration
   K6_EXECUTABLE_PATH=/usr/local/bin/k6

   # InfluxDB Configuration
   INFLUXDB_URL=http://localhost:8086
   INFLUXDB_DATABASE=k6
   INFLUXDB_USERNAME=
   INFLUXDB_PASSWORD=

   # Grafana Configuration
   GRAFANA_URL=http://localhost:3000
   ```

4. **Start the backend server**
   ```bash
   npm run dev
   ```

### Frontend Setup

1. **Navigate to the client directory**
   ```bash
   cd client
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Start the frontend development server**
   ```bash
   npm start
   ```

### K6 Agent Setup

#### Local Agent (for testing)
1. **Navigate to the agent directory**
   ```bash
   cd agent
   ```

2. **Install dependencies**
   ```bash
   npm install
   ```

3. **Start the agent service**
   ```bash
   npm start
   ```
   
   Default port: 2080

#### Remote Agent Configuration

1. **Install Node.js on the target machine**

2. **Copy the agent directory to the remote machine**

3. **Install dependencies**
   ```bash
   npm install
   ```

4. **Configure environment variables (optional)**
   ```bash
   export PORT=2080           # Agent service port
   export AGENT_DIR=./agent_data  # Agent data directory
   ```

5. **Start the agent service**
   ```bash
   npm start
   ```

#### Agent Working Mechanism

1. **Script Synchronization**: When a test plan is created, the system automatically synchronizes scripts to the agent's `k6/scripts/` directory
2. **Execute Command**: Send execution commands to the agent via WebSocket
3. **Log Transmission**: Agent sends k6 execution logs back to the server in real-time
4. **Report Retrieval**: After execution completes, the server automatically downloads HTML reports from the agent

#### Report Path Explanation

- **Local Execution**: Reports are generated at `uploads/reports/{machineIp}_{scriptName}_{executionId}_summary.html`
- **Agent Execution**: Reports are first generated on the agent at `k6/reports/{machineIp}_{scriptName}_{executionId}_summary.html`, then automatically downloaded to the server's `uploads/reports/` directory

## Usage

### 1. User Registration & Login
- Access the application: `http://localhost:8080`
- Register a new account or login with existing credentials

### 2. Script Management
- Navigate to the "Test Scripts" page
- Upload new k6 scripts or edit existing ones
- View and manage your script library

### 3. Test Machine Configuration
- Navigate to the "Test Machines" page
- Add test machines, including:
  - **Machine Name**: For identification
  - **IP Address**: localhost or remote machine IP
  - **Proxy Port**: Required for remote machines (default 2080)
  - **k6 Path**: Path to the k6 executable
- Enable/disable machine status
- System automatically detects machine online status

### 4. Test Plan Creation
- Navigate to the "Test Plans" page
- Create new test plans by selecting scripts and configuring parameters (virtual users, duration, RPS)
- **Select Test Machines**: Select multiple machines for parallel testing
- Edit or delete existing plans
- Sync Scripts: Update plan-associated script content

### 5. Test Execution
- Navigate to the "Test Executions" page
- Select a test plan and click "Execute" to run the test
- Monitor execution status and logs in real-time
- Distinguish outputs from different machines during multi-machine parallel execution

### 6. Result Visualization
- Navigate to the "Test Results" page
- Select execution records to view detailed results
- **View HTML Reports**: Select reports generated by different machines
- Select available Grafana dashboards to visualize performance data
- Filter data by `machine` tag in Grafana

## API Endpoints

### Authentication
- `POST /api/auth/register` - Register a new user
- `POST /api/auth/login` - Login with existing credentials
- `GET /api/auth/me` - Get current user information

### Scripts
- `GET /api/scripts` - Get all scripts
- `POST /api/scripts/upload` - Upload a new script
- `GET /api/scripts/:id` - Get a specific script
- `PUT /api/scripts/:id` - Update a script
- `DELETE /api/scripts/:id` - Delete a script

### Plans
- `GET /api/plans` - Get all test plans
- `POST /api/plans` - Create a new test plan
- `GET /api/plans/:id` - Get a specific test plan
- `PUT /api/plans/:id` - Update a test plan
- `DELETE /api/plans/:id` - Delete a test plan

### Executions
- `POST /api/executions/run` - Run a test plan
- `GET /api/executions` - Get all execution records
- `GET /api/executions/:id` - Get a specific execution record
- `DELETE /api/executions/:id` - Delete an execution record
- `PUT /api/executions/:id/stop` - Stop a running execution

### Machines
- `GET /api/machines` - Get all test machines
- `POST /api/machines` - Add a new test machine
- `PUT /api/machines/:id` - Update a test machine
- `DELETE /api/machines/:id` - Delete a test machine
- `PUT /api/machines/:id/status` - Update machine status

### Settings
- `GET /api/settings` - Get system settings
- `PUT /api/settings` - Update system settings

## Project Structure

```
K6TestSystem/
├── agent/               # K6 Agent Service
│   ├── k6/              # Agent-side k6 files
│   │   ├── scripts/     # Synchronized test scripts
│   │   └── reports/     # Generated report files
│   ├── main.js          # Agent main program
│   └── package.json     # Agent dependency configuration
├── client/              # Frontend React Application
│   ├── public/          # Public static files
│   └── src/             # React source code
│       ├── components/  # Reusable components
│       ├── pages/       # Page components
│       ├── i18n/        # Internationalization files
│       └── utils/       # Utility functions
├── routes/              # Backend API routes
├── middleware/          # Express middleware
├── utils/               # Backend utility functions
├── data/                # SQLite database files
├── uploads/             # Uploaded scripts and reports
│   ├── scripts/         # Test scripts
│   └── reports/         # HTML report files
├── server.js            # Main backend server
└── package.json         # Project configuration
```

## Technologies Used

- **Backend**: Node.js, Express, SQLite, WebSocket (ws)
- **Frontend**: React, React Router, Material UI, Axios, react-i18next
- **Agent Service**: Node.js, WebSocket (ws)
- **Monitoring**: k6, InfluxDB, Grafana

## Contributing

Contributions are welcome! Please feel free to submit Pull Requests.

## License

This project is licensed under the MIT License.