Initial commit

2025-11-29 18:47:11 +08:00
commit 8d68fa43fc
13 changed files with 4244 additions and 0 deletions
--- a/commands/test-all.md
+++ b/commands/test-all.md
@@ -0,0 +1,355 @@
+# Test All Command
+
+Run the comprehensive test suite for the ExFabrica Agentic Factory monorepo, including unit tests, integration tests, and end-to-end tests for both backend and frontend applications.
+
+## Usage
+
+```
+/test-all [target] [--coverage] [--watch] [--verbose]
+```
+
+## Parameters
+
+- **target** (optional): Specific test target to run
+  - `backend` - Run only backend tests
+  - `frontend` - Run only frontend tests
+  - `e2e` - Run only end-to-end tests
+  - `unit` - Run only unit tests (backend + frontend)
+  - `integration` - Run only integration tests
+  - If omitted, runs all test suites
+- **--coverage** (optional): Generate code coverage reports
+- **--watch** (optional): Run tests in watch mode (auto-rerun on changes)
+- **--verbose** (optional): Show detailed test output
+
+## Test Suites
+
+### Backend Tests (NestJS + Drizzle ORM)
+
+**Unit Tests**
+- Service layer tests
+- Controller tests
+- Utility function tests
+- Guard and interceptor tests
+
+**Integration Tests**
+- API endpoint tests
+- Database operation tests
+- Authentication and authorization flows
+- Third-party service integrations
+
+**Test Location**: `apps/backend/src/**/*.spec.ts`
+**Test Runner**: Jest
+**Configuration**: `apps/backend/jest.config.js`
+
+### Frontend Tests (Angular 20)
+
+**Unit Tests**
+- Component tests
+- Service tests
+- Pipe and directive tests
+- Utility function tests
+
+**Integration Tests**
+- Component integration tests
+- Router navigation tests
+- State management tests
+- HTTP interceptor tests
+
+**Test Location**: `apps/frontend/src/**/*.spec.ts`
+**Test Runner**: Karma + Jasmine
+**Configuration**: `apps/frontend/karma.conf.js`
+
+### End-to-End Tests
+
+**E2E Scenarios**
+- User authentication flows
+- Critical user journeys
+- Cross-application workflows
+- API integration tests
+
+**Test Location**: `apps/frontend/e2e/`
+**Test Runner**: Protractor/Cypress (based on configuration)
+
+## Workflow
+
+When you execute this command, Claude will:
+
+1. **Environment Setup**
+   - Verify Node.js version (22+)
+   - Check Yarn version (4.9.2)
+   - Ensure test database is available
+   - Set test environment variables
+
+2. **Backend Tests**
+   - Run unit tests: `yarn workspace @bdqt/backend test`
+   - Run integration tests: `yarn workspace @bdqt/backend test:integration`
+   - Generate coverage report if requested
+
+3. **Frontend Tests**
+   - Run unit tests: `yarn workspace @bdqt/frontend test --watch=false`
+   - Run in headless Chrome for CI compatibility
+   - Generate coverage report if requested
+
+4. **E2E Tests** (if applicable)
+   - Start backend server in test mode
+   - Start frontend development server
+   - Run E2E test suite
+   - Shutdown servers after tests complete
+
+5. **Results Aggregation**
+   - Combine test results from all suites
+   - Calculate overall coverage
+   - Generate unified test report
+   - Highlight any failures or warnings
+
+## Examples
+
+### Run All Tests
+```
+/test-all
+```
+Executes the complete test suite across all applications.
+
+### Run Backend Tests Only
+```
+/test-all backend
+```
+Runs only the backend unit and integration tests.
+
+### Run Frontend Tests Only
+```
+/test-all frontend
+```
+Runs only the frontend unit tests using Karma.
+
+### Run Tests with Coverage
+```
+/test-all --coverage
+```
+Generates code coverage reports for all test suites.
+
+### Run Tests in Watch Mode
+```
+/test-all backend --watch
+```
+Runs backend tests in watch mode for active development.
+
+### Run E2E Tests with Verbose Output
+```
+/test-all e2e --verbose
+```
+Runs end-to-end tests with detailed logging.
+
+## Coverage Thresholds
+
+The test suite enforces minimum coverage thresholds:
+
+### Backend Coverage Requirements
+- **Statements**: 80%
+- **Branches**: 75%
+- **Functions**: 80%
+- **Lines**: 80%
+
+### Frontend Coverage Requirements
+- **Statements**: 75%
+- **Branches**: 70%
+- **Functions**: 75%
+- **Lines**: 75%
+
+Tests will fail if coverage drops below these thresholds.
+
+## Test Environment Configuration
+
+### Backend Test Environment
+- Uses in-memory SQLite for fast unit tests
+- Uses test PostgreSQL database for integration tests (port 5442)
+- JWT secrets use test values
+- External API calls are mocked
+
+### Frontend Test Environment
+- Runs in headless Chrome
+- Uses Angular testing utilities (TestBed)
+- HTTP calls are mocked via HttpClientTestingModule
+- LocalStorage/SessionStorage use test implementations
+
+### E2E Test Environment
+- Backend runs on port 3001 (test port)
+- Frontend runs on port 4201 (test port)
+- Test database is seeded with fixtures
+- Clean state before each test suite
+
+## Output Format
+
+### Success Output
+```
+✓ Backend Unit Tests: 245 passed
+✓ Backend Integration Tests: 67 passed
+✓ Frontend Unit Tests: 189 passed
+✓ E2E Tests: 34 passed
+
+Total: 535 tests passed
+Coverage: 82.5% (above threshold)
+Duration: 3m 24s
+
+All tests passed successfully! ✓
+```
+
+### Failure Output
+```
+✗ Backend Unit Tests: 243 passed, 2 failed
+  - UserService.createUser should hash password (apps/backend/src/users/users.service.spec.ts:42)
+  - AuthGuard should reject expired tokens (apps/backend/src/auth/auth.guard.spec.ts:78)
+
+✓ Backend Integration Tests: 67 passed
+✓ Frontend Unit Tests: 189 passed
+
+Total: 499 tests passed, 2 failed
+Coverage: 79.2% (below threshold)
+
+Tests failed. Please fix the failing tests before proceeding.
+```
+
+## Troubleshooting
+
+### Test Database Connection Issues
+```
+Error: Cannot connect to test database
+```
+**Solution**: Ensure Docker is running and test database is available
+```bash
+docker compose up -d postgres-test
+```
+
+### Chrome/Browser Not Found (Frontend Tests)
+```
+Error: ChromeHeadless not found
+```
+**Solution**: Install Chromium or configure alternative browser
+```bash
+yarn add -D puppeteer
+```
+
+### Port Already in Use (E2E Tests)
+```
+Error: Port 3001 already in use
+```
+**Solution**: Stop any running development servers or use different test ports
+
+### Memory Issues (Large Test Suites)
+```
+Error: JavaScript heap out of memory
+```
+**Solution**: Increase Node.js memory limit
+```bash
+export NODE_OPTIONS="--max-old-space-size=4096"
+```
+
+### Flaky E2E Tests
+```
+Error: Element not found within timeout
+```
+**Solution**: Increase wait timeouts or add explicit waits in E2E tests
+
+## Performance Optimization
+
+### Parallel Test Execution
+Tests run in parallel by default using Jest workers:
+- Backend: `--maxWorkers=50%`
+- Frontend: `--parallel=true`
+
+### Test Caching
+Jest caches test results between runs:
+```bash
+# Clear test cache if needed
+yarn jest --clearCache
+```
+
+### Selective Test Running
+Run only changed tests during development:
+```bash
+yarn test --onlyChanged
+```
+
+## CI/CD Integration
+
+This command is designed to work seamlessly with Azure DevOps pipelines:
+
+### Pipeline Integration
+```yaml
+- task: Script@1
+  displayName: 'Run Test Suite'
+  inputs:
+    script: |
+      /test-all --coverage
+```
+
+### Test Results Publishing
+Test results are automatically formatted for Azure DevOps:
+- JUnit XML for test results
+- Cobertura XML for coverage reports
+- HTML reports for detailed analysis
+
+## Best Practices
+
+1. **Run tests before committing**
+   ```
+   /test-all
+   # Commit only if all tests pass
+   ```
+
+2. **Use watch mode during development**
+   ```
+   /test-all backend --watch
+   ```
+
+3. **Check coverage regularly**
+   ```
+   /test-all --coverage
+   ```
+
+4. **Fix failing tests immediately**
+   - Don't let failing tests accumulate
+   - Maintain high test quality standards
+
+5. **Run E2E tests before major releases**
+   ```
+   /test-all e2e
+   ```
+
+## Related Commands
+
+- `/deploy` - Deploy after tests pass
+- `/analyze-code` - Check code quality and test coverage
+- `/db-operations seed` - Seed test database with fixtures
+
+## Test Writing Guidelines
+
+### Backend Test Example
+```typescript
+describe('UserService', () => {
+  it('should create a new user with hashed password', async () => {
+    const userData = { email: 'test@example.com', password: 'password123' };
+    const user = await userService.create(userData);
+
+    expect(user.password).not.toBe('password123');
+    expect(await bcrypt.compare('password123', user.password)).toBe(true);
+  });
+});
+```
+
+### Frontend Test Example
+```typescript
+describe('LoginComponent', () => {
+  it('should disable submit button when form is invalid', () => {
+    component.loginForm.controls['email'].setValue('');
+    fixture.detectChanges();
+
+    const submitButton = fixture.nativeElement.querySelector('button[type="submit"]');
+    expect(submitButton.disabled).toBe(true);
+  });
+});
+```
+
+---
+
+**Note**: All tests use the Yarn workspace structure. Direct Jest/Karma commands should be run through Yarn workspaces to respect the monorepo configuration.