Update docs and remove obsolete test README
Improved instructions and added Zotero integration steps in both English and Chinese README files. Removed references to tests/README.md in setup scripts and deleted the obsolete tests/README.md file.
This commit is contained in:
xixu-me committed
1 parent
8776d917db
commit
6542951001
4 files changed
+26
-268
No files matched your search
@@ -206,7 +206,7 @@ Configure API clients to use the pre-deployed instance:
|
||||
|
||||
### [DeepLX App](https://github.com/xixu-me/DeepLX-App) (Open-source web app)
|
||||
|
||||
A modern, free web-based translation app powered by DeepLX API. Features include:
|
||||
A modern, free web-based translation app powered by the DeepLX API. Features include:
|
||||
|
||||
- Multi-language auto-detection support
|
||||
- Real-time translation as you type
|
||||
@@ -216,24 +216,31 @@ A modern, free web-based translation app powered by DeepLX API. Features include
|
||||
|
||||
**Live Demo**: [https://deeplx.xi-xu.me](https://deeplx.xi-xu.me)
|
||||
|
||||
### [Pot](https://github.com/pot-app/pot-desktop/blob/master/README_EN.md) (Open-source cross-platform Windows, macOS and Linux app)
|
||||
### [Pot](https://github.com/pot-app/pot-desktop/blob/master/README_EN.md) (Open-source cross-platform Windows, macOS, and Linux app)
|
||||
|
||||
1. [Download and install Pot for your platform](https://github.com/pot-app/pot-desktop/releases/latest)
|
||||
2. Open Pot settings and navigate to service settings
|
||||
3. Configure DeepL service type as DeepLX and set custom URL to: `https://dplx.xi-xu.me/translate`
|
||||
2. Open Pot settings and navigate to Service Settings
|
||||
3. Configure the DeepL service type as DeepLX and set the custom URL to `https://dplx.xi-xu.me/translate`
|
||||
|
||||
### [Zotero](https://www.zotero.org/) (Open-source reference management app)
|
||||
|
||||
1. [Download and install Zotero for your platform](https://www.zotero.org/download/)
|
||||
2. Download and install the [Translate for Zotero](https://github.com/windingwind/zotero-pdf-translate) plugin
|
||||
3. Open Zotero settings and navigate to the Services section under Translation
|
||||
4. Configure the translation service as DeepLX (API) and set the endpoint to `https://dplx.xi-xu.me/translate` after clicking the config button
|
||||
|
||||
### [Immersive Translate](https://immersivetranslate.com/) (Closed-source browser extension)
|
||||
|
||||
1. [Install Immersive Translate](https://immersivetranslate.com/download/)
|
||||
2. Go to developer settings and enable beta testing features
|
||||
3. Go to translation services and add custom translation service DeepLX, set API URL to: `https://dplx.xi-xu.me/translate`
|
||||
4. Set the maximum requests per second and the maximum text length per request to appropriate values (e.g., `80` and `5000`) to ensure stability and performance
|
||||
3. Go to translation services and add a custom translation service DeepLX, configure the API URL to `https://dplx.xi-xu.me/translate`
|
||||
4. Configure the maximum requests per second and maximum text length per request to appropriate values (e.g., `80` and `5000`) to ensure stability and performance
|
||||
|
||||
### [Bob](https://bobtranslate.com/) (Closed-source macOS app)
|
||||
|
||||
1. [Download and install Bob from Mac App Store](https://apps.apple.com/app/id1630034110)
|
||||
2. Download and install [bob-plugin-deeplx](https://github.com/missuo/bob-plugin-deeplx) plugin
|
||||
3. Configure plugin to use `https://dplx.xi-xu.me/translate`
|
||||
1. [Download and install Bob from the Mac App Store](https://apps.apple.com/app/id1630034110)
|
||||
2. Download and install the [bob-plugin-deeplx](https://github.com/missuo/bob-plugin-deeplx) plugin
|
||||
3. Configure the plugin to use `https://dplx.xi-xu.me/translate`
|
||||
|
||||
## 🚀 Self-deployment
|
||||
|
||||
|
||||
+10
-3
@@ -220,14 +220,21 @@ except Exception as e:
|
||||
|
||||
1. [下载并安装适用于您平台的 Pot](https://github.com/pot-app/pot-desktop/releases/latest)
|
||||
2. 打开 Pot 设置并导航到服务设置
|
||||
3. 将 DeepL 服务类型配置为 DeepLX，并将自定义 URL 设置为：`https://dplx.xi-xu.me/translate`
|
||||
3. 将 DeepL 服务类型配置为 DeepLX，并将自定义 URL 配置为 `https://dplx.xi-xu.me/translate`
|
||||
|
||||
### [Zotero](https://www.zotero.org/)（开源文献管理应用）
|
||||
|
||||
1. [下载并安装适用于您平台的 Zotero](https://www.zotero.org/download/)
|
||||
2. 下载并安装 [Translate for Zotero](https://github.com/windingwind/zotero-pdf-translate) 插件
|
||||
3. 打开 Zotero 设置并导航到翻译中的服务部分
|
||||
4. 将翻译服务配置为 DeepLX（API），并点击配置按钮后将接口配置为 `https://dplx.xi-xu.me/translate`
|
||||
|
||||
### [沉浸式翻译](https://immersivetranslate.com/zh-Hans/)（闭源浏览器扩展）
|
||||
|
||||
1. [安装沉浸式翻译](https://immersivetranslate.com/zh-Hans/download/)
|
||||
2. 进入开发者设置并开启 beta 测试特性
|
||||
3. 进入翻译服务添加自定义翻译服务 DeepLX，将 API URL 设置为：`https://dplx.xi-xu.me/translate`
|
||||
4. 将每秒最大请求数和每次请求最大文本长度设置为合适的值（例如 `80` 和 `5000`），以确保稳定性和性能
|
||||
3. 进入翻译服务添加自定义翻译服务 DeepLX，将 API URL 配置为 `https://dplx.xi-xu.me/translate`
|
||||
4. 将每秒最大请求数和每次请求最大文本长度配置为合适的值（例如 `80` 和 `5000`），以确保稳定性和性能
|
||||
|
||||
### [Bob](https://bobtranslate.com/)（闭源 macOS 应用）
|
||||
|
||||
|
||||
@@ -220,7 +220,6 @@ function showSummary() {
|
||||
log(" npm run test:watch # Run tests in watch mode", "cyan");
|
||||
|
||||
console.log("\n" + colorize("📚 Documentation:", "bright"));
|
||||
log(" • tests/README.md # Comprehensive test docs", "cyan");
|
||||
log(" • TESTING.md # Quick start guide", "cyan");
|
||||
log(" • DEPLOYMENT_GUIDE.md # Deployment help", "cyan");
|
||||
log(" • README_TEST_SUITE.md # Complete overview", "cyan");
|
||||
@@ -229,7 +228,6 @@ function showSummary() {
|
||||
log(' 1. Run "npm test" to execute all tests', "magenta");
|
||||
log(' 2. Check coverage with "npm run test:coverage"', "magenta");
|
||||
log(' 3. Use "npm run test:watch" for development', "magenta");
|
||||
log(" 4. Review the documentation in tests/README.md", "magenta");
|
||||
|
||||
console.log(
|
||||
"\n" +
|
||||
|
||||
-254
@@ -1,254 +0,0 @@
|
||||
# DeepLX Test Suite
|
||||
|
||||
This directory contains comprehensive tests for DeepLX. The test suite is designed to ensure reliability, performance, and security of the translation service.
|
||||
|
||||
## Test Structure
|
||||
|
||||
```
|
||||
tests/
|
||||
├── lib/ # Unit tests for library modules
|
||||
│ ├── query.test.ts # Core translation functionality
|
||||
│ ├── cache.test.ts # Caching system tests
|
||||
│ ├── rateLimit.test.ts # Rate limiting tests
|
||||
│ ├── proxyManager.test.ts # Proxy management tests
|
||||
│ ├── circuitBreaker.test.ts # Circuit breaker tests
|
||||
│ ├── retryLogic.test.ts # Retry mechanism tests
|
||||
│ ├── security.test.ts # Security middleware tests
|
||||
│ ├── validation.test.ts # Input validation tests
|
||||
│ ├── textUtils.test.ts # Text processing utilities
|
||||
│ ├── types.test.ts # Type definitions and utilities
|
||||
│ └── errorHandler.test.ts # Error handling tests
|
||||
├── integration/ # Integration tests
|
||||
│ └── translation.test.ts # End-to-end translation workflows
|
||||
├── performance/ # Performance and load tests
|
||||
│ └── load.test.ts # Load testing and benchmarks
|
||||
├── utils/ # Test utilities and helpers
|
||||
│ └── testHelpers.ts # Common test utilities
|
||||
├── setup.ts # Jest setup configuration
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
## Test Categories
|
||||
|
||||
### Unit Tests (`tests/lib/`)
|
||||
|
||||
Unit tests focus on individual modules and functions in isolation:
|
||||
|
||||
- **Query Module**: Tests core translation functionality, request building, and API communication
|
||||
- **Cache Module**: Tests translation caching, cache key generation, and cache invalidation
|
||||
- **Rate Limiting**: Tests token bucket algorithm, IP-based limiting, and rate limit recovery
|
||||
- **Proxy Management**: Tests proxy selection, and failover logic
|
||||
- **Circuit Breaker**: Tests failure detection, circuit states, and recovery mechanisms
|
||||
- **Retry Logic**: Tests exponential backoff, retry conditions, and failure handling
|
||||
- **Security**: Tests input sanitization, CORS handling, and IP validation
|
||||
- **Validation**: Tests request validation, parameter sanitization, and error reporting
|
||||
- **Text Utils**: Tests text chunking, payload estimation, and length validation
|
||||
- **Error Handling**: Tests error response formatting and error categorization
|
||||
|
||||
### Integration Tests (`tests/integration/`)
|
||||
|
||||
Integration tests verify complete workflows and component interactions:
|
||||
|
||||
- **End-to-end Translation**: Complete translation workflows with caching and rate limiting
|
||||
- **Proxy Failover**: Proxy selection and automatic failover scenarios
|
||||
- **Security Integration**: Input validation and sanitization in real workflows
|
||||
- **Performance Integration**: Response time and resource utilization under load
|
||||
|
||||
### Performance Tests (`tests/performance/`)
|
||||
|
||||
Performance tests ensure the service meets performance requirements:
|
||||
|
||||
- **Response Time Benchmarks**: Measure translation response times
|
||||
- **Memory Usage**: Monitor memory consumption and leak detection
|
||||
- **Concurrent Requests**: Test handling of simultaneous requests
|
||||
- **Load Testing**: Stress testing with high request volumes
|
||||
- **Resource Utilization**: CPU and memory usage under various loads
|
||||
|
||||
## Running Tests
|
||||
|
||||
### All Tests
|
||||
|
||||
```bash
|
||||
npm test
|
||||
```
|
||||
|
||||
### Test Categories
|
||||
|
||||
```bash
|
||||
# Unit tests only
|
||||
npm run test:unit
|
||||
|
||||
# Integration tests only
|
||||
npm run test:integration
|
||||
|
||||
# Performance tests only
|
||||
npm run test:performance
|
||||
|
||||
# With coverage report
|
||||
npm run test:coverage
|
||||
|
||||
# Continuous integration mode
|
||||
npm run test:ci
|
||||
```
|
||||
|
||||
### Development Mode
|
||||
|
||||
```bash
|
||||
# Watch mode for development
|
||||
npm run test:watch
|
||||
|
||||
# Verbose output for debugging
|
||||
npm run test:verbose
|
||||
|
||||
# Debug mode with detailed output
|
||||
npm run test:debug
|
||||
```
|
||||
|
||||
## Test Configuration
|
||||
|
||||
### Jest Configuration (`jest.config.js`)
|
||||
|
||||
The test suite uses Jest with the following key configurations:
|
||||
|
||||
- **Environment**: Miniflare for Cloudflare Workers simulation
|
||||
- **TypeScript**: ts-jest for TypeScript support
|
||||
- **Coverage**: Comprehensive coverage reporting
|
||||
- **Mocking**: Extensive mocking of external dependencies
|
||||
|
||||
### Environment Setup (`tests/setup.ts`)
|
||||
|
||||
Global test setup includes:
|
||||
|
||||
- Mock environment creation
|
||||
- Global utilities and matchers
|
||||
- Console output management
|
||||
- Request/Response mocking
|
||||
|
||||
## Writing Tests
|
||||
|
||||
### Test Structure
|
||||
|
||||
Follow this structure for new tests:
|
||||
|
||||
```typescript
|
||||
describe('Module Name', () => {
|
||||
let mockEnv: Env;
|
||||
|
||||
beforeEach(() => {
|
||||
mockEnv = createMockEnv();
|
||||
});
|
||||
|
||||
afterEach(() => {
|
||||
jest.clearAllMocks();
|
||||
});
|
||||
|
||||
describe('function name', () => {
|
||||
it('should handle normal case', () => {
|
||||
// Test implementation
|
||||
});
|
||||
|
||||
it('should handle error case', () => {
|
||||
// Error test implementation
|
||||
});
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
|
||||
1. **Isolation**: Each test should be independent and not rely on other tests
|
||||
2. **Mocking**: Mock external dependencies and focus on the unit under test
|
||||
3. **Coverage**: Aim for high code coverage but focus on meaningful tests
|
||||
4. **Error Cases**: Test both success and failure scenarios
|
||||
5. **Edge Cases**: Include boundary conditions and edge cases
|
||||
6. **Performance**: Include performance assertions where relevant
|
||||
|
||||
### Custom Matchers
|
||||
|
||||
The test suite includes custom Jest matchers:
|
||||
|
||||
```typescript
|
||||
expect(response).toBeValidTranslationResponse();
|
||||
expect(response).toBeValidErrorResponse();
|
||||
```
|
||||
|
||||
### Test Utilities
|
||||
|
||||
Use the provided test utilities for common operations:
|
||||
|
||||
```typescript
|
||||
import {
|
||||
createMockTranslationResponse,
|
||||
createMockErrorResponse,
|
||||
createTestEnvironment,
|
||||
expectValidTranslationResponse
|
||||
} from './utils/testHelpers';
|
||||
```
|
||||
|
||||
## Continuous Integration
|
||||
|
||||
The test suite runs automatically on:
|
||||
|
||||
- **Push to main/develop branches**
|
||||
- **Pull requests to main branch**
|
||||
- **Multiple Node.js versions** (18.x, 20.x)
|
||||
|
||||
### CI Pipeline
|
||||
|
||||
1. **Lint**: TypeScript type checking
|
||||
2. **Unit Tests**: All library module tests
|
||||
3. **Integration Tests**: End-to-end workflow tests
|
||||
4. **Performance Tests**: Load and performance benchmarks
|
||||
5. **Coverage**: Code coverage reporting
|
||||
|
||||
## Coverage Requirements
|
||||
|
||||
The test suite aims for:
|
||||
|
||||
- **Line Coverage**: > 90%
|
||||
- **Function Coverage**: > 95%
|
||||
- **Branch Coverage**: > 85%
|
||||
- **Statement Coverage**: > 90%
|
||||
|
||||
## Debugging Tests
|
||||
|
||||
### Common Issues
|
||||
|
||||
1. **Async/Await**: Ensure all async operations are properly awaited
|
||||
2. **Mocking**: Verify mocks are properly reset between tests
|
||||
3. **Timeouts**: Increase timeout for slow operations
|
||||
4. **Memory**: Clear references to prevent memory leaks
|
||||
|
||||
### Debug Commands
|
||||
|
||||
```bash
|
||||
# Run specific test file
|
||||
npm test -- query.test.ts
|
||||
|
||||
# Run with debug output
|
||||
npm run test:debug
|
||||
|
||||
# Run single test
|
||||
npm test -- --testNamePattern="should handle successful translation"
|
||||
```
|
||||
|
||||
## Contributing
|
||||
|
||||
When adding new features:
|
||||
|
||||
1. **Write tests first** (TDD approach recommended)
|
||||
2. **Update existing tests** if behavior changes
|
||||
3. **Add integration tests** for new workflows
|
||||
4. **Include performance tests** for performance-critical features
|
||||
5. **Update documentation** including this README
|
||||
|
||||
## Monitoring and Alerts
|
||||
|
||||
The test suite includes monitoring for:
|
||||
|
||||
- **Test execution time trends**
|
||||
- **Flaky test detection**
|
||||
- **Coverage regression alerts**
|
||||
- **Performance regression detection**
|
||||
|
||||
For questions or issues with the test suite, please refer to the main repository documentation or create an issue in the repository.
|
||||
Reference in new issue
Block a user