# SmarTest

**Repository Path**: ksllh/SmarTest

## Basic Information

- **Project Name**: SmarTest
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-05-22
- **Last Updated**: 2025-08-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SmarTest 🚀

[![CI/CD Pipeline](https://github.com/smartest/smartest/workflows/CI/CD%20Pipeline/badge.svg)](https://github.com/smartest/smartest/actions)
[![codecov](https://codecov.io/gh/smartest/smartest/branch/main/graph/badge.svg)](https://codecov.io/gh/smartest/smartest)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://github.com/PyCQA/bandit)

A modern, scalable smart testing platform with WebRTC support for real-time device interaction and automated testing workflows.

## ✨ Features

- 🎥 **Real-time WebRTC Communication** - Live video streaming and device control
- 🔧 **Device Management** - Comprehensive device lifecycle management
- 🌐 **Web-based Interface** - Modern, responsive web UI
- 🔄 **Automated Testing** - Configurable test workflows and reporting
- 📊 **Monitoring & Analytics** - Built-in metrics and observability
- 🐳 **Container Ready** - Full Docker and Kubernetes support
- 🔒 **Security First** - Comprehensive security features and best practices
- ⚡ **High Performance** - Optimized for scalability and performance

SmarTest是一个分布式智能测试平台，支持设备管理、测试用例执行和结果分析。

## 系统架构

### 核心组件

1. **Proxy Server (代理服务器)**
   - Web界面和API网关
   - 用户认证和权限管理
   - 项目和测试用例管理
   - 设备服务器管理

2. **Device Server (设备服务器)**
   - 分布式设备管理
   - UiTest服务 (TCP+ZMQ+JSON)
   - 资源服务 (HTTP+Flask)
   - Consul服务注册

3. **Service Discovery (服务发现)**
   - 使用Consul进行服务注册和发现
   - 健康检查和负载均衡
   - 配置管理

### 通信协议

- **API通信**: TCP + ZMQ + JSON
- **资源访问**: HTTP + Flask
- **服务发现**: Consul HTTP API

## 快速开始

### 环境要求

- Python 3.8+
- Consul 1.15+
- Docker (可选)

## 🚀 Quick Start

### Prerequisites

- Python 3.8+ 🐍
- Node.js 14+ 📦
- Docker & Docker Compose 🐳 (optional)
- PostgreSQL 13+ 🗄️ (for production)

### Installation

#### Option 1: Development Setup

```bash
# Clone the repository
git clone https://github.com/smartest/smartest.git
cd smartest

# Setup development environment
make setup-dev

# Copy environment configuration
cp .env.example .env
# Edit .env with your settings

# Install dependencies
make install-dev

# Run development servers
make run-dev
```

#### Option 2: Docker Setup

```bash
# Clone the repository
git clone https://github.com/smartest/smartest.git
cd smartest

# Copy environment configuration
cp .env.example .env
# Edit .env with your settings

# Start with Docker Compose
docker-compose up -d

# For production
docker-compose -f docker-compose.prod.yml up -d
```

#### Option 3: Traditional pip install

```bash
# Clone the repository
git clone https://github.com/smartest/smartest.git
cd smartest

# Install with pip
pip install -e ".[dev]"

# Copy configuration
cp .env.example .env
cp common/example_config.json common/config.json
```

## 🛠️ Development

### Available Commands

```bash
# Development
make run-dev          # Run development servers
make test             # Run tests
make lint             # Run linters
make format           # Format code
make type-check       # Run type checking

# Quality Assurance
make security-check   # Run security checks
make pre-commit       # Run pre-commit hooks

# Docker
make docker-build     # Build Docker images
make docker-run       # Run with Docker

# Documentation
make docs             # Build documentation
make serve-docs       # Serve docs locally

# Database
make db-init          # Initialize database
make db-migrate       # Run migrations

# Utilities
make clean            # Clean build artifacts
make env-check        # Check environment
make health-check     # Check service health
```

### Services

| Service | URL | Description |
|---------|-----|-------------|
| Proxy Server | http://localhost:8000 | Main web interface |
| Device Server | http://localhost:8001 | Device management API |
| WebRTC Demo | http://localhost:8000/webrtc_demo.html | WebRTC testing |
| Prometheus | http://localhost:9090 | Metrics dashboard |
| Grafana | http://localhost:3000 | Monitoring dashboard |

### Project Structure

```
smartest/
├── 📁 device_server/          # Device management service
├── 📁 proxy_server/           # Main web application
├── 📁 common/                 # Shared utilities
├── 📁 docs/                   # Documentation
├── 📁 scripts/                # Utility scripts
├── 📁 monitoring/             # Monitoring configs
├── 📁 database/               # Database configs
├── 📄 pyproject.toml          # Python project config
├── 📄 package.json            # Node.js dependencies
├── � Makefile                # Development commands
├── � docker-compose.yml      # Development containers
└── 📄 docker-compose.prod.yml # Production containers
```

### 启动服务

#### 方式1: 手动启动

1. **启动Consul**
```bash
consul agent -dev -bind=172.16.1.84 -client=172.16.1.84
```

2. **启动代理服务器**
```bash
python proxy_server/main.py
```

3. **启动设备服务器**
sudo setcap cap_net_admin+ep $(readlink -f $(which python))
```bash
# 启动单个设备服务器
python device_server/start_device_server.py

# 启动多个设备服务器
./device_server/start_multiple_devices.sh 3
```

#### 方式2: Docker Compose

```bash
# 启动所有服务
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down
```

### 验证部署

1. **检查Consul服务**
```bash
curl http://localhost:8500/v1/agent/services
```

2. **访问Web界面**
```bash
open http://localhost:5000
```

3. **测试设备API**
```bash
# 列出设备
curl -X POST http://localhost:5000/api/devices \
  -H "Content-Type: application/json" \
  -d '{"api": "load_devices"}'

# 获取设备截图
curl http://localhost:5000/devices/device-001/screenshot
```

## 项目结构

```
SmarTest/
├── common/                 # 公共模块
│   ├── config.py          # 配置管理
│   ├── utils.py           # 工具函数
│   └── activity_types.py  # 活动类型定义
├── proxy_server/          # 代理服务器
│   ├── main.py           # 主入口
│   ├── proxy_service.py  # 核心服务
│   ├── models/           # 数据模型
│   │   ├── device_mgr.py # 设备管理器
│   │   ├── user_mgr.py   # 用户管理器
│   │   └── ...
│   ├── templates/        # Web模板
│   └── static/          # 静态资源
├── device_server/         # 设备服务器
│   ├── device_server.py  # 设备服务器实现
│   ├── start_device_server.py # 启动脚本
│   ├── config.py         # 配置文件
│   ├── test_device_server.py # 测试脚本
│   ├── start_multiple_devices.sh # 批量启动脚本
│   ├── stop_devices.sh   # 停止脚本
│   └── README.md         # 设备服务器文档
├── requirements.txt       # Python依赖
├── docker-compose.yml    # Docker编排
├── Dockerfile.http      # 代理服务器镜像
├── Dockerfile.device     # 设备服务器镜像
└── README.md            # 项目文档
```

## 设备服务器

### 功能特性

- **分布式架构**: 支持多个设备服务器实例
- **服务注册**: 自动向Consul注册服务
- **双协议支持**: UiTest服务(ZMQ) + 资源服务(HTTP)
- **健康监控**: 自动健康检查和故障恢复
- **资源管理**: 截图、视频、日志等资源访问

### API接口

#### ZMQ API
- `health_check` - 健康检查
- `get_device_info` - 获取设备信息
- `execute_command` - 执行设备命令
- `get_device_status` - 获取设备状态

#### HTTP资源
- `GET /health` - 健康检查
- `GET /screenshot` - 获取截图
- `GET /video/<filename>` - 获取视频
- `GET /logs?lines=<n>` - 获取日志

### 配置选项

| 环境变量 | 默认值 | 说明 |
|---------|--------|------|
| CONSUL_HOST | localhost | Consul服务器地址 |
| CONSUL_PORT | 8500 | Consul服务器端口 |
| DEVICE_API_PORT | 5555 | UiTest服务端口 |
| DEVICE_RESOURCE_PORT | 8080 | 资源服务端口 |
| DEVICE_SERVICE_ID | 自动生成 | 服务ID |
| LOG_LEVEL | INFO | 日志级别 |

## 代理服务器

### 设备管理API

- `load_devices` - 列出所有设备
- `get_device_info` - 获取设备信息
- `call_device_api` - 调用设备API
- `health_check_device` - 检查设备健康状态
- `health_check_all_devices` - 检查所有设备健康状态

### Web路由

- `/api/devices` - 设备API调用
- `/api/devices/<service_id>/resources/<path>` - 设备资源访问
- `/devices/<service_id>/screenshot` - 设备截图

## 开发指南

### 添加新的设备API

在`DeviceServer`类中添加以`api_`开头的方法：

```python
def api_custom_command(self, param1: str, param2: int) -> Dict[str, Any]:
    """自定义API方法"""
    try:
        result = self.execute_custom_logic(param1, param2)
        return {
            'success': True,
            'data': result,
            'timestamp': int(time.time())
        }
    except Exception as e:
        return {
            'success': False,
            'error': str(e),
            'timestamp': int(time.time())
        }
```

### 添加新的资源端点

在`DeviceResourceService`类中添加Flask路由：

```python
@self.app.route('/custom-resource', methods=['GET'])
def get_custom_resource():
    try:
        data = self.device_server.get_custom_resource()
        return data, 200, {'Content-Type': 'application/json'}
    except Exception as e:
        return jsonify({'error': str(e)}), 500
```

### 测试

```bash
# 测试设备服务器
python device_server/test_device_server.py

# 测试代理服务器
python -m pytest tests/
```

## 部署

### 生产环境

1. **使用Docker Compose**
```bash
docker-compose -f docker-compose.prod.yml up -d
```

2. **使用Kubernetes**
```bash
kubectl apply -f k8s/
```

3. **手动部署**
- 配置反向代理(Nginx)
- 设置进程管理(systemd)
- 配置日志轮转
- 设置监控告警

### 监控

- **Consul UI**: http://localhost:8500
- **应用日志**: `logs/` 目录
- **健康检查**: 各服务的 `/health` 端点

## 故障排除

### 常见问题

1. **服务注册失败**
   - 检查Consul是否运行
   - 检查网络连接
   - 检查端口占用

2. **ZMQ连接失败**
   - 检查防火墙设置
   - 检查端口可访问性
   - 检查ZMQ版本兼容性

3. **设备服务器无响应**
   - 检查进程状态
   - 查看错误日志
   - 重启服务

### 日志查看

```bash
# 查看所有日志
tail -f logs/*.log

# 查看特定服务日志
tail -f logs/device_servers/device-001.log

# 查看Docker日志
docker-compose logs -f device-server-1
```

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Workflow

1. **Fork** the repository
2. **Create** a feature branch: `git checkout -b feature/amazing-feature`
3. **Install** pre-commit hooks: `make setup-dev`
4. **Make** your changes and ensure tests pass: `make test`
5. **Run** quality checks: `make lint && make type-check && make security-check`
6. **Commit** your changes: `git commit -m 'Add amazing feature'`
7. **Push** to the branch: `git push origin feature/amazing-feature`
8. **Open** a Pull Request

### Code Standards

- ✅ Follow [PEP 8](https://pep8.org/) style guide
- ✅ Write comprehensive tests
- ✅ Add type hints
- ✅ Update documentation
- ✅ Pass all CI checks

## 📊 Monitoring & Observability

### Metrics

- **Application Metrics**: Custom business metrics via Prometheus
- **System Metrics**: CPU, memory, disk, network via Node Exporter
- **Container Metrics**: Docker container stats via cAdvisor
- **Database Metrics**: PostgreSQL performance metrics

### Logging

- **Structured Logging**: JSON format with correlation IDs
- **Log Aggregation**: Centralized via Loki
- **Log Levels**: DEBUG, INFO, WARNING, ERROR, CRITICAL

### Health Checks

```bash
# Check service health
curl http://localhost:8000/health
curl http://localhost:8001/health

# Or use make command
make health-check
```

## 🔒 Security

### Security Features

- 🔐 **Authentication**: JWT-based authentication
- 🛡️ **Authorization**: Role-based access control (RBAC)
- 🔒 **Encryption**: TLS/SSL for all communications
- 🚫 **Input Validation**: Comprehensive input sanitization
- 🔍 **Security Scanning**: Automated vulnerability scanning

### Security Checks

```bash
# Run security audit
python scripts/security_check.py

# Or use make command
make security-check
```

### Reporting Security Issues

Please report security vulnerabilities to [security@smartest.com](mailto:security@smartest.com)

## 📚 Documentation

- 📖 **API Documentation**: Available at `/docs` endpoint
- 🏗️ **Architecture Guide**: See [docs/architecture.md](docs/architecture.md)
- 🔧 **Configuration Guide**: See [docs/configuration.md](docs/configuration.md)
- 🚀 **Deployment Guide**: See [docs/deployment.md](docs/deployment.md)

## 🆘 Support

- 📧 **Email**: support@smartest.com
- 💬 **Discord**: [SmarTest Community](https://discord.gg/smartest)
- 🐛 **Issues**: [GitHub Issues](https://github.com/smartest/smartest/issues)
- 📚 **Documentation**: [docs.smartest.com](https://docs.smartest.com)

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Thanks to all [contributors](https://github.com/smartest/smartest/contributors)
- Built with ❤️ using Flask, WebRTC, and modern DevOps practices
- Special thanks to the open-source community

---

<div align="center">
  <strong>Made with ❤️ by the SmarTest Team</strong>
</div>

## 联系方式

- 项目主页: https://github.com/your-org/smartest
- 问题反馈: https://github.com/your-org/smartest/issues
- 文档: https://smartest.readthedocs.io