mirror of
https://github.com/rustfs/console.git
synced 2026-09-01 15:17:45 +08:00
docs: translate tests README and rewrite main README
- Translate all Chinese content in tests/README.md to English - Rewrite main README.md with accurate project information - Update tech stack versions (Nuxt 4, Node.js 22+, pnpm) - Add detailed project structure documentation - Improve deployment and contribution guidelines - Add comprehensive testing documentation references
This commit is contained in:
overtrue
@@ -3,107 +3,105 @@
|
||||
[](LICENSE)
|
||||
[](https://www.typescriptlang.org/)
|
||||
[](https://vuejs.org/)
|
||||
[](https://nuxt.com/)
|
||||
[](https://nuxt.com/)
|
||||
|
||||
A modern, responsive web management console for RustFS distributed file system, built with Vue 3, Nuxt 3, and TypeScript.
|
||||
A modern, responsive web management console for [RustFS](https://github.com/rustfs/rustfs) distributed file system, built with Vue 3, Nuxt 4, TypeScript, and Tailwind CSS.
|
||||
|
||||
## ✨ Features
|
||||
|
||||
- 🚀 **Modern Stack**: Built with Vue 3, Nuxt 3, TypeScript, and Tailwind CSS
|
||||
- 🎨 **Beautiful UI**: Clean and intuitive interface with dark mode support
|
||||
- 🌍 **Internationalization**: Full i18n support with English and Chinese
|
||||
- 🚀 **Modern Stack**: Vue 3 Composition API, Nuxt 4, TypeScript, Tailwind CSS v4
|
||||
- 🎨 **Beautiful UI**: Clean interface with shadcn-vue components and dark mode support
|
||||
- 🌍 **Internationalization**: Full i18n support (English, Chinese, Turkish)
|
||||
- 📱 **Responsive Design**: Mobile-friendly design that works on all devices
|
||||
- ⚡ **High Performance**: Optimized with caching, lazy loading, and code splitting
|
||||
- 🔒 **Enterprise Security**: Secure authentication and authorization
|
||||
- 📊 **Rich Analytics**: Comprehensive monitoring and metrics dashboard
|
||||
- 🛠 **Developer Experience**: Hot reload, TypeScript, ESLint, and Prettier
|
||||
- ⚡ **High Performance**: Optimized with code splitting, lazy loading, and efficient caching
|
||||
- 🔒 **Enterprise Security**: Secure authentication with AWS-compatible S3 API
|
||||
- 📊 **Rich Analytics**: Comprehensive monitoring dashboard with real-time metrics
|
||||
- 🛠 **Developer Experience**: Hot reload, TypeScript, ESLint, Prettier, and Vitest
|
||||
|
||||
## 🎯 Core Functionalities
|
||||
|
||||
### Storage Management
|
||||
|
||||
- **Bucket Operations**: Create, delete, configure buckets
|
||||
- **Bucket Operations**: Create, delete, configure buckets with policies
|
||||
- **Object Management**: Upload, download, delete objects with batch operations
|
||||
- **File Browser**: Intuitive file explorer with search and filtering
|
||||
- **Access Control**: Granular permissions and bucket policies
|
||||
- **File Browser**: Intuitive file explorer with search, filtering, and navigation
|
||||
- **Access Control**: Granular permissions and bucket policies (IAM-like)
|
||||
- **Object Versions**: Manage object versions and delete markers
|
||||
- **Object Locking**: WORM (Write Once Read Many) compliance and legal hold
|
||||
|
||||
### User & Access Management
|
||||
|
||||
- **User Management**: Create and manage users and groups
|
||||
- **User Management**: Create and manage users and user groups
|
||||
- **Access Keys**: Generate and manage API credentials
|
||||
- **Policies**: Fine-grained access control policies
|
||||
- **Authentication**: Multiple authentication methods (AccessKey, STS)
|
||||
- **Service Accounts**: Create and manage service account credentials
|
||||
- **Policies**: Fine-grained access control policies (canned and custom)
|
||||
- **Authentication**: Multiple authentication methods (AccessKey, STS temporary credentials)
|
||||
|
||||
### System Monitoring
|
||||
|
||||
- **Performance Metrics**: Real-time system performance monitoring
|
||||
- **Usage Analytics**: Storage usage and bandwidth statistics
|
||||
- **Usage Analytics**: Storage usage, bandwidth, and capacity statistics
|
||||
- **Health Monitoring**: System health and status indicators
|
||||
- **Audit Logs**: Comprehensive audit trail and logging
|
||||
- **License Management**: View license information and usage limits
|
||||
|
||||
### Advanced Features
|
||||
|
||||
- **Lifecycle Management**: Automated data lifecycle policies
|
||||
- **Replication**: Cross-region and site replication
|
||||
- **Tiering**: Intelligent data tiering and archival
|
||||
- **Encryption**: Data encryption at rest and in transit
|
||||
- **Event Notifications**: Real-time event notifications
|
||||
- **Lifecycle Management**: Automated data lifecycle policies (ILM)
|
||||
- **Replication**: Cross-region and site replication configuration
|
||||
- **Tiering**: Intelligent data tiering and archival strategies
|
||||
- **Event Notifications**: Real-time event notifications (SQS, SNS, Lambda)
|
||||
- **Event Targets**: Configure and manage event notification targets
|
||||
- **Site Replication**: Multi-site replication management
|
||||
|
||||
## 🛠 Technical Stack
|
||||
|
||||
- **Frontend Framework**: [Vue 3](https://vuejs.org/) with Composition API
|
||||
- **Meta Framework**: [Nuxt 3](https://nuxt.com/) for SSR/SPA
|
||||
- **Language**: [TypeScript](https://www.typescriptlang.org/) for type safety
|
||||
- **Styling**: [Tailwind CSS](https://tailwindcss.com/) + [shadcn-vue](https://www.shadcn-vue.com/)
|
||||
- **Frontend Framework**: [Vue 3](https://vuejs.org/) with Composition API and `<script setup>`
|
||||
- **Meta Framework**: [Nuxt 4](https://nuxt.com/) (SPA mode)
|
||||
- **Language**: [TypeScript](https://www.typescriptlang.org/) 5.8+ with strict mode
|
||||
- **Styling**: [Tailwind CSS](https://tailwindcss.com/) v4 + [shadcn-vue](https://www.shadcn-vue.com/)
|
||||
- **State Management**: [Pinia](https://pinia.vuejs.org/) for reactive state
|
||||
- **HTTP Client**: Custom AWS-compatible client with automatic signing
|
||||
- **Build Tool**: [Vite](https://vitejs.dev/) for fast development and building
|
||||
- **Package Manager**: npm/pnpm/yarn
|
||||
- **HTTP Client**: Custom AWS-compatible client with automatic request signing
|
||||
- **Build Tool**: [Vite](https://vitejs.dev/) (via Nuxt)
|
||||
- **Package Manager**: [pnpm](https://pnpm.io/) 10.19+
|
||||
- **Testing**: [Vitest](https://vitest.dev/) for unit and integration tests
|
||||
- **Table Component**: [TanStack Table](https://tanstack.com/table) (Vue)
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js 18+
|
||||
- npm/pnpm/yarn package manager
|
||||
- RustFS backend server running
|
||||
- **Node.js**: >= 22.0.0
|
||||
- **pnpm**: >= 10.19.0
|
||||
- **RustFS Backend**: RustFS server must be running and accessible
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
# Clone the repository
|
||||
git clone https://github.com/your-org/rustfs-console.git
|
||||
cd rustfs-console
|
||||
git clone https://github.com/rustfs/console.git
|
||||
cd console
|
||||
|
||||
# Install dependencies
|
||||
npm install
|
||||
# or
|
||||
# Install dependencies using pnpm
|
||||
pnpm install
|
||||
# or
|
||||
yarn install
|
||||
```
|
||||
|
||||
### Development
|
||||
|
||||
```bash
|
||||
# Start development server
|
||||
npm run dev
|
||||
# or
|
||||
pnpm dev
|
||||
# or
|
||||
yarn dev
|
||||
```
|
||||
|
||||
The development server will start at `http://localhost:3000`.
|
||||
The development server will start at `http://localhost:3000` (or the next available port).
|
||||
|
||||
### Environment Configuration
|
||||
|
||||
Create a `.env` file in the root directory:
|
||||
Create a `.env` file in the root directory (optional, defaults are provided):
|
||||
|
||||
```env
|
||||
# Application Configuration
|
||||
APP_NAME=RustFS
|
||||
APP_DESCRIPTION=RustFS Console
|
||||
APP_DESCRIPTION=RustFS is a distributed file system written in Rust.
|
||||
BASE_URL=/rustfs/console/
|
||||
|
||||
# API Configuration
|
||||
@@ -118,73 +116,131 @@ S3_ENDPOINT=http://localhost:9000
|
||||
SESSION_DURATION_SECONDS=43200
|
||||
```
|
||||
|
||||
The application automatically detects configuration from:
|
||||
1. Server config at `{SERVER_HOST}/config.json`
|
||||
2. localStorage saved configuration
|
||||
3. Current browser host
|
||||
4. Default configuration (localhost:9000)
|
||||
|
||||
### Production Build
|
||||
|
||||
```bash
|
||||
# Build for production
|
||||
npm run build
|
||||
# or
|
||||
pnpm build
|
||||
# or
|
||||
yarn build
|
||||
|
||||
# Preview production build locally
|
||||
npm run preview
|
||||
pnpm preview
|
||||
```
|
||||
|
||||
The built application will be in the `.output` directory.
|
||||
|
||||
## 🔧 Development
|
||||
|
||||
### Project Structure
|
||||
|
||||
```
|
||||
├── assets/ # Static assets (images, styles)
|
||||
├── assets/ # Static assets (images, styles, backgrounds)
|
||||
│ ├── css/ # Global styles and Tailwind CSS
|
||||
│ ├── img/ # Images and logos
|
||||
│ └── svg/ # SVG icons for providers
|
||||
├── components/ # Vue components
|
||||
│ ├── access-keys/ # Access key management
|
||||
│ ├── buckets/ # Bucket operations
|
||||
│ ├── object/ # Object management
|
||||
│ ├── users/ # User management
|
||||
│ └── ui/ # Reusable UI components
|
||||
├── composables/ # Vue composables
|
||||
├── layouts/ # Nuxt layouts
|
||||
├── middleware/ # Route middleware
|
||||
├── pages/ # File-based routing
|
||||
├── plugins/ # Nuxt plugins
|
||||
├── server/ # Server-side code
|
||||
├── store/ # Pinia stores
|
||||
├── types/ # TypeScript definitions
|
||||
├── utils/ # Utility functions
|
||||
└── nuxt.config.ts # Nuxt configuration
|
||||
│ ├── access-keys/ # Access key management components
|
||||
│ ├── buckets/ # Bucket operation components
|
||||
│ ├── data-table/ # Reusable data table components
|
||||
│ ├── object/ # Object management components
|
||||
│ ├── user/ # User management components
|
||||
│ ├── user-group/ # User group components
|
||||
│ └── ui/ # shadcn-vue UI primitives
|
||||
├── composables/ # Vue composables (reusable logic)
|
||||
├── config/ # Configuration files (navigation, etc.)
|
||||
├── i18n/ # Internationalization
|
||||
│ └── locales/ # Translation files (en, zh-CN, tr-TR)
|
||||
├── layouts/ # Nuxt layouts
|
||||
├── lib/ # Library code (API clients, utilities)
|
||||
│ ├── api-client.ts # API client with AWS signing
|
||||
│ ├── upload-task-manager.ts # File upload manager
|
||||
│ └── delete-task-manager.ts # File deletion manager
|
||||
├── middleware/ # Route middleware (auth, analytics)
|
||||
├── pages/ # File-based routing (Nuxt pages)
|
||||
├── plugins/ # Nuxt plugins (config, API, S3, icons)
|
||||
├── server/ # Server-side API routes
|
||||
├── store/ # Pinia stores
|
||||
│ ├── upload-tasks.ts # Upload task management store
|
||||
│ └── delete-tasks.ts # Delete task management store
|
||||
├── tests/ # Test files
|
||||
│ ├── utils/ # Utility function tests
|
||||
│ └── README.md # Test documentation
|
||||
├── types/ # TypeScript type definitions
|
||||
├── utils/ # Utility functions
|
||||
│ ├── config-helpers.ts # Configuration management
|
||||
│ ├── functions.ts # General utilities
|
||||
│ └── bucket-policy.ts # Bucket policy utilities
|
||||
├── app.config.ts # Application configuration
|
||||
├── nuxt.config.ts # Nuxt configuration
|
||||
└── package.json # Dependencies and scripts
|
||||
```
|
||||
|
||||
### Code Quality
|
||||
|
||||
- Component files use **kebab-case** (e.g., `search-input.vue`, `action-bar.vue`).
|
||||
|
||||
We maintain high code quality standards with:
|
||||
|
||||
- **TypeScript**: Full type safety and better developer experience
|
||||
- **TypeScript**: Full type safety with strict mode enabled
|
||||
- **ESLint**: Code linting and style enforcement
|
||||
- **Prettier**: Automatic code formatting
|
||||
- **Vue TSC**: Vue-specific TypeScript checking
|
||||
|
||||
```bash
|
||||
# Run type checking
|
||||
npm run type-check
|
||||
pnpm type-check
|
||||
|
||||
# Run linting
|
||||
npm run lint
|
||||
pnpm lint
|
||||
|
||||
# Fix linting issues
|
||||
npm run lint:fix
|
||||
# Fix linting issues automatically
|
||||
pnpm lint:fix
|
||||
```
|
||||
|
||||
### Coding Standards
|
||||
|
||||
- **Component Files**: Use **kebab-case** (e.g., `bucket-selector.vue`, `data-table.vue`)
|
||||
- **Component Usage**: Reference components using **StudlyCase** in templates (e.g., `<BucketSelector />`)
|
||||
- **Composables**: Use camelCase with `use` prefix (e.g., `useBucket.ts`, `useUsers.ts`)
|
||||
- **TypeScript**: All code must be typed, avoid `any` without justification
|
||||
- **Comments**: All comments and documentation in English
|
||||
|
||||
### Key Architecture Patterns
|
||||
|
||||
- **Composables**: Reusable logic with Vue Composition API
|
||||
- **Plugin System**: Modular configuration and service injection
|
||||
- **Error Boundaries**: Comprehensive error handling and user feedback
|
||||
- **Error Handling**: Comprehensive error handling with user-friendly messages
|
||||
- **Performance Optimization**: Smart caching, lazy loading, and code splitting
|
||||
- **Security**: Input validation, XSS protection, and secure authentication
|
||||
- **Security**: Input validation, XSS protection, and secure AWS-compatible authentication
|
||||
|
||||
### Testing
|
||||
|
||||
```bash
|
||||
# Run all tests
|
||||
pnpm test
|
||||
|
||||
# Run tests in watch mode
|
||||
pnpm test:watch
|
||||
|
||||
# Run tests with UI
|
||||
pnpm test:ui
|
||||
|
||||
# Run tests once (CI mode)
|
||||
pnpm test:run
|
||||
|
||||
# Generate coverage report
|
||||
pnpm test:coverage
|
||||
|
||||
# Run specific test suites
|
||||
pnpm test:config-helpers
|
||||
pnpm test:performance
|
||||
pnpm test:integration
|
||||
```
|
||||
|
||||
See [tests/README.md](tests/README.md) for detailed testing documentation.
|
||||
|
||||
## 🎨 Customization
|
||||
|
||||
@@ -192,7 +248,7 @@ npm run lint:fix
|
||||
|
||||
The application supports light and dark themes. Customize themes in:
|
||||
|
||||
- `assets/css/tailwind.css` - Tailwind configuration
|
||||
- `assets/css/tailwind.css` - Tailwind CSS configuration
|
||||
- `tailwind.config.ts` - Theme colors and design tokens
|
||||
- `components/theme-switcher.vue` - Theme switching logic
|
||||
|
||||
@@ -200,45 +256,57 @@ The application supports light and dark themes. Customize themes in:
|
||||
|
||||
Add new languages by:
|
||||
|
||||
1. Creating locale files in `i18n/locales/`
|
||||
2. Updating `nuxt.config.ts` locales configuration
|
||||
3. Adding language switcher options
|
||||
1. Creating locale files in `i18n/locales/` (e.g., `fr-FR.json`)
|
||||
2. Updating `nuxt.config.ts` i18n configuration
|
||||
3. Adding language switcher options in `components/language-switcher.vue`
|
||||
|
||||
Currently supported languages:
|
||||
- English (`en`)
|
||||
- Chinese (`zh-CN`)
|
||||
- Turkish (`tr-TR`)
|
||||
|
||||
### Component Library
|
||||
|
||||
Built on shadcn-vue primitives with custom wrappers in `components/ui/` and the root `components/` directory (e.g. `modal.vue`, `drawer.vue`, `selector.vue`). Extend the design system by:
|
||||
|
||||
- Adding new components to `components/ui/`
|
||||
- Following established naming conventions
|
||||
- Including proper TypeScript definitions
|
||||
Built on [shadcn-vue](https://www.shadcn-vue.com/) primitives with custom wrappers. The UI components are in `components/ui/` and should not be modified directly. Instead, create wrapper components in the root `components/` directory.
|
||||
|
||||
## 🚀 Deployment
|
||||
|
||||
### Docker Deployment
|
||||
|
||||
```dockerfile
|
||||
FROM node:18-alpine AS builder
|
||||
WORKDIR /app
|
||||
COPY package*.json ./
|
||||
RUN npm ci
|
||||
COPY . .
|
||||
RUN npm run build
|
||||
|
||||
FROM node:18-alpine AS runtime
|
||||
WORKDIR /app
|
||||
COPY --from=builder /app/.output ./.output
|
||||
EXPOSE 3000
|
||||
CMD ["node", ".output/server/index.mjs"]
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Production deployment requires these environment variables:
|
||||
|
||||
- `API_BASE_URL`: RustFS backend API endpoint
|
||||
- `SERVER_HOST`: RustFS server host
|
||||
- `BASE_URL`: Application base path
|
||||
- `API_BASE_URL`: RustFS backend API endpoint (e.g., `https://api.example.com/rustfs/admin/v3`)
|
||||
- `SERVER_HOST`: RustFS server host (e.g., `https://api.example.com`)
|
||||
- `BASE_URL`: Application base path (e.g., `/rustfs/console/`)
|
||||
- `NODE_ENV`: Set to `production`
|
||||
- `SESSION_DURATION_SECONDS`: Session duration in seconds (default: 43200)
|
||||
|
||||
### Build for Production
|
||||
|
||||
```bash
|
||||
# Build for production
|
||||
pnpm build
|
||||
```
|
||||
|
||||
The production build will be in `.output/public` (static files) and `.output/server` (server-side code if SSR is enabled).
|
||||
|
||||
### Docker Deployment
|
||||
|
||||
```dockerfile
|
||||
FROM node:22-alpine AS builder
|
||||
WORKDIR /app
|
||||
COPY package.json pnpm-lock.yaml ./
|
||||
RUN corepack enable && corepack prepare pnpm@10.19.0 --activate
|
||||
RUN pnpm install --frozen-lockfile
|
||||
COPY . .
|
||||
RUN pnpm build
|
||||
|
||||
FROM nginx:alpine
|
||||
COPY --from=builder /app/.output/public /usr/share/nginx/html
|
||||
COPY nginx.conf /etc/nginx/conf.d/default.conf
|
||||
EXPOSE 80
|
||||
CMD ["nginx", "-g", "daemon off;"]
|
||||
```
|
||||
|
||||
### Build Optimization
|
||||
|
||||
@@ -247,7 +315,7 @@ For optimal production builds:
|
||||
- Enable gzip/brotli compression
|
||||
- Configure proper caching headers
|
||||
- Use CDN for static assets
|
||||
- Monitor bundle size and performance
|
||||
- Monitor bundle size and performance metrics
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
@@ -258,19 +326,19 @@ We welcome contributions! Please follow our contribution guidelines:
|
||||
1. **Fork** the repository
|
||||
2. **Clone** your fork locally
|
||||
3. **Create** a feature branch: `git checkout -b feature/amazing-feature`
|
||||
4. **Install** dependencies: `npm install`
|
||||
4. **Install** dependencies: `pnpm install`
|
||||
5. **Make** your changes following our coding standards
|
||||
6. **Test** your changes: `npm run type-check && npm run lint`
|
||||
6. **Test** your changes: `pnpm type-check && pnpm lint && pnpm test:run`
|
||||
7. **Commit** your changes: `git commit -m 'feat: add amazing feature'`
|
||||
8. **Push** to your branch: `git push origin feature/amazing-feature`
|
||||
9. **Submit** a Pull Request
|
||||
|
||||
### Coding Standards
|
||||
|
||||
- **TypeScript**: Use TypeScript for all new code
|
||||
- **TypeScript**: Use TypeScript for all new code with strict mode
|
||||
- **Vue 3**: Use Composition API and `<script setup>` syntax
|
||||
- **Naming**: Use kebab-case for files and components
|
||||
- **Comments**: Add JSDoc comments for public APIs
|
||||
- **Comments**: All comments and documentation in English
|
||||
- **Testing**: Include tests for new features
|
||||
- **Performance**: Consider performance implications
|
||||
|
||||
@@ -280,10 +348,10 @@ We use automated code formatting:
|
||||
|
||||
```bash
|
||||
# Format code
|
||||
npm run lint:fix
|
||||
pnpm lint:fix
|
||||
|
||||
# Check formatting
|
||||
npm run lint
|
||||
pnpm lint
|
||||
```
|
||||
|
||||
### Commit Convention
|
||||
@@ -293,18 +361,20 @@ Follow [Conventional Commits](https://www.conventionalcommits.org/):
|
||||
- `feat`: New features
|
||||
- `fix`: Bug fixes
|
||||
- `docs`: Documentation changes
|
||||
- `style`: Code style changes
|
||||
- `style`: Code style changes (formatting, etc.)
|
||||
- `refactor`: Code refactoring
|
||||
- `test`: Test additions/modifications
|
||||
- `chore`: Build process or auxiliary tool changes
|
||||
- `perf`: Performance improvements
|
||||
|
||||
### Pull Request Guidelines
|
||||
|
||||
- **Title**: Use clear, descriptive titles
|
||||
- **Title**: Use clear, descriptive titles following conventional commits
|
||||
- **Description**: Explain what changes were made and why
|
||||
- **Testing**: Describe how the changes were tested
|
||||
- **Breaking Changes**: Clearly mark any breaking changes
|
||||
- **Screenshots**: Include screenshots for UI changes
|
||||
- **Checklist**: Complete the PR checklist
|
||||
|
||||
### Issue Reporting
|
||||
|
||||
@@ -316,25 +386,6 @@ When reporting issues:
|
||||
4. **Include** system information and error logs
|
||||
5. **Add** relevant labels
|
||||
|
||||
### Development Setup
|
||||
|
||||
```bash
|
||||
# Clone and setup
|
||||
git clone https://github.com/your-username/rustfs-console.git
|
||||
cd rustfs-console
|
||||
npm install
|
||||
|
||||
# Create feature branch
|
||||
git checkout -b feature/your-feature
|
||||
|
||||
# Start development
|
||||
npm run dev
|
||||
|
||||
# Run checks before committing
|
||||
npm run type-check
|
||||
npm run lint
|
||||
```
|
||||
|
||||
## 📄 License
|
||||
|
||||
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
|
||||
@@ -343,16 +394,17 @@ This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENS
|
||||
|
||||
- [Vue.js](https://vuejs.org/) - The progressive JavaScript framework
|
||||
- [Nuxt](https://nuxt.com/) - The intuitive Vue framework
|
||||
- [shadcn-vue](https://www.shadcn-vue.com/) - Headless, accessible Vue UI components built on Radix
|
||||
- [shadcn-vue](https://www.shadcn-vue.com/) - Beautiful Vue components built on Radix UI
|
||||
- [Tailwind CSS](https://tailwindcss.com/) - A utility-first CSS framework
|
||||
- [Iconify](https://iconify.design/) - Universal icon framework
|
||||
- [TanStack Table](https://tanstack.com/table) - Powerful table/data grid library
|
||||
|
||||
## 📞 Support
|
||||
|
||||
- **Documentation**: [RustFS Docs](https://docs.rustfs.com)
|
||||
- **Community**: [GitHub Discussions](https://github.com/your-org/rustfs-console/discussions)
|
||||
- **Issues**: [GitHub Issues](https://github.com/your-org/rustfs-console/issues)
|
||||
- **Email**: support@rustfs.com
|
||||
- **Documentation**: [RustFS Documentation](https://docs.rustfs.com)
|
||||
- **Community**: [GitHub Discussions](https://github.com/rustfs/console/discussions)
|
||||
- **Issues**: [GitHub Issues](https://github.com/rustfs/console/issues)
|
||||
- **Repository**: [rustfs/console](https://github.com/rustfs/console)
|
||||
|
||||
---
|
||||
|
||||
|
||||
+146
-146
@@ -1,173 +1,173 @@
|
||||
# Config Helpers 测试套件
|
||||
# Config Helpers Test Suite
|
||||
|
||||
这是 `config-helpers.ts` 模块的完整测试套件，包含单元测试、集成测试、性能测试和边界条件测试。
|
||||
This is a comprehensive test suite for the `config-helpers.ts` module, including unit tests, integration tests, performance tests, and edge case tests.
|
||||
|
||||
## 测试结构
|
||||
## Test Structure
|
||||
|
||||
```
|
||||
tests/
|
||||
├── setup.ts # 测试环境设置
|
||||
├── setup.ts # Test environment setup
|
||||
├── utils/
|
||||
│ ├── config-helpers.test.ts # 主要单元测试
|
||||
│ ├── config-helpers.integration.test.ts # 集成测试和边界条件
|
||||
│ ├── config-helpers.performance.test.ts # 性能和压力测试
|
||||
│ └── test-helpers.ts # 测试工具和 Mock 函数
|
||||
└── README.md # 本文件
|
||||
│ ├── config-helpers.test.ts # Main unit tests
|
||||
│ ├── config-helpers.integration.test.ts # Integration tests and edge cases
|
||||
│ ├── config-helpers.performance.test.ts # Performance and stress tests
|
||||
│ └── test-helpers.ts # Test utilities and Mock functions
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## 安装测试依赖
|
||||
## Installing Test Dependencies
|
||||
|
||||
```bash
|
||||
# 安装测试依赖
|
||||
# Install test dependencies
|
||||
npm install --save-dev vitest jsdom @vitest/ui c8
|
||||
|
||||
# 或者使用 yarn
|
||||
# Or using yarn
|
||||
yarn add --dev vitest jsdom @vitest/ui c8
|
||||
```
|
||||
|
||||
## 运行测试
|
||||
## Running Tests
|
||||
|
||||
### 基本测试命令
|
||||
### Basic Test Commands
|
||||
|
||||
```bash
|
||||
# 运行所有测试
|
||||
# Run all tests
|
||||
npm run test
|
||||
|
||||
# 运行测试并生成覆盖率报告
|
||||
# Run tests and generate coverage report
|
||||
npm run test:coverage
|
||||
|
||||
# 运行测试 UI 界面
|
||||
# Run test UI interface
|
||||
npm run test:ui
|
||||
|
||||
# 运行单次测试（CI 模式）
|
||||
# Run tests once (CI mode)
|
||||
npm run test:run
|
||||
```
|
||||
|
||||
### 针对性测试
|
||||
### Targeted Tests
|
||||
|
||||
```bash
|
||||
# 只运行 config-helpers 相关测试
|
||||
# Run only config-helpers related tests
|
||||
npm run test:config-helpers
|
||||
|
||||
# 只运行性能测试
|
||||
# Run only performance tests
|
||||
npm run test:performance
|
||||
|
||||
# 只运行集成测试
|
||||
# Run only integration tests
|
||||
npm run test:integration
|
||||
|
||||
# 运行特定测试文件
|
||||
# Run specific test file
|
||||
npx vitest tests/utils/config-helpers.test.ts
|
||||
|
||||
# 运行特定测试用例
|
||||
# Run specific test case
|
||||
npx vitest -t "getCurrentBrowserConfig"
|
||||
```
|
||||
|
||||
## 测试覆盖范围
|
||||
## Test Coverage
|
||||
|
||||
### 1. 单元测试 (`config-helpers.test.ts`)
|
||||
### 1. Unit Tests (`config-helpers.test.ts`)
|
||||
|
||||
- ✅ **createDefaultConfig**: 默认配置创建
|
||||
- ✅ **getCurrentBrowserConfig**: 浏览器配置获取
|
||||
- ✅ **getStoredHostConfig**: localStorage 配置获取
|
||||
- ✅ **fetchConfigFromServer**: 服务器配置获取和合并
|
||||
- ✅ **getConfig**: 智能配置策略
|
||||
- ✅ **saveHostConfig**: 配置保存
|
||||
- ✅ **clearStoredHostConfig**: 配置清除
|
||||
- ✅ **validateConfig**: 配置验证
|
||||
- ✅ **getConfigSources**: 调试信息获取
|
||||
- ✅ **Legacy Functions**: 向后兼容函数
|
||||
- ✅ **createDefaultConfig**: Default configuration creation
|
||||
- ✅ **getCurrentBrowserConfig**: Browser configuration retrieval
|
||||
- ✅ **getStoredHostConfig**: localStorage configuration retrieval
|
||||
- ✅ **fetchConfigFromServer**: Server configuration retrieval and merging
|
||||
- ✅ **getConfig**: Smart configuration strategy
|
||||
- ✅ **saveHostConfig**: Configuration saving
|
||||
- ✅ **clearStoredHostConfig**: Configuration clearing
|
||||
- ✅ **validateConfig**: Configuration validation
|
||||
- ✅ **getConfigSources**: Debug information retrieval
|
||||
- ✅ **Legacy Functions**: Backward compatibility functions
|
||||
|
||||
### 2. 集成测试 (`config-helpers.integration.test.ts`)
|
||||
### 2. Integration Tests (`config-helpers.integration.test.ts`)
|
||||
|
||||
- ✅ **完整配置流程**: 保存 → 获取 → 验证 → 清除
|
||||
- ✅ **配置优先级**: server > localStorage > browser > default
|
||||
- ✅ **边界条件**: 极端 URL、特殊字符、异常处理
|
||||
- ✅ **并发操作**: 竞态条件、并发读写
|
||||
- ✅ **跨浏览器兼容性**: 不同环境下的行为
|
||||
- ✅ **错误恢复**: 网络错误、JSON 解析错误、存储异常
|
||||
- ✅ **Complete Configuration Flow**: Save → Retrieve → Validate → Clear
|
||||
- ✅ **Configuration Priority**: server > localStorage > browser > default
|
||||
- ✅ **Edge Cases**: Extreme URLs, special characters, error handling
|
||||
- ✅ **Concurrent Operations**: Race conditions, concurrent read/write
|
||||
- ✅ **Cross-browser Compatibility**: Behavior in different environments
|
||||
- ✅ **Error Recovery**: Network errors, JSON parsing errors, storage exceptions
|
||||
|
||||
### 3. 性能测试 (`config-helpers.performance.test.ts`)
|
||||
### 3. Performance Tests (`config-helpers.performance.test.ts`)
|
||||
|
||||
- ✅ **单函数性能**: 执行时间基准测试
|
||||
- ✅ **批量操作**: 大量数据处理能力
|
||||
- ✅ **并发性能**: 高并发场景下的稳定性
|
||||
- ✅ **内存管理**: 内存泄漏检测
|
||||
- ✅ **网络性能**: 慢速网络、超时处理
|
||||
- ✅ **压力测试**: 极限负载下的表现
|
||||
- ✅ **Single Function Performance**: Execution time benchmarks
|
||||
- ✅ **Batch Operations**: Large data processing capability
|
||||
- ✅ **Concurrent Performance**: Stability under high concurrency
|
||||
- ✅ **Memory Management**: Memory leak detection
|
||||
- ✅ **Network Performance**: Slow network, timeout handling
|
||||
- ✅ **Stress Tests**: Performance under extreme load
|
||||
|
||||
## 测试工具 (`test-helpers.ts`)
|
||||
## Test Utilities (`test-helpers.ts`)
|
||||
|
||||
### Mock 工具
|
||||
### Mock Utilities
|
||||
|
||||
- **BrowserMock**: 模拟浏览器环境和 window.location
|
||||
- **LocalStorageMock**: 模拟 localStorage 行为和异常
|
||||
- **FetchMock**: 模拟各种网络响应场景
|
||||
- **BrowserMock**: Mock browser environment and window.location
|
||||
- **LocalStorageMock**: Mock localStorage behavior and exceptions
|
||||
- **FetchMock**: Mock various network response scenarios
|
||||
|
||||
### 数据生成器
|
||||
### Data Generators
|
||||
|
||||
- **createTestConfig**: 生成测试配置对象
|
||||
- **createTestServerResponse**: 生成服务器响应数据
|
||||
- **generateUrlTestCases**: 生成 URL 测试用例
|
||||
- **generateConfigTestCases**: 生成配置测试用例
|
||||
- **createTestConfig**: Generate test configuration objects
|
||||
- **createTestServerResponse**: Generate server response data
|
||||
- **generateUrlTestCases**: Generate URL test cases
|
||||
- **generateConfigTestCases**: Generate configuration test cases
|
||||
|
||||
### 性能工具
|
||||
### Performance Utilities
|
||||
|
||||
- **measureExecutionTime**: 测量函数执行时间
|
||||
- **runBatchTest**: 批量执行测试
|
||||
- **TestCleaner**: 测试环境清理
|
||||
- **measureExecutionTime**: Measure function execution time
|
||||
- **runBatchTest**: Execute tests in batch
|
||||
- **TestCleaner**: Test environment cleanup
|
||||
|
||||
### 断言辅助
|
||||
### Assertion Helpers
|
||||
|
||||
- **expectValidConfig**: 验证配置对象结构
|
||||
- **expectValidConfigResult**: 验证 ConfigResult 结构
|
||||
- **expectErrorResult**: 验证错误结果
|
||||
- **expectValidConfig**: Validate configuration object structure
|
||||
- **expectValidConfigResult**: Validate ConfigResult structure
|
||||
- **expectErrorResult**: Validate error results
|
||||
|
||||
## 测试场景
|
||||
## Test Scenarios
|
||||
|
||||
### 正常流程测试
|
||||
### Normal Flow Tests
|
||||
|
||||
1. **配置创建**: 验证默认配置生成的正确性
|
||||
2. **配置获取**: 测试各种配置源的获取逻辑
|
||||
3. **配置合并**: 验证服务器配置与默认配置的合并
|
||||
4. **配置保存**: 测试配置持久化功能
|
||||
5. **配置验证**: 验证配置完整性检查
|
||||
1. **Configuration Creation**: Verify correctness of default configuration generation
|
||||
2. **Configuration Retrieval**: Test retrieval logic for various configuration sources
|
||||
3. **Configuration Merging**: Verify merging of server configuration with default configuration
|
||||
4. **Configuration Saving**: Test configuration persistence functionality
|
||||
5. **Configuration Validation**: Verify configuration completeness checks
|
||||
|
||||
### 异常情况测试
|
||||
### Exception Handling Tests
|
||||
|
||||
1. **网络异常**: 超时、连接失败、无效响应
|
||||
2. **存储异常**: localStorage 不可用、配额超限
|
||||
3. **数据异常**: 无效 URL、损坏的 JSON、缺失字段
|
||||
4. **环境异常**: 非浏览器环境、缺失 API
|
||||
1. **Network Exceptions**: Timeouts, connection failures, invalid responses
|
||||
2. **Storage Exceptions**: localStorage unavailable, quota exceeded
|
||||
3. **Data Exceptions**: Invalid URLs, corrupted JSON, missing fields
|
||||
4. **Environment Exceptions**: Non-browser environment, missing APIs
|
||||
|
||||
### 边界条件测试
|
||||
### Edge Case Tests
|
||||
|
||||
1. **极端数据**: 超长 URL、大型配置对象、特殊字符
|
||||
2. **并发操作**: 同时读写、竞态条件、资源竞争
|
||||
3. **性能极限**: 大量数据、高频操作、内存压力
|
||||
1. **Extreme Data**: Ultra-long URLs, large configuration objects, special characters
|
||||
2. **Concurrent Operations**: Simultaneous read/write, race conditions, resource contention
|
||||
3. **Performance Limits**: Large amounts of data, high-frequency operations, memory pressure
|
||||
|
||||
## 性能基准
|
||||
## Performance Benchmarks
|
||||
|
||||
### 执行时间要求
|
||||
### Execution Time Requirements
|
||||
|
||||
- `getCurrentBrowserConfig`: < 1ms
|
||||
- `saveHostConfig`: < 5ms
|
||||
- `validateConfig`: < 1ms
|
||||
- `fetchConfigFromServer`: < 100ms (mock 环境)
|
||||
- `fetchConfigFromServer`: < 100ms (mock environment)
|
||||
|
||||
### 批量操作要求
|
||||
### Batch Operation Requirements
|
||||
|
||||
- 1000 次配置获取: < 1 秒
|
||||
- 100 次配置保存: 平均 < 10ms/次
|
||||
- 1000 次配置验证: 平均 < 0.5ms/次
|
||||
- 1000 configuration retrievals: < 1 second
|
||||
- 100 configuration saves: average < 10ms per operation
|
||||
- 1000 configuration validations: average < 0.5ms per operation
|
||||
|
||||
### 并发性能要求
|
||||
### Concurrent Performance Requirements
|
||||
|
||||
- 50 个并发请求: < 1 秒完成
|
||||
- 200 个极端并发操作: 全部成功完成
|
||||
- 50 concurrent requests: < 1 second completion
|
||||
- 200 extreme concurrent operations: all succeed
|
||||
|
||||
## CI/CD 集成
|
||||
## CI/CD Integration
|
||||
|
||||
### GitHub Actions 示例
|
||||
### GitHub Actions Example
|
||||
|
||||
```yaml
|
||||
name: Test Config Helpers
|
||||
@@ -186,88 +186,88 @@ jobs:
|
||||
- run: npm run test:coverage
|
||||
```
|
||||
|
||||
### 覆盖率要求
|
||||
### Coverage Requirements
|
||||
|
||||
- **语句覆盖率**: > 95%
|
||||
- **分支覆盖率**: > 90%
|
||||
- **函数覆盖率**: 100%
|
||||
- **行覆盖率**: > 95%
|
||||
- **Statement Coverage**: > 95%
|
||||
- **Branch Coverage**: > 90%
|
||||
- **Function Coverage**: 100%
|
||||
- **Line Coverage**: > 95%
|
||||
|
||||
## 调试技巧
|
||||
## Debugging Tips
|
||||
|
||||
### 运行单个测试
|
||||
### Running Single Tests
|
||||
|
||||
```bash
|
||||
# 使用 describe 或 it 的名称
|
||||
npx vitest -t "getCurrentBrowserConfig 应该基于当前浏览器位置创建配置"
|
||||
# Using describe or it names
|
||||
npx vitest -t "getCurrentBrowserConfig should create config based on current browser location"
|
||||
|
||||
# 使用文件路径和行号
|
||||
# Using file path and line number
|
||||
npx vitest tests/utils/config-helpers.test.ts:45
|
||||
```
|
||||
|
||||
### 查看详细输出
|
||||
### Viewing Detailed Output
|
||||
|
||||
```bash
|
||||
# 显示详细的测试输出
|
||||
# Show detailed test output
|
||||
npx vitest --reporter=verbose
|
||||
|
||||
# 显示覆盖率详情
|
||||
# Show coverage details
|
||||
npx vitest --coverage --reporter=verbose
|
||||
```
|
||||
|
||||
### 调试模式
|
||||
### Debug Mode
|
||||
|
||||
```bash
|
||||
# 在 Node.js 调试模式下运行
|
||||
# Run in Node.js debug mode
|
||||
npx vitest --inspect-brk
|
||||
|
||||
# 使用 VS Code 调试
|
||||
# 在 .vscode/launch.json 中添加配置
|
||||
# Using VS Code debugger
|
||||
# Add configuration in .vscode/launch.json
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
## Best Practices
|
||||
|
||||
1. **测试隔离**: 每个测试都应该独立，不依赖其他测试的状态
|
||||
2. **Mock 管理**: 在 `beforeEach` 中重置 Mock，在 `afterEach` 中清理
|
||||
3. **断言明确**: 使用具体的断言，避免过于宽泛的检查
|
||||
4. **错误测试**: 不仅测试成功路径，也要测试失败路径
|
||||
5. **性能监控**: 定期运行性能测试，监控性能回归
|
||||
1. **Test Isolation**: Each test should be independent and not depend on other tests' state
|
||||
2. **Mock Management**: Reset mocks in `beforeEach`, clean up in `afterEach`
|
||||
3. **Clear Assertions**: Use specific assertions, avoid overly broad checks
|
||||
4. **Error Testing**: Test both success and failure paths
|
||||
5. **Performance Monitoring**: Regularly run performance tests, monitor for performance regressions
|
||||
|
||||
## 故障排除
|
||||
## Troubleshooting
|
||||
|
||||
### 常见问题
|
||||
### Common Issues
|
||||
|
||||
1. **localStorage 不可用**: 确保在测试设置中正确 Mock localStorage
|
||||
2. **fetch 未定义**: 确保在 setup.ts 中 Mock fetch
|
||||
3. **window 对象缺失**: 使用 jsdom 环境或正确 Mock window
|
||||
4. **异步测试超时**: 增加超时时间或优化异步逻辑
|
||||
1. **localStorage Unavailable**: Ensure localStorage is properly mocked in test setup
|
||||
2. **fetch Undefined**: Ensure fetch is mocked in setup.ts
|
||||
3. **window Object Missing**: Use jsdom environment or properly mock window
|
||||
4. **Async Test Timeout**: Increase timeout or optimize async logic
|
||||
|
||||
### 调试步骤
|
||||
### Debugging Steps
|
||||
|
||||
1. 检查测试设置文件 (`setup.ts`)
|
||||
2. 验证 Mock 配置是否正确
|
||||
3. 查看测试输出和错误信息
|
||||
4. 使用 `console.log` 或调试器检查状态
|
||||
5. 运行单个测试以隔离问题
|
||||
1. Check test setup file (`setup.ts`)
|
||||
2. Verify mock configuration is correct
|
||||
3. Review test output and error messages
|
||||
4. Use `console.log` or debugger to check state
|
||||
5. Run single test to isolate issues
|
||||
|
||||
## 贡献指南
|
||||
## Contributing Guidelines
|
||||
|
||||
### 添加新测试
|
||||
### Adding New Tests
|
||||
|
||||
1. 确定测试类型（单元/集成/性能）
|
||||
2. 选择合适的测试文件
|
||||
3. 使用现有的测试工具和 Mock
|
||||
4. 遵循命名约定和结构
|
||||
5. 添加必要的文档注释
|
||||
1. Determine test type (unit/integration/performance)
|
||||
2. Choose appropriate test file
|
||||
3. Use existing test utilities and mocks
|
||||
4. Follow naming conventions and structure
|
||||
5. Add necessary documentation comments
|
||||
|
||||
### 测试命名约定
|
||||
### Test Naming Conventions
|
||||
|
||||
- 使用中文描述测试意图
|
||||
- 格式：`应该 + 期望行为`
|
||||
- 例如：`应该在服务器配置失败时回退到浏览器配置`
|
||||
- Use descriptive English test descriptions
|
||||
- Format: `should + expected behavior`
|
||||
- Example: `should fallback to browser config when server config fails`
|
||||
|
||||
### 代码覆盖率
|
||||
### Code Coverage
|
||||
|
||||
- 新功能必须有对应的测试
|
||||
- 保持高覆盖率（> 95%）
|
||||
- 重点测试边界条件和错误路径
|
||||
- New features must have corresponding tests
|
||||
- Maintain high coverage (> 95%)
|
||||
- Focus on testing edge conditions and error paths
|
||||
|
||||
Reference in New Issue
Block a user